Ability™ Developer Portal v23.1
Try Sandbox for free
Get a month of free access to ABB Ability™ Platform to learn and experiment!
API Playground
Play with ABB Ability™ Platform APIs (no time limits)

# ABB Ability Factory Module API

An AsyncAPI description of the ABB Ability Factory Module API.

# Endpoint details

URL Protocol Description
factory-broker:{port}/{basePath} mqtt 5.0 Allows you to connect using the MQTT protocol

# URL Variables

Name Default value Possible values Description
port 1883 1883, 8883 Secure connection (TLS) is available through port 8883.
basePath v1 Any -

# Security Requirements

Type In Name Scheme Format Description
password - - - - -

# Enrollment Generate

# PUB from/module/{module_id}/action/enrollment/generate

Generate enrollment codes for devices.

# Functionality

  • EnrollmentGenerate Behvaiour gets activated on the reception of a message from the Broker, where the topic contains the fields "action/enrollment/generate"
  • CMS API "POST /enrollments" is invoked to post the enrollment generate request to CMS
  • Upon reception of successful response from CMS, the CMS polling mechanisms is invoked at the frequency of received in configuration to get the status of the enrollment generate request.
  • Only non-pending status results are propagated on acknowledgement

# Parameters

Property Type Mandatory Description
module_id string Required Module identifier

# Message Body

Select one of the formats:

  • Auto-generated device identifiers
  • Pre-generated device identifiers

# Common

Property Type Mandatory Description
Message Payload object - -
timestamp string Required -
operationId string Required Unique identifier to track ack or to submit enrollment.get action, every action request must have different operationId
tags [string] Optional Additional meta data string array

# Auto-generated device identifiers

Property Type Mandatory Description
count integer Required Number of generated device Ids and their enrollment codes to be generated

# Pre-generated device identifiers

Property Type Mandatory Description
deviceIds [string] Required Device Ids for which enrollment codes shall be generated
registered boolean Required Flag indicating whether provided device Ids are already registered in Ability Global ID Generator

# Examples of payload

{
  "timestamp": "2020-08-10T13:36:13.187179Z",
  "operationId": "7953f9d1-52a4-4582-9412-d35c34c17298",
  "count": 15
}

{
  "tags": [
    "drive"
  ],
  "timestamp": "2020-08-10T13:36:13.187179Z",
  "operationId": "7953f9d1-52a4-4582-9412-d35c34c17298",
  "deviceIds": [
    "abbeeed3-198c-4184-9502-a10796d9e0be",
    "8c82195d-95ac-4f44-a731-8eb3c6cbce69",
    "e4eafb7a-f0c7-4112-89cf-16b7a43fc209"
  ],
  "registered": true
}

{
  "timestamp": "2020-08-10T13:36:13.187179Z",
  "operationId": "7953f9d1-52a4-4582-9412-d35c34c17298",
  "deviceIds": [
    "abbeeed3-198c-4184-9502-a10796d9e0be",
    "8c82195d-95ac-4f44-a731-8eb3c6cbce69",
    "e4eafb7a-f0c7-4112-89cf-16b7a43fc209"
  ],
  "registered": false
}

# SUB to/module/{module_id}/ack/enrollment/generate

Result of generation of enrollment codes

# Parameters

Property Type Mandatory Description
module_id string Required Module identifier

# Message Body

Result in one of the formats:

  • Success
  • Error

# Success

Property Type Mandatory Description
Message Payload object - -
tags [string] Optional Additional meta data string array
timestamp string Required -
success boolean Required Set to true
operationId string Required Unique identifier to track ack or to submit enrollment.get action, every action request must have different operationId
codes [object] Required -
codes.deviceId string - Identifier of device generated, registered or to be registered in Ability Global ID Generator. Common name in certificate.
codes.code string - Enrollment codes generated for the device Identifier
codes.status string - Value set to one of the: (new, redeemed)
conflicts [object] Optional -
conflicts.deviceId string - Identifier of device generated, registered or to be registered in Ability Global ID Generator. Common name in certificate.

# Error

