Attachment B RTLS Maximo ICD.pdf

Real Time Location System (RTLS)

Maximo – Intelligent InSites

Interface Control Document

October 2021

Version 1.9

Department of Veterans Affairs

RTLS Maximo Intelligent InSites Interface Control Document ii October 2021

Revision History

Date Version Description Author October 2021 1.9 Revisions made due to the performance of an upgrade of MuleSoft to Version 4.3 Team Liberty

April 2021 1.8 Updated for Maximo POC, InSites/RTLS Release Number and Vendor Name Updated Revision Table

Team Liberty

October 2019 1.7 Updated Maximo-RTLS Data Element Mapping Table in Section 6.2 Asset Name Field Mapping:

• Replaced VA_FM_EQUIPCAT with VA_OMNI_23

• Updated Maximo WSDLs in Appendix C

Team Liberty

August 2019 1.6 Added date compare configurable parameter.

Updated:

• Maximo version and RTLS contact information

• Operational agreement

• References to systems of record

(SOR) to add Maximo as the SOR for locations

• Communication details from Maximo to the interface

• Property file information

• API calls to Intelligent InSites

• References to SOARD changed to EAWM

Team Liberty

November

1.5 Updated to respond to VA feedback DXC

October 2017 1.4 Updated:

• RESTful API calls (Appendix D)

• RTLS version and contact information

• References to quartz scheduler

DXC

February 2016 1.3 Added content about Exception Handling.

Updated:

• Data Element Mapping spreadsheet (Section 6.2)

HP

Interface Control Document iii October 2021

• Description of decommissioned rooms (Section 2.3.3)

• Security description (2.10)

• Special Character handling (2.4)

May 2015 1.2 Subsequent Submission to VA HP

April 2015 1.1 Subsequent Submission to VA HP

February 2015 1.0 Initial Submission to VA HP

Interface Control Document iv October 2021

Table of Contents

1. Introduction

1.1. Purpose

1.2. Scope

1.3. System Identification

1.3.1. Maximo

1.3.2. Intelligent InSites RTLS

1.4. Operational Agreement

1.5. References

2. Interface Definition

2.1. System Overview

2.2. Interface Overview

2.3. Operations

2.3.1. Equipment Details/New Equipment/Equipment Types

2.3.2. Equipment Inventory

2.3.3. Space (Location) Management

2.3.4. Exception Handling

2.4. Data Transfer

2.5. Transaction Types

2.6. Data Exchange

2.7. Precedence and Criticality

2.8. Communications Methods

2.9. Performance Requirements

2.10. Security

3. Interface Requirements

3.1. Interface #1 Requirements

3.1.1. Interface Processing Time Requirements

3.1.2. Message/File Requirements

3.1.3. Communication Methods

3.1.4. Security Requirements

3.1.5. Physical Requirements

3.1.6. Structural Requirements

3.1.7. Mechanical Requirements

3.1.8. Electrical Requirements

3.1.9. Thermal Requirements

3.1.10. Special Fluid Requirements

3.1.11. Signal Requirements

3.2. Interface #2 Requirements

Interface Control Document v October 2021

4. Interface Verification

5. Interface Control

5.1. Electrical Interface

6. Appendix A – Data Elements

6.1. Data Structure

6.2. Data Elements

6.2.1. RTLS Equipment Type Determination

7. Appendix B – ESB Orchestration Entry Points

7.1. Asset Detail Update Endpoint

7.2. Location Update Endpoint

8. Appendix C – Maximo WSDLs

9. Appendix D – RTLS RESTful Web Service calls

9.1. Example Help command

9.2. Example Form command

9.3. Maximo-RTLS Interface RESTful API calls

10. Appendix E - Mapping RTLS Locations to Maximo

10.1. Format of External References

10.1.1. One-to-one Format

10.1.2. Many-to-one Format

10.2. Example of Many-to-one Format

11. Appendix F – Acronyms

Interface Control Document vi October 2021

Table of Figures Figure 1: High Level View of the Interface and Interactions

Figure 2: Overwriting of Asset Details Manually Entered in RTLS

Figure 3: Update of RTLS from Asset Detail Changes in Maximo

Figure 4: New Asset Subscription to Asset Details from Maximo

Figure 5: Asset Movement Inventory Update to Maximo

Figure 6: Passive Asset Inventory Update to Maximo

Figure 7: Idle Active Asset Inventory Update to Maximo

Figure 8: New Location and Location Status Changes to RTLS

Figure 9: New Location Notification in RTLS

Interface Control Document 7 October 2021

