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 8400 minutes (140 hours) from creation and will expire automatically after that time. If a Client API user is deleted, any API token created by that user account is deprovisioned at the same time. If a Client API user is only disabled, any API token created by that user account will continue to work until its expiration, but it is not possible to create a new token until the user is enabled again.

  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.

BOARD Public APIs queries configuration

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.
    • 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

     

    By default, the following quotas apply to all Public API 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. If the remote API server does not return a response within 100 seconds, Board closes the connection.

 

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".

The API DOCUMENTATION in Board

 

Board has a timeout of 100 seconds. If the remote API server does not return a response within 100 seconds, Board closes the connection.