Callback notifications for resources and lifecycle events

The callback notification API allows the client application to receive the following information from IMPACT IoT:

Operations on resources
Life cycle events
Observed resources

IMPACT IoT sends the requested information in the form of asynchronous notifications on the callback URL of the client application.

Callback notifications describes the structure of the callback notification API.

Table 1. Callback notifications
Title	Callback notifications
URL	https://<netApp_callback_url>
Method	POST
Content-Type	application/json
URL Params	None
Data Params	The following are the data parameters: serialNumber:[string]: Specifies the unique endpoint ID of the device. timestamp:[integer]: Specifies the IMPACT processing time (number of milliseconds since 1970). subscriptionId:[string]: Specifies the subscription correlator generated by IMPACT on acknowledgement of the subscription request. resourcePath:[string]: Specifies the path of the resource observed within the scope of a subscription. This parameter is mandatory inside a resources element. The resourcePath is obtained in case of data policy notification. For example, Time resource has the value sent by the device which is appended with three zeroes. Example: `resourcePath":"3/0/13",*"value":"1543422580000""` value:[string]: Specifies the payload of the resource subject to observation (base64-encoded in case of binary content). make:[string]: Specifies the name of the device manufacturer. model:[string]: Specifies the device model. firmwareVersion:[string]: Specifies the current firmware version of the device. groupName:[string]: Specifies the IMPACT group to which the device pertains to. imsi:[string]: Specifies the IMSI of the device. address:[string]: Specifies the address of the device. freeFormAddress:[string]: Specifies the free form address or identifier of the device. tags:[string]: Specifies the list of device tags. requestId:[string]: Specifies the request correlator as generated by IMPACT on acknowledgement of the request. creationDate:[string]: Specifies the date on which the device was created (registered) on the system. resources:[composite]: Specifies the list of resources supported by the device with current known values or resources requested within the scope of a READ command. None in case of Write, Delete, and Execute commands, as these operations do not return any resource value. result:[complex]: Specifies the final result codes and reason of request on device ( READ, Write, Delete, and Execute). code:[ string]: Specifies the main result code of the original request or operation, set by IMPACT system. Valid values are: 0-Success 1-Failure 2-Warning subCode:[string]: Specifies the result code specified by the device protocol. In case of internal error, it specifies the result code generated by IMPACT. Value of the subCode depends on the device protocol, hence it is protocol specific. Default value of subCode if 0, if undetermined. reason:[string]: Specifies the error message.
Success Code	Response Code: 200
Error Code	400: Bad request 401: Unauthorized 500: Internal network application error
Sample Call	Curl: curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: Basic YXJhdmludGg6VGVzdEAxMjM=' -d '{"reports":[{"serialNumber":"352253064335283","timestamp":1485339813341,"subscriptionId":"e7a570f4-a175-4f2a-8080-d44400065ada","resourcePath":"vehicle/0/batteryVoltage","value":"12.6"},{"serialNumber":"352253064335283","timestamp":1485339813347,"subscriptionId":"e7a570f4-a175-4f2a-8080-d44400065ada","resourcePath":"location/0/latitude","value":"13.78631"},{"serialNumber":"352253064335283","timestamp":1485339813356,"subscriptionId":"e7a570f4-a175-4f2a-8080-d44400065ada","resourcePath":"location/0/longitude","value":"100.54647"},{"serialNumber":"352253064335283","timestamp":1485339813377,"subscriptionId":"e7a570f4-a175-4f2a-8080-d44400065ada","resourcePath":"vehicle/0/rpm","value":"0.0"},{"serialNumber":"352253064335283","timestamp":1485339813397,"subscriptionId":"e7a570f4-a175-4f2a-8080-d44400065ada","resourcePath":"vehicle/0/speed","value":"0.0"},{"serialNumber":"352253064335283","timestamp":1485339813417,"subscriptionId":"e7a570f4-a175-4f2a-8080-d44400065ada","resourcePath":"vehicle/0/milesTravelled","value":"1015.0"},{"serialNumber":"352253064335283","timestamp":1485339813438,"subscriptionId":"e7a570f4-a175-4f2a-8080-d44400065ada","resourcePath":"vehicle/0/fuelLevel","value":"0.0"}],"registrations":[],"deregistrations":[],"updates":[],"expirations":[],"responses":[]}' '<http://CallbackURL>'
Notes	None

IMPACT allows controlling the payload size for the Application callback notifications. The payload size is set at a system level and can be overridden by the Application at registration.

For controlling the payload size at the user level, the user can configure the payload size at the time of registration using the registration API using the optional payloadSize field, in Bytes.

For example:

PUT /m2m/applications/registration HTTP/1.1
Host: devlwm2m-edge-01
Authorization: Basic ZHRhZzpkdGFn
Content-Type: application/json
Content-Length: 153
{
"headers": 
{"authorization": "Basic ZGVtbzpkZW1v"}
,
"url": "http://10.75.74.104:8503",
"payloadSize": 40000
}

Note: The user with the admin permissions can configure the field at the system level using the fieldmaxBatchDataLength present in the values.yaml of impact-dc helm chart.

For more information, see the section Sample values.yaml file in the Installation Guide.

Oversized uplink payloads

In cases where the payload cannot be segmented, for example, due to a large single encrypted uplink packet, the application may receive a payload greater than the maximum payload size.

Precendence order

The payload size from the API (user level) will get precedence over the system level limit. If the payloadSize is not provided for a user, IMPACT will use the system level value for the user.