EIP Software Development Kit Guide

Transcription

1 EIP Software Development Kit Guide

2 EIP Software Development Kit Guide Contents EIP Software Development Kit Guide 2 Commercial In Confidence 3 Preface Information 4 Overview 5 Summary 5 License 5 Assumptions 5 Limitations 5 Supporting Components 6 Custom Integration Requirements Overview 7 Alternate Ellipse Integration Options 7 Ellipse Custom Adapters 7 External System Adapters 7 SDK Setup 8 Assumptions 8 Sample Project 8 Eclipse 8 JBoss 8 Configure Eclipse for JBoss Server 8 Deployment 9 Local JBoss Admin Console Access 9 Remote JBoss Admin Console Access 9 Configuration Changes 9 Add Module Via Administration Console 10 Integration Examples 11 Overview 11 Queues 11 Topics 11 FTP Examples 11 FTP Client Download 11 FTP Download 12 FTP Upload 12 HTTP Examples 13 HTTP Message Receipt 13 HTTP Message Transmit 13 JMS Examples 14 JMS Message Receipt and JMS Message Response 14 JMS Message Receipt and Web Service Response 15 JMS Message Transmit 17 Troubleshooting 19 Access to ActiveMQ Server 19

3 Commercial In Confidence Copyright 2016 ABB All Rights Reserved Confidential and Proprietary Legal Disclaimer The product described in this documentation may be connected to, and/or communicate information and data via, a network interface, which should be connected to a secure network. It is your sole responsibility to ensure a secure connection to the network and to establish and maintain appropriate measures (such as but not limited to the installation of firewalls, application of authentication measures, encryption of data, installation of antivirus programs, etc.) to protect the product, the network, your systems, and the interface against any kind of security breach, unauthorised access, interference, intrusion, leakage, damage, or corruption or theft of data. We are not liable for damages or losses related to any such security breach, unauthorised access, interference, intrusion, leakage, damage, or corruption or theft of data.

4 Preface Information This document is intended for use by professional services personal or other technical resources needing to develop end-to-end integration between Ellipse and external systems using the Ellipse Integration Platform (EIP).

5 Overview The Ellipse Integration Platform (EIP) is an open, standards-based platform that offers out-of-box integrations between the ABB suite of products as well as to leading ERP platforms. Leveraging industry standards such as Java, XML, Web Services and JMS, the platform provides a SOI (Service Oriented Infrastructure) that can quickly be leveraged to integrate existing customer solutions to the ABB suite of product services. Using this technology virtually eliminates the need to spend time and money developing custom point to point solutions, thereby reducing project implementation time and cost. Summary The Ellipse integration platform is provided to cater for asynchronous integration between Ellipse and external systems within a customer's environment. It is intended to enable faster development of end-to-end integration solutions by providing standard adapters for Ellipse integration. The Software Development Kit (SDK) is also intended to enable faster development of end-to-end integration solutions by providing sample design patterns and code that can be used to develop custom adapters for external system integration. The SDK caters for the development of custom adapters for Ellipse and/or external systems with this documentation and sample code. The EIP is provided with standard Ellipse adapters that enable communication with Ellipse via OAGIS messages transported over JMS providers. In order to enable development of an end-to-end integration solution between Ellipse and an external system, the integration components that communicate with the standard Ellipse adapters (via OAGIS over JMS) and the external system will need to be developed. Where standard Ellipse adapters do not exist, then both custom Ellipse adapters and adapters for the external system will need to be developed to meet this requirement. The contents of the SDK are intended to aid this development. Note that in order to communicate with the standard Ellipse adapters, there are three options available: 1. Develop adapters in the external system that will provide OAGIS messages to the relevant JMS endpoints in the EIP. This assumes that it is technically feasible to do this in the external system. 2. Develop adapters in the client's corporate integration broker that will provide OAGIS messages to the JMS endpoints in the EIP. This assumes that the client has a corporate integration broker and resources with the knowledge and skills to do this. 3. Develop custom adapters in the EIP. It is this scenario that this document is intended to support. For more information on the EIP, refer to the Ellipse Knowledge Repository for details. The Ellipse Knowledge Repository can be accessed from any deployed instance of Ellipse. To access, use the URL below with the <server:port> changed to be the actual values for the Ellipse instance: License Use and support of the EIP SDK is conferred with the procurement of a license for an EIP adapter pack. The SDK is intended to support the development of an end-to-end integration solution between Ellipse and external systems via standard Ellipse adapters and the EIP. Assumptions It is assumed that the customer will have or have access to resources with the integration knowledge and technical skills required to develop custom adapters. This document is intended to provide a basic starting guide only to custom adapter development. It is assumed that the customer has a version of Ellipse 8.7+ with a matching version of the EIP. The examples provided in this document rely on the components and versions of those within the EIP for that version and above. Limitations The SDK is limited to the most common protocols used for integration, those being FTP, HTTP and JMS. The SDK has been developed using specific component versions, those are listed in the table below. The use of other components or other versions of components will not be supported. The EIP infrastructure components used in the examples for message handling, error handling, routing, etc is allowed for use by customers as this may decrease development effort. These are only supported though where the use case is as per the standard Ellipse adapters. These infrastructure components have been developed specifically to support the standard Ellipse adapters, thus changes will only be made where the use case is as per the standard Ellipse adapters. The code provided in this document is intended as a guide to integration development and therefore these are examples only, they are not working solutions and are therefore not supported. Custom configuration information should not be stored in the EIP database. This is subject to changes in later releases that may adversely affect any custom information stored there.

