Creating and Updating Technical Attributes Through REST APIs
The technical attributes API allows connected systems to send asset attribute details to Asset 360 using REST services. Using the API, for any asset, you can:
• Update existing attributes with new values.
• Create missing attributes and capture value for the same attribute in the same request.
• Update/create multiple attributes for one asset.
• Update/create multiple attributes for multiple assets.
• Send time of occurrence information for each attribute.
• Send multiple entries for the same attribute with time of occurrence and value details.
• Recognize the correct asset based on the Name, Salesforce ID, or External Identifier field.
The following list represents the API Execution Status:
• A Success response is displayed along with details sent in the request when the action is successful.
• An error response is displayed when execution fails due to format or server issues.
• An entry is created in the Technical Attribute Activity Log object every time the API is executed. It holds operation status as Success or Failed, with message and timestamp details for each execution.
 |
The platform allows you to process a maximum of 200 attribute entries for a single request.
|
You can create and update technical attributes using REST API with the following details.
• Endpoint URL: /services/apexrest/SVMXA360/technicalAttribute/v1/saveTechnicalAttributes/
• Method: POST
|
|
To access from an external system, you must prefix the Salesforce instance URL or the custom URL in the request. For example, https://MyDomainName.my.salesforce.com/services/apexrest/SVMXA360/technicalAttribute/v1/saveTechnicalAttributes/
|
Request JSON
The following is an example of the JSON input.
{
"source": "External System",
"objectName": "Asset",
"assetIdentifierFieldAPIName": "ExternalIdentifier",
"attributeList": [
{
"value": "10800",
"unit": "Watt",
"attributeKey": "EnergyConsumption",
"dataType": "Number",
"timeOfOccurence": "2022-06-16 02:30:00",
"recordName": null,
"recordId": null,
"assetIdentifiers": [
{
"identifierName": "ThingName",
"value": "TFS500-6391703713"
}
]
},
{
"value": "363.8",
"unit": "Watt",
"attributeKey": "SealingPressure",
"timeOfOccurence": "2023-09-04 17:32:00",
"assetIdentifiers": [
{
"identifierName": "Serial Number",
"value": "D-W789-0"
},
{
"identifierName": "Model",
"value": "MOMD"
}
],
"lastOccurrenceTimeList": [
{
"timeOfOccurence": "2023-09-04 05:45:00",
"value": "500"
},
{
"timeOfOccurence": "2023-09-03 17:00:00",
"value": "650"
}
]
}
]
}
Input Description
The following table describes the fields in the request JSON. See the sample input data file for examples.
|
Input Type
|
Field
|
Mandatory or Optional?
|
Description
|
Notes
|
||
|---|---|---|---|---|---|---|
|
targetObject
|
Optional
|
The target object.
|
The value must be set to null.
|
|||
|
source
|
Mandatory
|
The source from where the technical attribute is being added.
|
• The value must be set to External System.
• If you want to set the source as a different value (for example, the name of a platform), then you must add it as a picklist value for the Source field in the Asset Technical Attribute object beforehand.
|
|||
|
objectName
|
Mandatory
|
The name of the object to which the technical attribute is associated.
|
The value must be set to Asset.
|
|||
|
assetIdentifierFieldAPIName
|
Mandatory
|
The API name of the field on the Asset object that holds the unique value of the asset. For example, ExternalIdentifier
|
• This is used to recognize the asset which needs to be updated.
• If keys, recordId, or recordName are not populated in the request then asset search will be on this key field. The value on this asset field must match the assetIdentifier value.
• When asset data has been synchronized between Asset 360 and the external system using a unique key, then it is recommended to use this key to recognize the matching asset.
|
|||
|
attributeList
|
value
|
Mandatory
|
The value of the technical attribute.
|
• When you pass "" or a null value, the technical attribute is created, but without a value.
• To clear the value, send “” or null.
• The date value must be in the format yyyy-mm-dd.
• The datetime must be in the format yyyy-mm-dd hh:mm:ss.
• Boolean must be in the true/false format.
• The value format must match the attribute datatype when updating the existing attribute.
|
||
|
unit
|
Optional
|
The unit of the technical attribute.
|
• Pass the API name of the picklist value of the Unit field in the Asset Technical Attribute object.
• Entry must be present in the global picklist value set in the Unit field.
|
|||
|
recordName
|
Optional
|
The name of the asset for which you are creating the technical attribute.
|
• This field is optional only if you are providing the recordId value.
• If you provide both recordName and recordId values, the recordName value is ignored.
• When a search is made on the name and multiple assets are found with the same name, then the attribute is associated with the first matching asset, by the recordId value.
|
|||
|
recordId
|
Optional
|
The record ID of the asset for which you are creating the technical attribute.
|
• This field is optional only if you are providing the recordName value.
• recordId takes priority when both recordName and recordId are sent in the request
|
|||
|
dataType
|
Optional
|
The datatype of the technical attribute.
|
• If you do not provide the datatype, the datatype is set as text when creating missing attributes.
• The format must match: Text / Number / Picklist / Boolean / Date / Datetime.
|
|||
|
attributeKey
|
Mandatory
|
The developer name of the technical attribute.
|
• If the technical attribute does not exist, a new technical attribute with the provided name is created.
• If a technical attribute with the same name already exists, that technical attribute is updated.
|
|||
|
timeOfOccurence
|
Optional
|
Timestamp when the attribute displayed a specific value or event occurred.
|
• The format must be yyyy:mm:dd hh:mm:ss.
• If the value does not send the date and time when the attribute value is captured on Asset 360, it is set as the time of occurrence.
|
|||
|
assetIdentifiers
|
Mandatory
|
Unique value of the asset from external system, to search in Asset 360.
|
• This is mandatory only when assetIdentifierFieldAPIName is set.
• You can send one or multiple values. The values sent in this list will be concatenated in the order it is sent to form the unique external asset Identifier value
|
|||
|
lastOccurrenceTimeList
|
Optional
|
Multiple entries for the same attributes.
|
Pass the time of occurrence and attribute value in descending order (time of occurrence).
|
Response JSON
The following is an example of the JSON response.
|
|
Activity logs are maintained in the Technical Attribute Activity Log object record entries.
|
{
"success":true,
"message":"Technical Attribute value(s) saved successfully.",
"data": {
"targetObject":"SVMXA360__SM_TA_AssetTechnicalAttribute__c",
"source":"External System",
"objectName":"Asset",
"attributeList": [
{"value":"Demo",
"unit":"",
"recordId":"02i53000000qY8oAAE",
"dataType":"text",
"attributeKey":"SLText"
}
]
}
}