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.

Clockworks has the ability to run in-depth diagnostics to quantify the avoidable energy costs of each identified performance issue and prioritize by impacts to energy, comfort, and maintenance on a 0-10 scale. Diagnostics can be sorted by portfolio or individual building, as well as equipment class and type of analyses. This allows a user to drill into a specific building, piece of equipment, or type of analysis.

Open

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.

Integrating Clockworks to the CMMS results in many benefits:

• Very little change management and training required for personnel completing the work orders

• A large reduction of reactive work orders

• Less effort when reactive work orders are carried out

• Live results of performance of equipment

• High value, proactive work order generation

• Implement a data-driven maintenance program

• Enrich the asset information within your CMMS

How do we do it?

Clockworks provides a comprehensive Application Programming Interface (API) which allows the CMMS to communicate with Clockworks to transfer Task data required for the integration.

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.

Open

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.

Creating New Task Records

All tasks within Clockworks are created from, and associated with, a Diagnostic record. It is important to understand how the “Create Work Order” checkbox is used when creating a new task. This checkbox allows the user to optionally indicate the task record should trigger the creation of a work order within the CMMS. When calling for task records in the API, this will result in the “HasGenerateWorkOrder” field to be TRUE:

Viewing and Updating Existing Task Records

The Tasks feature within Clockworks will display all task records for the selected client organization(s). The columns displayed within the Task feature can be adjusted via the “Select Columns” option from the drop-down menu in the upper right of the table. The “Work Order ID” and “Task ID” columns should be selected to help test the integration.

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.

The REST API is comprised of “containers” which provide access to various resources within the API. Each container must be called upon with a unique URL when performing API calls. The CMMS integration will require accessing the following API containers:

Clockworks Asset Identifiers

When retrieving a task record from the API the first objective is to understand which equipment is impacted. The task record will contain the following unique identifiers of the equipment along with the building and client the equipment is contained within.

CMMS Asset Identifiers

In addition to the Clockworks unique IDs, the Task record contains several CMMS identifiers which can be utilized during the integration. All of the fields listed below are by default NULL but can be populated with the CMMS IDs during the integration and leveraged when configuring API calls.

Task Fields

The Task contains many fields which will map to the Work Order being created. Certain fields, especially the “Status” of the task, should be updated as the work order progresses. This is an abbreviated list of the most commonly used task fields, the full list of available fields can be found in the API Documentation.

Steps to Perform the Integration

1. Setup Your Clockworks User Account and Obtain an API Subscriber Key

The first step toward integrating Clockworks to a CMMS is setting up a user within Clockworks with a subscriber key to the REST API. This will be required to authenticate all API calls.

To request a new user account and subscriber key send an email to support@clockworksanalytics.com with the following information:

• User’s First Name, Last Name, and Email

• The client organization name the user will need access to

A Clockworks representative will respond and provide the following:

1. Invitation email to setup your user account in Clockworks

2. A 32-digit API subscriber key unique to the newly created user

3. A 32-digit “CMMS Code” which is unique to the integration being pursued. This CMMS Code can be leverage in API calls to simplify the integration (as detailed below).

2. Setup and Test Your First API Call

Once your user account and API subscriber key have been provided you will be able to perform an API call against the buildings and equipment your user account was granted access to.

To setup your first API call ensure the following parameters are provided in the API call header:

 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:

3. Map the CMMS Assets to Clockworks Equipment

While not technically required, the CMMS Asset Identifiers described above are available to support the mapping of the CMMS Assets to Clockworks. When performing a new integration to existing buildings and equipment in Clockworks, these fields will be initially NULL until a value is provided. All fields can be populated with any type of identifier which aligns with the format and naming conventions utilized within the CMMS.

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:

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:

4. Schedule the Retrieval of New Tasks

Once the equipment mapping is complete the API calls can be configured to retrieve new task records which do NOT currently have a work order. A POST call can be leveraged to specifically target task records which should generate a new work order within the CMMS.

This call should be scheduled to run on a recurring basis to ensure newly created tasks are generating new work orders. Each client organization may have different requirements for how frequently the task records should be retrieved, but generally speaking the work orders created from a Clockworks task are not considered critical in nature and can be retrieved on an hourly or daily basis.

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.

6. Update a Task Record as the Work Order Progresses

The final step is to configure updates to the task record to ensure it aligns with the latest state of the work order within the CMMS. All subsequent API calls can be performed with the CMMS code provided in step 1 and the CMMS Work Order ID applied to the task from step 5.

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.