6 Supporting Components The table below outlines the components used in the EIP and the versions of those. +===========================+============+ FreeMarker v ===========================+============+ Smooks v1.5 +===========================+============+ H2 Database Engine v ===========================+============+ Oracle ===========================+============+ Granite Data Services GA +===========================+============+ Hibernate v ===========================+============+ Apache Commons +===========================+============+ commons-beanutils ===========================+============+ commons-configuration 1.7 +===========================+============+ commons-dbcp 1.4 +===========================+============+ commons-io 2.4 +===========================+============+ commons-lang 2.6 +===========================+============+ commons-httpclient 3.1 +===========================+============+ commons-pool 1.6 +===========================+============+ Apache Camel v ===========================+============+ ActiveMQ ===========================+============+ JBoss AS v ===========================+============+ Java v1.7 +===========================+============+ Spring ===========================+============+ Where other versions of these components are used, they may or may not work. The SDK code samples provided have been built and tested against these versions of the components.

7 Custom Integration Requirements Overview The standard Ellipse adapters for the EIP and any custom adapters developed to be executed within the EIP are expected to operate as part of an asynchronous message based solution. This is best suited to the requirement for ad-hoc synchronisation of data between Ellipse and an external system(s) in a near-real-time timeframe. This may be able to cater for periodic bulk uploads of data, but the performance requirements for that type of interface would need to be assessed to determine if such a solution is technically feasible. Alternate Ellipse Integration Options Where a synchronous interface with requests for and responses from Ellipse is required, the EWS capability should be assessed to meet this requirement. The EWS options are published with each deployed Ellipse instance. To access, use the URL below with the <server:port> changed to be the actual values for the Ellipse instance: This will provide the list of web services available for the Ellipse instance and the wsdl's for each service. The documentation for the web services is available in the Ellipse Knowledge Repository. Where periodic bulk uploads of data from and to Ellipse is required and the performance requirements cannot feasibly be met by the EIP, then the Ellipse batch subsystem should be considered as an option. Ellipse batch caters for the processing of large volumes of data in an offline environment. Flat files of information can produced or consumed by standard Ellipse batch programs or custom groovy batch programs. More information on the ellipse Batch subsystem is available in the Ellipse Knowledge Repository: Ellipse Custom Adapters Where the provided standard Ellipse adapters do not meet requirements or there is no standard Ellipse adapter for the business entity required for an interface then custom Ellipse adapters can be developed. These custom Ellipse adapters should cater for the following: Consumption or production of OAGIS messages from/to a JMS provider. Mapping of data between OAGIS messages and Ellipse Web Services (EWS). Orchestration of EWS to perform required processing in Ellipse. For each request message processed from a JMS provider provision of a response message to a JMS provider. Refer to the Ellipse adapter documentation in the Ellipse Knowledge Repository (EKR) for details of how the standard Ellipse adapters cater for the above. Refer to the EIP Custom adapter development documentation in the EKR for details of how to develop these adapters. External System Adapters In order for Ellipse adapters to communicate with an external system, there will need to be adapters developed that translate from the OAGIS messages required by the Ellipse system and the integration technology catered for by the external system. These external system adapters should cater for the following: Consumption or production of OAGIS messages from/to a JMS provider for integration to Ellipse via the standard Ellipse adapters. Mapping of data between OAGIS messages and the API's catered for by the external system. Orchestration of external system API's to perform required processing in external system. For each request message processed from a JMS provider provision of a response message to a JMS provider. These external system adapters will need to be developed to be able to be executed in the EIP working with the technology of the API's of the external system.

