Client API

• Applies to: All Board Cloud subscriptions

WHAT: Introduction to Client API users

Client API users allow to configure and customize how the Board ecosystem gets integrated into other third-party software environments.

Once the initial configuration has been created, the external environment will be able to read and manipulate data from Board and to execute specific operations on its platforms. 

For example, through a HTTPS requests, it is possible to obtain lists of Entities, Cubes, Relationships or Entity members in JSON format. It is also possible to execute a Layout, search for a Capsule, execute a Database procedure, and perform a full text search.

Client API users cannot be imported via CSV file. They can be manually imported from a Board platform, once you associate it with the Subscription Hub.

HOW: Client API configuration

1. Click on "CLIENT API" and fill in all required fields, marked with a *.
   The Client ID and the client secret are essentially a username and a password that the external client will use to obtain an access token from the Subscription Hub. The request must comply to OAuth2 client credentials flow specifications.
   Once that token has been provided, it'll have to be included in the API requests' header to access Board's resources.

   Tokens are valid for 30 days from creation and will expire automatically after that time.
   If a Client API user is disabled or deleted, any API token created by that user account is deprovisioned at the same time.

2. From the License dropdown menu, select the License type you'd like to assign to the client API, just like you'd do when adding a new user account.

   The available License types may vary, depending on your Cloud Subscription. To know more about Board Licenses please visit this page.

   When the "Disabled"checkbox is ticked, the external client won't be able to make API requests using the configured credentials and its license will be available to assign to other user accounts.

   Choose the appropriate "Culture" option to apply a specific date and time format to API responses. Leave it blank to apply the default date and time format.
3. If you are creating the client API to be used with Board's SCIM API service, tick the “enable SCIM endpoint” option.
4. In the Platform authorization table, select a Role, assign a License type and, if applicable, tick the "Admin" checkbox: if checked, the external client will be able to launch business critical procedures, as per your Board platforms configuration. You will need to set those attributes for each listed Board platform you want to give the external client access to.
   To know more about the Platform authorization table, please see this paragraph.
