| Table of Contents |
|---|
Introduction to Clockworks Analytics
Clockworks is a cloud-based fault detection and diagnostics (FDD) platform, with a global analysis engine built on 30 person-years of research and development. The comprehensive library of root-cause diagnostics is curated and updated continuously to cover all HVAC equipment and systems.
...
| Info |
|---|
The main goal of Clockworks is to motivate users to create and complete Tasks to resolve performance issues identified by the Diagnostic Reports. |
...
Integrating Clockworks with a CMMS
Why we do it?
When an organization deploys Clockworks, the goal of the program is to prioritize the highest impact work which improves energy performance, comfort compliance, and equipment reliability. Integrating to the Computerized Maintenance Management System (CMMS) allows the organization to automatically create Work Orders from performance issues identified by Clockworks.
...
The integration requires the CMMS to call the Clockworks API to retrieve new task records and create a corresponding work order. Updates to the work order should simultaneously update the Clockworks task until the work order is completed.
...
Creating and Updating Task Records
To begin familiarizing yourself with the task records contained within Clockworks it is helpful to login to Clockworks and understand how tasks are created and updated by users. To get started read through the Clockworks User Manual walkthrough of the Tasks feature.
...
| Info |
|---|
Client Task ID versus Task ID The Client Task ID is unique within a client organization, but could be duplicated across multiple clients (e.g. Task #12 could exist in many client organizations). The Task ID is unique globally across the Clockworks system and should be used to isolate task records when configuring API calls. |
...
Introduction to the Clockworks API
The Clockworks REST API contains a rich dataset providing access to everything from interval data collected from a building’s BMS to Diagnostic records produced from the Clockworks analysis.
...
Container Name and URL | Description |
Base https://rest.buildingsapi.net/core-base | The Base API container contains static information about the building and equipment assets contained within Clockworks. |
Work Orders https://rest.buildingsapi.net/workorders | The Work Orders API container contains Task records which are created by Clockworks users and will need to be synchronized to work orders within the CMMS. |
...
API Response Key | Description |
ID | The unique ID of the Clockworks task across the entire application. This ID will always be unique and never duplicated across any client organization. |
ClientTaskID | The ID of the Clockworks task within the client organization. This ID is what the end-user will see in Clockworks and could be duplicated across different client organizations (e.g. Task #12 could be present across many client organizations). |
WorkOrderID | The unique ID of the CMMS work order. This field is default NULL and must be updated by the CMMS when the work order is created. |
Reporter | The email of the person that created the task. |
Assignee | The email of the person the task was assigned to. |
Status | The status of the task: Open, In Process, Completed, On Hold, or Cancelled. |
Summary | A required text field which provides a summary of the identified performance issue. This field is auto-populated from the Clockworks diagnostic report, but can be modified by the user. |
Description | An optional text field to describe the issue in more detail. |
Recommendations | An optional text field to recommend corrective actions. |
Actions | An optional text field to document the corrective actions that occurred. |
Date Created | DateTime the task record was created within Clockworks. |
Date Modified | DateTime the task record was modified within Clockworks. |
Date Completed | DateTime the task record was completed within Clockworks. |
HasGenerateWorkOrder | A boolean TRUE/FALSE field which indicates the user which created the task wants to also create a Work Order within the CMMS system. |
HasWorkOrderID | A boolean TRUE/FALSE field which defaults to FALSE for a newly created task. When the WorkOrderID field is populated, it automatically updates to TRUE to indicate the task record is now associated to a work order. |
Steps to Perform the Integration
1. Setup Your Clockworks User Account and Obtain an API Subscriber Key
...
A simple test to confirm you’ve configured your API header’s correctly is to perform a GET call for the buildings you have access to:
API Call Example: GET Buildings | |
GET | https://rest.buildingsapi.net/core-base/buildings |
...
To begin the mapping exercise, obtain a complete list of Equipment contained within Clockworks by calling the Base API container. Equipment details can be obtained via the following API call. Within the response, you will see the Equipment ID, Building ID, Equipment Name, and CMMS references available for the mapping:
API Call Example: GET Equipment | |
GET | https://rest.buildingsapi.net/core-base/equipment |
...
Any number of CMMS Asset Identifiers can be used to support the integration. The most commonly leveraged field is the CMMSReferenceID, which should align 1:1 to the Clockworks equipment. Any CMMS field can be populated via a PATCH call to the Work Order API container. The response will show the updated CMMS value which was provided in the body of the API call, as shown below:
API Call Example: PATCH Equipment | |
PATCH | https://rest.buildingsapi.net/core-base/equipment |
Body | { "Resource" : { "EID" : "122655", "Update" :{ "CMMSReferenceID" : 1234 } } } |
| Expand | ||
|---|---|---|
| ||
{ "data": [ { "type": "Equipment", "id": 122655, "links": { "self": "https://rest.buildingsapi.net/core-base/Equipment/122655/" }, "attributes": { "BID": 6065, "EquipmentName": "Chiller-4", "EquipmentLocation": null, "SerialNumber": null, "Description": null, "EquipmentTypeID": 95, "IsActive": true, "IsVisible": true, "IsConfigurationComplete": true, "DateCreated": "2016-12-21T20:46:04.08", "DateModified": "2023-09-07T16:48:41.49", "ExternalEquipmentTypeName": null, "EquipmentNotes": "", "ManufacturerModelID": 1, "CMMSReferenceID": "1234", "CMMSLink": null, "CMMSLocationID": null, "CMMSSiteID": null }, |
...
| Info |
|---|
How to determine which Task records should generate a new work order: The body of the POST call can include two specific conditions which indicate the Clockworks user wants the task record to create a work order (HasGenerateWorkOrder = TRUE) and that there is no existing work order associated with the task (HasWorkOrderID = FALSE). |
API Call Example: POST Task Records | |
POST | https://rest.buildingsapi.net/workorders/taskrecords |
Body | { "HasGenerateWorkOrder": "true", "HasWorkOrderID": "false" } |
| Expand | ||
|---|---|---|
| ||
{ "data": [ { "type": "TaskRecords", "id": 177030 }, "attributes": { "AEID": 17975, "Summary": "AHU-7 leaking valve” "CID": 79, "BID": 181, "EID": 21352, "AID": 30, "AnalysisStartDate": "2023-08-16T00:00:00", "ClientTaskID": 777, "CMMSSiteID": null, "CMMSLocationID": null, "CMMSAssetID": "9921352", "WorkOrderID": null, "HasGenerateWorkOrder": true, "HasWorkOrderID": false, } }, |
5. Update Task Record with Work Order ID from the CMMS
Once a work order has been created it is necessary to update the Clockworks task record with the work order ID to indicate the task record now has a corresponding work order in the CMMS. Providing the work order ID will also automatically update the “HasWorkOrderID” field to TRUE so the task record won’t be returned when rerunning the API call outlined in step 4 above.
API Call Example: PATCH Task Records | |
PATCH | https://rest.buildingsapi.net/workorders/taskrecords |
Body | { "Resource" : { "TaskID" : "177030", "Update" :{ "WorkOrderID" : "12345" } } } |
| Expand | ||
|---|---|---|
| ||
{ "data": [ { "type": "TaskRecords", "id": 177030 }, "attributes": { "AEID": 17975, "Summary": "AHU-7 leaking valve” "CID": 79, "BID": 181, "EID": 21352, "AID": 30, "AnalysisStartDate": "2023-08-16T00:00:00", "ClientTaskID": 777, "CMMSSiteID": null, "CMMSLocationID": null, "CMMSAssetID": "9921352", "WorkOrderID": "12345", "HasGenerateWorkOrder": true, "HasWorkOrderID": true, } }, |
...
The example below shows a PATCH call which simultaneously updates the task status to “Completed” and populates the Action field with “Repaired Valve” to summarize the corrective actions.
API Call Example: PATCH Task Records | |
PATCH | https://rest.buildingsapi.net/workorders/taskrecords |
Body | { "CMMSCode" : "dea836ff-b15b-4ecc-8d1f-XXXXXXXXXXXX", "Resource" : { "WorkOrderID" : "1234", "Update" :{ "Status" : "Completed", "Actions" : "Repaired valve" } } } |
| Expand | ||
|---|---|---|
| ||
{ "data": [ { "type": "TaskRecords", "id": 177030 }, "attributes": { "AEID": 17975, "Summary": "AHU-7 leaking valve” "CID": 79, "BID": 181, "EID": 21352, "AID": 30, "AnalysisStartDate": "2023-08-16T00:00:00", "ClientTaskID": 777, "CMMSSiteID": null, "CMMSLocationID": null, "CMMSAssetID": "9921352", "WorkOrderID": "1234", "HasGenerateWorkOrder": true, "HasWorkOrderID": true, "Status": "Completed", "Description": null, "Recommendations": null, "Actions": "Repaired Valve", } }, |