8 SDK Setup The SDK provided for the Ellipse Integration Platform is essentially an Eclipse project that contains some example code that covers various integration scenarios. This should be downloaded and then imported into an Eclipse environment for use. Assumptions It is assumed for the setup that Java 1.7 is already installed on your computer, this is required for the SDK. It is assumed that the development environment is using a Windows operating system. Sample Project The sample project for the EIP can be downloaded from any running instance of EIP. The URL will be something like this: Replace the host and port values above with the actual server and port values of your deployed EIP instance. The contents of the vip-custom-adapter.zip should be extracted to a directory of your choice. Eclipse The IDE that can be used to develop adapters in the EIP is Eclipse. ABB also use Eclipse as the IDE to develop standard Ellipse adapters. If you don't have an Eclipse environment to use then this can be downloaded from here: ABB use the Luna and Kepler versions of Eclipse, this SDK has been tested using the Kepler version of Eclipse. Extract the contents of the Eclipse.zip file downloaded to a directory of your choice. To launch Eclipse select the eclipse.exe executable from the directory that the Eclipse.zip download was extracted to. In the launched Eclipse instance you will need to import the contents of the vip-custom-adapter.zip as a project. To do this select File > Import > General > Existing Projects into Workspace. Select Next, then Browse to the directory where the vip-custom-adapter.zip was extracted to, then select Finish. JBoss The EIP runs on JBoss AS 7.1, therefore to develop and test custom adapters that will run in EIP JBoss 7 version of the JBoss server will be required. If you don't have a JBoss 7 server environment to use then this can be downloaded from here: ABB use the JBoss AS Final version of JBoss server for Ellipse and EIP, this SDK has been tested using the same version of JBoss server. Configure Eclipse for JBoss Server The steps to configure Eclipse for the JBoss server are as follows: 1. Launch Eclipse and once opened select the Servers tab. If that tab is not shown go the Window menu option and select Show View > Servers. In the servers tab there should be a URL 'No servers are available. Click this link to create a new server...', click that. Select the server type as JBossAS Tools. Then select Next, accept the terms of the license agreement (if that is acceptable) and select Finish. Eclipse will need to restart for the changes to take effect. 2. In the Server tab, right click in the tab and select New > Server. Select the server type as JBoss AS 7.1, and set the server host name as 'localhost' and set the server name as 'JBoss SDK' (or whatever you wish) and then select Next. Accept the defaults for the Create a new Server Adapter page and select Next. Browse to the directory where JBoss AS is installed and select Ok. Select the execution environment to be JavaSE1.7. Accept the defaults for the Configuration base directory and Configuration file and select Next. On the Add and Remove page then select Finish. 3. Right click on the server 'JBoss SDK' in the server tab and select Open. Select Open launch configuration option and check the server settings are ok and then exit using the Ok button (if you have made changes Apply these first). Right click on the server in the Servers tab and select the Start option. Check that the server starts cleanly, review the details of the server startup in the Console tab. Right click on the server in the Servers tab and select the Stop option. Check that the server stops cleanly, review the details of the server shutdown in the Console tab. Refer to the URL below for more details: The recommended Program arguments for the JBoss server are as follows: -mp "C:/opt/mincom/mib/modules" -jaxpmodule javax.xml.jaxp-provider org.jboss.as.standalone -b localhost --server-config=standalone.xml -Djboss.server.base.dir=C:optmincommibstandalone The recommended VM arguments for the JBoss server are as follows: -Dprogram.name="JBossTools: JBoss AS 7.1" -server -Xms64m -Xmx512m -XX:MaxPermSize=256m -Dorg.jboss.resolver.warning=true -Djava.net.preferIPv4Stack=true -Dsun.rmi.dgc.client.gcInterval= Dsun.rmi.dgc.server.gcInterval= Djboss.modules.system.pkgs=org.jboss.byteman -Djava.awt.headless=true -Dorg.jboss.boot.log.file=C:/opt/mincom/mib/standalone/log/boot.log

9 -Dlogging.configuration=file:/C:/opt/mincom/mib/standalone/configuration/logging.properties -Djboss.home.dir=C:/opt/mincom/mib -Djboss.bind.address.management=localhost -Ddb.type="h2" -Ddb.user="sa" -Ddb.password="password" -Ddb.driver="org.h2.Driver" -Ddb.url="jdbc:h2:./.mib_data/h2/mib_esbDB;MVCC=TRUE" -Ddb.dialect="org.hibernate.dialect.H2Dialect" -Dellipse.serviceUrl=" Note The ellipse.serviceurl argument value should be updated with the actual URL for the Ellipse instance that the server is to connect to. Deployment To deploy the developed custom code into an instance of EIP, the custom code will need to be wrapped up in a war. Then the war must be deployed to the EIP server through the JBoss administration console. The reason for this is there will be 3rd party dependencies in the war and there's no easy way to manage those. To create the WAR file in Eclipse, create the project with the custom code as a dynamic web application. Then use Eclipse to create the WAR file, refer: To deploy the war file as a module through the JBoss administration console, ensure that the JBoss server hosting EIP has been started successfully. When changes to the custom code have been made, these changes should be packaged via the export of a new WAR file from Eclipse. The new WAR file should then be deployed to the EIP server to replace the existing WAR file. Where a new version of EIP is released, a new instance of EIP is typically created. In that scenario the WAR file with the custom code will have to be deployed to the new EIP server. Local JBoss Admin Console Access Where you need to access the administration console when the EIP JBoss server is running on your local PC server, then access your web browser of choice. Then access the administration console using this URL: Remote JBoss Admin Console Access Where you need to access the administration console when the EIP JBoss server is running on a separate Unix server from the PC you are running the web browser on, then the steps outlined below are required. Configuration Changes The configuration file for JBoss will need to be updated. This is the standalone.xml file held under the dir: <server>/standalone/configuration. The address of the server hosting the JBoss server will need to be provided in place of the default value of for the management and public interfaces. <interfaces> <interface name="management"> <inet-address value="${jboss.bind.address.management: }"/> </interface> <interface name="public"> <inet-address value="${jboss.bind.address: }"/> </interface> <interface name="unsecure"> <inet-address value="${jboss.bind.address.unsecure: }"/> </interface> </interfaces> The socket-binding for the management-http interface will need to changed from 'management' to 'public'. Note that if the port is set to 9990 and the port-offset is specified as 100 (as in the above example) then the port to access the admin console on will then be in this case, otherwise it is 9990 as specified. <socket-binding-group name="standard-sockets" default-interface="public" port-offset="${jboss.socket.binding.port-offset:100}"> <socket-binding name="management-native" interface="management" port="${jboss.management.native.port:9999}"/> <socket-binding name="management-http" interface="public" port="${jboss.management.http.port:9990}"/> <socket-binding name="management-https" interface="management" port="${jboss.management.https.port:9443}"/> <socket-binding name="ajp" port="8009"/> <socket-binding name="http" port="8080"/> <socket-binding name="https" port="8443"/> <socket-binding name="osgi-http" interface="management" port="8090"/> <socket-binding name="remoting" port="4447"/>

