Batch Rules & Scenes
This guide provides information on how to use the Batch API to create rules and scenes across multiple locations within the SmartThings ecosystem.
The Batch API enables developers to streamline automation processes by allowing multiple API requests to be combined into a single HTTP call. This is particularly useful for managing devices, rules, and scenes across different locations, reducing the overhead and latency associated with multiple network requests.
By leveraging the Batch API, you can:
- Improve Performance: Reduce the number of HTTP requests and responses, leading to faster execution of operations.
- Simplify Automation: Manage complex scenarios involving multiple locations and devices with ease.
- Enhance User Experience: Provide seamless setup and control for users with devices in multiple locations.
A strong understanding of Rules & Scenes APIs is recommended prior to using this API - refer to the About Automations section for details on constructing Rules.
Getting Started
The Batch API is structured to allow a single API request to create N routines in N locations.
When creating a Batch Request, Templates are required to define the routines that are to be created. Operation Parameters are required to specify the target location(s), device(s), location mode(s), etc... The Batch API then combines these two pieces of data and creates the routines in each specified location.
The create batch request returns a status and a requestId. The status represents whether the Batch operation was accepted for processing. It does not represent whether installation of the routines was successful. The requestId can be used to check the status of the batch operation through a separate API call.
Creating Batches
A batch operation has two top level required fields:
templatesoperationParameters
Templates
The structure of a template is similar to rules and scenes - the one difference is that instead of providing deviceIds,
locationIds, etc.. within the template, placeholders are used which will be replaced when the batch operation is processed.
- The
templateIdis used as a hint to identify which set of variables should be used for replacement. - The
routineTypeis used as a hint to identify whether the template is a Rule or a Scene. - The
templateshould be familiar - the JSON representation of a rule or a scene with placeholders instead of entity IDs.
In the example below, the template represents a scene to turn off a switch.
{
"templateId": "98571df4-c001-48bb-b0da-b40b2ad7c2db",
"routineType": "SCENE",
"template": {
"name": "Scene - Turn Switch Off",
"actions": [
{
"command": {
"devices": [
"{{living-room-lamp}}"
],
"commands": [
{
"component": "main",
"capability": "switch",
"command": "off"
}
]
},
"type": "command"
}
]
}
}
The templateId does not persist and should be generated on a per-request basis, it will be used in the operationParameters
field to identify which operationParameter should be used for which template.
Operation Parameters
This field supplies the data needed by the template to install routines in specific locations.
- The
locationIdfield specifies the target location where the routine will be installed. - The
templateIdfield specifies the template that will be used when replacing variables. - The
variablesfield provides the mapping(s) to be used when building the routine.
In the example below, the operationParameters provides locationId & deviceId for a template.
{
"locationId": "fe7f24a4-0155-4126-bcd5-708253efb1c3",
"templateId": "47072c64-6b39-4e51-aed2-2ad9549e3e10",
"variables": [
{
"name": "living-room-light",
"value": "78923a77-83e4-48e3-a2e9-d852391edb6f"
},
{
"name": "foyer-light",
"value": "52a71080-d54c-4f64-a1ff-ee56b29bd0e3"
}
]
}
Putting it together
In the example below, the batch creation request would install a routine and scene in one location and install a scene in another location.
{
"operationParameters": [
{
"locationId": "cfdbc234-631a-40af-bc1b-65880669c3a0",
"templateId": "6fcfd657-3618-4542-b549-00c10e83d388",
"variables": [
{
"name": "living-room-light",
"value": "e91e30ff-b924-490e-a1b6-515b0aec9117"
},
{
"name": "foyer-light",
"value": "dfcd41af-b546-4af9-8306-ac469c4630ce"
}
]
},
{
"locationId": "cfdbc234-631a-40af-bc1b-65880669c3a0",
"templateId": "37e1ef0a-5d20-4e18-a828-83d109779021",
"variables": [
{
"name": "living-room-lamp",
"value": "b4e49709-8ec5-4376-b463-44b5198c656f"
}
]
},
{
"locationId": "fca0498c-b004-4666-a22a-7d35435aaca5",
"templateId": "37e1ef0a-5d20-4e18-a828-83d109779021",
"variables": [
{
"name": "living-room-lamp",
"value": "08ca6f2b-7241-482d-a8ac-292e0eff160d"
}
]
}
],
"templates": [
{
"templateId": "6fcfd657-3618-4542-b549-00c10e83d388",
"routineType": "RULE",
"template": {
"name": "Turn on Living Room Light when Foyer Light is turned on",
"actions": [
{
"if": {
"equals": {
"left": {
"device": {
"devices": [
"{{foyer-light}}"
],
"component": "main",
"capability": "switch",
"attribute": "switch",
"trigger": "Always"
}
},
"right": {
"string": "on"
}
},
"then": [
{
"command": {
"devices": [
"{{living-room-light}}"
],
"commands": [
{
"component": "main",
"capability": "switch",
"command": "on"
}
]
}
}
]
}
}
]
}
},
{
"templateId": "37e1ef0a-5d20-4e18-a828-83d109779021",
"behaviorType": "SCENE",
"behavior": {
"name": "Turn off Living Room Lamp",
"actions": [
{
"command": {
"devices": [
"{{living-room-lamp}}"
],
"commands": [
{
"component": "main",
"capability": "switch",
"command": "off"
}
]
}
}
]
}
}
]
}
Checking Progress
When dealing with large numbers of installations, it may not be practical to check whether every rule and scene was successfully installed in every location. The Batch API provides a status endpoint that provides a detailed status for a batch operation.
In the example below, the status of an operation shows the success, pending, and failure counts as well as reasons for failures.
{
"requestMethod": "CREATE",
"requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
"status": "FAILURE",
"totalCount": 1,
"successCount": 0,
"failureCount": 1,
"pendingCount": 0,
"operations": [
{
"operationId": "3051932a-fdd2-48fa-b330-7e7d41535969",
"requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
"locationId": "342893ed-6ec8-46d0-ac87-5381d258b3d4",
"routineId": "fe130fc4-ee2b-4013-aa6a-fb517b313072",
"createdAt": "2024-01-24T14:15:22Z",
"updatedAt": "2024-01-24T14:15:22Z",
"status": "FAILURE",
"errorMessage": "The device: b4341705-2fc1-45f4-8c31-c90aa9004afe does not implement capability: switch."
}
]
}