Property Type Mandatory Description
Message Payload object - -
timestamp string Required -
success boolean Required Set to false
operationId string Required Unique identifier to track ack or to submit enrollment.get action, every action request must have different operationId
code string Required must contain an error code expressed as astring value from on of the enumeration: Mandatory_Parameters_Not_Exist, Invalid_Input_Parameters, Invalid_Input, Invalid_Payload_From_CMS, Null_Response_From_CMS, Cms_Connection_Failed, Cms_Bad_Request, Cms_Request_Forbidden, Cms_Input_Parameter_Not_Found, Cms_Conflicts, Cms_Internal_Server_Error, Cms_Connection_Unauthorized, Cms_Unknown_Error, No_App_Credentials_Exist, Unable_To_Generate_Token, Tpm_Communication_Failed, Tpm_Communication_Null_String, Invalid_Error, Exception
details string Optional a human-readable explanation specific to this occurrence of the problem and the CMS error Response payload, if error origin is from CMS

# Examples of payload

{
  "tags": [
    "drive"
  ],
  "timestamp": "2020-08-10T13:36:13.187179Z",
  "success": true,
  "operationId": "7953f9d1-52a4-4582-9412-d35c34c17298",
  "codes": [
    {
      "deviceId": "abbeeed3-198c-4184-9502-a10796d9e0be",
      "code": "932617102",
      "status": "new"
    },
    {
      "deviceId": "8c82195d-95ac-4f44-a731-8eb3c6cbce69",
      "code": "851993174",
      "status": "new"
    }
  ],
  "conflicts": [
    {
      "deviceId": "e4eafb7a-f0c7-4112-89cf-16b7a43fc209"
    }
  ]
}

{
  "timestamp": "2020-08-10T13:36:13.187179Z",
  "success": false,
  "operationId": "7953f9d1-52a4-4582-9412-d35c34c17298",
  "code": "Cms_Bad_Request",
  "details": "Bad Request error received from CMS, Verify request payload, CMS Response is{\"errors\":[{\"code\":\"NotFoundError\",\"title\":\"Operation (id:1bcdd677ff9bfc80c4d8) for module (id:reference-BL) not found.\"}]}"
}

# Enrollment Regenerate

# PUB from/module/{module_id}/action/enrollment/regenerate

Regenerate not redeemed enrollment codes for devices

# Parameters

Property Type Mandatory Description
module_id string Required Module identifier

# Message Body

Property Type Mandatory Description
operationId string Required Unique identifier to track ack or to submit enrollment.get action, every action request must have different operationId

# Examples of payload

{
  "operationId": "7953f9d1-52a4-4582-9412-d35c34c17298"
}

# SUB to/module/{module_id}/ack/enrollment/regenerate

Result of regeneration of enrollment codes

# Parameters

Property Type Mandatory Description
module_id string Required Module identifier

# Message Body

Result in one of the formats:

  • Success
  • Error

# Success

Property Type Mandatory Description
Message Payload object - -
tags [string] Optional Additional meta data string array
timestamp string Required -
success boolean Required Set to true
operationId string Required Unique identifier to track ack or to submit enrollment.get action, every action request must have different operationId
codes [object] Required -
codes.deviceId string - Identifier of device generated, registered or to be registered in Ability Global ID Generator. Common name in certificate.
codes.code string - Enrollment codes generated for the device Identifier
codes.status string - Value set to one of the: (new, redeemed)
conflicts [object] Optional -
conflicts.deviceId string - Identifier of device generated, registered or to be registered in Ability Global ID Generator. Common name in certificate.

# Error

Property Type Mandatory Description
Message Payload object - -
timestamp string Required -
success boolean Required Set to false
operationId string Required Unique identifier to track ack or to submit enrollment.get action, every action request must have different operationId
code string Required must contain an error code expressed as astring value from on of the enumeration: Mandatory_Parameters_Not_Exist, Invalid_Input_Parameters, Invalid_Input, Invalid_Payload_From_CMS, Null_Response_From_CMS, Cms_Connection_Failed, Cms_Bad_Request, Cms_Request_Forbidden, Cms_Input_Parameter_Not_Found, Cms_Conflicts, Cms_Internal_Server_Error, Cms_Connection_Unauthorized, Cms_Unknown_Error, No_App_Credentials_Exist, Unable_To_Generate_Token, Tpm_Communication_Failed, Tpm_Communication_Null_String, Invalid_Error, Exception
details string Optional a human-readable explanation specific to this occurrence of the problem and the CMS error Response payload, if error origin is from CMS

