Developing Remote Connector Servers and Connectors
Tip
Click here to download the JSON (JavaScript Object Notation) snippets included in these topics, and customize them to use according to your requirements.
Developing an empty Remote Connector Server
To develop a Remote Connector Server, you must implement a set of REST APIs that form a service provider interface (SPI) that BMC Digital Workplace Catalog expects. Depending on its capabilities, different parts of the SPI need to be implemented. A Remote Connector Server does not need to implement all the SPIs unless a use case requires all the SPIs.
Server descriptor
Use the server descriptor to provide the metadata necessary to make BMC Digital Workplace Catalog aware of the capabilities of that Remote Connector Server. For instance, it can describe the available connectors, their specific capabilities, and the actions they provide.
GET /rcf/descriptor | |
---|---|
Success | HTTP status: 200 Payload example (for an empty Remote Connector Server):
|
Server Health Check
The server health check end-point is primarily used by BMC Digital Workplace Catalog to validate the registration of a server.
GET /rcf/health | |
---|---|
Success | HTTP status: 200 Payload (plain text): OK |
Developing connectors
A connector is a component of a remote connector server, which implements the connector SPI for a type of integration target like a specific product or service. Thanks to connection instance, that same component is able to give access to different instances of the same product or service.
The responsibility of a connector implementation is to translate the data and concepts between BMC Digital Workplace Catalog and the integration target.
Connector Descriptor
{
"connectors": [
{
"name": "My Connector",
//Display name of the connector
"version": "1.0",
//Display version provided for supportability
"type": "com.example.my.connector",
//Identifies the connector and used as a scope to concepts like actions within process definitions
"path": "myconnector",
//Path of the connector; used as a prefix for all the end-point paths (actions and custom calls).
//"rcf" is not allowed; it is used for built-in end-points of the remote server
"capabilities": [...],
//List of tags which declares the general capabilities of this connector i.e. "does it support catalog import?", "does it support data lookups in questionnaires?", etc
"activeConnectionInstances": [...],
//List of the connection instances available to Digital Workplace administrators
"actions": [...]
//List of the connector actions available to administrators to use in workflows
}
]
}
Developing a Connection Instance for a Connector
Connection instances allow to leverage the same remote connector against different integration target. For instance, the same running instance of a remote connector could propose a "Staging" and a "Production" connection instance. BMC Digital Workplace Catalog administrators are then free to leverage one of these in her workflows or in her other use cases.
Each connector needs at least one connection instance.
Within BMC Digital Workplace Catalog, there is also a concept of "connection". In the context of the Remote Connector Server, a BMC Digital Workplace Catalog connection references one Remote Connector Server connection instance.
Connection Instance Descriptor
{
"connectors": [
{
...
"activeConnectionInstances": [
{
"id": "DEV",
"name": "Development"
},
{
"id": "PROD",
"name": "Production"
}
],
...
}
]
}
Connection Instance Health Check
The connection health check is a custom call that allows BMC Digital Workplace Catalog to validate that a connection instance is healthy down to the integration target.
In general, it should be implemented by connectors using relatively cheap calls to the integration targets. It should, at least, validate that:
- It can reach the integration target associated with the specified connection instance ID
- It can authenticate.
Other checks can also be implemented.
POST ${connector_path}/com.bmc.dsm.catalog:checkHealth | |
---|---|
request |
|
successful connection | HTTP status: 200 Payload:
|
failed connection | HTTP status: 200 Payload:
|
Response properties:
Property | |||||||
---|---|---|---|---|---|---|---|
status |
| ||||||
message | Provides additional information like error messages to BMC Digital Workplace Catalog. | ||||||
messages | Additional and informational messages to communicate to the BMC Digital Workplace Catalog administrator. While "message" refers to the overall status of the health check, "messages" can bring any information destined to improve the supportability of the integration. The severity of these "messages" will not be taken into account by BMC Digital Workplace Catalog to assess the connectivity. Instead, they will be displayed in the user interface. Here are examples of interesting information:
|
Developing Connector Actions
Actions are activities that can be executed from a service fulfillment workflow. After registering the Remote Connector Server, it will be made available to BMC Digital Workplace Catalog administrators in the process designer.
{
"connectors": [
{
...
"actions": [
{
"name": "submitOrder",
"displayName": "Submit Order",
"path": "order_product",
"inputs": [ ... ],
"outputs": [ ... ]
},
...
]
},
...
]
}
Action Descriptor
Inputs
An action inputs are described by a flat list of input descriptors.
"inputs": [
{ "name": "recipient", "type": "String", "required": true },
{ "name": "quantity", "type": "Integer" } // "required" is false by default
]
Data Types of Action Inputs
Action Input Data Type | JSON representation |
---|---|
String | String Any value of a process can be assigned to a String action input. Complex objects will be serialized to their JSON representation before being passed |
Integer | Number (integer) |
Double | Number |
DateTime | String with ISO 8601 format. |
Object | Object All process values can be passed to an Object input and they will have their usual representation. Complex objects will be passed as JSON objects. |
Boolean | Boolean |
Outputs
These are the results of the action. The only supported data type is Object
, which means that anything can be returned by the connector and it will be made available in the process without conversion.
Example:
"outputs": [
{"name": "message", "type": "Object"}
]
Action SPI
Each action gets its own end-point with a similar contract.
| |
---|---|
example: /com.example.myconnector/order_product | |
request |
|
response |
|
Comments
Log in or register to comment.