Topic outline

• Creating a Basic Production in InterSystems IRIS

  Creating a Basic Production in InterSystems IRIS

  See how to easily integrate systems, applications, data sources, and databases in real time with an InterSystems IRIS® data platform production.

  In this activity, you will create a simple production that organizes files on a local file system. The production will sort inbound files into two separate folders depending on their file type. You will also use file adapters to read and write files from the system.
• Collapse allExpand all
  About Productions

  About 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.

  A production consists of business services, processes, and operations.

  • Business services, with the use of inbound adapters, connect with external systems and receive messages from them.
  • Business processes allow you to define business logic, including routing and message transformation, to ensure data gets where it needs to go in the correct format.
  • Business operations, with the use of outbound adapters, connect with external systems and send the messages to them.

  Data passes between components via messages. Productions provide persistent storage of messages, which allow you to trace the path of a message and audit whether a message is successfully delivered.

  In a production, external systems sit outside the business service and operation. The business process is in the middle and receives information from the business service; it can exchange information with the business operation in two directions.
• Try It! Create a Production with File Adapters

  Try It! Create a Production with File Adapters

  In this exercise, you will create a production step-by-step. You will create a blank production, then add and configure the inbound and outbound adapters. You will test the adapters by sending a file through the system, then add a message router that includes logic to organize files.

  Along the way, you will use pre-built business services, processes, and operations—so you do not have to download or write any code.

  • Launch an InterSystems IRIS instance

    You are provided with a free temporary instance of InterSystems IRIS for use in this exercise, as well as an IDE in which you can develop and test your production.

    Click the button in the launcher below to deploy an instance of InterSystems IRIS.

    Note:

    You can also follow along with this exercise on your own InterSystems IRIS server. You will need to adapt some instructions as you go, such as creating a new interoperability-enabled namespace and local directories.

    Once you have a running instance, you are ready to begin developing a production.

  •  You must be logged in to launch an InterSystems IRIS instance.

    • Log in with your existing account.
    • Don't have an InterSystems account? Create a new account.
  • Create a blank production

    In this step, you will create a generic production that can be used for any purpose.

    1. Open the system Management Portal using the link in the launcher above.
    2. Check that you are in the USER namespace, an interoperability-enabled namespace that has the package mappings you will need for a production.
    3. Navigate to Interoperability > List > Productions.
    4. Click New to create a new production.
    5. Specify TEST as the package name and FileProd as the production name.
    6. Click OK to create the production.

    You will be brought to the Production Configuration screen, where you can add components and define a data processing pipeline.

  • Add file-processing components

    Now you will add and configure the main components in the production. Add one business service and two business operations to the production:

    1. Click 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. Click OK.
    6. Repeat steps 1-5 for the two business operations.
       1. Click the Operations plus sign to display the Business Operation Wizard.
       2. Use the EnsLib.File.PassthroughOperation class for both operations.
       3. Name one operation WriteFileOp and the other WritePDFsOp.

    In productions, many connections to external system are created using adapters. The production in this document uses file adapters and represents external systems as file systems. Using REST, TCP, SOAP, or HTTP adapters in a production is very similar to using file adapters.

  • Configure the components

    Note:

    If you are following along on your own instance, you will need to create file directories similar to those used here.

    Next, you will add settings to the business service and business operations. These components work by reading from input file directories and writing to output file directories. For simplicity, the IDE already contains the directory /home/project/shared/production. It is already readable and writable by the InterSystems IRIS instance for your use in this exercise.

    1. On the Production Configuration screen, select the business service you created.
    2. Open the Settings tab on the right and configure the basic settings as follows:
       1. Select Enabled.
       2. File Path: /home/project/shared/production/In
       3. Archive Path: /home/project/shared/production/Work
       4. Work Path: /home/project/shared/production/Work
       5. Target Config Name: WriteFileOp
       6. Leave the default values in the other fields and click Apply.
    3. Specify the settings for each of the two business operations. Select the business operation in the production diagram and configure the following:
       1. Select Enabled.
       2. File Path:
          • WriteFileOp operation: /home/project/shared/production/Out
          • WritePDFsOp operation: /home/project/shared/production/PDFsOut
       3. Leave the default values in the other fields and click Apply.

    The file adapters are now configured to read and write from the local file system. Recall the local file system's permissions were already set for you in this activity.

  • Start the production and send data through it

    In this task, you will start the production so it is ready to process data. After starting the production, you will copy a file to the file service's incoming directory.

    Note:

    If you are following along on your own instance, you can create a text file and use it to test the production.

    1. On the Production Configuration screen, start the production by clicking Start.
    2. Open your IDE by clicking the link in the launcher above.
    3. Copy the Sample.txt file from /shared/production/Source and paste it into the /shared/production/In directory.

    If the production is configured properly, the following should happen:

    • In a few seconds, the file is moved from the /shared/production/In directory to the /shared/production/Work directory. A time stamp is appended to the file specification.
    • A new copy of the file is written to the /shared/production/Out directory. It also has a time stamp appended to it.

    Note:

    The circles in the production diagram should stay green. If they are grey or turn red, it means there is an error in the production. Try the steps above again.

    Your production is now running; it is capable of processing a very high rate of incoming files. For now, it is a simple pass-through data pipeline, but it sets the stage for more complex processing.

  • Trace the message you sent

    You will be able to view the file in the file operation's outgoing directory and trace the message through the production. Note that the PDF operation is not used yet.

    1. Return to the Production Configuration page in the Management Portal and clickFileService. Click the Messages tab on the right, which lists each message that went through the production.
    2. Click Go To Message Viewer.
    3. Select a message in the Message Viewer and click the Trace tab on the right.
       The trace shows that the message went from FileService to WriteFileOp.
    4. Click the Body tab to see the message type and fields in the message. Note that the message class name is Ens.StreamContainer and one of its fields is OriginalFilename.

    Tracing messages is useful both for auditing and debugging purposes.

  • Add a router to the production

    In this task, you will add a routing business process and rule to your production, then copy a file to the incoming directory and view a trace that shows the message going though the router. In the Management Portal:

    1. Return to the Production Configuration page.
    2. Click the plus sign next to Processes to display the Business Process Wizard.
    3. In the wizard:
       1. Select EnsLib.MsgRouter.RoutingEngine from the Business Process Class drop-down menu.
       2. Select Auto-Create Rule.
       3. Enter the Business Process Name: FileRouter
       4. Leave the Enable Now check box clear and click OK.
       5. Click OK in the dialog box to approve the rule class name.
    Note:
    It is OK to have a grey circle in the new process since you did not enable it in the previous step.
    4. Click FileRouter on the Production Configuration page.
    5. Under the Settings tab, configure the following:
       1. Select Enabled under Basic Settings and click Apply. Click OK.
          The circle has turned green.
       2. Click 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.
    6. In the Rule Editor, create a rule that sends PDF files to WritePDFsOp and all other files to WriteFileOp:
       1. Double-click constraint in the rule and enter:
          • Source: FileService
          • Message Class: Ens.StreamContainer
       2. Click OK.
       3. Click rule in the Rule Editor, then select when in the Rule Assistant to add it to the diagram.
       4. Click condition next to when, and enter Document.OriginalFilename Contains ".pdf" in the text box that appears above the rule diagram. Click OK.
       5. Click the when clause in the diagram, then select the send action in the Rule Assistant.
       6. Double-click the target value and select the WritePDFsOp configuration item, then click OK.
          
       7. Click the when clause again, then select otherwise in the Rule Assistant.
       8. Click the otherwise clause in the diagram, then select the send action in the Rule Assistant.
       9. Double-click the target value of this send clause and select the WriteFileOp configuration item. Click OK.
          Your rule should now contain a when clause indicating that if the document is a PDF, it is sent to WritePDFsOp; otherwise, it is sent to WriteFileOp.
       10. Click Save, then OK to the prompt about the rule compilation.
    7. Return to the Production Configuration page in the Management Portal and click FileService. Under the Settings tab:
       1. Select FileRouterunder Target Config Name and clear WriteFileOp.
       2. Click Apply.
  • Test your new production

    After completing the production configuration, it is time to test it. In this example, you generated the FileService, which consumes files found in /home/project/shared/production/In/.

    The FileRouter then uses a rule to determine which Business Operation receives the file; this is based on whether or not its extension is .pdf. The target Business Operations are WritePDFsOpand WriteFileOp, respectively.

    To test the production configuration:

    1. Open the Production Configuration page and verify that all the circles are green for business services, business processes and business operations.
    2. Open the IDE using the link above.
    3. Copy the Sample.txt file located in /production/Source and paste it in the folder /production/In.
    4. Repeat the last step for the SamplePDF.pdf file.
    5. Open the /production/Out folder and verify that the .txt file was sent correctly.
    6. Open the /production/PDFsOut folder, and verify that the .pdffile was sent correctly.

    Assuming that all verification steps are accurate, the configuration of your initial production has been successful. However, the intricacy of your particular system is influenced by many factors and may not always be as straightforward as this example.

• What's next?

  What's next?

  Continue learning about productions with the following resources:

  • See a sample production and learn about receiving and routing data in a production (exercise, 10m).
  • Read the technical references for developing productions (documentation, 3h) and configuring productions (documentation, 2h).
  • Read the documentation for developing business rules (documentation, 1h).
  • Explore more samples and use cases with the Building Custom Integrations learning path (5h).

  • Share Your Feedback!