docs.intersystems.com
Home  /  First Look: Connecting Systems in InterSystems IRIS Using Integration Productions


Articles
First Look: Connecting Systems in InterSystems IRIS Using Integration Productions
InterSystems: The power behind what matters   
Search:  


This First Look guide helps you connect systems together with InterSystems IRIS Data Platform™ integration productions. Connecting systems involves allowing messages from one system to be processed by another system. For example, the following scenarios require connecting systems:
When connecting systems together, you may be faced with challenges such as:
While it is possible to code a custom application to connect systems, it is much easier and faster to develop an InterSystems IRIS™ production. InterSystems IRIS provides a framework that allows you to connect systems and either minimizes or eliminates the need for custom code.
Introducing Integration Productions
An InterSystems IRIS production is an integration framework for easily connecting systems and for developing applications for interoperability. A production provides built-in connections to a wide variety of message formats and communications protocols. You can easily add other formats and protocols – and define business logic and message transformations either by coding or using graphic wizards. Productions provide persistent storage of messages, which allow you to trace the path of a message and audit whether a message is successfully delivered. A production consists of business services, processes, and operations:
When connecting systems together, it can be challenging to get them to understand the other system’s messages and documents. For example, consider the following problem:
You can solve this problem using an InterSystems IRIS production. It provides the framework for defining an interface that accepts messages from the data collection system, transforming the message into one that can be understood by the repair system, and then sending it to the repair system. It also stores a record of the message path.
The following illustrates a simple production:
For demonstration purposes, the production in this document uses file adapters and represents the external systems as files. Because most of the work dealing with the external system is done by adapters provided with InterSystems IRIS, developing a production connecting to the external systems with REST, TCP, SOAP, or HTTP is very similar to developing a production using file adapters.
Trying Connecting Systems for Yourself
In this section, you will create a production using an inbound and outbound file adapter. You will use business services, processes, and operations built in to InterSystems IRIS, so you won’t have to download any code. For instructions on how to install and license a development instance of InterSystems IRIS, see Quick Start: InterSystems IRIS Installation.
Creating a Production-Enabled Namespace
In order to create a production, you must have a production-enabled namespace. If you have already created an interoperability production-enabled namespace, you can use that for this production. To create a new production-enabled namespace:
  1. On the Namespaces page, select Create New Namespace. This displays the New Namespace page:
  2. On the New Namespace page, enter the name for the new namespace, such as INTEROP.
  3. Next to the Select an existing database for Globals drop-down menu, select Create New Database. This displays the Database Wizard.
  4. On the first page of the Database Wizard, in the Enter the name of your database field, enter the name of the database you are creating, such as interop. Enter a directory for the database, such as C:\InterSystems\IRIS\mgr\interop. On that page, select Next.
  5. On the next page, select Finish.
  6. Back on the New Namespace page, in the Select an existing database for Routines drop-down menu, select the database you just created.
  7. Ensure that the Make this a production-enabled namespace check box is selected.
  8. Select Save near the top of the page and then select Close at the end of the resulting log.
You have now created a production-enabled namespace.
For more details about creating a namespace and its associated database, see Create/Modify a Namespace in the “Configuring InterSystems IRIS” chapter of the InterSystems IRIS System Administration Guide. For background information, see Namespaces and Databases in the Orientation Guide for Server-Side Programming.
Creating a Simple Production with Business Services and Operations
In this step, you will:
You will need four directories on your system to run this production. Create them in the operating system before creating the production. For example on a Windows system, you could create the following directories:
c:\Practice\In
c:\Practice\Out
c:\Practice\PDFsOut
c:\Practice\Work
In the Management Portal, create a new production:
  1. Select Interoperability and, if prompted, select a production-enabled namespace.
  2. If a production is currently running in the namespace, open it, and then select Stop. Return to the production list page.
  3. Select New to create a new production.
  4. Specify a package name, such as TEST, and a production name, such as FileProd. You will be creating a generic production that can be used for any purpose. Select OK to create the production.
Add one business service and two business operations to the production:
  1. Select the Services plus sign to display the Business Service Wizard.
  2. In the Service Class drop-down menu, select EnsLib.File.PassthroughService.
  3. Specify the Service Name FileService.
  4. Leave the Enabled check box clear.
  5. Select OK.
  6. Repeat these steps for the two business operations. Start by selecting the Operations plus sign to display the Business Operation Wizard. Use the EnsLib.File.PassthroughOperation class for both operations. Name one operation WriteFileOp and the other WritePDFsOp.