10 <socket-binding name="txn-recovery-environment" port="4712"/> <socket-binding name="txn-status-manager" port="4713"/> <socket-binding name="messaging" port="5445"/> <socket-binding name="messaging-throughput" port="5455"/> <outbound-socket-binding name="mail-smtp"> <remote-destination host="localhost" port="25"/> </outbound-socket-binding> </socket-binding-group> An example of the URL to access the administration console on then is as follows: Add Module Via Administration Console The steps to add a module via the JBoss Administration Console are as follows: 1. You will firstly need to login to the administration console with the appropriate administrator credentials. 2. Then select the Manage Deployments menu option. Then select the Add Content option, then Choose File option, then Next, then Save. 3. In the Manage Deployments tab then select Enable for the WAR, then Confirm. The EIP server.log file should then be checked to confirm that the module was installed with no errors. It is recommended that the EIP server is restarted after the load of the module is completed to ensure there will be no problems with the next restart of EIP. The EIP server.log should then be checked once again to ensure no issues have arisen from the addition of the custom war file as a module. For more information on the JBoss 7 Administration Console refer to this URL:

11 Integration Examples Overview The Ellipse integration platform caters for integration between Ellipse and external systems via adapters for Ellipse and the external system. The Ellipse integration platform allows exchange of data with external systems via various communication protocols. The most commonly used protocols are as follows: File Transfer Protocol (FTP) Hyper Text Transfer Protocol (HTTP) Java Message Standard (JMS) There are examples of code for communicating with EIP from an external system included in the SDK for each of these protocols. For each example, a functional scenario is specified to make the examples more realistic. In addition, the examples cover information flows in both directions. Queues The queues typically used by the standard Ellipse adapters are as follows: 1. MIB.COMMON.GW - this is used for inbound messages to the Ellipse adapters. 2. MIB.COMMON.REPLY - this is used for response messages returned from the Ellipse adapters. 3. MIB.COMMON.ERROR - this is used for messages that could not be processed by EIP for the Ellipse adapters. The actual queues used by the Ellipse adapters are specified in the adapter documentation held under the Ellipse Knowledge Repository, there are some variations from these. Where messages are to be provided to or consumed from standard Ellipse adapters, the relevant queues for these adapters should be used. Where queues for custom adapters are required, these should be custom queues defined in the route for those custom adapters. Topics The topics available in EIP for storing messages published from Ellipse are as follows: 1. MIB.EVENT.REPLY - this is a topic used for the storing of the show messages published by EIP where changes have been made to data entities in Ellipse. 2. EllipseServices - this is a topic used for storing the event messages sent from Ellipse where changes have been made to data entities in Ellipse. Custom adapters can be used to consume messages from these topics by creating a subscription to specified messages on these topics in the route component of the custom adapter. There are JMS header properties available in the messages on these topics that allow for the selection of specific messages for the subscription. These are as follows: 1. MIB.EVENT.REPLY - property name 'eventname'. Refer to the Ellipse adapter documentation for the values of the 'eventname' to be used. 2. EllipseServices - properties named 'table' and 'type'. The 'table' value will be the Ellipse database table that the update was made for and the type value will be 'create', 'update' or 'delete'. FTP Examples Included in the SDK are 2 examples that use the FTP protocol to receive files from or transmit files to an external system that is to be integrated to Ellipse. FTP Client Download For these examples the apache-commons-net.jar will need to be downloaded to provide an FTP client. This can be downloaded from this URL:

12 FTP Download This example covers how to receive a file from an external system, extract the required information from this and update that information into Ellipse. The functional scenario for this example is the download of a file containing work order information that is to be updated into Ellipse via the EIP Work Order adapter. This example assumes that the generation of the trigger message to start the download processing is handled separately. For testing purposes the trigger message can be manually sent to the FTP.DOWNLOAD.GW queue using the EIP console. In the example processing of the FTP Download is to be initiated by the receipt of a WorkOrderFTPDownloadTrigger message on the queue FTP.DOWNLOAD.GW. This message is expected to be as follows: <?xml version="1.0" encoding="utf-8"?> <WorkOrderFTPDownloadTrigger xmlns:xsi=" </WorkOrderFTPDownloadTrigger> Note To test this example, the trigger message can be manually placed on the queue via the EIP console. Access the console, select the tab Integration > Queues. Select and right click on the queue FTP.DOWNLOAD.GW and then select the tab Send Message in the dialogue box. Paste the contents of the message into the tab and click the Send Message button. The external server in this example is expected to be a Unix server, the directory required is /tmp and the filename required is WODownload.xml. The contents of the file are required to be as follows: <WorkOrder> <WorkOrderHeader> <DistrictCode>R100</DistrictCode> <WorkOrder>DCVIP001</WorkOrder> <Description>Download work order desc</description> </WorkOrderHeader> <WorkOrderTask> <TaskNo>001</TaskNo> <Description>Task 1 Test</Description> </WorkOrderTask> </WorkOrder> The components that are included in the SDK to perform the processing for this example are as follows: WorkOrderDownloadRouteBuilder.java: this class defines the route to be processed when a WorkOrderFTPDownloadTrigger message is received on the queue FTP.DOWNLOAD.GW. WorkOrderDownloadProcessor.java: this class sets some properties that are required to be populated into the SyncMaintenanceOrder message generated and executes the FTPDownload class to get the required file from the external server. FTPFileDownload.java: this is a generic class that will download the passed remote filename from the passed server to the passed local filename. WorkOrderSyncMapping.xsl: this xslt transform will create a SyncMaintenanceOrder message and use the information contained in the downloaded file to populate the Work Order fields in that message. customconfig.properties: a custom properties file containing values for server, port, user, password and path that will be used to process the connection to server via ftp. FTP Upload This example covers how to select show messages generated from changes to the data in Ellipse (via the events framework), extract the required information from this into a file and upload that file to an external server. The functional scenario for this example is the upload of a file containing work order information that has been updated in Ellipse to an external server. This example assumes that EIP has been configured for Work Order events to be processed. The external server in this example is expected to be a Unix server, the directory uploaded to is /tmp and the filename uploaded is WO.<WorkOrderNumber>-<TaskNumber>.xml. The contents of the file uploaded will be as follows: <WORKORDER> <EQUIPMENTDETAIL> <EquipNo></EquipNo> </EQUIPMENTDETAIL> <WORKORDERDETAIL> <DistrictCode></DistrictCode> <WorkOrderNo></WorkOrderNo> <WOTASKNO></WOTASKNO> </WORKORDERDETAIL> </WORKORDER> The components that are included in the SDK to perform this processing are as follows:

13 WorkOrderUploadRouteBuilder.java: this class defines the route to be processed when a ShowMaintenanceOrder message (generated by an event) is received on the queue MIB.COMMON.REPLY. WorkOrderUploadProcessor.java: this class creates the file name using the details in the message, writes the content of the message to the file and then executes the FTPUpload class to put the created file on the external server. FTPFileUpload.java: this is a generic class that will upload the passed local filename to the passed server with the passed remote filename. WorkOrderShowMapping.xsl: this xsl transform will create a WorkOrder message and use the information contained in the ShowMaintenanceOrder message to populate the Work Order fields in that message. customconfig.properties: a custom properties file containing values for server, port, user, password and path that will be used to process the connection to server via ftp. HTTP Examples Included in the SDK are 2 examples that use HTTP to receive from or transmit to an external system that is to be integrated to Ellipse. The HTTP server that is included in EIP is the Apache HTTP Client 3.1. HTTP Message Receipt This example covers how to receive a file from an external system, extract the required information from this and update that information into Ellipse. The functional scenario for this example is the receipt of a file containing work order information that is to be updated into Ellipse via the EIP Work Order adapter. Where information is to be sent from an external system to Ellipse via HTTP, the xml messages can be posted to EIP via this URL: In the example processing of the HTTP Message Receipt is to be initiated by the receipt of a message on the queue MIB.HTTP.GW. This message is expected to be as follows: <WorkOrderHTTP> <WorkOrderHeader> <DistrictCode>R100</DistrictCode> <WorkOrder>DCVIP001</WorkOrder> <Description>Download work order desc</description> </WorkOrderHeader> <WorkOrderTask> <TaskNo>001</TaskNo> <Description>Task 1 Test</Description> </WorkOrderTask> </WorkOrderHTTP> Note To test this example, the http message can be posted to EIP using the curl command. An example of this when executed from a Windows server is as follows: curl -X POST --header "Content-Type:application/xml" Alternatively the message can manually be placed on the queue via the EIP console for testing purposes. Access the console, select the tab Integration > Queues. Select and right click on the queue FTP.HTTP.GW and then select the tab Send Message in the dialogue box. Paste the contents of the message into the tab and click the Send Message button. The components that are included in the SDK to perform this processing are as follows: WorkOrderHTTPRouteBuilder.java: this class defines the route to be processed when a WorkOrderHTTP message is received on the queue MIB.HTTP.GW. WorkOrderHTTPProcessor.java: this class sets some properties to be populated into the SyncMaintenanceOrder message generated. WorkOrderSyncMapping.xsl: this xsl transform will create a SyncMaintenanceOrder message and use the information contained in the received message to populate the Work Order fields in that message. HTTP Message Transmit This example covers how to select show messages generated from changes to the data in Ellipse (via the events framework), extract the required information from this and call an external web service with that information to update it into an external system. The functional scenario for this example is the extraction of Equipment information that has been updated in Ellipse and updating this into an external system. The messages to be processed from Ellipse via EIP will be selected from the topic MIB.EVENT.REPLY (this contains messages that are published with details of the specific data entity when changes to data occur in Ellipse). The information in these messages will be updated into an external system via a web service request (this assumes the external system has a web service to support that function).

