Diagrama de temas

• Creating a Basic Production in InterSystems IRIS

  Creating a Basic Production in InterSystems IRIS

  Content Type
  Exercise

  Duration
  20m

  Level
  Introductory

  See how to easily integrate systems, applications, data sources, and databases in real time with an InterSystems IRIS® data platform production—an integration framework for easily connecting systems and for developing applications for interoperability. It provides built-in connections to a wide variety of message formats and communication protocols. In this exercise, you will use pre-built business services, processes, and operations—so you do not have to download or write any code.

  Learning Objectives

  • Create and configure a basic production with inbound and outbound file adapters.
  • Apply routing logic to process and forward files based on their file type.
  • Test and trace the flow of messages within the production to verify proper file handling and routing.

  Prerequisites

  None
• Start the Exercise

  Start the Exercise
  • Launch Your Lab

    You are provided with a free temporary instance of InterSystems IRIS for use in this exercise. Click the button in the launcher below to launch your lab.

    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 start the exercise.

  • Launch the virtual machine (VM) below to begin working on the exercise. For responses to common questions on using VM-based Learning Labs, visit FAQ: Using Learning Services Virtual Machines.

    Your login information for the VM is the following:

    • Username: student
    • Password: LearningServices7
  •  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 task, you will create a generic production that can be used for any purpose.

    1. In Google Chrome, use the IRIS bookmark to launch the system Management Portal.
    2. Log in with username tech and password demo7.
    3. Check that you are in the USER namespace, an interoperability-enabled namespace that has the package mappings you will need for a production.
    4. Navigate to Interoperability > List > Productions.
    5. Click New to create a new production.
    6. Specify TEST as the package name and FileProd as the production name.
    7. 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.

  • 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.
  • Add a file-processing service

    Now you will add and configure the main service 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 Services Name  FileService.
    4. Leave the Enabled check box clear.
    5. Click OK.
  • Add file-processing operations

    Now you will add and configure two operations in the production. Repeat the following steps twice to create 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.
    4. Leave the Enabled check box clear.
    5. Click OK.

    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 /external with Data/In and Data/Out folders. 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: /external/In
       3. Archive Path: /external/Work
       4. Work Path: /external/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: /external/Out
          • WritePDFsOp operation: /external/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 Visual Studio Code.
    3. Copy the Sample.txt file from /Data/Source and paste it into the /Data/In directory.

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

    • In a few seconds, the file is moved from the /Data/In directory to the /Data/Work directory. A time stamp is appended to the file specification.
    • A new copy of the file is written to the /Data/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 the rule and enter the following in Constraints:
          • Source: FileService
          • Message Class: Ens.StreamContainer
       2. Click OK.
       3. Click rule in the Rule Editor, then select  condition to add it to the diagram.
       4. Click condition next to if, and enter Document.OriginalFilename Contains ".pdf" in the text box that appears above the rule diagram. Click OK.
       5. Click the then clause in the diagram, then select the send action in the Rule Assistant.
       6. Double-click the send action to edit it. In the Target dropdown, select the WritePDFsOp configuration item, then click OK.
          
       7. Click the then clause again, then select return in the Rule Assistant to add it to the diagram.
       8. Click the rule again, then select else in the Rule Assistant.
       9. Click the else clause in the diagram, then select the send action in the Rule Assistant.
       10. Double-click the target value of this send clause and select the WriteFileOp configuration item. Click OK.
       11. Add a return to the else clause.
           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.
       12. Click Compile to save and compile the rule.
    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 /external/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 Visual Studio Code.
    3. Copy the Sample.txt file located in /Data/Source and paste it in the folder /Data/In.
    4. Repeat the last step for the SamplePDF.pdf file.
    5. Open the /Data/Out folder and verify that the .txt file was sent correctly.
    6. Open the /Data/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!