Edit

Integrate 3270 screen-driven apps on IBM mainframes with Azure using Azure Logic Apps and IBM 3270 connector

  • Article

Applies to: Azure Logic Apps (Consumption + Standard)

To access and run IBM mainframe apps, which you usually execute by navigating through 3270 emulator screens, from Consumption and Standard workflows in Azure Logic Apps, you can use the IBM 3270 connector. That way, you can integrate your IBM mainframe apps with Azure, Microsoft, and other apps, services, and systems by creating automated workflows with Azure Logic Apps. The connector communicates with IBM mainframes by using the TN3270 protocol. The IBM 3270 connector is available in all Azure Logic Apps regions except for Azure Government and Microsoft Azure operated by 21Vianet.

This how-to guide describes the following aspects about the IBM 3270 connector:

  • Why use the IBM 3270 connector in Azure Logic Apps

  • How does the IBM 3270 connector run 3270 screen-driven apps

  • Prerequisites and setup for using the IBM 3270 connector

  • Steps for adding IBM 3270 connector actions to your workflow

Why use this connector?

To access apps on IBM mainframes, you typically use a 3270 terminal emulator, often called a "green screen". This method is a time-tested way but has limitations. Although Host Integration Server (HIS) helps you work directly with these apps, sometimes, separating the screen and business logic might not be possible. Or, maybe you no longer have information for how the host applications work.

To extend these scenarios, the IBM 3270 connector in Azure Logic Apps works with the 3270 Design Tool, which you use to record, or "capture", the host screens used for a specific task, define the navigation flow for that task through your mainframe app, and define the methods with input and output parameters for that task. The design tool converts that information into metadata that the 3270 connector uses when running an action in your workflow.

After you generate the metadata file from the 3270 Design Tool, you add that file as a map artifact either to your Standard logic app resource or to your linked integration account for a Consumption logic app in Azure Logic Apps. That way, your workflow can access your app's metadata when you add an IBM 3270 connector action. The connector reads the metadata file from your logic app resource (Standard) or your integration account (Consumption), handles navigation through the 3270 screens, and dynamically presents the parameters to use with the 3270 connector in your workflow. You can then provide data to the host application, and the connector returns the results to your workflow. As a result, you can integrate your legacy apps with Azure, Microsoft, and other apps, services, and systems that Azure Logic Apps supports.

Connector technical reference

The IBM 3270 connector has different versions, based on logic app type and host environment.

Logic app Environment Connection version
Consumption Multi-tenant Azure Logic Apps Managed connector, which appears in the designer under the Enterprise label. This connector provides only single action and no triggers. For more information, see IBM 3270 managed connector reference.
Standard Single-tenant Azure Logic Apps and App Service Environment v3 (ASE v3 with Windows plans only) Managed connector, which appears in the connector gallery under Runtime > Shared, and the built-in, service provider-based connector, which appears in the connector gallery under Runtime > In-App. The built-in version differs in the following ways: -

- The built-in connector requires that you upload your HIDX file to your Standard logic app resource, not an integration account.

- The built-in connector can directly connect to a 3270 server and access Azure virtual networks using a connection string.

- The built-in version supports server authentication with TLS (SSL) encryption for data in transit, message encoding for its operation, and Azure virtual network integration.

For more information, see the following documentation:

- IBM 3270 managed connector reference
- IBM 3270 built-in connector reference

Built-in connector reference

The following section describes the operations for the IBM 3270 connector, which currently includes only the following action:

Execute a navigation plan

Parameter Required Type Description
HIDX Name Yes String Select the 3270 HIDX file that you want to use.
Method Name Yes String Select the method in the HIDX file that you want to use.
Advanced parameters No Varies This list appears after you select a method so that you can add other parameters to use with the selected method. The available parameters vary based on your HIDX file and the method that you select.

This operation also includes advanced parameters, which appear after you select a method, for you to select and use with the selected method. These parameters vary based on your HIDX file and the method that you select.