1. Introduction The Department of Veterans Affairs (VA) is in the process of deploying a Real Time Location System (RTLS) solution nationally to VA Medical Centers (VAMC) and other VA facilities. The VA national RTLS solution is a system of systems employing multiple Commercial Off-The-Shelf (COTS) RTLS systems. One of the primary applications for RTLS is Asset Tracking. The Intelligent InSites RTLS solution provides the ability to track assets that have been tagged as they move throughout a facility, and provide valuable insights into workflow, performance and other metrics associated with asset tracking.

The Enterprise Asset and Work Management (EAWM) project is a multi-year effort to replace VA’s existing asset and service management systems with a single web-based, integrated, enterprise-level system. It leverages a federated, partnership-based enterprise management model to help ensure the needs of Veterans are met. EAWM addresses VA’s critical need for a modernized and integrated asset and service management capability. EAWM will deploy International Business Machines’ (IBM’s) Maximo Enterprise Asset Management Commercial Off-The-Shelf (COTS) solution.

The EAWM Project and RTLS Program have several intersection points. EAWM will eventually be the official system of record for assets and locations (i.e., space definitions). RTLS is the official system of record for the location of assets. Inherently, the two systems must communicate and be integrated at specific points via an interface in order for both systems to have current and accurate information. This integration must also appear seamless to VA end users.

Note: EAWM was formerly known as Service Oriented Architecture Research and Development

(SOARD).

Purpose This ICD details the interaction between the Intelligent InSites Real Time Location System (RTLS) solution and Maximo. The interface is limited to exchanging data required to complete the asset tracking. The ICD describes this interaction and includes all system, software components, protocols and data elements employed for the purpose of interfacing RTLS with Maximo.

1.1. Scope

This ICD specifies the bi-directional interface between Maximo and RTLS. Upon formal approval for each participating system, this ICD shall be incorporated into the requirements baseline for each system. This document provides details on the functional, performance, operational and design requirements for the interface between Maximo and RTLS. This document describes the file parameters and record layouts for the data that Maximo receives from RTLS as well as the data that RTLS receives from Maximo. It is intended for all parties requiring such information, including software developers, system designers and testers responsible for implementing the interface.

1.2. System Identification

In this interface, Maximo will receive the last known physical location data for all equipment tracked and send asset detail information to RTLS for all equipment tracked. The interface also includes space management functionality: Maximo will send information about new, changed, and decommissioned spaces to RTLS.

RTLS will provide real time location information for all equipment tracked as well as reporting and analytical services.

Interface Control Document 8 October 2021

1.2.1. Maximo

Table 1: Maximo System Details

System Details Title International Business Machines’ (IBM’s)

Maximo Enterprise Asset Management solution

Abbreviation Maximo

Version/Release number 7.6.x

Point of Contact Mike Carrick, EAWM Point of Contact Mike.Carrick@va.gov

1.2.2. Intelligent InSites RTLS

Table 2: Intelligent InSites RTLS System Details

System Details Title Intelligent InSites Real Time Location System

(RTLS)

Abbreviation RTLS

Version/Release number 5.3.x

Point of Contact Chris Clemenson, Intelligent InSites Technical Customer Architect Christopher.Clemenson@va.gov chris.clemenson@infor.com

Vendor [optional] Infor

1.3. Operational Agreement

This ICD provides the specification for an interface between Maximo and RTLS, specifically, to Intelligent InSites, the RTLS asset tracking application that is part of the overall VA RTLS solution.

The VA is responsible for notifying Liberty of any potential or planned changes to Maximo once these changes are known in order to minimize adverse impacts on the interface.

Modifications to the ICD will be made by the Liberty team with a copy of the revised ICD sent to VA RTLS Program Management Office (PMO) and the EAWM Project Management Team.

1.4. References

• Intelligent InSites 2.0 API RESTful Web Services, v 2.0

• RTLS-Maximo Production Operations Manual (POM)

2. Interface Definition The Maximo-RTLS interface is a software solution orchestrated by a series of Enterprise Service Bus (ESB) flows. The ESB selected for the Enterprise RTLS solution is an open source solution called mailto:Mike.Carrick@va.gov mailto:Christopher.Clemenson@va.gov mailto:chris.clemenson@infor.com

Interface Control Document 9 October 2021

Mule ESB. Mule ESB is a Java-based ESB and integration platform to facilitate message routing and data transformation.

A Mule ESB flow is a way to choreograph or orchestrate services. Flows provide a flexible method to build integrations by choosing building blocks from a standard list of defined components. By separating configuration information from the underlying code using building blocks, building, deploying, and maintaining the interface is easier to manage.