14 The components that are included in the SDK to perform this processing are as follows: EquipmentOutJMSRouteBuilder: this class defines the route to be processed when a ShowEquipment message (from an Ellipse Equipment update) is received on the topic MIB.EVENT.REPLY. EquipmentResponseMapping.xml: this smooks transform takes the required information from the ShowEquipment message and populates this into a Java DTO. EquipmentOutAction: this class takes the information from the Java DTO and transforms into values required for the external web service request. EquipmentExternalMapping.xml: this calls the EquipmentExternalMapping Freemarker Template to construct the soap EquipmentResponse message that is to go back to the external system. EquipmentExternalMapping.ftl: this Freemarker Template transform creates a soap request for the external system with the values passed from the EquipmentOutAction class. EquipmentServiceAction: this class calls the external web service with the passed soap request to update that external system. A message with the result of the web service update is output to the queue MIB.EXTERNAL.REPLY. EquipmentDTO.java: the DTO that wraps the ShowEquipment message information from the Ellipse Equipment update. Note When calling a web service, a proxy may be required depending on the security implementation for the specific customer environment. The above example assumes this is not the case and calls an Ellipse web service directly. There are two test classes provided in the SDK for calling a web service either directly or through a proxy. These are as follows: GenericDirectWebServiceCall: calls a public web service directly. GenericProxyWebServiceCall: calls a public web service via a proxy. These may be used to test how a web service can be accessed and also provide the code required to do this for each way. JMS Examples Included in the SDK are 2 examples that use JMS to receive from or transmit to an external system that is to be integrated to Ellipse. JMS Message Receipt and JMS Message Response This example covers how to receive a message from an external system, extract the required information from this, update that information into Ellipse and provide a response back to the external system with the status of the Ellipse update. The functional scenario for this example is the receipt of a message containing work request information from an external system, that is to be updated into Ellipse via the EIP Work Request adapter. The external system will send the request message to EIP by sending the message to a queue hosted in EIP. The response message from the EIP Work Request adapter containing the status of the update will then be returned to the external system in the format required by the external system via a queue hosted in EIP. This example expects the message from the external system to be sent to the queue MIB.JMS.GW hosted in EIP. This message is expected to be as follows: <?xml version="1.0" encoding="utf-8"?> <WorkRequestInJMS> <Document> <ID> </ID> <Details>Test Work Request Update</Details> </Document> <Description>Hello Ted.</Description> <Requestor> <ID>C </ID> </Requestor> <Item> <Classification>A1</Classification> <Type>CA</Type> </Item> </WorkRequestInJMS> Alternatively the message can manually be placed on the queue via the EIP console for testing purposes. Access the console, select the tab Integration > Queues. Select and right click on the queue MIB.JMS.GW and then select the tab Send Message in the dialogue box. Paste the contents of the message into the tab and click the Send Message button. This example provides a message back to the external system via the queue MIB.JMS.REPLY hosted in EIP. This message will be as follows: <?xml version="1.0" encoding="utf-8"?> <WorkRequestResponse xmlns:ip=" xmlns:xsi=" <ResponseDetails>

15 <ChangeStatus> <Code>OK</Code> <Description>Sync created 0 work requests, modified 1 work requests.</description> <ReasonCode>WorkRequest.sync</ReasonCode> <Reason></Reason> </ChangeStatus> </ResponseDetails> </WorkRequestResponse> The components that are included in the SDK to perform this processing are as follows: WorkRequestInJMSRouteBuilder.java: this class defines the route to be processed when a WorkRequestInJMS message is received on the queue MIB.JMS.GW. WorkRequestInJMSProcessor.java: this class sets a JMS header property (setheader("externalid", "WorkRequestUpdate"))on the message to allow the selection of this from the queue MIB.COMMON.REPLY when returning the response information to the external system. WorkRequestSyncMapping.xsl: this xsl transform will create a SyncEngineeringWorkDocument message and use the information contained in the received message to populate the Work Request fields in that message. WorkRequestOutJMSRouteBuilder.java: this class defines the route to be processed when a ConfirmBOD message is received on the queue MIB.COMMON.REPLY that has a JMS header property externalid that is set to "WorkRequestUpdate". WorkRequestResponseMapping.xml: this smooks transform will convert the ConfirmBOD message information into java for processing by the WorkRequestOutAction class. WorkRequestOutAction.java: this action class will extract the information from the ConfirmBOD message required for the WorkRequestResponse message that is to go back to the external system. WorkRequestExternalMapping.xml: this calls the WorkRequestExternalMapping Freemarker Template to construct the WorkRequestResponse message that is to go back to the external system. WorkRequestExternalMapping.ftl: this is the Freemarker Template that will construct the WorkRequestResponse message that is to go back to the external system. ResponseCriteriaDTO.java: the DTO that wraps the Change Status information from the Ellipse Work Request update. ChangeStatusDTO.java: the DTO that contains the Change Status information from the Ellipse Work Request update. Note When receiving a message from a JMS provider, either a queue or a topic may be required as the endpoint. Additionally, the JMS provider may be either local or remote. The above example assumes that the endpoint is a queue hosted by a local JMS provider. In this case a route is used to receive the messages. Where the messages need to received programatically, there are four test classes provided in the SDK for receiving a message from a queue or topic hosted by a local or remote JMS provider. These are as follows: GenericLocalQueueMessageReceiver: this receives a message to a local queue. GenericLocalTopicMessageReceiver: this receives a message to a local topic. GenericRemoteQueueMessageReceiver: this receives a message to a remote queue. GenericRemoteTopicMessageReceiver: this receives a message to a remote topic. These may be used to test how a message can be received from a JMS endpoint and also provide the code required to do this for each way. JMS Message Receipt and Web Service Response This example covers how to receive a message from an external system, extract the required information from this, update that information into Ellipse and provide a response back to the external system with the status of the Ellipse update. The functional scenario for this example is the receipt of a message containing work order task closure information from an external system, that is to be updated into Ellipse via the EIP Work Order adapter. The external system will send the request message to EIP by sending the message to a queue hosted in EIP. The response message from the EIP Work Order adapter containing the status of the update will then be returned to the external system in the form of a web service request. This example expects the message from the external system to be sent to the queue MIB.FIELDREACH.GW in EIP. This message is expected to be as follows: <?xml version="1.0" encoding="utf-8"?> <FDCS> <Header> <Destination>ELLIPSE</Destination> <ExtractTime>13/01/ :09</ExtractTime> <CorrelationId>23</CorrelationId> <EventType>ELL_WOCLOSE</EventType> <DeviceId>iPad</DeviceId>

