Skip to main content

Try it! Create a Production with File Adapters

Try it! Create a Production with File Adapters

In this section, you will create a production using an inbound and outbound file adapter. You will use business services, processes, and operations built into InterSystems IRIS, so you won’t have to download any code.

Want to try an online video-based demo of InterSystems IRIS interoperability features? Check out the Interoperability QuickStart!

Before You Begin

To use the procedure, you will need a running InterSystems IRIS instance. Your choices include several types of licensed and free evaluation instances; the instance need not be hosted by the system you are working on (although they must have network access to each other). For information on how to deploy each type of instance if you do not already have one to work with, see Deploying InterSystems IRIS in InterSystems IRIS Basics: Connecting an IDE. Connect Visual Studio to your InterSystems IRIS instance using the information in InterSystems IRIS Connection Information and .Net IDEs in the same document.

Creating an Interoperability-Enabled Namespace

In order to create a production, you must have an interoperability-enabled namespace. If you have already created an interoperability-enabled namespace, you can use that for this production. To create a new interoperability-enabled namespace, use the following procedure. (The namespaces created when you first install InterSystems IRIS are not interoperability-enabled.)

  1. Open the Management Portal for your instance in your browser, using the URL described for your instance in InterSystems IRIS Basics: Connecting an IDE.

  2. Select System Administration > Configuration > System Configuration > Namespaces to go to the Namespaces page.

  3. On the Namespaces page, select Create New Namespace. This displays the New Namespace page; follow the instructions for using this page in Create/Modify a Namespace in the “Configuring InterSystems IRIS” chapter of the System Administration Guide, making sure that the Enable namespace for interoperability productions check-box is selected.

  4. Select Save near the top of the page and then select Close at the end of the resulting log.

Creating a Simple Production with Business Services and Operations

In this step, you will:

  • Create a new production.

  • Add one business service and two business operations to the production.

  • Configure the business service and business operations.

You should now create four directories needed to run this production on the system hosting your InterSystems IRIS instance. The way to do this depends on the type of instance you are using, as follows:

  • For an instance deployed by ICM, use the icm exec command with the -machine and -interactive options to open a bash shell inside the container in which the instance is running, for example:

    icm exec -command bash -machine MYIRIS-AM-TEST-0004 -interactive
    Copy code to clipboard

    You can then create the directories on the container file system.

  • For any containerized instance, whether licensed or Community Edition, use the command docker exec -it container_name bash to open a bash shell in the container (the name of a Community Edition container is try-iris). Then create four directories on the container file system.

  • For InterSystems Learning Labs, use the command-line terminal in the integrated IDE to create new folders in the Shared folder; you can browse to these in the Management Portal under /home/project/shared.

  • For an installed instance, create four directories on the local file system.

This text assumes the following directory paths for an installed instance on a Windows system; substitute the paths of the actual directories you create.

Copy code to clipboard

In the Management Portal, create a new production:

  1. Select Interoperability and, if prompted, select an interoperability-enabled namespace.

  2. Select Interoperability > List > Productions.

  3. If a production is currently running in the namespace, open it, and then select Stop. Return to the production list page.

  4. Select New to create a new production.

  5. 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:

    • In a few seconds, the file is moved from the c:\Practice\In directory to the c:\Practice\Work directory. A time-stamp is appended to the file specification. For example, if the original file was hello.txt, the work file could have a name such as hello.txt_2018-05-07_17.24.57.056.

    • A new copy of the file is written to the c:\Practice\Out directory. It also has a time stamp appended to it.

    • The circles in the production diagram should stay green. If the circles turn red, it means there’s an error in the production. Go over the preceding steps and ensure that the directories exist.

  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.

    generated description: productions trace1

  5. Select the Body tab and it shows the message type and the fields in the message:

    generated description: productions body

    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 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:

    generated description: productions rule

    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:

generated description: productions trace2