Within the ESB flows, Simple Object Access Protocol (SOAP) and RESTful web service Application Programming Interface (API) calls are employed to facilitate communication.

Communication with RTLS is accomplished using event queues and API calls as described in the Intelligent InSites RESTful web service API Guide. Communication with Maximo is managed with a series of SOAP web service methods which are part of the Maximo Integration Framework/Maximo Enterprise Adapter (MIF/MEA). The Maximo-RTLS interface is designed to implement a data synchronization process. Mule ESB orchestrates read and update operations between RTLS and Maximo to keep asset location data and asset details data synchronized. This synchronization is controlled through both scheduled jobs (i.e., batch) which run at a configurable time frequency and outbound message queues on the Maximo and Intelligent InSites systems (i.e., near real time updates).

Additionally, the interface includes some space management functionality. New spaces detected in Maximo generate a corresponding new space to be created in RTLS. Decommissioning of existing Maximo spaces generate updates to RTLS to keep space information synchronized.

The following processes comprise the complete feature set of the interface:

• Equipment Details / New Equipment / Equipment Types

• Equipment Inventory

• Space (Location) Management

• Exception Handling

For more information about the processes, see Section 2.3 Operations.

Interface Control Document 10 October 2021

Figure 1: High Level View of the Interface and Interactions

Subsequent sections of this document provide detailed process flow and configuration descriptions.

2.1. System Overview

VA Medical Centers (VAMC) are responsible for tracking all assets. VA currently employs asset tracking tools to assign codes (i.e., EE numbers and MX numbers) to individual assets as they are deployed at VAMCs. Data about these assets are managed by an automated system called Maximo.

Maximo is currently used for asset tracking and allows for identification of the assets and associated data maintenance. Locating the assets in the facility, however, is currently accomplished through manual tracking.

While complementary of each other, Maximo and RTLS have several intersection points. Maximo will eventually be the official system of record for assets and locations (i.e., space definitions) in Veterans Health Administration (VHA); RTLS is the official system of record for the location of assets. Inherently, the two systems will communicate and be integrated at specific points via this interface in order for both to have all of the current and accurate information. This integration must also appear seamless to VA end users.

2.2. Interface Overview

The property and configuration files are as follows:

• maximoConfig6.dat The maximoConfig6.dat file contains the InSites connection information for each VISN system. The file contains the VISN identifiers, Station numbers, host systems, ports, userids and passwords. The interface code retrieves the connection information by providing either a VISN or Station number as input. The connection information within the file is encrypted.

Interface Control Document 11 October 2021

• log4j.xml This is a standard configuration file for the Java open source Log4j framework and defines the level of detail and delivery mechanism for application logging.

• Maximo properties file The Maximo properties file is designed to externalize server information, credentials, and other application configuration parameters. This file is a standard Java properties file.

Note: Within the property and configuration files, userids, and passwords are encrypted using Triple- DES cryptography (PBEWithMD5AndTripleDES) which is then encoded as base64 string values.

For a comprehensive list of properties, see the RTLS-Maximo Production Operations Manual.

2.3. Operations

The Maximo-RTLS interface suite is comprised of several interface processes to synchronize the equipment tracking data and space updates between Maximo and RTLS.

The high-level interface processes include:

• Equipment Details / New Equipment / Equipment Types

• Equipment Inventory

• Space (Location) Management

The interface uses an informal Canonical Message Model (CMM) between the RTLS model and the Maximo model to handle interoperability of system messaging. As a message passes from one system to another, a set of data elements is involved. Both the sender and the receiver have a shared understanding of what the data elements are (i.e., types, range of values, semantic meaning). The CMM provides an intermediate stage in the transformation. The CMM is a form of Enterprise Application Integration and is intended to reduce costs and standardize on data definitions. The level of abstraction provided by the CMM makes the interface more portable if either system needs replacement. The CMM is considered informal because it doesn’t involve a governance body and formalized message formats.

All messages described in subsequent sections are passed between the systems without human intervention unless otherwise noted.

2.3.1. Equipment Details/New Equipment/Equipment Types

Changes detected to equipment details on either RTLS or Maximo initiate an update from Maximo to RTLS in near real time. This provides timely updates of RTLS with data maintained in Maximo to keep the systems synchronized. Changes are detected in RTLS by monitoring an Intelligent InSites event queue (i.e., core.updated.equipment). When equipment details change in RTLS, a request is made to Maximo for the equipment item’s details and the retrieved details are posted to RTLS. The synchronization is represented in high level logical diagrams in Figures 2 and 3.

Interface Control Document 12 October 2021

