APIs Device to Cloud One M2 M FlexContainer

A flexContainer (resourceType = 28) represents a customizable container for data instances that can be extended with so-called custom attributes. For this, a flexContainer is a template and is never directly created but only as a specialization of it. This is a similar concept as the mgmtObj resource that is also not directly instantiated. This is a similar concept as “inheritance by extending” in programming.

flexContainer specializations need to be separately defined. They may have their own set of custom attributes and/or child resources.

All specializations have the same resource type (ty) attribute set to 28, but are distinguished by an entry in the containerDefinition (cnd) attribute. See oneM2M Data Dictionary for examples.

This specification of the flexContainer resource adds a draft extension, namely the support for flexContainerInstance resources. This means that this specification might change in the future.

Supported child resources

Child Resources Type	Multiplicity	Description
flexContainer	0..n	A `flexContainer` represents a customizable container for data instances that can be extended with so-called custom attributes.

Universal and common attributes

Name	Full Name	Type	Multiplicity	Mode
ty	resourceType	m2m:resourceType / integer	1	RO
ri	resourceID	m2m:ID / string	1	RO
rn	resourceName	string	1	WO
pi	parentID	m2m:ID / string	1	RO
lbl	labels	m2m:labels / list of string	0..1(L)	RW
acpi	accessControlPolicyIDs	m2m:acpType / list of resourceID	0..1(L)	RW
ct	creationTime	m2m:timestamp	1	RO
lt	lastModifiedTime	m2m:timestamp	1	RO
	stateTag		1	RW
	announcedAttribute		0..1(L)	RW
	announceSyncType		0..1	RW
	holder		0..1	RW
	stateTag		1	RO

Mode: RW = Read/Write, RO = Read Only, WO = Write Once

Resource specific attributes

Name	Full Name	Multiplicity	Mode	Create	Update
cnd	containerDefinition	1	WO	M	NP
cs	contentSize	0..1	RW	O	O
nl	nodeLink	0..1	RW	O	O
	customAttribute	0..n	RW	O	O

Mode: RW = Read/Write, RO = Read Only, WO = Write Once

Request Optionality: NP = not provisioned, O = optional, M = Mandatory

Attribute: cnd (containerDefinition)

This attribute contains an identifier reference (URI) to the flexContainer schema definition which shall be used by the CSE to validate the syntax of the flexContainer resource. This URI may refer to one of the oneM2M flexContainer definitions specified in one of oneM2M’s specifications, but can also be a proprietary definitions.

Attribute: cs (contentSize)

Sum of the size in bytes of all of the custom attributes.

** Attribute: nl (nodeLink)**

The resource identifier of a node resource that stores the node specific information of the NoDN on which the interworked service represented by this flexContainer resource resides.

Attribute: customAttribute

One or more specialization-specific attribute(s). Name and data type defined in each specialization of flexContainer resource.

FlexContainer “nodeProvisioningRequest”

This nodeProvisioningRequest (dtiot:noPRt) resource type is a specialization of flexContainer, and it is located under an container resource. It represents a request containing a list of nodes to be provisioned in IoT Hub, enabling the respective devices to communicate with the IoT Hub afterwards. The requests will be processed by a device provisioning AE, that integrates with the underlying device communication layer to provision there the appropriate device information.

Custom Attributes:

Name	Full Name	Type	Multiplicity	Mode
opern	operation	dtiot:enumNodeProvisioningOperation	1	RW
reqLt	requestList	list of dtiot:nodeProvisioningData	1	RW

Attribute: opern (operation)

Identifies the provisioning operation to be applied:

1= provision
2= remove

Attribute: reqLt (requestList)

The list of devices for which the provisioning operation will be applied, including the required information depending of the operation |

Attribute type: dtiot:nodeProvisioningData

Name	Full Name	Type	Multiplicity	Mode
ni	nodeID	xs:string	1	RW
noRNe	nodeResourceName	xs:string	0..1	RW
ICCID	ICCID	xs:string	0..1	RW
profe	profile	xs:string	0..1	RW

Attribute: ni (nodeID)

This is the main identifier of the node to be provisioned and it will be used as the nodeID of the node that will be created as part of the provisioning processing. Thus the value shall be a valid nodeID string in one of the following formats: urn:gsma:imei:<imei> or urn:x-dtiot:dev:sn:<string with the serial number from device>

Attribute: noRNe (nodeResourceName)

Name of the node resource that will be created for the device. Used only if the operation is provision.

Attribute: ICCID

ICCID of the SIM Card that will be used by the device. Used only if the operation is provision and even in this case that is an optional attribute.

Attribute: profe (profile)

The profile of the device to be provisionied. It shall be one of

SCS-UDP
SCS-lwM2M
SCS-MQTT

Used only if the operation is provision

Example JSON:

The following is an example JSON encoding of a flexContainer that stores the device provisioning requests. The first part are the common and universal attributes if the resource, and at the end it the actual payload data (aka “custom attributes” of the flexContainer).

