Technologies / Innovative Solutions / Integrations - BMS
Getting Started with BMS Integration
Review this material to get started with BMS integration.
Sample Data
If you wish to explore the BMS features by first working with sample data, use Data Transfer to import the sample data from the /public/dt/26.3.001/sample-data/clockworks folder.
The sample data includes:
-
BMS analyses configured to import equipment diagnostics and auto-create work requests
-
Sample SLAs (The sample SLAs govern how the automatically-created work requests are processed.)
-
Sample Equipment Standard and Equipment records that exist in Clockworks but not in Archibus.
Procedure
-
Deploy the Archibus BMS Solution. See:
-
Run Technologies / Innovative Solutions / Integrations - BMS / Configure BMS Analysis to configure each specific diagnostic.
-
For example, for each diagnostic you can set the priority level at which Archibus will generate a work request and the Problem Type for the generated work request.
-
-
Once the workflow rules run, view the imported diagnostics with Technologies / Innovative Solutions / Integrations - BMS / View Equipment Diagnostics History. See Equipment Diagnostic History Report
-
Review other reports.
-
Archibus has provided four sample reports that analyze BMS equipment diagnostics and associated work requests. These reports are not automatically included in the HQ sample database. You must import them manually by using the Database Update Wizard to run %archibus%/projects/users/public/dt/v2022.01.001/sample-data/reports/update-sample-data.duw.
-
-
Review the work requests generated from diagnostics.
Match Archibus Equipment to Clockworks Equipment
In order to assure that the diagnostics that you import are assigned to the correct equipment, it is important that the equipment records in Archibus map to equipment in Clockworks.
In integrating the two systems, note that:
-
Archibus is the source of truth. Buildings and equipment are managed in Archibus.
-
Clockworks is deployed only for a sub-set of buildings and equipment that is tracked in Archibus. For example, there are no diagnostics for office equipment or for smaller buildings that do not have a BMS installed.
-
Archibus users do not import equipment inventory from Clockworks into Archibus; rather, they add building and equipment inventory into Clockworks.
Editing Clockwork Records
To map Archibus and Clockwork records, you must set up Equipment Name in Clockworks so that the following is prefixed to the existing Clockworks value:
-
the Archibus Equipment Code field (eq.eq_id)
-
the pipe character + any other desired string (for example ABCD or Daikin).
You can enter any value after the pipe character, such as the manufacturer name or another ID that you use in a different system. The Equipment Name in Clockworks is a larger size than Equipment Code in Archibus and can therefore accommodate these characters. The pipe character enables the workflow rule to understand where the value of the Archibus Equipment Code ends.
If a record exists in Clockworks but does not have a match in Archibus, Archibus does not create a record to match the Clockworks record. You must manually create the record in Archibus before importing diagnostics for it.
Archibus Equipment Code | Clockworks Equipment Name(original) | Clockworks Equipment Name (new) |
---|---|---|
HVAC-01 |
ABCD | HVAC-01|ABCD |
HVAC-01 | does not exist in Clockworks | HVAC-01|ABCD (created manually) |
Workflow Rules
The bmsImportDiagnostics
and bmsImportDiagnosticsDemo
workflow rules follow this general procedure:
-
Get equipment ID from Clockworks and try to match it against an existing Archibus equipment using the eq.source_record_id field
SELECT * FROM eq WHERE eq.source_record_id = EID AND eq.source_system_id = 'Clockworks’_
-
If this does not return an Equipment Code from Archibus, then the assumption is that this is a new equipment in Clockworks that was not previously identified in Archibus. Match the equipment based on its name:
-
Clockworks Equipment API Field: EquipmentName = Archibus Equipment Code (eq.eq_id) + optionally “I%”
-
-
Once the equipment is identified, the workflow rules save the Clockworks External Equipment ID of the equipment into the Archibus Equipment table for future reference as follows:
-
eq.source_record_id = Clockworks Equipment External ID
-
eq.source_record_system = “Clockworks”
-
-
If the workflow rule cannot match the Archibus equipment, it skips importing diagnostics for that equipment.