# Examples of payload

{
  "tags": [
    "drive"
  ],
  "timestamp": "2020-08-10T13:36:13.187179Z",
  "success": true,
  "operationId": "7953f9d1-52a4-4582-9412-d35c34c17298",
  "codes": [
    {
      "deviceId": "abbeeed3-198c-4184-9502-a10796d9e0be",
      "code": "932617102",
      "status": "new"
    },
    {
      "deviceId": "8c82195d-95ac-4f44-a731-8eb3c6cbce69",
      "code": "851993174",
      "status": "new"
    }
  ],
  "conflicts": [
    {
      "deviceId": "e4eafb7a-f0c7-4112-89cf-16b7a43fc209"
    }
  ]
}

{
  "success": false,
  "timestamp": "2020-08-10T13:36:13.187179Z",
  "code": "Cms_Bad_Request",
  "operationId": "94cd1194-e91b-416f-90ae-e3668b02e01a",
  "details": "Bad Request error received from CMS, Verify request payload, CMS Response is{\"errors\":[{\"code\":\"NotFoundError\",\"title\":\"Operation (id:1bcdd677ff9bfc80c4d8) for module (id:reference-BL) not found.\"}]}"
}

# Enrollments Get

# PUB from/module/{module_id}/action/enrollment/get

Get enrollment codes and their statuses

# Parameters

Property Type Mandatory Description
module_id string Required Module identifier

# Message Body

Property Type Mandatory Description
operationId string Required Unique identifier to track ack or to submit enrollment.get action, every action request must have different operationId
timestamp string Required -

# Examples of payload

{
  "timestamp": "2020-08-10T13:36:13.187179Z",
  "operationId": "7953f9d1-52a4-4582-9412-d35c34c17298"
}

# SUB to/module/{module_id}/ack/enrollment/get

Result of retrieval of enrollment codes and their statuses

# Parameters

Property Type Mandatory Description
module_id string Required Module identifier

# Message Body

Result in one of the formats:

  • Success
  • Error

# Success

Property Type Mandatory Description
Message Payload object - -
tags [string] Optional Additional meta data string array
timestamp string Required -
success boolean Required Set to true
operationId string Required Unique identifier to track ack or to submit enrollment.get action, every action request must have different operationId
codes [object] Required -
codes.deviceId string - Identifier of device generated, registered or to be registered in Ability Global ID Generator. Common name in certificate.
codes.code string - Enrollment codes generated for the device Identifier
codes.status string - Value set to one of the: (new, redeemed)
conflicts [object] Optional -
conflicts.deviceId string - Identifier of device generated, registered or to be registered in Ability Global ID Generator. Common name in certificate.

# Error

Property Type Mandatory Description
Message Payload object - -
timestamp string Required -
success boolean Required Set to false
operationId string Required Unique identifier to track ack or to submit enrollment.get action, every action request must have different operationId
code string Required must contain an error code expressed as astring value from on of the enumeration: Mandatory_Parameters_Not_Exist, Invalid_Input_Parameters, Invalid_Input, Invalid_Payload_From_CMS, Null_Response_From_CMS, Cms_Connection_Failed, Cms_Bad_Request, Cms_Request_Forbidden, Cms_Input_Parameter_Not_Found, Cms_Conflicts, Cms_Internal_Server_Error, Cms_Connection_Unauthorized, Cms_Unknown_Error, No_App_Credentials_Exist, Unable_To_Generate_Token, Tpm_Communication_Failed, Tpm_Communication_Null_String, Invalid_Error, Exception
details string Optional a human-readable explanation specific to this occurrence of the problem and the CMS error Response payload, if error origin is from CMS