Figure 2: Overwriting of Asset Details Manually Entered in RTLS

Figure 3: Update of RTLS from Asset Detail Changes in Maximo

When new equipment items are commissioned in RTLS, the RTLS record contains only a small subset of data elements needed to identify the item in Maximo. The new equipment process detects new equipment items in RTLS, sends a message to Maximo to post the item’s location and retrieves the additional equipment details from Maximo, and finally, updates RTLS. Maximo manages assets tracked in RTLS on a subscription basis. When the new asset process sends the initial request to Maximo a relationship called a subscription is established. Any subsequent change to the asset’s details is sent from Maximo to the interface for updating in RTLS.

The process is initiated by an event queue polled at a configurable internal that monitors an Intelligent InSites event queue (i.e., the core.created.equipment queue). The periodicity is configurable and intended to be short so Maximo and RTLS records are synchronized without a long lag time.

Interface Control Document 13 October 2021

For each item that is processed, an additional check is run to ensure the Maximo equipment type designation referenced by category pointer corresponds with a valid value known to the RTLS system. See section 6.2.1 for more information about the pseudo code for determining a valid equipment type.

The new asset process is represented in Figure 4.

Figure 4: New Asset Subscription to Asset Details from Maximo

2.3.2. Equipment Inventory

The Equipment Inventory process is comprised of three different sub-processes to support VA’s annual inventory processes. Assets that have changed location provide the new location and a timestamp to Maximo. Assets that have remained in the same location, referred to as static, but have been sensed by RTLS provide an updated timestamp to Maximo. All processes include a configurable parameter to do a date compare to ensure Maximo is never updated with an older inventory date from RTLS. If the configurable date compare is enabled, the inventory processes described below fetch the current inventory timestamp from Maximo and compare it to the last-inventory-date-time. If the Maximo timestamp is newer, the inventory update is not posted to Maximo. If the configurable date compare is disabled, the interface does not do the additional fetch from Maximo and does not compare the dates.

All processes initiate communication with RTLS via event queues. The periodicity of the processes is adjustable. The processes are described in more detail below.

Asset Movement Update The asset movement update process monitors an RTLS event queue listening for asset location change events. When an asset location change event is detected, the process uses the RTLS Asset Identity Document (ID) to fetch additional details from RTLS about the location change including, but not limited to, the Maximo Location ID (i.e., the External Reference field) and the type of tag (active vs passive). With the additional details, the process transforms the timestamp and other fields into the Maximo SOAP message format and sends the message to the Maximo framework for processing. The asset movement update process is represented in Figure 5.

Interface Control Document 14 October 2021

Figure 5: Asset Movement Inventory Update to Maximo

Passive Idle Inventory Update

The Passive Idle Inventory Update Process is initiated via an event queue which is polled on a configurable internal and communicates with RTLS via an API call. RTLS has a custom attribute called the Last-inventory-date-time which contains the last time the passive tag was scanned which is essentially the last time the asset was “seen” by RTLS. If equipment is passively tagged and has not changed location, the Passive Idle Inventory Update process compares the last-inventory-date-time timestamp to the last time the job was run. If the last-inventory-date-time is newer than the last time the job ran, the last-inventory-date-time and asset ID are extracted and transformed into the standardized Maximo SOAP message format and the message is sent to the Maximo framework for processing. The passive idle inventory update process is represented in Figure 6.

Figure 6: Passive Asset Inventory Update to Maximo

Active Idle Inventory Update

The Active Idle Inventory Update Process is initiated via an event queue which is polled on a configurable internal and communicates with RTLS via an API call. RTLS has a not-reporting

Interface Control Document 15 October 2021 service running to monitor active tag communication. The service runs at a configurable time frequency (typically every 24 hours). When RTLS loses communication with a tag, the not-reporting flag is set to true. The Active Idle Inventory Update process queries the not-reporting API field. If the tag is still communicating and the equipment has not changed location the inventory date is set to an approximation of the last time the not-reporting service was run (i.e., the last time Intelligent InSites knew where the asset was). The inventory date and Asset ID are extracted and transformed into the standardized Maximo SOAP message format and the message is sent to the Maximo framework for processing. If the not-reporting flag is set to true, meaning RTLS has lost communication with the tag, the inventory date is not updated. The active idle inventory update process is represented in Figure 7.

Figure 7: Idle Active Asset Inventory Update to Maximo

2.3.3. Space (Location) Management

The Maximo-RTLS interface synchronizes space (i.e., location) information between Maximo and RTLS. Maximo is the system of record for locations (i.e., space definitions). All updates flow from Maximo to RTLS and occur in near-real time. Space updates are placed in a Maximo outbound message queue then Maximo makes a SOAP call to push the transaction to the interface. All updates are captured in Maximo’s system logging. The following sub-processes are implemented to manage space information:

