Understanding Payload Structure for Custom Events
The IoT service API allows the admin to initiate bulk IB record updates to send the last ping time or any real-time data of all connected devices to the user daily. To facilitate this, the admin can configure the IoT Setup > Map to Object tab for IoT Events to build custom events that map data from an external system to specified fields of the IB record. In the JSON request:
• For a single record update, specify the parameters in the CustomEvent section.
• For multiple record updates, specify the parameters in the customEvents section.
 |
In a single payload, you can successfully process 200 records with five fields being updated per record. The total number of records processed in a single payload request can be higher or lower than the recommended 200 count. It depends on the following factors:
• Number of custom triggers executed on save
• Number of fields being updated per record
• Total record count on the object when performing an update
• Type of org instance
|
The following is the request payload structure for updating a single record:
{
"Asset": {
"ThingName": "<value>",
"ProductName": "<value>",
"InstalledProductName": "<value>",
"SerialNumber": "<value>",
"ExternalId": "<value>"
},
"Event": {
"Subject": <value>,
"Description": <value>,
"Priority": <value>,
"EventTime": <value>,
"AlertType": <value>,
"Property": <value>,
"ServiceSessionID": <value>
},
"Custom Event": {
"Subject": <value>,
"Country": <value>,
"AccountNumber": <value>,
"Location": <value>,
"City": <value>,
"ModifiedTime": <value>,
},
"customEvents":[],
"Others": {
"<Optional field1>": value1,
"<Optional field2>": value2,
...
"<Optional fieldN>": valueN,
}
"Asset": {
"ThingName": "<value>",
"ProductName": "<value>",
"InstalledProductName": "<value>",
"SerialNumber": "<value>",
"ExternalId": "<value>"
},
"Event": {
"Subject": <value>,
"Description": <value>,
"Priority": <value>,
"EventTime": <value>,
"AlertType": <value>,
"Property": <value>,
"ServiceSessionID": <value>
},
"Custom Event": {
"Subject": <value>,
"Country": <value>,
"AccountNumber": <value>,
"Location": <value>,
"City": <value>,
"ModifiedTime": <value>,
},
"customEvents":[],
"Others": {
"<Optional field1>": value1,
"<Optional field2>": value2,
...
"<Optional fieldN>": valueN,
}
In the JSON request:
• The default fields are case-insensitive to minimize errors
• All default fields are optional
• The Others group is optional and is used to send extra parameters required to apply the Installed Product Lookup configuration.
The default field details are explained in the following table.
Asset Group
|
Field
|
Required/Optional
|
Description
|
||
|---|---|---|---|---|
|
ThingName
|
Optional
|
Unique identifier for a connected IB that is invoking the event.
|
||
|
ProductName
|
Optional
|
Name of product type of the asset.
|
||
|
InstalledProductName
|
Optional
|
Name of a specific instance of a product at a location.
|
||
|
SerialNumber
|
Optional
|
Serial number of the installed product.
|
||
|
ExternalId
|
Optional
|
External Id of the installed product.
|
Currently, no out-of-the-box functionality is associated with the Asset group, except for including the ThingName parameter value in the description field of a case, work order, or service request. It is introduced to collect specific data related to the asset for future/custom implementations.
Event Group
The standard IoT events use information sent in this group to set various fields in the records created as a result of the event request. Refer to the following sections to learn about the field mappings used for each event.
|
Field
|
Required/Optional
|
Description
|
|---|---|---|
|
Subject
|
Optional
|
IoT event detail that will be saved as the target record's subject
|
|
Description
|
Optional
|
Detailed message about the IoT event
|
|
Priority
|
Optional
|
Priority level for the IoT event (takes numeric value)
|
|
EventTime
|
Optional
|
Date and Time of the IoT event occurrence. The value should be in GMT. See Salesforce date and date time format.
|
|
AlertType
|
Optional
|
Type associated with the IoT event
|
|
Property
|
Optional
|
Property associated with the IoT event
|
|
ServiceSessionID
|
Optional
|
Session ID of the connection
|
Custom Event/Custom Events Group This section holds the keys and values that are passed as per the IoT custom event configuration. Others Group Fields and data sent in this group apply the Installed Product Lookup configuration if the web service associated with the invoked event implements it (by using the IPLookup_IoT() method). The field names must exactly match the field names mentioned in the configuration. It is a case-sensitive match.
|
Field
|
Optional/Required
|
Description
|
|---|---|---|
|
Optional Parameters
|
Optional
|
Optional key-value pairs that can be passed in the payload
|
Sample Request Payload The following is a sample request payload.
{
"Asset": {
"ThingName": "MR-1.5T-XDT-7768",
"ProductName": "MRI Machine",
"InstalledProductName": "MRI Machine #7768",
"SerialNumber": "MR-1.5T-XDT-7768"
},
"Event": {
"Subject": "Vibration detected during machine operation.",
"Description": "5.0 <= 5.5",
"Priority": "2",
"EventTime": "2015-12-29 22: 27: 06.006",
"AlertType": "Above",
"Property": "Vibration",
"ServiceSessionID": "DSBBB0056"
},
{
"customEvents":
[
{
"city":"Pune","Externalid":"112124"
},
{
"city":"Mangalore","Externalid":"112123"
}
]
},
"Others": {
"ThingName": "MR-1.5T-XDT-7768",
"ModelYear": "2008",
"ProductionCode": "XDT"
}
}
"Asset": {
"ThingName": "MR-1.5T-XDT-7768",
"ProductName": "MRI Machine",
"InstalledProductName": "MRI Machine #7768",
"SerialNumber": "MR-1.5T-XDT-7768"
},
"Event": {
"Subject": "Vibration detected during machine operation.",
"Description": "5.0 <= 5.5",
"Priority": "2",
"EventTime": "2015-12-29 22: 27: 06.006",
"AlertType": "Above",
"Property": "Vibration",
"ServiceSessionID": "DSBBB0056"
},
{
"customEvents":
[
{
"city":"Pune","Externalid":"112124"
},
{
"city":"Mangalore","Externalid":"112123"
}
]
},
"Others": {
"ThingName": "MR-1.5T-XDT-7768",
"ModelYear": "2008",
"ProductionCode": "XDT"
}
}