# Examples of payload

{
  "success": true,
  "timestamp": "2020-08-10T13:36:13.187179Z",
  "operationId": "7953f9d1-52a4-4582-9412-d35c34c17298",
  "codes": [
    {
      "deviceId": "abbeeed3-198c-4184-9502-a10796d9e0be",
      "code": "932617102",
      "status": "redeemed"
    },
    {
      "deviceId": "8c82195d-95ac-4f44-a731-8eb3c6cbce69",
      "code": "851993174",
      "status": "new"
    }
  ],
  "conflicts": [
    {
      "deviceId": "e4eafb7a-f0c7-4112-89cf-16b7a43fc209"
    }
  ]
}

{
  "success": false,
  "timestamp": "2020-08-10T13:36:13.187179Z",
  "code": "Cms_Bad_Request",
  "operationId": "7953f9d1-52a4-4582-9412-d35c34c17298",
  "details": "Bad Request error received from CMS, Verify request payload, CMS Response is{\"errors\":[{\"code\":\"NotFoundError\",\"title\":\"Operation (id:1bcdd677ff9bfc80c4d8) for module (id:reference-BL) not found.\"}]}"
}

# Enrollment List

# PUB from/module/{module_id}/action/enrollment/list

Get all enrollment operations

# Parameters

Property Type Mandatory Description
module_id string Required Module identifier

# Message Body

Property Type Mandatory Description
Message Payload string - Empty payload

# SUB to/module/{module_id}/ack/enrollment/list

Result of retrieval of enrollments list

# Parameters

Property Type Mandatory Description
module_id string Required Module identifier

# Message Body

Result in one of the formats:

  • Success
  • Error

# Success

Property Type Mandatory Description
Message Payload object - -
timestamp string Required -
success boolean Required Set to true
operationIds [string] Required Unique identifier to track ack or to submit enrollment.get action, every action request must have different operationId

# Error

Property Type Mandatory Description
Message Payload object - -
timestamp string Required -
success boolean Required Set to false
code string Required must contain an error code expressed as astring value from on of the enumeration: Mandatory_Parameters_Not_Exist, Invalid_Input_Parameters, Invalid_Input, Invalid_Payload_From_CMS, Null_Response_From_CMS, Cms_Connection_Failed, Cms_Bad_Request, Cms_Request_Forbidden, Cms_Input_Parameter_Not_Found, Cms_Conflicts, Cms_Internal_Server_Error, Cms_Connection_Unauthorized, Cms_Unknown_Error, No_App_Credentials_Exist, Unable_To_Generate_Token, Tpm_Communication_Failed, Tpm_Communication_Null_String, Invalid_Error, Exception
details string Optional a human-readable explanation specific to this occurrence of the problem and the CMS error Response payload, if error origin is from CMS

# Examples of payload

{
  "success": true,
  "timestamp": "2020-08-10T13:36:13.187179Z",
  "operationId": [
    "7953f9d1-52a4-4582-9412-d35c34c17298"
  ]
}

{
  "success": false,
  "timestamp": "2020-08-10T13:36:13.187179Z",
  "code": "Cms_Input_Parameter_Not_Found",
  "details": "Not Found error received from CMS, Any of the following parameter Profile,Proxy,OperationId Not found, CMS Response is{\"errors\":[{\"code\":\"NotFoundError\"}]}"
}

# Certificate Sign

# PUB from/module/{module_id}/action/certificate/sign

Send certificate signing request (CSR)

# Functionality

  • Certificate Sign Request Behvaiour gets activated on the reception of message from the Broker, where topic contains the fields "action/certificate/get"
  • CMS API "Post /certificates" is invoked to post the certificate request to the the CMS
  • Upon successful response from CMS, certificate is sent to the module

# Parameters

Property Type Mandatory Description
module_id string Required Module identifier

# Message Body

Property Type Mandatory Description
Message Payload object - -
timestamp string Required -
deviceId string Required Identifier of device generated, registered or to be registered in Ability Global ID Generator. Common name in certificate.
csr string Required Certificate Signing Request (Base64 encoded PEM format)