5. Set API permissions by ticking the desired checkboxes. You will need to do this for each listed Board platform you want to give the external client access to (see the paragraph below for more information about Board's public API).
6. Click "SAVE" to create the system user and start using Board's public APIs.

To know more about available APIs, please see the paragraph below.

 

Client APIs overview

Depending on which version of Board is installed, you will have some or all the following APIs available. The API Queries have to be configured in all Board platforms, under the "API queries" section of each Data model you want the APIs to work with.

Once you've created the necessary Client API user, an authorization token must be generated before making any request.

The token returned from this request must be used to manage the authentication in the API requests.

The authentication must comply with OAuth2 client credentials flow specifications.

To obtain the authorization token, you need to set the following additional parameters:

• Grant Type: "Client Credentials"
• Access Token URL: https://your-subscription-hub-url/connect/token
• Scope: "public-api"
• Client Authentication: "Send client credentials in body"

Client API users don't consume any Board license, but Roles applied in the "Platform authorization" table are always respected.

 

Board's Public APIs

Here's an overview of Board's public APIs:

Unless otherwise indicated below, query parameters are case sensitive.
OAuth 2.0 Authorization Code with PKCE flow specifications are also supported for the authentication in API requests.

• ApiQuery: returns the result of the specified query. It is possible to add querystring parameters for the select.

  By default, the following quotas apply to ApiQuery calls:
  - 500 requests per day (this limit can be increased with an additional license. If you need an increase to your quota, please contact your Board Customer Success Manager or Key Account Manager)
  - 10 requests per second

  • Submission method: GET
  • Syntax: /public/{dbName}/query/{queryName}
  • Parameters

    Parameter	Value	Description	Parameter Type	Data Type
    dbName	Required	Database name	path	string
    queryName	Required	API query name	path	string
    json	Accepted Value: full (Optional)	Set the parameter to full to repeat keys for each returned record	query	string

    The queryName parameter value must match an existing API query name in the specified database.

  • Examples:
     
    • Base

      ?{entity_name}={member_code}
      ?year=2012
      
      Result: returns all values from 2012

    • Multiple
      ?{entity_name}={member_code}&{entity_name}={member_code}
      ?year=2012&city=IT01
      
      Result: returns all values from 2012 and city with code IT01

    • List
      ?{entity_name}={member_code},{member_code},{member_code}
      ?year=2012,2017,2019
      
      Result: returns all values from years 2012, 2017 and 2019

    • Range
      ?{entity_name}={member_code}..{member_code}
      ?year=2015..2019
      
      Result: returns all values from years 2015 to 2019

    • Escape
      ?{entity_name}="{member_code}"
      ?city="IT01"
      
      Result: returns all values from city with code IT01

    • Json
      ?json=full
      
      Result: repeats all keys for each returned record, instead of listing all keys once at the beginning of the returned dataset
       

• Schema: returns a list of entities, of entity members or cubes for a specified database.
  • Submission method: GET
  • Syntax: /public/{dbName}/schema/Entities
  • Parameter

    Parameter	Value	Description	Parameter Type	Data Type
    dbName	Required	Database name	path	string
    format	Optional	The format of the response: tree or flat	query	string

  • Syntax: /public/{dbName}/schema/Entities/{name}
  • Parameters

    Parameter	Value	Description	Parameter Type	Data Type
    dbName	Required	Database name	path	string
    name	Required	Entity name	path	string
    skip	Optional	Bypass a specified number of search results then return the remaining results	query	integer
    take	Optional	Specify the number of search results to return	query	integer
    searchString	Optional	Text query. Case insensitive	query	string

     
  • Syntax: /public/{dbName}/schema/Cubes
  • Parameters

    Parameter	Value	Description	Parameter Type	Data Type
    dbName	Required	Database name	path	string

    
    
     
• Procedure: starts the execution of a specified Procedure and returns the Procedure status after its execution.
  • Submission method: POST
  • Syntax: /public/{dbName}/procedure/Execute/{procedureName}
  • Parameters

    Parameter	Value	Description	Parameter Type	Data Type
    dbName	Required	Database name	path	string
    procedureName	Required	Procedure name	path	string

    
    It is possible to trigger the execution of a Procedure with a selection added through query string parameters: the selection will define the scope of the Procedure, just as it happens when the Procedure is triggered from a Capsule Screen which has an active Selection applied.
     
  • Examples:
     
    • Base

      ?{entity_name}={member_code}
      ?year=2012
      
      Result: the Procedure is executed considering the year 2012 

    • Multiple
      ?{entity_name}={member_code}&{entity_name}={member_code}
      ?year=2012&city=IT01
       
      Result: the Procedure is executed considering the year 2012 and the city code IT01

    • List
      ?{entity_name}={member_code},{member_code},{member_code}
      ?year=2012,2017,2019
      
      Result: the Procedure is executed considering the years 2012, 2017 and 2019

    • Range
      ?{entity_name}={member_code}..{member_code}
      ?year=2015..2019
      
      Result: the Procedure is executed considering the years 2015 to 2019

    • Escape
      ?{entity_name}="{member_code}"
      ?city="IT01"
      
      Result: the Procedure is executed considering the city with code IT01
       

  • Submission method: GET
  • Syntax: /public/{dbName}/procedure/Status/{sessionId}
  • Parameters

    Parameter	Value	Description	Parameter Type	Data Type
    dbName	Required	Database name	path	string
    sessionId	Required	The Session id value included in the response of the execute procedure query	path	string

    
    
  • Response types
     
    • Procedure status: running.
      Response:
      {
        "status": 1,
        "message": "Running"
      }
       
    • Procedure status: stopped.
      Response:
      {
        "status": 0,
        "message": "Stopped"
      }
      
       
• Capsule: returns the Capsule tree (with folders, if present) o a specific Capsule by name. By passing a username as a query parameter, the endpoint will return results based on that user's specific authorizations.
  • Submission method: GET
  • Syntax: /public/capsules/{capsuleName}
  • Parameters

    Parameter	Value	Description	Parameter Type	Data Type
    capsuleName	Required	Capsule name	path	string
    username	Optional	Username	query	string

    
    
     
• FullTextSearch: returns the results of a Full Text Search in the entire Platform (the search is executed in Capsules and Presentations, but it will return also Data models, procedures and anything that matches or contains the search query).
  By passing a username as a query parameter, the endpoint will return results based on that user's specific authorizations.
  • Submission method: GET
  • Syntax: /public/search/{textToSearch}
  • Parameters

    Parameter	Value	Description	Parameter Type	Data Type
    textToSearch	Required	Text search query	path	string
    username	Optional	Username	query	string

    
     
• Presentations: returns a list of available Presentations, metadata about a specific Presentation, the list of Slides from a specific Presentation, metadata about a specific Slide, a list of Screen Objects/Layout titles from a specific Slide, values from a single Layout. By passing a username as a query parameter, the endpoint will return results based on that user's specific authorizations.
  • Submission method: GET
  • Syntax: /public/presentations/{name}
  • Parameters

    Parameter	Value	Description	Parameter Type	Data Type
    name	Optional	The Presentation name	path	string
    username	Optional	The owner of the Presentation	query	string

  • Syntax: /public/presentations/{name}/slides/{slideName}
  • Submission method: GET
  • Parameters

    Parameter	Value	Description	Parameter Type	Data Type
    name	Required	The Presentation name	path	string
    slideName	Optional	The Slide name	path	string
    username	Optional	The owner of the Presentation	query	string

    
     
  • Syntax: /public/presentations/{name}/slides/{slideName}/toolboxes
  • Submission method: GET
  • Parameters

    Parameter	Value	Description	Parameter Type	Data Type
    name	Required	The Presentation name	path	string
    slideName	Required	The Slide name	path	string
    username	Optional	The owner of the Presentation	query	string

    
     
  • Syntax: /public/presentations/{name}/slides/{slideName}/toolbox/{toolboxName}
  • Submission method: GET
  • Parameters

    Parameter	Value	Description	Parameter Type	Data Type
    name	Required	The Presentation name	path	string
    slideName	Required	The Slide name	path	string
    toolboxName	Required	The Toolbox name	path	string
    username	Optional	The owner of the Presentation	query	string

 

 

The most up-to-date technical documentation is available right in each active Board platform. To access it, head to the desired platform, click on "Data model" from the main menu, select any data model you have in place, and click on "API queries". Once there, click on "GO TO API DOCUMENTATION".