• New Spaces – When a new space is added to Maximo and the status is set to “Operating”, the interface receives a message. The Maximo message is transformed by the interface and a corresponding new site-specific location record is posted to RTLS. New locations are placed in a designated area within the RTLS location hierarchy (i.e., “buckets”) for manual remediation. RTLS periodically (e.g., weekly) monitors the new location buckets and sends a notification to designated user/user group at the site-level indicating there is new location information awaiting further action.

• Decommissioned Spaces – When a location is decommissioned in Maximo (i.e., status is set to “Decommissioned”) the interface receives a message. The Maximo message is transformed by the interface and an inactivation request is posted to RTLS to “inactivate” the record. In addition, the name of the room in RTLS is prefixed with “ZZ”. Once the status of a location is set to “Inactive,” the interface ignores the location, and periodic inventory updates to

Interface Control Document 16 October 2021

Maximo are discontinued. An asset within the RTLS “inactive” location will resume inventory updates when a movement to a new valid location occurs. Inactive locations are not visible in the RTLS User Interface (UI) by users without administrative privileges.

The space management and space notification processes are represented in Figures 8 and 9 respectively.

Figure 8: New Location and Location Status Changes to RTLS

Figure 9: New Location Notification in RTLS

2.3.4. Exception Handling

A report with details about rejected messages is available via the Intelligent InSites Snap In feature.

The report provides RTLS administrators visibility into rejected messages that were unable to be posted to either Maximo or RTLS. For more information, see the RTLS-Maximo Production Operations Manual.

2.4. Data Transfer

Data is transferred using SOAP and RESTful messaging protocols as shown in Figure 1. Data is transferred to and from Maximo using the SOAP messaging protocol. Data is transferred to and from RTLS using the RESTful messaging protocol. Mule ESB manages the inbound and outbound messages and transformations between the two systems.

Interface Control Document 17 October 2021

2.5. Transaction Types

Intelligent InSites RESTful web services contain GET and POST methods. The GET method is utilized to collect equipment location information and the POST method is utilized to store equipment detail information, space additions, and updates. The methods are based on standard Hypertext Transfer Protocol Secure (HTTPS) methods. The Intelligent InSites RESTful web services methods return data in eXtensible Markup Language (XML) format.

Maximo is a SOAP-based implementation with XML standard message formats. Web Service Definition Language (WSDL) files provide a description of how the service can be called, what parameters it expects, and what data structures it returns.

2.6. Data Exchange

Data exchanged between Maximo and RTLS is specified in Section 6.2 Data Elements.

2.7. Precedence and Criticality

Accurate asset management data is necessary in VA facilities in order for the VA to reduce operation costs, create a more streamlined operation, enhance efficiency, and increase patient safety. Workflow capabilities include but are not limited to activity and tag monitoring, reporting, analysis, and tracking. The interface will improve workflow through the analysis of data provided by RTLS.

2.8. Communications Methods

Intelligent InSites RESTful web services and Maximo SOAP web services are employed on RTLS and Maximo respectively to facilitate communication between RTLS and Maximo.

Mule ESB processes orchestrate the updates based on configurable internals set in a Java properties file. Mule ESB flows request data from Intelligent InSites and Maximo. Mule ESB flows transform the data and make updates to both systems based on business rules.

2.9. Performance Requirements

Each of the asset tracking interface processes is dependent on the responsiveness of Maximo and RTLS which are being synchronized in conjunction with overall wide area network performance.

While not bandwidth intensive, network latency can affect overall process performance. On an unburdened test system, the Equipment Inventory processes average about 3-5 assets per second within a local network enclave.

2.10. Security

National Institutes of Technology (NIST)-validated Federal Information Processing (FIPS 140-2) encryption is provided for the encryption of VA sensitive data in transit. The Maximo and Intelligent InSites systems reside behind the VA’s firewall in a private network. The communication protocols used are HTTPS/SSL. Access on both the ESB, Intelligent InSites, and Maximo servers is protected by account-level username and password which are encrypted using Triple-DES cryptography (PBEWithMD5AndTripleDES) and then encoded as base64 string values. The passwords do not expire.

Data payloads are validated with:

• XML schema

Interface Control Document 18 October 2021

• Common validation routines as appropriate To ensure the systems are communicating with each other, fault tolerance and peak load management is built in using queuing of requests on both Maximo and ESB.

For Intelligent InSites, the security is HTTPS basic-authentication for RESTful API calls.

3. Interface Requirements

3.1. Interface #1 Requirements

Maximo provides equipment detail information including, but not limited to, a unique equipment identifier, equipment category, manufacturer, model, and serial number related to the equipment being tracked. The equipment details are sent from Maximo to RTLS. RTLS updates Maximo with the last known physical location and a timestamp for all equipment tracked. In addition, Maximo provides space information (i.e., physical location information such as room names) updates to

RTLS.

3.1.1. Interface Processing Time Requirements

Mule ESB applications orchestrate updates to/from Maximo and RTLS based on a schedule which is adjustable by the System Administrator via a Java properties file.

The definitions and conditions under which each message is to be sent are defined in Section 2 Interface Definition. For more information about processing time, see Section 2.9 Performance Requirements.

3.1.2. Message/File Requirements

The conditions that cause messages to be sent are as follows:

• From Maximo to RTLS: Equipment detail and location updates are placed on Maximo outbound messages queues. Maximo makes SOAP calls to push transactions to the interface.

• From RTLS to Maximo: The interface monitors the equipment inventory processes via API calls and outbound message queues.

Data Assembly Characteristics All messages are exchanged in XML format.

Field/Element Definition All data elements, along with frequency of update and data directionality, are available in Section 6.2, Data Elements.

3.1.3. Communication Methods

Interface Initiation Changes to equipment location are detected by RTLS and sent to Maximo as part of a scheduled operation configurable by authorized users. Changes to equipment details, locations, and equipment categories are sent from Maximo to RTLS when changes are detected in Maximo, placed on a Maximo outbound message queue, and then sent via SOAP call to the interface.

Flow Control

Interface Control Document 19 October 2021

N/A

3.1.4. Security Requirements

The interface relies solely on network and firewalls through which the systems are connected.

3.1.5. Physical Requirements

N/A

3.1.6. Structural Requirements

N/A

3.1.7. Mechanical Requirements

N/A

3.1.8. Electrical Requirements

N/A

3.1.9. Thermal Requirements

N/A

3.1.10. Special Fluid Requirements

N/A

3.1.11. Signal Requirements

N/A

3.2. Interface #2 Requirements

N/A

4. Interface Verification The RTLS-Maximo Interface Master Test Plan outlines the testing objectives and overall plan for testing the Maximo-RTLS interface. The testing of the interface occurred at the Alexandria VA Health Care System.

5. Interface Control

5.1. Electrical Interface

N/A

6. Appendix A – Data Elements

6.1. Data Structure

N/A

Interface Control Document 20 October 2021

6.2. Data Elements

Data elements exchanged between Maximo and RTLS are specified in the attached spreadsheet.

The Intelligent InSites RTLS field names are the names exposed through the API. Intelligent InSites provides a RESTful API architecture. The RESTful API provides a layer of abstraction, so developers do not need to understand the underlying database schema. RESTful web services use resources to address items contained in the system such as equipment, sensors, and locations. All RTLS field names are related to the Equipment Resource unless otherwise noted. For more information about the Intelligent InSites RESTful API, see the InSites 2.0 API REST-ful Web Services Guide.

Maximo supports data element exchange through SOAP web services. The data elements within the SOAP web services are not described in a published guide, therefore the Maximo fields are described using the database table and field names within the Maximo system. The user interface name, where applicable, is also provided as a supplementary method for field identification.

RTLS Maximo Data Element Mapping

6.2.1. RTLS Equipment Type Determination

The RTLS Equipment Type for individual equipment items is determined using two different Maximo fields (ASSET.VA_TYPE_OF_ENTRY and ASSET.VA_CSN) and interface business logic. Not all Maximo equipment items have valid Category Stock Numbers (CSNs). Items without valid CSNs are mapped to appropriate “uncategorized” buckets by Type of Entry, allowing for manual Equipment Type categorization within the Intelligent InSites User Interface. The Type of Entry values checked in the below pseudo code are:

• NXE for Non-Expendable Equipment

• BSE for Building Service Equipment

• EE for Expendable Equipment

Note: The interface does not set the Equipment Type strings but rather associates the existing RTLS Equipment Type ID values by doing a database lookup within Intelligent InSites.

The following pseudo code outlines the mapping solution:

When ASSET.VA_TYPE_OF_ENTRY equals NXE

Do a lookup from the equipment type table by using ASSET.VA_CSN

If the lookup is successful

Associate existing Equipment type using the resulting ID field

Otherwise

Associate existing Equipment Type ID for Uncategorized NXE

End If

Interface Control Document 21 October 2021

Set maximo-entry-type = NXE

End When

When ASSET.VA_TYPE_OF_ENTRY equals EE

If ASSET.VA_TYPE_OF_ENTRY is equal to maximo-entry-type

Leave Equipment Type unchanged (i.e. preserve RTLS user assigned

EquipmentType)

Leave maximo-entry-type unchanged

Otherwise

If maximo-entry-type equals BSE

If Equipment Type equals Uncategorized BSE

Associate existing Equipment Type ID for Uncategorized EE

Otherwise

Leave Equipment Type unchanged (i.e. preserve RTLS user assigned

Equipment Type)

End If

Otherwise

Associate existing Equipment Type ID for Uncategorized EE

End If

Set maximo-entry-type = EE

When ASSET.VA_TYPE_OF_ENTRY equals BSE

If ASSET.VA_TYPE_OF_ENTRY is equal to maximo-entry-type

Leave Equipment Type unchanged (i.e. preserve RTLS user assigned

Equipment Type)

Leave aems-entry-type unchanged

Otherwise

If maximo-entry-type equals EE

If Equipment Type equals Uncategorized EE

Associate existing Equipment Type ID for Uncategorized BSE

Interface Control Document 22 October 2021

Otherwise

Leave Equipment Type unchanged (i.e. preserve user assigned

Equipment Type)

End If

Otherwise

Associate existing Equipment Type ID for Uncategorized BSE

End If

Set maximo-entry-type = BSE

When ASSET.VA_TYPE_OF_ENTRY is null or blank

Associate existing Equipment Type ID for Uncategorized Null

Set maximo-entry-type = null

Interface Control Document 23 October 2021

7. Appendix B – ESB Orchestration Entry Points Service orchestration works through the development of complete process flows from beginning to end utilizing a combination of reusable and custom components to define enterprise applications.

Entire enterprise applications within a given logical domain are scripted from initiation to termination. This model has limited reusability of common logic segments via those supported by synchronous web services and often results in duplication of common logic segments between similar orchestrations.

Related to service orchestration is service choreography. A service choreography model provides more discrete, loosely coupled services, where the participating services each know the business logic pertaining to their own input message types and the expected resulting outputs. Choreographed services rely on more discrete segments of business logic, connected by message queues. Individual segments do not know anything about the logic employed in other segments, only the means of processing input messages resulting in corresponding output messages or interactions with external systems (i.e., remote SOAP web services or REST APIs). Choreographed services provide a higher level of reuse due to a greater granularity of the logic segments.

The RTLS-Maximo interface is designed as a choreography model. As opposed to the AEMS- MERS-RTLS interface which used an orchestration design.

The entry points representing the ESB services are described below with the WSDL’s representing the SOAP service methods and message payloads.

7.1. Asset Detail Update Endpoint

This service endpoint is used to accept asset detail messages posted from Maximo to be applied to

RTLS.

Scheme: https Hostname: environment specific Port: 443 (unless otherwise directed) Path: esb/maximo/services/asset/update Method: POST Payload: (see embedded WSDL)

Interface Control Document 24 October 2021

7.2. Location Update Endpoint

This service endpoint is used to accept location creation and update messages posted from Maximo to be applied to RTLS.

Scheme: https Hostname: environment specific Port: 443 (unless otherwise directed) Path: esb/maximo/services/location Method: POST Payload: (see embedded WSDL)

Interface Control Document 25 October 2021

8. Appendix C – Maximo WSDLs WSDL Purpose

VA_INSITES_VA_ASS

ETININV_INS_NEWLO

To support inventory updates, location and timestamp, via maximo asset id. (Moved assets)

VA_INSITES_VA_ASS

ETINREC_INS_NEWLO

To support inventory updates, location and timestamp, via barcode.

(New assets)

VA_ASSETINQRY_INS

.wsdl

To support asset detail queries.

Provides asset update details.

VA_ASSETINLTQRY_I

NS.wsdl

To support asset details queries.

Provides light weight queries used for inventory date checks.

Interface Control Document 26 October 2021

9. Appendix D – RTLS RESTful Web Service calls The Maximo RTLS interface communicates with the RTLS database via RESTful API calls. The semantics of the API are documented in the Intelligent InSites Web Services Guide. The following sections provide examples of the Help and Form commands using the equipment service status resource to demonstrate the availability of information related to the Intelligent InSites RESTful API calls. These commands are documented in the API guide and the online API documentation.

9.1. Example Help command

The Help command returns documentation on a particular resource and the associated parameters.

For example:

../api/2.0/rest/equipment-service-statuses.html?help Returns more information on the equipment service status resource, parameters, and related services.

