Developing Remote Connector Servers and Connectors

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.

{
  "connectors": []
}

Server Health Check

The server health check end-point is primarily used by BMC Digital Workplace Catalog to validate the registration of a server.

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.

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

{
  "connectionInstanceId" : "DEV",
  "response" : {
    "status": "CONNECTION_SUCCESS",
    "message": null,
    "messages": [
      {
        "severity": "INFO",
            // INFO, WARNING or ERROR
        "message": "connected to v2.5"
      }
    ]
  }
}

{
  "connectionInstanceId" : "DEV",
  "response" : {
    "status": "CONNECTION_FAILURE",
    "message": "unknown error"
  }
}

Response properties:

CONNECTION_SUCCESS

CONNECTION_FAILURE

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

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.

{
  "connectionInstanceId": "DEV",
  "inputs": {    
    "recipient": "Bob",
    "quantity": 1,
    "productId": "93820"
  }
}

{
  "outputs": {
    "orderId": "987656500",
    "ETA": "2099-12-25T00:00:00",
    "shippingAddress": {
      "state": "CA",
      "city": "Santa Clara"
    }
  }
}