×
 
 
  •  
$helper.renderConfluenceMacro('{bmc-global-announcement:$space.key}')

Space banner

 

This documentation supports the 20.02 version of BMC Digital Workplace Advanced.

To view the latest version, select the version from the Product Version menu.
BMC Digital Workplace Advanced 20.02 ... Developing Integrating BMC Digital Workplace with remote servers

Implementing the Data Lookup Service Provider Interface

Tip

Click here to download the JSON (JavaScript Object Notation) snippets included in these topics, and customize them to use according to your requirements.

A host of features in BMC Digital Workplace Catalog rely on connectors exposing data by lookup:

  • Ability to populate the possible answers of a multi-choice question (e.g. drop-down or radio button question).
  • Ability to assign a value to an answer by performing a data lookup and using fields of the result (i.e. "questionnaire actions").

These features are based on three possible capabilities of connectors.


Dataset Provider

Capability:

 com.bmc.dsm.catalog:datasetProvider

Simple datasets are lists of records, each of which has one predetermined display value and one predetermined data value. How the display value or the data value of each dataset is defined is hard-coded in the connector.


Queryable Dataset Provider

Capability:

com.bmc.dsm.catalog:queryableDatasetProvider

This capability supports both cabilities:

  • Populate multi-choice questions (called "map to form" in the admin "Questions" UI).
  • Perform answer prefills based on data lookups (called "Actions" in the admin "Questions" UI).

For populating multi-choice questions, enable BMC Digital Workplace Catalog to query a table-like source while allowing its administrators to pick:

  • The field that will be the display value
  • The field that will be the data value

Both fields will be passed along with the request for the dataset items (see "SPI" below).

For the answer prefill, BMC Digital Workplace Catalog will use the same API to retrieve the data and will assign the returned values to the mapped answer.


Table Dataset Provider

Capability:

com.bmc.dsm.catalog:tableDatasetProvider

This capability is an enhancement over queryable dataset providers. It allows BMC Digital Workplace Catalog to retrieve the values of many fields of a dataset at the same time (instead of just a couple through the queryable dataset provider SPI). Implementing this interface can make the request checkout experience more responsive for some complex service questionnaires. It is also leveraged by dynamic table questions.

All table dataset providers are considered queryable dataset providers as well and should implement the corresponding SPI.


Dataset Fields

Queryable dataset providers and table dataset providers need must expose a list of fields on each queryable dataset. These fields are available to the catalog administrator or to BMC Digital Workplace Catalog to perform queries.

By default, dataset fields are considered to be textual. This makes the development of the capability easier in many cases. However, for table questions, providing a type will enhance the experience of requesters by allowing proper formatting and sorting in the UI. Here are the supported types:

  • TEXT

  • DATETIME

  • DATE

  • TIME

  • SELECTION (predefined enumeration)

  • INTEGER

  • DECIMAL

  • CURRENCY (money amount)

Note that the values of the dataset fields are still transferred as strings, disregarding these declared types. In particular, integers or decimals are transferred as strings e.g. "123" or 123.45. Text and selection values are naturally textual. Refer to Principles of the Remote Connector Service Provider Interface for the formatting of dates, times, date-times and currency values.


SPI

Dataset providers, queryable dataset providers and table dataset providers implement the same general end-points, but request/response properties may differ for each depending on the use case.

POST ${connector_path}/com.bmc.dsm.catalog:getDatasets

Lists all the datasets exposed by the connector.

request
{
  "connectionInstanceId": "DEV",
  "request": {    
    "queryable": false
		//Indicates whether  wants to list queryable/table datasets 
          versus simple datasets. 
          A simple dataset provider can ignore the "queryable" property 
          (it will only be called when it is false). 
          If null, all the datasets, queryable or not should be returned.
  }
}
response
{
  "response": {    
    "datasets": [
      {
        "id": "T_SIZES",
				//ID of the dataset. Other calls to retrieve further details or get 
                  the items will use this ID. 
                  If you have different kinds of datasets to expose, you may have to 
                  use naming conventions (like prefixes) to ensure that you are able to 
                  discriminate them and that you are able to lookup the right resource 
                  in the integration target.
        "name": "T-Shirt Size",
				//Display name of the dataset. 
                  You should make sure display names are distinguishable from each other, 
                  especially when you merge different kinds of data sources together behind 
                  one connector.
        "queryable": false,
				//Indicates whether the dataset is queryable.
        "serviceId": null,
				//Optional ID of an importable service, which owns the dataset.
        "serviceDisplayId": null,
				//Optional display ID of an importable service, which owns the dataset.
        "serviceName": null
				//Optional display name of an importable service, which owns the dataset.
      },
      {
        "id": "T_COLORS",
        "name": "T-Shirt Color",
        "queryable": false,
        "serviceId": null,
        "serviceDisplayId": null,
        "serviceName": null
      }
    ]
  }
}

POST ${connector_path}/com.bmc.dsm.catalog:getDataset

Returns the details of a specified dataset.

request
{
  "connectionInstanceId": "DEV",
  "request": {    
    "datasetId": "T_SIZES"
  }
}
simple dataset response
{
  "response": {    
  "dataset": {
      "id": "T_SIZES",
      "name": "T-Shirt Size",
      "queryable": false
    }
  }
}
queryable or table dataset response
{
  "response": {   
  "dataset": {
      "id": "T_SIZES",
      "name": "T-Shirt Size",
      "queryable": true,
      "fields": [
        { "id": "key", "name": "Key" },
        { "id": "label", "name": "Label" },
        { "id": "cost", "name": "Extra Cost", "type": "CURRENCY" },
        {
          "id": "age",
          "name": "Age",
          "type": "SELECTION",
          "selectionItems": [
            { "value": "A", "label": "Adult" },
            { "value": "K", "label": "Kid" }
          ]
        }
      ]
    }
  }
}
response properties