Prerequisites

  • An Azure account and subscription. If you don't have an Azure subscription, sign up for a free Azure account.

  • Access to the TN3270 server that hosts your 3270 screen-driven app

  • The Host Integration Designer XML (HIDX) file that provides the necessary metadata for the IBM 3270 connector to run your 3270 screen-driven app.

    To create this HIDX file, download and install the 3270 Design Tool. The only prerequisite is Microsoft .NET Framework 4.8.

    This tool helps you record the screens, navigation paths, methods, and parameters for the tasks in your app that you add and run as 3270 connector actions. The tool generates a Host Integration Designer XML (HIDX) file that provides the necessary metadata for the connector to run your 3270 screen-driven app.

    After you download and install this tool, follow these steps to connect with your TN3270 host server, design the required metadata artifact, and generate the HIDX file.

  • The Standard or Consumption logic app resource and workflow where you want to run your 3270 screen-driven app

    The IBM 3270 connector doesn't have triggers, so use any trigger to start your workflow, such as the Recurrence trigger or Request trigger. You can then add the 3270 connector actions.

  • An integration account, which is required based on the 3270 connector version that you use and is an Azure resource where you can centrally store B2B artifacts such as trading partners, agreements, maps, schemas, and certificates to use with specific workflow actions.

    Workflow Description
    Standard - 3270 built-in connector: Upload HIDX file to Standard logic app resource.

    - 3270 managed connector: Upload HIDX file to your Standard logic app resource or your linked integration account.
    Consumption 3270 managed connector: Upload HIDX file to your linked integration account.

    For more information, see Upload the HIDX file.

Upload the HIDX file

For your workflow to use the HIDX file, follow these steps:

  1. Go to the folder where you saved your HIDX file, and copy the file.

  2. In the Azure portal, choose the following steps, based on the connector version:

  3. Now, add an IBM 3270 action to your workflow.

Later in this guide, when you add an IBM 3270 connector action to your workflow for the first time, you're prompted to create a connection between your workflow and the mainframe system. After you create the connection, you can select your previously added HIDX file, the method to run, and the parameters to use.

Add an IBM 3270 action

A Standard logic app workflow can use the IBM 3270 managed connector and the IBM 3270 built-in connector. However, a Consumption logic app workflow can use only the IBM 3270 managed connector. Each version has different actions. Based on whether you have a Consumption or Standard logic app workflow, follow the corresponding steps:

  1. In the Azure portal, open your Standard logic app resource and workflow where you've already add a trigger.

  2. If you haven't already added a trigger, follow these general steps to add the trigger that you want to your workflow.

    This example continues with the Request trigger named When a HTTP request is received.

  3. Follow these general steps to add the IBM 3270 built-in connector action named Execute a navigation plan.

  4. When the connection information box appears, provide the following necessary parameter values:

    Property Required Value Description
    Connection Name Yes <connection-name> A name for your connection
    Code Page No <code-page> The code page number for the host to use for converting text. If left blank, the connector uses 37 as the default value.
    Device Type No <IBM-terminal-model> The model name or number for the IBM terminal to emulate. If left blank, the connector uses default values.
    Log Exception Screens No True or false Log the host screen if an error occurs during screen navigation.
    Logical Unit Name No <logical-unit-name> The specific logical unit name to request from the host
    Port Number No <TN3270-server-port> The port used by your TN3270 server. If left blank, the connector uses 23 as the default value.
    Server Yes <TN3270-server-name> The server name for your TN3270 service
    Timeout No <timeout-seconds> The timeout duration in seconds while waiting for screens
    Use TLS No On or off Turn on or turn off TLS encryption.
    Validate TN3270 Server Certificate No On or off Turn on or turn off validation for the server's certificate.

    For example:

    Screenshot shows Azure portal, Standard workflow designer, and IBM 3270 connection properties.

  5. When you're done, select Create New.

  6. When the action information box appears, provide the necessary parameter values:

    Property Required Value Description
    HIDX Name Yes <HIDX-file-name> Select the 3270 HIDX file that you want to use.
    Method Name Yes <method-name> Select the method in the HIDX file that you want to use. After you select a method, the Add new parameter list appears so you can select parameters to use with that method.
    Advanced parameters No Varies This list appears after you select a method so that you can add other parameters to use with the selected method. The available parameters vary based on your HIDX file and the method that you select.

    For example:

    Select the HIDX file

    Screenshot shows Standard workflow designer, 3270 action, and selected HIDX file.

    Select the method

    Screenshot shows Standard workflow designer, 3270 action, and selected method.

    Select the parameters

    Screenshot shows Standard workflow designer, 3270 action, and more parameters.

  7. When you're done, save your workflow. On designer toolbar, select Save.

Test your workflow

  1. To run your workflow, on the designer, select workflow menu, select Overview. On the Overview toolbar, select Run > Run.

    After your workflow finishes running, your workflow's run history appears. Successful steps show check marks, while unsuccessful steps show an exclamation point (!).

  2. To review the inputs and outputs for each step, expand that step.

  3. To review the outputs, select See raw outputs.

  4. To review the inputs and outputs for each step, expand that step.

  5. To review the outputs, select See raw outputs.

Next steps