# Examples of payload

{
  "timestamp": "2020-08-10T13:36:13.187179Z",
  "deviceId": "abbeeed3-198c-4184-9502-a10796d9e0be",
  "csr": "-----BEGIN CERTIFICATE REQUEST-----..."
}

# SUB to/module/{module_id}/ack/certificate/sign

Result of signing of certificate. The returned certificate has a format that is explaned in a separate article.

# Parameters

Property Type Mandatory Description
module_id string Required Module identifier

# Message Body

Result in one of the formats:

  • Success
  • Error

# Success

Property Type Mandatory Description
Message Payload object - -
success boolean Required true
timestamp string Required -
deviceId string Required Identifier of device generated, registered or to be registered in Ability Global ID Generator. Common name in certificate.
certificate string Required Signed certificate (Base64 encoded in PEM format)

# Error

Property Type Mandatory Description
Message Payload object - -
timestamp string Required -
success boolean Required Set to false
deviceId string Required Identifier of device generated, registered or to be registered in Ability Global ID Generator. Common name in certificate.
code string Required must contain an error code expressed as astring value from on of the enumeration: Mandatory_Parameters_Not_Exist, Invalid_Input_Parameters, Invalid_Input, Invalid_Payload_From_CMS, Null_Response_From_CMS, Cms_Connection_Failed, Cms_Bad_Request, Cms_Request_Forbidden, Cms_Input_Parameter_Not_Found, Cms_Conflicts, Cms_Internal_Server_Error, Cms_Connection_Unauthorized, Cms_Unknown_Error, No_App_Credentials_Exist, Unable_To_Generate_Token, Tpm_Communication_Failed, Tpm_Communication_Null_String, Invalid_Error, Exception
details string Optional a human-readable explanation specific to this occurrence of the problem and the CMS error Response payload, if error origin is from CMS

# Examples of payload

{
  "success": true,
  "timestamp": "2020-08-10T13:36:13.187179Z",
  "deviceId": "abbeeed3-198c-4184-9502-a10796d9e0be",
  "certificate": "-----BEGIN CERTIFICATE-----..."
}

{
  "success": false,
  "timestamp": "2020-08-10T13:36:13.187179Z",
  "code": "Cms_Input_Parameter_Not_Found",
  "deviceId": "abbeeed3-198c-4184-9502-a10796d9e0be",
  "details": "Not Found error received from CMS, Any of the following parameter Profile,Proxy,deviceId Not found, CMS Response{\"errors\":[{\"code\":\"deviceIDNotFound\"}]}"
}

# Certificate Get

# PUB from/module/{module_id}/action/certificate/get

Get signed certificate

# Parameters

Property Type Mandatory Description
module_id string Required Module identifier

# Message Body

Property Type Mandatory Description
Message Payload object - -
timestamp string Required -
deviceId string Required Identifier of device generated, registered or to be registered in Ability Global ID Generator. Common name in certificate.

# Examples of payload

{
  "timestamp": "2020-08-10T13:36:13.187179Z",
  "deviceId": "abbeeed3-198c-4184-9502-a10796d9e0be"
}

# SUB to/module/{module_id}/ack/certificate/get

Result of getting certificate. The returned certificate has a format that is explaned in a separate article.

# Parameters

Property Type Mandatory Description
module_id string Required Module identifier

# Message Body

Result in one of the formats:

  • Success
  • Error

# Success

Property Type Mandatory Description
Message Payload object - -
success boolean Required true
timestamp string Required Any
deviceId string Required Identifier of device generated, registered or to be registered in Ability Global ID Generator. Common name in certificate.
certificate string Required Signed certificate (Base64 encoded in PEM format)

# Error