16 </Header> <Script ID="35" ReturnID="23" ScriptCode="WOCLOSE" ScriptDesc="Work Order Closure" VersionNo="7"> <CompletedDate> </CompletedDate> <CompletedTime>001415</CompletedTime> <CompletedUser UserName="Signals Team 1" UserClass="" WorkGroupDesc="SIGNALS Operations" WorkGroupCode="SIGNALS" WorkGroupClassA="" WorkGroupClassB="">AEMP025</CompletedUser> <WorkOrder>DCVIP </WorkOrder> <EquipNo>PS400</EquipNo> <InstanceName/> <SchemaName/> </Script> <ResultStatusHistory> <StatusLog AcquiredDate=" " AcquiredTime="070858" UserCode="SYSTEM">UNCHECKED</StatusLog> </ResultStatusHistory> <ResultsWorkFlow> <ResultStatus>UNCHECKED</ResultStatus> <CurrentStatus System="0">ARCHIVED</CurrentStatus> </ResultsWorkFlow> <CarryThrough> <DataItem FieldName="GPS FIRST FIX"> </DataItem> <DataItem FieldName="GPS LAST FIX"> </DataItem> <DataItem FieldName="WORKORDERNO">CW </DataItem> </CarryThrough> <Results> <FieldRole Role="ELLIPSE_WOCLOSE"> <FieldResult ItemText="Close-Date" SeqNo="2" ResOrder="2" RGroup="" ItemType="DATE"> <Response Type="OK" ResponseDate=" " ResponseTime="001415"> <ResponseItem> </ResponseItem> </Response> <Defects/> <AddRefs> <RefItem Name="HIDDENDEFAULT" SubCategory="SCRIPT ITEM PROPERTIES"/> <RefItem Name="CLOSEDDATE" SubCategory="WOCLOSE"> </RefItem> </AddRefs> </FieldResult> <FieldResult ItemText="Close Time" SeqNo="3" ResOrder="3" RGroup="" ItemType="TIME"> <Response Type="OK" ResponseDate=" " ResponseTime="001415"> <ResponseItem>141500</ResponseItem> </Response> <Defects/> <AddRefs> <RefItem Name="HIDDENDEFAULT" SubCategory="SCRIPT ITEM PROPERTIES"/> <RefItem Name="CLOSEDTIME" SubCategory="WOCLOSE">141500</RefItem> </AddRefs> </FieldResult> <FieldResult ItemText="Completed By" SeqNo="4" ResOrder="4" RGroup="" ItemType="STRING"> <Response Type="OK" ResponseDate=" " ResponseTime="001415"> <ResponseItem> </ResponseItem> </Response> <Defects/> <AddRefs> <RefItem Name="HIDDENDEFAULT" SubCategory="SCRIPT ITEM PROPERTIES"/> <RefItem Name="COMPLETEDBY" SubCategory="WOCLOSE"> </RefItem> </AddRefs> </FieldResult> <FieldResult ItemText="Completion Code" SeqNo="5" ResOrder="5" RGroup="" ItemType="STRING"> <Response Type="OK" ResponseDate=" " ResponseTime="001415"> <ResponseItem>AC</ResponseItem> </Response> <Defects/> <AddRefs> <RefItem Name="HIDDENDEFAULT" SubCategory="SCRIPT ITEM PROPERTIES"/> <RefItem Name="COMPLETEDCODE" SubCategory="WOCLOSE">AC</RefItem> </AddRefs> </FieldResult> </FieldRole> </Results> <ExceptionDetails> <RaisedIn>String</RaisedIn> <Type>String</Type> <Message>String</Message> </ExceptionDetails> </FDCS> This example provides a message back to the external system via a web service. In this example an Ellipse web service is called directly (to provide a known web service). This soap request will be as follows: <soapenv:envelope xmlns:soapenv=" xmlns:tab=" xmlns:con=" xmlns:ser=" xmlns:att=" xmlns:ins=" <soapenv:header> <wsse:security soapenv:mustunderstand="1" xmlns:wsse=" <wsse:usernametoken wsu:id="usernametoken " xmlns:wsu=" <wsse:username>user</wsse:username> <wsse:password Type=" </wsse:usernametoken> </wsse:security> </soapenv:header> <soapenv:body> <tab:read> <tab:context> <!--Optional:--> <con:district>r100</con:district> <!--Optional:--> <con:maxinstances>1</con:maxinstances> <!--Optional:--> <con:position>sysad</con:position> <!--Optional:--> <con:returnwarnings>false</con:returnwarnings> </tab:context> <tab:servicedto> <!--Optional:--> <ins:tablecode>${changedto.description?xml}</ins:tablecode> <!--Optional:--> <ins:tabletype>${changedto.code?xml}</ins:tabletype> </tab:servicedto> </tab:read> </soapenv:body> </soapenv:envelope> The components that are included in the SDK to perform this processing are as follows: FieldReachInJMSRouteBuilder.java: this class defines the route to be processed when a FDCS message is received on the queue MIB.FIELDREACH.GW. FieldReachInJMSProcessor.java: this class sets a JMS header property (setheader("fieldreachid", "WorkOrderClose"))on the message to allow the selection of this from the queue MIB.COMMON.REPLY when returning the response information to the external system. WorkOrderSyncMapping.xsl: this xsl transform will create a SyncMaintenanceOrder message and use the information contained in the received message to populate the Work Order fields in that message. FieldReachOutJMSRouteBuilder.java: this class defines the route to be processed when a ConfirmBOD message is received on the queue MIB.COMMON.REPLY that has a JMS header property "fieldreachid" that is set to "WorkOrderClose". WorkOrderResponseMapping.xml: this smooks transform will convert the ConfirmBOD message information into java for processing by the FieldReachOutAction class. FieldReachOutAction.java: this action class will extract the information from the ConfirmBOD message required for the WorkOrderResponse. soap request that is to be processed by a web service for the external system. WorkOrderFieldReachMapping.xml: this Smooks mapping calls the WorkOrderFieldReachMapping Freemarker Template to construct the soap request that is to be processed by a web service for the external system.