{
    "dtiot:noPRt": {
        "cnd": "com.telekom.iot.orchestrator.nodeProvisioningRequest",
        "cr": "A-Customer-Management-AE",
        "cs": 16,
        "ct": "20200313T141200,890746",
        "lt": "20200313T141200,890746",
        "pi": "5e7ded3794abce201c0029f9",
        "ri": "890990770660",
        "rn": "myProvisioningRequest",
        "st": 0,
        "ty": 28,
 
        "operation": 1,
        "requestList": [
            {
                "nodeID" : "urn:gsma:imei:35193454678897",
                "nodeResourceName" : "device001",
                "ICCID" : "89882280000004495285",
                "profile" : "SCS-lwM2M"
            },
            {
                "nodeID" : "urn:gsma:imei:35193454679876",
                "nodeResourceName" : "device002",
                "profile" : "SCS-UDP"
            },
            {
                "nodeID" : "urn:gsma:imei:35193454673391",
                "nodeResourceName" : "device003",
                "ICCID" : "89882280000004495345",
                "profile" : "SCS-lwM2M"
            }
            // D2C request proposal
            ,{
                "nodeID" : "urn:gsma:imei:35193454673391",
                "nodeResourceName" : "device003",
                "lbl" : [ "profile:SCS-lwM2M", "ICCID:89882280000004495345", ... ],
                "credentials": [ "psk-id:...", "psk:....", "cert:...", ... ], // option 1
                "credentials": "<base64string>", // option 2
            }
        ],
    }
}

FlexContainer “provisioningRequestResponse”

This resource type (dtiot:prRRe) is a specialization of flexContainer, and it is located under an container resource. It represents a response to a request containing a list of devices to be provisioned in IoT Hub, enabling their communication afterwards. A device provisioning AE, that processes device provisioning requests shall create resources of this specialization to indicate the results of the provisioning processing.

Name	Full Name	Type	Multiplicity	Mode
reqRD	requestResourceID	xs:string	1	RW
resSs	responseStatus	dtiot:enumNodeProvisioningResponseStatus	1	RW
geEMe	generalErrorMessage	xs:string	0..1	RW
inEMs	individualErrorMessages	list of dtiot:provisioningErrorMessage	0..1	RW

Attribute: reqRD (requestResourceID)

The resourceID of the request, whose results are contained in the resource. Since the original request is deleted after it is processed it won’t be possible to use this attribute to retrieve the original request. That means the requestor shall keep the resourceID of the created request and use it as a correlation ID to identify the respective response.

Attribute: resSs (responseStatus)

Final processing status of the provisioning request.

Attribute: geEMe (generalErrorMessage)

Error message regarding the processing of the whole request. Only present when responseStatus is completedWithErrors or rejected.

Attribute: inEMs (individualErrorMessages)

Error message for each individual device not successfully processed. Only present if there is any error message.

Attribute Type: dtiot:enumNodeProvisioningResponseStatus

1 = completed
2 = completedWithErrors
3 = rejected

Attribute Type: dtiot:provisioningErrorMessage

Name	Full Name	Type	Multiplicity	Mode
nodID	nodeID	xs:string	1	RW
errMe	errorMessage	xs:string	1	RW

Attribute: nodeID

This is the main identifier of the device that should have been provisioned

Attribute: errorMessage

Description of the error occurred in the processing of the provisioning of that device

JSON representation example:

{
    "dtiot:prRRe": {
        "cnd": "com.telekom.iot.orchestrator.provisioningRequestResponse",
        "cr": "deviceProvisioning-AE",
        "cs": 16,
        "ct": "20200313T141200,890746",
        "lt": "20200313T141200,890746",
        "pi": "5e7ded3794abce201c0029f9",
        "ri": "61eac0cf71ad087179702f7b",
        "rn": "responseToRequest-61ba162b1543fc25abe8acea",
        "st": 0,
        "ty": 28,
 
        "requestResourceID": "61ba162b1543fc25abe8acea",
        "responseStatus" : 2,
        "generalErrorMessage" : "Total to be provisioned: 100; Successfully processed: 98; Errors: 2"
        "individualErrorMessages": [
            {
                "nodeID" : "urn:gsma:imei:35193454678897",
                "errorMessage" : "device profile not supported"
            },
            {
                "nodeID" : "urn:gsma:imei:35193454679876",
                "errorMessage" : "device with same nodeID already exists"
            },
        ],
    }
}

FlexContainer “DeviceGroup”

Name	Full Name	Type	Multiplicity	Mode
nodes	nodes	array(String)	0..1(L)	RW
applicationEntities	applicationEntities	array(String)	0..1(L)	RW

Attribute: nodes

List of nodes .

Attribute: applicationEntities

List of application entities AE .

APIs Device to Cloud One M2 M FlexContainer

Supported child resources Copied!

Universal and common attributes Copied!

Resource specific attributes Copied!

FlexContainer “nodeProvisioningRequest” Copied!