Property Type Mandatory Description
Message Payload object - -
timestamp string Required -
success boolean Required Set to false
deviceId string Required Identifier of device generated, registered or to be registered in Ability Global ID Generator. Common name in certificate.
code string Required must contain an error code expressed as astring value from on of the enumeration: Mandatory_Parameters_Not_Exist, Invalid_Input_Parameters, Invalid_Input, Invalid_Payload_From_CMS, Null_Response_From_CMS, Cms_Connection_Failed, Cms_Bad_Request, Cms_Request_Forbidden, Cms_Input_Parameter_Not_Found, Cms_Conflicts, Cms_Internal_Server_Error, Cms_Connection_Unauthorized, Cms_Unknown_Error, No_App_Credentials_Exist, Unable_To_Generate_Token, Tpm_Communication_Failed, Tpm_Communication_Null_String, Invalid_Error, Exception
details string Optional a human-readable explanation specific to this occurrence of the problem and the CMS error Response payload, if error origin is from CMS

# Examples of payload

{
  "success": true,
  "timestamp": "2020-08-10T13:36:13.187179Z",
  "deviceId": "abbeeed3-198c-4184-9502-a10796d9e0be",
  "certificate": "-----BEGIN CERTIFICATE-----..."
}

{
  "success": false,
  "timestamp": "2020-08-10T13:36:13.187179Z",
  "code": "Cms_Input_Parameter_Not_Found",
  "deviceId": "abbeeed3-198c-4184-9502-a10796d9e0be",
  "details": "Not Found error received from CMS, Any of the following parameter Profile,Proxy,deviceId Not found, CMS Response{\"errors\":[{\"code\":\"deviceIDNotFound\"}]}"
}

# Error Codes Description

The following table explains all possible error codes and their short descriptions.

Error Code Error Description
Mandatory_Parameters_Not_Exist Mandatory parameters expected is not present in module's request Ex: operationID
Invalid_Input_Parameters Invalid input parameters in module's request Ex: count is out of range(-1)
Invalid_Payload_From_CMS Invalid input payload received from CMS Ex:Response is null
Invalid_Input Invalid input format in module's request, Ex: Device ID is not in UUID format
Exception Exception occured while processing the module request Ex:Http request failed
Null_Response_From_CMS CMS sent null response payload
Cms_Connection_Failed Failed to make CMS connection Ex:http request timed out
Cms_Bad_Request Bad Request error received from CMS Ex: Device ID is invalid
Cms_Request_Forbidden Request Forbidden error received from CMS
Cms_Input_Parameter_Not_Found Not Found error received from CMS, Ex:Operation ID is not present
Cms_Conflicts Conflicts error received from CMS
Cms_Internal_Server_Error Internal Server Error received from CMS
Cms_Connection_Unauthorized Connection Unauthorized Error received from CMS
Cms_Unknown_Error Unknown Error received from CMS
No_App_Credentials_Exist No App credentials exist in the proxy due to failure in TPM NV RAM
Unable_To_Generate_Token Token Generation failed with the app credentials
Invalid_Error
Tpm_Communication_Failed Failed to cmmunicate to SecStore service, Ex:rpc file not accessible or doesn't exist
Tpm_Communication_Null_String credentials stored in TPM might have got erased
Tpm_Communication_Successful Successful in fetching credentials from TPM

# Example Errors

Enrollment Code Generation

Error Code Reason
Invalid_Input_Parameters Module payload received contains un desired count value {"timestamp": 1234, "operationId": "7953f9d1-52a4-4582-9412-d35c34c17298", "count": -1} Module payload received contains count and device ID's{"timestamp": 1234, "operationId": "7953f9d1-52a4-4582-9412-d35c34c17298", "count": 1,"deviceIds": ["abbeeed3-198c-184-9502-a10796d9e0be","8c82195d-95ac-4f44-a731-8eb3c6cbce69","e4eafb7a-f0c7-4112-89cf-16b7a43fc209" ],"registered": true}
Mandatory_Parameters_Not_Exist Module payload received do not contain count or device ID's {"timestamp": 1234, "operationId": "7953f9d1-52a4-4582-9412-d35c34c17298"}
Invalid_Input Module payload received contains count as string value {"timestamp": 1234, "operationId": "7953f9d1-52a4-4582-9412-d35c34c17298", "count": "abc"}
Last updated: 4/4/2022, 9:59:57 AM

← Overview →

Feedback