Converting Interfaces to Production Elements
This chapter assumes that for each application, you might need to define both inbound and outbound interfaces.
Often when you bring InterSystems IRIS® into such a configuration, it is for the purpose of replacing an existing interface engine with InterSystems IRIS. In order to do this you must:
Use a production as a routing engine, as described in previous chapters.
Convert each of the existing interfaces to use the InterSystems IRIS routing engine instead of the previous interface engine.
Once all of the interfaces are converted, remove the previous interface engine from the configuration.
The conversion approach in this chapter leaves the existing interface engine in place and converts the interfaces one by one to use InterSystems IRIS. Unconverted interfaces continue to use the previous engine while you test and confirm that the new interface works properly using InterSystems IRIS. As soon as the converted interface works correctly, you begin work on the next unconverted interface. This incremental change policy ensures the best chance of uninterrupted, error-free service during the conversion.
You could take an approach that converts groups of related interfaces at the same time. Still, you may find that the work boils down to converting one interface at a time.
This chapter explains how to convert one existing interface to use InterSystems IRIS. The general steps are as follows. Each section of this chapter describes one of these steps in detail:
The procedure in this chapter reverses the order in which you would usually describe a production. (“A business service receives an incoming message...”) However, experience with interface conversion shows that if you develop the elements top-down, beginning with the business service and working down to the custom schema, you must often backtrack to previous steps to fill in or correct the names of the lower-level items, in the various forms where you have configured higher-level items.
The procedure in this chapter takes a bottom-up approach, reducing backtracking to a minimum by creating the lower-level items first, so that their names are known when it is time to configure the higher-level items. Bottom-up order works as shown in this chapter: Steps 1 and 2; Steps 3, 4, 5, 6, 7, 8; Steps 9 and 10.
You might have success performing this procedure in top-down order, especially if you have well-established naming conventions, which reduce simple errors. Top-down order works as follows: Steps 1 and 2; Steps 8, 7, 6, 5, 4, 3; Steps 9 and 10.
Backing Up the Production
To perform a full backup, see “Deploying a Production” in Developing a Production.
Regarding XML backup files: If you use a UNIX® system, never FTP a backup XML file in binary mode. Regular FTP will convert this file from DOS to UNIX® properly, but binary FTP might not.
Describing the Interface
Each application in use at the enterprise should provide its own application specification document. The specification document explains which types of messages the application can send (or receive), and which message segments and pieces of each segment the application sends (or expects) for these events. The information is extremely detailed. The administrator of each application can show you this document for his or her application.
The source and target applications should each have an application specification document. However, any single interface between these applications, such as the interface that you are converting, uses a small subset of the possibilities listed in the specification document. Your best source for a description of an interface is actually the interface definition that you are replacing.
Open the existing interface definition. With this definition in view, open a text file and type into it a brief description of what the interface does. Do not try to reproduce the coding conventions of the existing definition (LOOP, CASE, etc.) in detail. Simply identify:
The message segments that you expect to arrive from the source
How the interface changes them before sending them to the target
Choosing Schema Categories
In this step, you must determine which schema will be used for the inbound and outbound sides of the interface. This begins with an approximate choice, which you refine by testing messages against that schema in the Management Portal.
Each application should have an application specification document that identifies the schema that it uses when sending messages, and that it expects when receiving messages.
Defining Routing Rule Sets
Create routing rule sets. For information, see “Creating and Editing Rule Sets” in Developing Business Rules.
Creating Data Transformations
Create DTL data transformations. For information, see Developing DTL Transformations.
Adding Business Operations
The business operation for an interface controls the outgoing message transmission to the target application. For information on adding business operations, see “Adding Business Hosts” in Configuring Productions.
For testing purposes, it is useful to configure a production with two business operations that have the same configuration name:
One is an FTP or TCP business operation that controls the FTP or TCP transmission of messages across the interface when the production is running normally.
The other is a File business operation that sends messages to a file during testing or troubleshooting of the interface.
By convention (the items have the same configured name) only one of these configuration items can be enabled at a time. Enable one or the other depending on whether you want a “test” environment (the File operation) or a “live” environment (the TCP or FTP operation).
The steps to create a “live” business operation and its “test” counterpart are as follows:
Examine the target application to see which separators it expects messages to contain.
Create the “live” (FTP or TCP) business operation.
Use similar steps to create a “test” (File) business operation.
Give the “test” (File) operation the same configuration Name as the “live” one.
Use the Enabled field to enable and disable the “live” (FTP or TCP) or “test” (File) versions of the business operation. Only one business service of the same name can be active at one time.
For additional details, see “Working with Multiple Versions of a Business Host” in Configuring Productions.
Creating or Editing a Routing Process
To enable your new interface to work with the routing engine, you must add a routing process to the production that:
Tells how to interpret data from the source (identifies a routing rule)
Tells where to send the interpreted data (identifies a business operation)
You can create a new routing process.
Adding Business Services
The business service for an interface receives the incoming messages from the source application.
For testing purposes, it is useful to configure a production with two business services that have the same configuration name:
One is an FTP or TCP business service that receives messages from the source application via FTP or TCP when the production is running normally.
The other is a File business service that receives messages from a file during testing or troubleshooting of the interface.
By convention (the items have the same configured name) only one of these configuration items can be enabled at a time. Enable one or the other depending on whether you want a “test” environment (the File service) or a “live” environment (the TCP or FTP service).
The steps to create a “live” business service and its “test” counterpart are as follows:
Create the “live” (FTP or TCP) business service.
Use similar steps to create a “test” (File) business service.
Give the “test” (File) service the same configuration Name as the “live” one.
Use the Enabled field to enable and disable the “live” (FTP or TCP) or “test” (File) versions of the business service. Only one business service of the same name can be active at one time.
For additional details, see “Working with Multiple Versions of a Business Host” in Configuring Productions.
Testing the Interface
Generally you need to maintain a separate “test” production that is an exact copy of the production that runs “live”. Develop the new interface within the “test” production. When that is done, you can migrate a copy of the new interface to the “live” production.
To test a new interface:
Capture some sample messages from the source application in files.
In the “test” production, enable the File business service and the File business operation and send the messages as files.
Examine the resulting message data in the output files to see if it meets the requirements for the target application.
If necessary, adjust the interface elements and retest.
Selectively disable the “test” (File) versions and re-enable the “live” (FTP or TCP) versions of the business service and business operation, still within the “test” production.
Deploying the Interface
Once you have completed testing the interface in the test production, it is time to add the new interface elements to the production that you are running live. To do this:
Back up the complete live production as described in the first step of this procedure.
Export the new elements of the test production, created in the previous steps:
Export the new classes for the interface: business process, data transformation(s), business operations, business services, and any utility classes.
Export the business rule(s).
Export the custom schema(s).
Copy the new XML <Item> elements that the new interface added to the XDATA section of the production class. For example:
Configuration Item Sample Start of <Item> Element Business service (Test) <Item name="App1toApp2_In" Business service (Live) <Item name="App1toApp2_In" Business process (if new) <Item name="App1toApp2" Business operation (Test) <Item name="App1toApp2_Out" Business operation (Live) <Item name="App1toApp2_Out"
Transfer the new interface elements to the live production as follows:
Suspend or shut down the live production.
Import and compile the new classes, rules, and schema.
If your choice was to edit the ACTIONS string on the business process on the “live” system rather than importing the business process as a class, do so now. Compile the edited class.
Paste the new <Item> elements into the XDATA section of the production class. Compile the production class.
Resume or restart the live production.
Optionally, configure alerts for the new production elements:
Business service and business operations have a configuration setting called Alert On Error. When Alert On Error is set to True, as soon as the item encounters any type of error condition it automatically triggers an alert. An alert writes a message to the Event Log and can also send notification to a user via email or pager. Setting Alert On Error to False disables the option.
Alert Grace Period (for business services) and Alert Retry Grace Period (for business operations) provide useful constraints on the frequency of alerts when they are enabled.
This procedure describes how to add interfaces to the “live” production one by one. Alerts are easy to configure as described in this step, once they have been set up. To set them up for the “test” or “live” production, see “Monitoring Alerts” in Monitoring Productions.
Ensure that the new interface is processing all new messages.
Disable or clean up the previous interface technology:
Ensure that all previously pending requests are satisfied and all queues are empty.
Disable the old interface. Disable the “start automatically” option.