Configure the business service and the two business operations:
  1. Select business service that you created in the production configuration diagram, and on the Settings tab:
    1. Select the Enabled check box.
    2. In the File Path field, enter c:\Practice\In.
    3. In the Archive Path field, enter c:\Practice\Work.
    4. In the Work Path field, enter c:\Practice\Work.
    5. In the Target Config Name field, select WriteFileOp.
    6. Leave the other fields with the default values.
    7. Select Apply.
  2. Specify the settings for each of the two business operations. Select the operation in the production diagram and:
    1. Select the Enabled check box.
    2. In the File Path field, enter c:\Practice\Out for the WriteFileOp operation and enter c:\Practice\PDFsOut for the WritePDFsOp operation.
    3. Leave the other fields with the default values.
    4. Select Apply.
Starting the Production and Tracing Messages
After starting the production, you will copy a file to the FileService’s incoming directory. You will be able to view the file in the WriteFileOp’s outgoing directory and trace the message through the production. Note that the WritePDFsOp operation is not used when running the simple production. To start the production and trace the message:
  1. Start the production by selecting Start.
  2. Copy any file into the c:\Practice\In directory. If the production is configured properly, the following should happen:
  3. Select the FileService in the production configuration page and select the Messages tab. It lists each message that went through the production. Select Go To Message Viewer.
  4. Select a message in the Message Viewer and select the Trace tab. It will show that the message went from the FileService to the WriteFileOp operation.
  5. Select the Body tab and it shows the message type and the fields in the message:
    Note that the message type is Ens.StreamContainer and that one of its fields is OriginalFilename.
Adding a Router to the Production
In this step, you will add a routing business process, and a rule to your production. Then you will use copy a file to the incoming directory and view a trace that shows the message going though the router. In the Management Portal::
  1. Select Interoperability > Configure > Production to get to the Production Configuration page and then select the Processes plus sign to display the Business Process Wizard. In the wizard:
    1. In the Business Process Class drop-down menu, select EnsLib.MsgRouter.RoutingEngine.
    2. Select the Auto-Create Rule check box.
    3. Specify the Business Process Name FileRouter.
    4. Leave the Enabled check box clear.
    5. Select OK.
    6. Select OK to the dialog box to approve the rule class name.
  2. Select FileRouter in the production configuration page, and on the Settings tab:
    1. Select the Enabled check box.
    2. Select Apply.
    3. Select the magnifying glass to the right of the Business Rule Name. This starts the Rule Editor and displays the rule that was automatically generated when you created the business process.
  3. In the Rule Editor, you will create a rule that sends PDF files to the WritePDFsOp operation and all other files to the WriteFileOp operation. Your rule will appear as follows:
    To create this rule:
    1. Double-click the constraint value in the rule.
    2. Enter FileService in the Source field.
    3. Enter Ens.StreamContainer in the Message Class field.
    4. Select OK.
    5. Select the rule and then select when in the Rule Assistant.
    6. Select the when condition value and enter Document.OriginalFilename Contains ".pdf" in the text box above the rule diagram and then select OK.
    7. Select the when clause in the diagram and then select send in the Rule Assistant.
    8. Double-click the target value and select the WritePDFsOp configuration item.
    9. Select the when clause in the diagram and then select otherwise in the Rule Assistant.
    10. Select the otherwise clause in the diagram and then select send in the Rule Assistant.
    11. Double-click this send clause’s target value and select the WriteFileOp configuration item.
    12. Select Save.
  4. Return to the Production Configuration page, select FileService and on the Settings tab: and
    1. Select the Target Config Name FileRouter check box.
    2. Clear the WriteFileOp check box.
    3. Then select Apply..
Your production is now complete. The FileService will send all messages to the FileRouter business process. The FileRouter will either send the message to the WritePDFsOp or the WriteFileOp operations based on the rule.
If you copy hello.pdf to the c:\Practice\In directory, it will be sent to the c:\Practice\PDFsOut directory, but, if you copy test.txt to the c:\Practice\In directory, it will be sent to the c:\Practice\Out directory. You can also view the message traces showing these paths through the file router. For example, hello.pdf would have a trace such as:
Learn More About Productions
For more information about productions, see: