®

Emonitor Version 3.70 CMMS XML Gateway Interface Guide Purpose and Scope This guide is intended for the programmer or software engineer responsible for creating the interface to the Emonitor CMMS XML gateway on the CMMS/EAM side. This interface is called the CMMS XML interface in this guide. This guide explains the use of XML files to communicate work order requests from Emonitor to the CMMS/EAM. It also explains the use of XML files to communicate work order status changes from the CMMS/EAM to Emonitor. This guide does not cover using any of the software or hardware components of an Emonitor system, including other types of Emonitor gateways. For information on using an Emonitor program, refer to the online help for that program. The CMMS XML Gateway is an optional component of the Emonitor installation program. After you install Emonitor with the CMMS XML Gateway, you must run an SQL script to add the Gateway to Emonitor. See Executing the SQL Script to Enable the Gateway on page 4. .

2 | Emonitor® Version 3.70 CMMS XML Gateway Interface Guide

Introduction The Emonitor CMMS XML gateway provides a way to create work orders in an external CMMS system, and track the status of those work orders within Emonitor. The Emonitor XML File Import program reads XML files created by the external CMMS XML Interface when the status of a work order changes. Both work order requests and work order status updates are communicated using XML files.

Terms used in this guide CMMS: Computerized Maintenance Management System. This guide uses CMMS to mean any external maintenance or asset management system that connects to Emonitor through the Emonitor XML gateway. EAM: Enterprise Asset Management system. The term “CMMS” is used in this guide for both CMMS and EAM systems. Emonitor Program: Refers to the software programs in the Emonitor family, such as those in the Emonitor Workstation, Emonitor Factory, and Emonitor Enterprise. Emonitor CMMS XML Gateway: An Emonitor software program that creates work order request XML files when an analysis is sent to the Gateway. CMMS XML interface: A software program that reads work order request XML files created by Emonitor, and then creates work orders in the CMMS. It also creates work order status update XML files, which are read by an Emonitor program to update the status of the work orders in Emonitor. Emonitor XML File Import program: An Emonitor software program that reads the work order status update files created by the CMMS XML Interface, and then updates the status of the corresponding work order in Emonitor.

3 | Emonitor® Version 3.70 CMMS XML Gateway Interface Guide

Creating Work Order Requests Emonitor creates a work order request XML file in one of two ways: •

A maintenance technician uses Emonitor to diagnose a problem with a machine. The technician manually sends the analysis of the problem to the Emonitor CMMS XML Gateway. The Gateway then creates the work order request XML file in the specified directory.

•

A maintenance technician creates an Intelligent Advisory assignment to automatically diagnose problems with a machine. If the diagnosis or rule set defined for the Intelligent Advisory assignment detects a problem, Emonitor automatically sends the analysis of the problem to the Emonitor CMMS XML Gateway. The Gateway then creates the work order request XML file in the specified directory.

For more information on creating analyses and sending them to Emonitor Gateways, refer to the Emonitor online help. The format for the work order request XML files is defined by the work order request XML file schema (defined later in this guide). The name for the work order request XML file is ‘nnnn.xml’ where ‘nnnn’ is a 32-character globally unique ID (GUID). This same GUID is used for the Work Order ID. The work order request XML file can contain one or more Custom Columns fields. You define Custom Column fields when you configure the Emonitor CMMS XML gateway. These fields are then included as part of a work order request XML file. A Custom Column field can be mandatory or optional. For more information, refer to the Emonitor online help, and the Emonitor CMMS XML Gateway online help. The CMMS XML interface reads the work order request XML files, and creates work orders in the CMMS. Tip: The directory for the work order request XML files is defined as part of setting up the Emonitor CMMS XLM Gateway.

Updating Work Order Status In the CMMS, the status of a work order may change as work is performed and completed. For example, the work order status may start as “Open”, change to “Waiting Parts”, change to “In Progress”, and finally change to “Completed”. The CMMS can communicate the change of work order status to Emonitor using XML files. The CMMS XML interface does this by creating a work order status update XML file in the specified directory. The format for the XML file is defined by the work order status update XML file schema. Tip: The directory for the work order status update XML files is defined as part of setting up the Emonitor CMMS XLM Gateway. This is the same directory that is used for the work order request XML files created by the Emonitor CMMS XML Gateway.

4 | Emonitor® Version 3.70 CMMS XML Gateway Interface Guide

Executing the SQL Script to Enable the Gateway The Emonitor CMMS XML gateway is an optional component of the Emonitor installation program. After you have installed the Emonitor with the CMMS XML gateway, you must execute an SQL script to add the CMMS XML gateway to the list of gateways in Emonitor. The SQL script is copied to the Emonitor program directory when you install the CMMS XML gateway. The steps to execute the script depend on the type of your Emonitor database. For SQLBase 1. Click Start > Programs > Gupta > SQLBase 9.0.1 > SQLTalk Interactive SQL. 2. Select Session > Connect. 3. In the Connect dialog box, type econfig in the Database field, and enter the Username and Password. The default values are entek and euser. 4. Click Connect. The econfig database name should appear in the Current Connections field. 5. Select the econfig database name, and then click Use. 6. Select File > Open. 7. Select the script file in the Emonitor program directory. The default location is c:\Program Files\Rockwell Software\Emonitor\XMLCMMSDataSourceInsert.sql 8. Append a semi-colon to the end of the last line. 9. Click at the end of the last line in the script to position the cursor to the right of the semi-colon in the last line. 10. Select Session > Execute Script to run the script. 11. Exit SQLTalk. For MS SQL You must run the database script on the econfig database, using the appropriate database tool. In most cases, you would use Query Analyzer (built into the SQL Server Management Studio in SQL Server 2008 and 2012). The database script is located in the Emonitor Program directory. The default location is: c:\Program Files\Rockwell Software\Emonitor\ The name of the script file is XMLCMMSDataSourceInsert.sql. Run this script on the ECONFIG database/schema. For more information on running a script on your database, refer to your database software documentation. For Oracle You must run the database script on the econfig database, using the appropriate database tool. In most cases, you would use SQL*Plus. The database script is located in the Emonitor Program directory. The default location is: c:\Program Files\Rockwell Software\Emonitor

5 | Emonitor® Version 3.70 CMMS XML Gateway Interface Guide

The name of the script file is XMLCMMSDataSourceInsert.sql. Run this script on the ECONFIG database/schema. For more information on running a script on your database, refer to your database software documentation.

Using the Emonitor CMMS XML Gateway Refer to the following documentation for more information on setting up and using the Emonitor CMMS XML Gateway: the online help for the Emonitor CMMS XML Gateway, and the online help for Emonitor. Importing Work Order Status Update XML Files The Emonitor XML File Import program reads the work order status XML files created by the CMMS XML Interface, and then updates the corresponding work order status in Emonitor. Tip: The work order status update XML file is named nnnn.xml where ‘nnnn’ is the same GUID used for the Work Order ID. The Work Order ID comes from the original work order request XML file. The work order status update XML file can be imported manually, or automatically using the Emonitor Scheduler. Manually Importing Work Order Status Update XML Files After the CMMS XML Interface creates the work order status update XML file in the correct directory, you can manually import the XML file into Emonitor. 1. Modify the default configuration file (xmlConfig.edi) for your specific Emonitor installation. For most installations, you only need to do this once to set the configuration parameters. You can rename the configuration file if desired. See the next section, “Sample XML File Import Program Configuration File”. 2. Run the XML File Import program, using the configuration file as a command line option. You must do this at the Command Prompt, or using the Windows Start > Run dialog. a) For each work order status update XML file in the directory, the Emonitor XML File Import program reads the XML file and updates the work order status in the Emonitor database. b) The XML File Import program adds an entry in the event_log table in the Emonitor database for each successful work order status update. c) The XML File Import program logs any errors to the log file specified in the XML File Import program configuration file. d) If successful, the XML File Import program deletes the XML file. If not successful, move the XML file to the backup directory.

6 | Emonitor® Version 3.70 CMMS XML Gateway Interface Guide

Here is an example showing the command line to run the XML File Import program. This example uses the default Emonitor program directory. Use the correct Emonitor program directory for your system. c:\Program Files\Rockwell Software\Emonitor>XMLCMMSGWDataImport.exe xmlConfig.edi Sample XML File Import Program Configuration File The Emonitor XML File Import program configuration file contains the parameters necessary to import the work order status update information. The configuration file contains three sections: •

The [Target] section contains the parameters required to connect to your database. This is the same information required to log into your Emonitor database.

•

The [Source] section contains the parameters required to locate the work order status XML files.

•

The [Options] section contains the path to the directory for any the XML files that could not be imported. It also contains the path and filename for the error log (event.log).

Note that the password is encrypted and does not appear in plain text as shown below. [Target] NumConnectionsToPool=3 ; --- following for Centura/Gupta AccessLib=GUPTA DBServer=ENTEK_Centura AccessLibDll=mdodd1.dll ; --- following for MSSQL ; AccessLib=MSSQL ; AccessLibDll=mdmqd1.dll ; --- following for Oracle ; AccessLib=Oracle ; AccessLibDll=mdord1.dll User=entek Password=euser [Source] DataFileDir=C:\xml\DataFiles DataFiles=C:\xml\DataFiles\*.xml [Options] BackupPathnameOnError=C:\xml\backup\ LogFilePathname=C:\xml\Log\event.log Automatically Importing Work Order Status XML Files You can also set the Emonitor Scheduler to automatically import work order status update XML files. Tip: The Emonitor Scheduler must be running in order to automatically import work order status update XML files. We recommend that you add the Emonitor Scheduler to the Windows Startup group so that the Scheduler automatically starts when you start Windows.

7 | Emonitor® Version 3.70 CMMS XML Gateway Interface Guide

You must configure the Emonitor Scheduler to automatically import XML files. 1. Start the Emonitor Scheduler from the Emonitor program group on the Windows Start menu. Tip: Press F1 at any time to display the Scheduler online help. 2. Click Add to create a new Scheduler profile. 3. In the Profile dialog, enter a name for the new profile. Make sure that Enable profile for scheduling is selected, and then click Next. 4. In the Response dialog, make sure Scheduled date/time frequency is selected, and then click Next. 5. In the Events dialog, click Add Event, and then enter the Emonitor XML File Import program command line: Executable file: XMLCMMSGWDataImport.exe Command line: xmlConfig.edi Tip: Use the correct name for your import configuration file if you have changed the configuration file name. 6. Click OK to save the event, and then click Next. 7. In the Frequency dialog, enter the date, time, and frequency information. This tells the Emonitor Scheduler when to run this profile. Click Finish to save the profile.

XML File Schema Work Order Request XML File Schema The work order request XML file is generated by the Emonitor CMMS XML gateway, and read by the CMMS XML Interface. The data type for the Custom Column fields depends on Custom Column fields defined when setting up the Emonitor CMMS XML Gateway.

8 | Emonitor® Version 3.70 CMMS XML Gateway Interface Guide

XML File Schema

9 | Emonitor® Version 3.70 CMMS XML Gateway Interface Guide

Notes: • • •

All the date fields have the format (yyyy-mm-dd). The WorkOrderID is a 32-character GUID (globally unique identifier). CMMSLinkItem is linked to the customer CMMS item (the corresponding equipment or location in the CMMS). In Emonitor, the CMMSLinkItem is entered as part of the Asset Information (in Emonitor, select Setup > Hierarchy, Asset tab in the Hierarchy dialog box). Refer to the Emonitor online help for more information.

XML File Example The following is a sample work order request XML file: 632C256DD86C469bA36C1344C3A456E1 Test XML GW4 Auto 1 External User Work Order Issued Location Loc4 XMLGW4 2006-02-14 Bearing Problem 5 Low Severity, Level 2 Moderate Level 1

10 | Emonitor® Version 3.70 CMMS XML Gateway Interface Guide

Work Order Status Update XML File Schema The work order status update XML file is generated by the CMMS XML Interface, and is read by the Emonitor XML File Import program. Notes: •

The work order status update XML files are named nnnn.xml where ‘nnnn’ is the same 32character GUID used for the original Work Order ID.

•

The Work Order XML Schema defines the work order status update XML file format.

•

The work order status update XML file must contain at least the WorkOrderID and Status.

•

All the date fields have the format (yyyy-mm-dd).

XML File Schema …

Publication EMONTR-AT001C-EN-E – December 2013

Copyright ©2013 Rockwell Automation Technologies, Inc. All Rights Reserved.