Implementing the Catalog 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.

The Catalog SPI is a subset of the remote connector SPIs that a connector can implement to support business features of BMC Digital Workplace Catalog beside the initial handshakes (descriptors, health checks) and actions (because each action is, in a way, specific to its connector).

Service Catalog Import

Capability:

com.bmc.dsm.catalog:catalogProvider

The catalog import SPI allows BMC Digital Workplace Catalog to import services i.e. catalog items or requestable offerings from external sources that support similar concepts.

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

List summaries of all importable services for a connection instance.

request

{
  "connectionInstanceId": "DEV",
  "request": {}
}

response

{
  "response": {
    "services": [
            {
                "id": "1",
                "displayId": "1",
						//(optional) identifier that can be displayed to users in some contexts
                "name": "Reset Password",
						//plain text display name of the service
                "logoUri": "reset_password.png",
						//(optional) logo URI (see the com.bmc.dsm.catalog:getContent)
                "modifiedDate": null,
						//(optional) last modified timestamp
                "excerpt": "excerpt (Reset Password)",
						//Plain text short description. It is meant to fit in space-constrained displays like tables or tiles. HTML tags will be stripped off.
                "description": "description (Reset Password)"
						//Rich text description
            }
        ]
  }
}

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

Fetches the localized details of the specified service on a connection instance. Each locale will have one version of the service details included in the "services" property of the response. In general, it is called by BMC Digital Workplace some time after listing the service summaries.

The default localization (locale = null) is a localization that will be used when no more specific locale can be matched by BMC Digital Workplace Catalog. Unsupported locales are ignored.

request

{
  "connectionInstanceId": "DEV",
  "request": {    
    "serviceId": "catalog_item_123"
  }
}

response

{
  "response": {
    "services": [
            {
                "id": "1",
                "displayId": "1",
                "name": "Reset Password",
                "logoUri": "reset_password.png",
                "modifiedDate": null,
                "excerpt": "excerpt (Reset Password)",
                "description": "description (Reset Password)",
                "cost": {
                    "amount": 5,
							//Cost amount as displayed to end-user. This may be different from the actual cost to the organization.
                    "currency": "USD"
							//3-letter ISO 4217 currency code of the cost. The whole cost will be ignored if this does not correspond to the one configured for the tenancy (USD by default).
                },
                "categoryIds": ["2","3"],
						//IDs of the categories in which this service should appear.
                "tags": ["account", "reset", "login", "password", "credentials"],
						//Array of plain text keywords. They can be used during searches.
                "fulfillment": null,
						//ignored
                "createDate": null,
						//Create datetime
		        "quantityEnabled": null,
						//indicates whether end-user can specify a quantity for this service
                "locale": null
						//ISO code of the locale of this localization of the service (mostly 2-letter e.g. "en", "de", "ja").
						//null is used to specify the default localization (the one displayed when no better localization is available).
						//Unsupported localizations will be ignored.
            }
        ]
  }
}

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

Fetches the bytes of a specified content. A "content" is anything binary and associated with some other concept, like, for instance, a service logo.

The "uri" parameter acts as a key for the content and should be constructed in a way that allows this end-point to find the content. You might have to use prefixes, paths, etc in order to concatenate information like so: catalog_items/ITEM_ID/logo.

request

{
  "connectionInstanceId": "DEV",
  "request": {    
    "uri": "reset_password.png"
  }
}

response

The binary payload of the content accompanied by an appropriate "Content-Type" header.

This end-point is an exception in the general request/response pattern of the remote connector SPI.

Implementing the Catalog Service Provider Interface

Service Catalog Import

Comments