17 WorkOrderFieldReachMapping1.ftl: this is the Freemarker Template that will construct the soap request that is to be processed by a web service for the external system. FieldReachServiceAction: this action class will call the required web service in the external system to process the soap request. ResponseCriteriaDTO.java: the DTO that wraps the Change Status information from the Ellipse Work Order update. ChangeStatusDTO.java: the DTO that contains the Change Status information from the Ellipse Work Order update. Note When calling a web service, a proxy may be required depending on the security implementation for the specific customer environment. The above example assumes this is not the case and calls an Ellipse web service directly. There are two test classes provided in the SDK for calling a web service either directly or through a proxy. These are as follows: GenericDirectWebServiceCall: calls a public web service directly. GenericProxyWebServiceCall: calls a public web service via a proxy. These may be used to test how a web service can be accessed and also provide the code required to do this for each way. JMS Message Transmit This example covers how to select show messages generated from changes to the data in Ellipse (via the events framework), extract the required information from this and pass this as a message to a queue hosted in an external system. The functional scenario for this example is the extraction of Standard Job information that has been updated in Ellipse and updating this into an external system. The messages to be processed from Ellipse via EIP will be selected from the topic MIB.EVENT.REPLY (this contains messages that are published with details of the specific data entity when changes to data occur in Ellipse). The information in these messages will be updated into an external system via a JMS Queue (this assumes the external system has a JMS provider to support that function). The components that are included in the SDK to perform this processing are as follows: StdJobOutJMSRouteBuilder: this class defines the route to be processed when a ShowStandardJob message (generated from an Ellipse update to a Standard Job) is received on the topic MIB.EVENT.REPLY. StandardJobExternalMapping.xsl: this xslt transform will create a message in the format required for the external system. This example provides a message to the external system via the queue MIB.EXTERNAL.REPLY hosted in EIP. An example of this message is as follows: <?xml version="1.0" encoding="utf-8"?> <StandardJobMessage xmlns:xsi=" <Header> <DistrictCode>R100</DistrictCode> <ID>DCSJ</ID> <Description>DEF Corrective SJ</Description> <Machine> <MachineID/> </Machine> <MaintenanceType>PR</MaintenanceType> <WorkType>NO</WorkType> <WorkGroup> <ID>ADMIN</ID> </WorkGroup> </Header> <Task> <ID>001</ID> <Description>Do 1000 hr mechanical check list</description> <JobDescription> <Code>IN</Code> </JobDescription> <SafetyInstruction> <Code>10</Code> </SafetyInstruction> </Task> </StandardJobMessage> Note When sending a message to a JMS provider, either a queue or a topic may be required as the endpoint. Additionally, the JMS provider may be either local or remote. The above example assumes that the endpoint is a queue hosted by a local JMS