9.2. Example Form command

The API supports a Form command which creates an HTML form to assist software development teams in rapid prototyping and testing. This command can be used to view the results in HTML, XML, JSON, or CSV formats. For example:

../api/2.0/rest/equipment-service-statuses.html?form=GET Returns an HTML form to query the equipment service status resource values (e.g., in service, not in service).

9.3. Maximo-RTLS Interface RESTful API calls

The following spreadsheet provides a list of the RTLS RESTful API calls utilized within the Maximo-RTLS interface. To understand the underlying conventions, calling parameters, and expected results, see the API documentation provided by Intelligent InSites.

Maximo-RTLS Interface RESTful API calls

Maximo-RTLS_Interf ace_RESTful_API_Cal

Interface Control Document 27 October 2021

10. Appendix E - Mapping RTLS Locations to Maximo In some circumstances, in order to provide appropriate hardware coverage for an area, RTLS needs to divide an existing physical space as defined as a single record in Maximo into multiple RTLS locations. The location to space mapping has been achieved by tying RTLS locations to Maximo spaces by an External Reference key/value pair that relates back to a specific Maximo location. The combination of key and value must be distinct since there is a unique constraint which ensures the ability to look up precisely a single record from RTLS via the key/value combination.

In order to accommodate the above scenario, the solution supports mapping multiple RTLS locations to a single Maximo location by appending a suffix to the External Reference value which can be easily stripped away. The suffix allows the values to remain unique within RTLS, and stripping the suffix away allows the location to be related directly back to the corresponding Maximo location record.

10.1. Format of External References

Two formats are supported, allowing references with or without a suffix for simple one-to-one correlations of RTLS locations to Maximo locations and adding the ability to use suffixes where multiple RTLS locations refer to the same Maximo location. This allows a theoretically infinite number of RTLS Location entries to be mapped to a single Maximo location while still remaining unique within the RTLS system.

10.1.1. One-to-one Format

System-key: maximo-location-id External-Id: 636A6|10E06-1-IC Maximo Location: 1-IC-10E06 Where:

• 636A6 is the facility identifier

• 10E06-1-IC is the Maximo location represented as a value in the RTLS external key-value pair (i.e., room-bldg-div)

• 1-IC-10E06 is the Maximo location represented in Maximo (i.e., bldg-div-room)

10.1.2. Many-to-one Format

System-key: maximo-location-id External-Id: 636A6|10E06-1-IC|1 Where:

• 636A6 is the facility identifier

• 10E06-1-IC is the Maximo location represented as a value in the RTLS external key-value pair (i.e., room-bldg-div)

• 1 is the sequential numeric suffix delimited by a “|” pipe character

Interface Control Document 28 October 2021

10.2. Example of Many-to-one Format

In the below example, three RTLS locations comprise a single Maximo room. The room is represented by a single Maximo record. In RTLS, the three records would be represented as follows:

System-key: maximo-location-id External-Id: 636A6|10E06-1-IC|1

System-key: maximo-location-id External-Id: 636A6|10E06-1-IC|2

System-key: maximo-location-id External-Id: 636A6|10E06-1-IC|3

All three RTLS records would map to the single Maximo location: 1-IC-10E06.

Having the suffix of “|1”, “|2”, or “|3” allows the External Reference key/value pair to remain unique, but by stripping off the suffix it allows the interface to tie back to the Maximo record. This solution ensures that equipment inventory updates occurring while equipment is in ANY of the three locations continues to update the inventory location and physical inventory date in Maximo.

Interface Control Document 29 October 2021

11. Appendix F – Acronyms The following table contains a list of acronyms used in this document and their explanations.

Table 3: Acronym List

Acronym Explanation API Application Programming Interface CMM Canonical Message Model CMR Consolidated Memoranda of Receipt COTS Commercial Off-the-Shelf CSN Category Stock Number DES Data Encryption Standard EAWM Enterprise Asset and Work Management ESB Enterprise Service Bus HCE Health Care Efficiency HTTP Hypertext Transfer Protocol ICD Interface Control Document MIF/MEA Maximo Integration Framework/Maximo Enterprise

Adapter NIST National Institutes of Technology PMO Program Management Office POM Production Operations Manual RTLS Real Time Location System SOAP Simple Object Access Protocol SSL Secure Sockets Layer VA Department of Veterans Affairs VAMC VA Medical Center VHA Veterans Health Administration WSDL Web Service Definition Language XML eXtensible Markup Language

3.2. Interface #2 Requirements

10.2. Example of Many-to-one Format

11. Appendix F – Acronyms