datasets.fields:

Array of the fields of this queryable dataset. The BMC Digital Workplace Catalog administrator
will be able to pick her display and data value fields from these.

POST ${connector_path}/com.bmc.dsm.catalog:findDatasetItems

Finds and returns the dataset items corresponding to the specified criteria.

simple dataset request
{
  "connectionInstanceId": "DEV",
  "request": {    
    "datasetId": "T_SIZES",
    "requestedBy": {
      "emailAddress": "tanya@example.com",
      "fullName": "Tanya Romero",
      "loginName": "tanya",
      "ntDomain": "NTPROD"
    },
    "requestedFor": {
      "emailAddress": "bob@example.com",
      "fullName": "Bob Berenstein",
      "loginName": "bob",
      "ntDomain": "NTPROD"
    },
    "idFieldId": null,
    "nameFieldId": null,
    "fieldIds": null,
    "searchText": null,
    "focusedOnDatasetItemIds": null,
    "qualificationExpression": null
  }
}
queryable dataset request
{
  "connectionInstanceId": "DEV",
  "request": {    
    "datasetId": "T_SIZES",
    "requestedBy": {
      "emailAddress": "tanya@example.com",
      "fullName": "Tanya Romero",
      "loginName": "tanya",
      "ntDomain": "NTPROD"
    },
    "requestedFor": {
      "emailAddress": "bob@example.com",
      "fullName": "Bob Berenstein",
      "loginName": "bob",
      "ntDomain": "NTPROD"
    },
    "idFieldId": "key",
    "nameFieldId": "label",
    "fieldIds": null,
    "searchText": null,
    "focusedOnDatasetItemIds": null,
    "qualificationExpression": null
  }
}
table dataset request
{
  "connectionInstanceId": "DEV",
  "request": {    
    "datasetId": "T_SIZES",
    "requestedBy": {
			//When called during a request checkout, this specified the identity 
              of the requester. 
              May be of use if the looked-up data is sensitive to the 
              requester's identity.
      "emailAddress": "tanya@example.com",
      "fullName": "Tanya Romero",
      "loginName": "tanya",
      "ntDomain": "NTPROD"
			//Note that "requestedBy.ntDomain" may not be available depending 
             on the actual user base.
    },
    "requestedFor": {
			//When called during a request checkout, this specified the identity 
              of the requestee. May be of use if the looked-up data is sensitive 
              to the requestee's identity.
      "emailAddress": "bob@example.com",
      "fullName": "Bob Berenstein",
      "loginName": "bob",
      "ntDomain": "NTPROD"
			//Note that "requestedFor.ntDomain" may not be available depending 
              on the actual user base.
    },
    "idFieldId": null,
			//ID of the data value field if querying a queryable dataset
    "nameFieldId": null,
			//ID of the display value field if querying a queryable dataset
    "fieldIds": ["key", "label"],
			//IDs of all the queried fields. The "idFieldId" and "nameFieldId" properties 
              can be ignored if these are specified. May provide a value for this property 
              but only for table dataset providers.
    "searchText": null,
			//A search text to filter the returned items. This is used for lookup questions, 
              which only start listing choices when an end-user starts typing the search text.
    "focusedOnDatasetItemIds": null,
			//In some instances, will give a hint at what specific items 
              it is interested in (often a single one). 
              The connector may use that as a way to not to return every item that 
              matches other criteria. If it still returns everything, will further 
              filter on its side.
    "qualificationExpression": null
			//For queryable and table dataset providers, a qualification expression 
              may be provided to filter down the results (in addition to other criteria). 
              The connector should interpret this expression as well as it can.
			//If null, this property can be ignored.
			// The structure of this property is described in 
               "Principles of the Remote Connector Service Provider Interface".
			//This property is not used with simple datasets.
  }
}
simple or queryable dataset response
{
  "response": {
    "datasetId": "T_SIZES"
    "items": [
      {"id": "S", "name": "Small"},
      {"id": "M", "name": "Medium"},
      {"id": "L", "name": "Large"} ]
  }
}

The items.id and items.name properties are always expected and correspond to either what is hard-coded in the connector (simple dataset)
or what has been specified in the request (queryable dataset).

table dataset response
{
  "response": {
    "datasetId": "T_SIZES"
    "items": [
      {"key": "S", "label": "Small"},
      {"key": "M", "label": "Medium"},
      {"key": "L", "label": "Large"} ]
  }
}

Here, the properties of the "items" property are the selection of fields specified in the request through the "fieldIds" property.

response properties
datasets.items: Array of the found items.


Was this page helpful? Yes No Submitting... Thank you
Last modified by Aaditi Lakade on Jun 01, 2022

Comments

Log in or register to comment.

Implementing the Category Service Provider Interface
Implementing the Activity Service Provider Interface
© Copyright 2013 - 2020 BMC Software, Inc.
Legal notices

Powered by Atlassian Confluence and Scroll Viewport

© Copyright 2005-2024 BMC Software, Inc. Use of this site signifies your acceptance of BMC’s Terms of Use . BMC, the BMC logo, and other BMC marks are assets of BMC Software, Inc. These trademarks are registered and may be registered in the U.S. and in other countries.