Principles of the Remote Connector Service Provider Interface

Authentication

BMC Digital Workplace Catalog supports HTTP Basic Authentication to establish trust with the Remote Connector Server. The Authorization header will be passed in every HTTP request.

Types of End-Points

We can say there are 3 categories of end-points in a remote connector server implementation:

• remote connector server calls:
  They are the server-level end-points providing descriptions for the supported connectors and other server-level functionalities.
• action calls:
  They are end-points offering connector-specific functionalities i.e. each connector exposing a different set of different actions. They are described in the server descriptor and made available to the BMC Digital Workplace Catalog administrators as part of the process designer toolbox.
• DWP calls:
  These calls are specific to BMC Digital Workplace Catalog and support some of its features like service import or data lookups.

Payloads & Forward Compatibility

New versions of BMC Digital Workplace Catalog will add new properties to data structures, new possible values for enumerations, etc. This will happen whether a new capability is added or not. The new properties or values may be passed to all connectors whether they implement the new capability or not (often the property will be passed with a null value for connectors that do not declare the corresponding capability).

Remote connector servers should do their best to ignore these new aspects when the impact is acceptable and should factor in the possibility of future modifications of the SPIs.

Errors

In general, a remote server/connector should attempt at following HTTP conventions when it comes to HTTP status codes. If an HTTP status code has a special meaning for BMC Digital Workplace Catalog, it will be documented. For instance, returning a 404 HTTP code for an unknown dataset seems appropriate.

To communicate further context to the error, the expected JSON error format is the following:

messageType:

is any type, key or code that you would expect to be searchable in logs or documentation. If you don't have anything specific at hand, passing some constant like "ERROR" is fine.

messageText:

the main description of the problem

moreInfo:

optionally describes the issue in further details (like a stack trace, for instance).

Note that BMC Digital Workplace Catalog will often substitute default responses or behaviors to errors happening during interactions with connectors. However, it will likely not be the case for activities like data creation or actions triggered from workflows. In these occasions, error messages may be presented to administrators or other users.

SPI Data Types

Strings

Plain Text

By default, all strings should only contain plain text (i.e. no styling, links, etc).

Rich Text

Some string properties support rich text. They are described as HTML fragments.

BMC Digital Workplace Catalog uses a small subset of HTML to express rich text. Any unsupported tags is stripped off. In particular, any scripting is excluded.

Datetimes

A datetime represents the time of a specific date down to the milliseconds.
Datetimes are represented as JSON strings in long ISO 8601 UTC format:

 yyyy-MM-ddTHH:mm:ss.SSSZ.

"T" separates the day and the time of the day. "Z" is a shorthand for UTC (timezone "0").

Example:

Dates

Calendar dates are represented as JSON strings in ISO 8601 format:

Example:

Times

Time values represent the time inside a day. They are represented as JSON strings in ISO 8601 format:

HH:mm:ss

Example:

Note that time values do not carry any information about the time zone. The implicit or explicit context of their use should carry that information.

Money Amounts

Money amounts are represented as JSON strings with the following format:

Examples:

"123.45 USD"
"10500 JPY"

The currency is specified in 3-letter ISO 4217 codes.

Locales

Supported locale codes:

Qualification Expressions

Qualification expressions are data structures used as filters when BMC Digital Workplace Catalog queries "queryable" or "table" dataset items (see "Data Lookup SPI" above).

Note that BMC Digital Workplace may enhance these expressions in the future. For instance, it may introduce new operators in comparisons. The connector developers will  have to choose whether they want to error out or just ignore the elements they do not understand. At this point, BMC Digital Workplace Catalog does not have yet a mechanism to detect what aspect of the expressions is supported or not by each connector.

Grammar

Qualification expressions are composed of binary logical expressions and binary comparisons.

Compare Expressions

"CONTAINS", "NOT_CONTAINS", "STARTS_WITH" and "ENDS_WITH" are operators on strings or string fields.

Compare Operands

Simple expression

where "user" is field ID, translates to the following JSON:

Simple expression (import example)

If you need to import a qualification expression that relies on the identity of the requested-for user then you will have to leverage a CONTEXT operand.

will translate to the following JSON:

When the expression will be executed (as part of a dataset query, for instance), the ${requestedFor.loginName} variable will be replaced by the actual login name by BMC Digital Workplace Catalog before it calls the connector.

Complex expression

translates to the following JSON: