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:

Invocation Details

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 must include an operationName field in every request payload.

Invocation Settings:

Implementation Example

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);
    };
}

Request Format Examples

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

OAuth 2.0 example:

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

General Authorization example:

{
        "header": {
                "auth": { 
                        "secretsManager": {
                                "arn": "string",
                                "versionId": "string"
                        },
                        "type": "GeneralAuthorization"
                }
        },
        "payload":{
                "operationName": "AWS.SendCommand",
                "operationVersion": "1.0",
                "connectorId": "exampleId",
        …
        }
}

Default request headers

The default header fields vary depending on the authorization type. Your connector must handle both OAuth 2.0 and General Authorization request headers.

OAuth 2.0 default header:

{
    "header": {
        "auth": {
            "token": string,    // End user's Access Token
            "type": "OAuth2.0"
        }
    }
}

General Authorization default header:

{
    "header": {
        "auth": {
            "secretsManager": {
                "arn": "string",
                "versionId": "string"
            },
            "type": "GeneralAuthorization"
        }
    }
}

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.

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.

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

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

Response Header Field

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 for AWS.DiscoverDevices and AWS.SendCommand operations, as well as proactive device events (such as a light being manually turned on and off).

Example Workflow

If your C2C connector receives a DiscoverDevices request, Managed integrations for AWS IoT Device Management expects it to:

The SendConnectorEvent 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.

SendConnectorEvent API

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