Implement C2C connector interface operations

Managed integrations for AWS IoT Device Management defines four operations your AWS Lambda must handle to qualify as a connector. Your C2C connector must implement each of the following operations:

1. AWS.ActivateUser - Managed integrations for AWS IoT Device Management service calls this API to retrieve a globally unique user identifier associated with the provided OAuth2.0 token. This operation can optionally be used to perform any additional requirements for the account linking process.

2. AWS.DiscoverDevices - managed integrations for AWS IoT Device Management service calls this API to your connector for discovering user’s devices

3. AWS.SendCommand - managed integrations for AWS IoT Device Management service calls this API to your connector for sending commands for user’s devices

4. AWS.DeactivateUser - managed integrations for AWS IoT Device Management service calls this API to your connector for deactivating user’s access token to delink in your authorization server.

Managed integrations for AWS IoT Device Management always invokes the Lambda function with a JSON string payload through the AWS Lambda invokeFunction action. Request operations are must include an operationName field in every request payload. For more, see Invoke in AWS Lambda API Reference.

Each invocation timeout is set to two seconds, and if the invocation failes it will be retried five times.

The Lambda you implement for your connector will parse an operationName from the request payload, and implement the corresponding functionality to map to the third-party cloud:

public ConnectorResponse handleRequest(final ConnectorRequest request) 
        throws OperationFailedException {
    Operation operation;
    try {
        operation = Operation.valueOf(request.payload().operationName());
    } catch (IllegalArgumentException ex) {
        throw new ValidationException(
           "Unknown operation '%s'".formatted(request.payload().operationName()), 
           ex
        );
    }

    return switch (operation) {
        case ActivateUser -> activateUserManager.activateUser(request);
        case DiscoverDevices -> deviceDiscoveryManager.listDevices(request);
        case SendCommand -> sendCommandManager.sendCommand(request);
        case DeactivateUser -> deactivateUser.deactivateUser(request);
    };
}

Note

The developer of the connector must implement the activateUserManager.activateUser(request), deviceDiscoveryManager.listDevices(request), sendCommandManager.sendCommand(request), and deactivateUser.deactivateUser operations listed in the preceding example.

The following example details a generic connector request from managed integrations, in which common fields to every required interface are present. From the example, you can see there is both a request header and request payload. Request headers are common throughout every operation interface.

{
 	"header": {
 		"auth": { 
 			"token": “ashriu32yr97feqy7afsaf”, 
 			"type": “OAuth2.0"
 		}
 	},
 	"payload":{
 		"operationName": "AWS.SendCommand",
 		"operationVersion": "1.0",
 		"connectorId": “exampleId”,
 	…
 	}
}

Default request headers

The default header fields are as follows.

{
    "header": {
        "auth": {                 
            "token": string,    // end user's Access Token
            "type": ENUM ["OAuth2.0"], 
        }
    }
}

Any API hosted by a connector must process the following header parameters:

Default headers and fields

Field	Required/Optional	Description
header:auth	Yes	Authorization information provided by the C2C connector builder during their connector registration.
header:auth:token	Yes	Authorization token of user generated by the third-party cloud provider and linked to connectorAssociationID.
header:auth:type	Yes	The type of authorization needed.

Note

All requests to your connector will have the end user's access token attached. You can assume that account linking between the end user and the managed integrations customer has already happened.

Request payload

In addition to common headers, every request will have a payload. While this payload will have unique fields for every operation type, each payload has a set of default fields that will always be present.

Request payload fields:

• operationName: The operation of a given request, equal to one of the following values: AWS.ActivateUser, AWS.SendCommand, AWS.DiscoverDevices, AWS.DeactivateUser.

• operationVersion: Every operation is versioned to allow its evolution over time and providing stable interface definition for third-party connectors. managed integrations passes a version field in the payload of all requests.

• connectorId: The ID of the connector in which the request has been sent to.

Default response headers

Every operation will respond with an ACK to managed integrations for AWS IoT Device Management that confirms your C2C connector has received the request and begun to process it. The following is a generic example of said response:

{
 	"header":{
 		"responseCode": 200 
 	},
 	"payload":{
 		"responseMessage": “Example response!”
 	}
}

Every operation response must have the following common header:

{
    "header": {
        "responseCode": Integer
    }
}

The following table lists the default response header:

Default response header and field

Field	Required/Optional	Comment
header:responseCode	Yes	ENUM of values that indicate the execution status of the request.

Throughout the various Connector Interfaces and API schemas described in this document there is a responseMessage or Message field. This is an optional field used for the C2C connector Lambda to respond with any context regarding the request and its execution. Preferably, any errors resulting in a status code other than 200 should include a message value describing the error.

Respond to C2C connector operation requests with the SendConnectorEvent API

Managed integrations for AWS IoT Device Management expects your connector to behave asynchronously for every AWS.SendCommand and AWS.DiscoverDevices operation. This means that the initial response to these operations, simply “acknowledges” that your C2C connector has received the request.

Using the SendConnectorEvent API, your connector is expected to send the event types from the list below to for AWS.DiscoverDevices and AWS.SendCommand operations, as well as proactive device events (such as a light being manually turned on and off). To read a detailed explanation of these event types and their use cases, see Implement the AWS.DiscoverDevices operation, Implement the AWS.SendCommand operation, and Send device events with the SendConnectorEvent API.

For example, if your C2C connector receives a DiscoverDevices request, managed integrations for AWS IoT Device Management expects it to respond synchronously with the response format defined above. Then, you must invoke the SendConnectorEventAPI with the request structure defined in Implement the AWS.DiscoverDevices operation, for a DEVICE_DISCOVERY event. The SendConnectorEvent on API call can take place anywhere you have access to your C2C connector Lambda AWS account credentials. The device discovery flow is not successful until managed integrations for AWS IoT Device Management receives this event.

Note

Alternatively, the SendConnectorEvent API call can occur before the C2C connector Lambda invocation response if necessary. However, this flow contradicts the asynchronous model for software development.

• SendConnectorEvent - Your connector calls this managed integrations for AWS IoT Device Management API to send device events to managed integrations for AWS IoT Device Management. Only 3 types of events accepted by managed integrations:

  • "DEVICE_DISCOVERY" – This event operation shall be used to send list of discovered devices within third-party cloud for a specific access token.

  • "DEVICE_COMMAND_RESPONSE" – This event operation shall be used to send a specific device event as a result of command execution.

  • "DEVICE_EVENT" – This event operation shall be used for any event that originates from the device which is not the direct result of a user-based command. This can serve as a general event type to proactively report device state changes or notifications.