Skip to content

User manual

Mulesoft Certified Connector

Introduction

Infoview Systems InfoConnect suite of products eliminates the stress and impact of IBM i / AS400 legacy system integration on development teams, minimizes the time and resources put into building integrations by hand, and enables non-IBM i developers to unlock legacy business logic and data directly from the comfort of their modern integration development stack. Certified and rigorously tested by MuleSoft, the connector was designed to accelerate IBM i / AS400 integrations with other systems and services.

We are a global cross-platform service team with a unique fluency in legacy and modern technology stacks, including Mulesoft and IBM i / AS400. Infoview's dedicated customer success representative coordinates just-in-time technical assistance and support to client teams ensuring you have all the help you may need, when you need it. We are more than happy to provide a trial license for our products, participate in discovery sessions, run live demos for typical integration scenarios with our Gateway products, as well as assist with or perform a proof of concept based on particular use cases.

Contact us for connector pricing info, trial license, or support questions.

IBM i / AS400 Connector for Mulesoft Overview

The IBM AS/400 was first introduced in 1988 and evolved into a very stable modern all-purpose integrated solution that requires little or no management. The system is able to run core line of business applications securely and predictably, focusing on quality of service and availability and offering a compelling total cost of ownership for integrated on-premises solutions. IBM made several changes to the server and OS name (iSeries, System i, IBM i, Power Systems for i) but most still refer to it as AS/400.

The IBM i platform offers a number of integration options including PHP, Java, WebSphere, specialized lightweight web service containers, FTP, SMTP / emails, DB2 interfaces, data queues, integrated file systems - IFS, as well as number of products offered by IBM and Third party vendors. The main benefit of using "native" options such as Program Calls and Data Queues is that IBM i development team does not have to learn another language or purchase and support another technology in order to build integration layer, and can easily communicate with external systems using only traditional development tools.

Program Call is the most straightforward and low code option for exposing IBM i business logic as a reusable asset. The IBM i connector enables direct program calls from Mule application, passing parameters into the program and receiving the results back in real time.

Data queues are native IBM i objects designed primarily for inter-process communications. They are lightweight persistent queues that support processing by a key, FIFO or LIFO. The majority of integration use cases can be implemented with the pair of request and response Data Queues. Source system places a message to request data queue and waits for acknowledgement message on response data queue. The target system receives and processes a message from the request data queue then places the acknowledgement to the response data queue.

The IBM i connector makes it easy to build Mule code that talks to IBM i applications. Infoview Systems also built the IBM i Web Transaction Framework that makes it very fast and easy to develop IBM i code that communicates with Mule.

Prerequisites

The connector is designed to work with IBM i objects (programs, service programs, data queues and commands) and therefore this document assumes you are familiar with IBM i operational and development environments and tools.

This document assumes you are familiar with Mule, Anypoint Connectors, and Anypoint Studio.

This document describes implementation examples within the context of Anypoint Studio, Mule ESB's graphical user interface, and, in parallel, includes configuration details for doing the same in the XML Editor.

Dependencies

  • Access to IBM i server

  • Mule Enterprise runtime or Anypoint Studio

Compatibility Matrix

Application/Service Version

Mule Runtime

4.1 or higher

Anypoint Studio

7.1 or higher

IBM i / OS400

V5R4 or higher

Installing and Configuring

Installation instructions

To install the connector open the pom.xml file in the project root folder, and add the following dependency:

as400-connector

<dependency>
    <groupId>com.infoview.mule</groupId>
    <artifactId>as400-connector</artifactId>
    <version>2.6.0</version>
    <classifier>mule-plugin</classifier>
</dependency>

After that you should be able to find AS400 connector in the Mule Pallete window.

connector_on_pallete

The IBM i connector requires a license key from Infoview to enable access to specific IBM i system(s). Please contact Infoview Systems IBM i Connector support team at (734) 293-2160 or via email mule400@infoviewsystems.com

In addition to Infoview license, the connector can only run on Mulesoft Enterprise runtimes.

IBM i server configuration and requirements

  • IBM i must have ports 446, 449, 8470, 8472,8473,8475 and 8476 accessible from Mule runtime for non-SSL communications, and ports 448, 449, 9470, 9472, 9473, 9475 and 9476 accessible for SSL communications

  • IBM i must have *CENTRAL, *DTAQ, *RMTCMD, *SIGNON and *SRVMAP host servers running in the QSYSWRK subsystem

  • If secure TLS connection is used, the TLS certificate must be applied to Central, Data Queue, Remote Command, File, Signon, and DDM / DRDA services in Digital Certificate Manager

  • IBM i user ID must be authorized to perform the operations on the intended IBM i objects

  • If there's an additional security software that locks down the remote execution functionality, the IBM i user ID defined for connector configuration must be allowed to execute remote calls and access database, IFS and DDM services

Configuring the IBM i Connector

To use the IBM i connector in your Mule application, you must configure global IBM i Connection Strategy element that can be used by all the IBM i connectors in the application

Follow these steps to configure IBM i connector in a Mule application:

  1. Click the Global Elements tab at the base of the canvas, then click Create.

  2. In the Choose Global Type menu, use the filter to locate and select AS400 Config, then click OK.

  3. Configure the parameters according to the table below.

    global_config

    Parameter Description Mandatory Default Value

    Name

    Enter a name for the configuration so it can be referenced later by the config-ref parameter in the flow.

    Optional

    AS400_Config

    URL

    Enter the IBM i endpoint.

    Required

    --

    UserID

    Enter the username that can connect to IBM i.

    Required

    --

    Password

    Enter the password for the above IBM i.

    Required

    --

    IASP

    Enter the IASP name.

    Optional

    --

    LibraryList

    Enter a comma separated list of libraries (if any) that needs to be added to the library list for Command call execution.

    Optional

    --

    LibraryListMode

    Choose mode of adding user libraries that established in LibraryList. Supported modes: ADD_FIRST, ADD_LAST, REPLACE

    Optional

    ADD_FIRST

    AS400JobTrace

    Add AS400 job metadata to the pre-defined local variable attributes.as400JobMetadata

    Optional

    False

    LicenseUrl

    Enter a fully qualified URL path and name of the license file. Supported transports are: HTTP/HTTPS http://path; https://path;. For using Basic auth: https://path;?useraname=param1&password=param2

    SMB smb://ipaddress;/path; . smb://username:password@ipaddres;/path;

    FILE file:/fullpath;

    CLASSPATH classpath:path;

    S3 s3://s3-url;?region=param1&accessKey=param2&secretKey=param3

    FTP ftp://ipaddres;/path;?username=param1&password=param2

    Optional

    as400-license.lic

    Secure Connection

    When True, the connector will try to establish secure SSL / TLS connection with IBM i endpoint.

    Optional

    False

    Socket Timeout

    Max socket timeout value for the AS400 connection. The value of -1 indicates the default system value is used

    Optional

    -1

    Connection Retries

    Number of connection retries internally within AS400 connector configuration before the exception is raised to Mulesoft runtime and connection management.

    Optional

    3

    Connection TTL

    Connection Active Time (Time to Live), 0 - no limit.

    Optional

    0

    TLS Configuration

    Reference to a TLS config element. This will enable secure connection for this config.

    Optional

    --

  4. Click OK to save the global connector configurations.

  5. Return to the Message Flow tab in Studio.

TLS Configuration

Parameter Description Mandatory Default Value

Truststore

Truststore is used to store certificates from Certified Authorities (CA) that verify the certificate presented by the server in SSL connection.

Truststore

Parameter Description Mandatory Default Value

Path

The location (which will be resolved relative to the current classpath and file system, if possible) of the trust store.

Required

--

Password

The password used to protect the trust store.

Required

--

Type

The type of store used.

Optional

--

Algorithm

The algorithm used by the trust store.

Optional

--

Insecure

If true, no certificate validations are performed, rendering connections vulnerable to attacks. Use at your own risk.

Optional

--

Connector Operations

The IBM i connector is an operation-based connector, which means that when you add the connector to your flow, you need to configure a specific operation the connector is intended to perform. The connector supports the following operations:

Operation Description

Read Data Queue (Message Source)

Perpetually listen for new messages arriving to specific data queue.

Read Data Queue (Processor)

Read messages from specific data queue as part of Mule flow.

Write to Data Queue

Write messages to data queue.

Command Call

Execute IBM i command call.

Program Call

Execute IBM i program or Service program procedure.

Configuring the IBM i Data Queue Listener (Message Source)

  1. Drag the Read data queue component onto the Message Source area of the flow and select it to open the Properties Editor console.

  2. Configure these connector parameters:

    source_config

    Field Description Mandatory Default

    Display Name

    Enter a unique label for the connector in your application.

    Optional

    Read data queue

    Connector Configuration

    Select the global IBM i connector element that you just created.

    Required

    --

    Data Queue

    Enter Data Queue name.

    Required

    --

    Library

    Enter Data Queue library name.

    Required

    --

    Key

    Must be specified for keyed data queues and blank for non-keyed data queues. For reading any message from data queue, enter ' '.

    Optional

    --

    Key Search Type

    Must be specified for keyed data queues. For reading any message from data queue, enter Greater or Equal.

    Optional

    Empty

    Keep messages in Queue

    Ensure it is unchecked.

    Required

    false

    Format File Name

    Optional parameter allows treating data queue entry as an externally defined data structure. When defined, the connector will dynamically retrieve the record format from the the specified IBMi file, and parse the received data queue entry into the map of field name / value pairs. The connector will perform the type conversion, supporting all types such as packed, date / time etc

    Optional

    --

    Format File Name Position

    Optional parameter allows to dynamically get format file name from data queue entry by getting 10 characters starting from the given starting position. If it's set to -1, static Format File Name definition is used

    Optional

    -1

    Format File Library

    When format file is specified, the format file library can also be specified, otherwise the format file will be located based on the connection library list.

    Optional

    *LIBL

    Format File Library Position

    Optional parameter allows to dynamically get format file library name from data queue entry by getting 10 characters starting from the given starting position. If it's set to -1, static Format File Library definition is used

    Optional

    -1

    Format Exception Action

    Optional parameter allows to process message failed while treating data queue entry as an externally defined data structure. Supported values: PLACE_BACK_INTO_QUEUE, DISCARD

    Optional

    DISCARD

    Polling period

    Time between message reads, ms. Can be used as crude throttling configuration

    Optional

    1

    Number of consumers

    Number of Data Queue Listener threads.

    Optional

    4

    Connection retries

    Number of times to retry.

    Optional

    -1

    Reconnection period

    Time between internal reconnection retries, ms

    Optional

    1000

    Reconnection period time unit

    Time unit to be used for reconnection period

    Optional

    MILLISECONDS

If message is received from the data queue, message text will be placed into payload and message key (if any) will be saved into #[attributes.key]

The output payload format depends on whether the external data format. When the format file has been specified, the output is a Map, where keys are format field names, and the values represent the data for each field. When no format file has been specified, the data queue entry will be returned as a String.

Configuring the IBM i Data Queue Reader (Message Processor)

  1. Drag the Read data queue processor component onto the Message Flow area (other than message source) and select it to open the Properties Editor console.

  2. Configure these connector parameters:

    read_config

    Field Description Mandatory Default

    Display Name

    Enter a unique label for the connector in your application.

    Required

    Read data queue processor

    Connector Configuration

    Select the global IBM i connector element that you just created.

    Required

    --

    Data Queue

    Enter Data Queue name.

    Required

    --

    Library

    Enter Data Queue library name.

    Required

    --

    Key

    Must be specified for keyed data queues and blank for non-keyed data queues. For reading any message from data queue, enter ' '.

    Required

    --

    Key Search Type

    Must be specified for keyed data queues. For reading any message from data queue, enter Greater or Equal.

    Required

    Empty

    Keep messages in Queue

    Ensure it is unchecked unless the intent is to leave the message in the queue after reading.

    Required

    False

    Format File Name

    Optional parameter allows treating data queue entry as an externally defined data structure. When defined, the connector will dynamically retrieve the record format from the the specified IBMi file, and parse the received data queue entry into the map of field name / value pairs. The connector will perform the type conversion, supporting all types such as packed, date / time etc

    Optional

    --

    Format File Name Position

    Optional parameter allows to dynamically get format file name from data queue entry by getting 10 characters starting from the given starting position. If it's set to -1, static Format File Name definition is used

    Optional

    -1

    Format File Library

    When format file is specified, the format file library can also be specified, otherwise the format file will be located based on the connection library list.

    Optional

    *LIBL

    Format File Library Position

    Optional parameter allows to dynamically get format file library name from data queue entry by getting 10 characters starting from the given starting position. If it's -1, static Format File Library definition is used

    Optional

    -1

    Format Exception Action

    Optional parameter allows to process message failed while treating data queue entry as an externally defined data structure. Supported values: PLACE_BACK_INTO_QUEUE, DISCARD

    Optional

    DISCARD

If message is received from the data queue, message text will be placed into payload and message key (if any) will be saved into #[attributes.key]

The output payload format depends on whether the external data format. When the format file has been specified, the output is a Map, where keys are format field names, and the values represent the data for each field. When no format file has been specified, the data queue entry will be returned as a String.

Configuring the IBM i Data Queue Writer

  1. Drag the Write data queue component onto the Message Flow area (other than message source) and select it to open the Properties Editor console.

  2. Configure these connector parameters:

    write_config

    Field Description Mandatory Default

    Display Name

    Enter a unique label for the connector in your application.

    Optional

    Write data queue

    Connector Configuration

    Select the global IBM i connector element that you just created.

    Required

    --

    Data Queue

    Enter Data Queue name.

    Required

    --

    Library

    Enter Data Queue library name.

    Required

    --

    Data Entry

    Enter Data Queue Message Text.

    Optional

    --

    Key

    Must be specified for keyed data queues and blank for non-keyed data queues. For reading any message from data queue, enter ' '.

    Optional

    --

    Format File Name

    Optional parameter allows treating data queue entry as an externally defined data structure. When defined, the connector expects the JSON string to be passed as Data Queue Entry. The connector will dynamically retrieve the record format from the the specified IBMi file, parse the JSON string passed into the processor, into a binary byte array that can be interpreted on IBM i side as a data structure. The JSON string must have a list of elements with element name matching the format file column name, and associated value. The connector will perform the type conversion, supporting all types such as packed, date / time etc

    Optional

    --

    Format File Library

    When format file is specified, the format file library can also be specified, otherwise the format file will be located based on the connection library list.

    Optional

    *LIBL

    DQ Entry Length

    Max DQ Entry Length. When specified and greater than 0, the parameter value will be truncated to fit the max length.

    Optional

    0

    DQ Key Length

    Max DQ Key Length. When specified and greater than 0, the parameter value will be used (instead of dynamically retrieving it from DQ definitions on the server).

    Optional

    0

Configuring the IBM i Command Call

  1. Drag the Command call component onto the Message Flow area (other than message source) and select it to open the Properties Editor console.

  2. Configure these connector parameters:

    command_call_config

    Field Description Mandatory Default

    Display Name

    Enter a unique label for the connector in your application.

    Optional

    Command call

    Connector Configuration

    Select the global IBM i connector element that you just created.

    Required

    --

    Command

    Enter IBM i command.

    Optional

    #[payload]

Configuring the IBM i Program Call and Service Program Procedure Call

  1. Drag the Program call component onto the Message Flow area (other than message source) and select it to open the Properties Editor console.

  2. Configure these connector parameters:

    program_call_config

    Field Description Mandatory Default

    Display name

    Enter a unique label for the connector in your application.

    Optional

    Program call processor

    Connector Configuration

    Select the global IBM i connector element that you just created.

    Required

    --

    Program or Service Program name

    Enter the program or Service Program name.

    Required

    --

    Program library

    Enter the library name.

    Required

    --

    LibraryList

    Enter a comma separated list of libraries (if any) that needs to be added to the library list.

    Optional

    -—

    LibraryListMode

    Choose mode of adding user libraries established in LibraryList program call. Supported modes: ADD_FIRST, ADD_LAST, REPLACE

    Optional

    ADD_FIRST

    Reset Library List on Each Call

    Parameter allows to reset library list to set it for each program call iteration if true, otherwise Library List will be set only on first call and then reused

    Optional

    False

    Service Program Procedure Name

    Enter the name of service program procedure.

    Optional

    --

    Procedure Returns Value

    Indicator if the service program procedure returns a value.

    Optional

    False

    Thread safe

    Indicator if the program is thread safe.

    Optional

    False

    Call Timeout

    Timeout of program call. By default the call timeout is 0 or negative - meaning no specific call timeout

    Optional

    -1

    Call Timeout Unit

    Call timeout time unit

    Optional

    MILLISECONDS

    Parameters

    List of definitions and value references of program parameters.

    Optional

    None

    There are several limitations for Service Program procedure call, imposed by the IBM i (AS400) external Service Program call API (QZRUCLSP):

    • Max 7 parameters are allowed (each parameter can be data structure or array of data structures)

    • If the procedure returns a value, it must be an integer

  3. In the case when it's need to run program with arguments, the Parameters property must be set to Expression or Edit inline, and list of definitions and value references of program parameters must be specified.

    program_call_parameter_config.png

    Field Description Mandatory Default

    Parameter name

    Enter a unique label for the program parameter

    Required

    --

    Data type

    Select the IBM i data type.

    Required

    Empty

    Length

    Parameter length, bytes

    Optional

    0

    Decimal positions

    Decimal points

    Optional

    0

    Usage

    In / Out / Inout

    Required

    Empty

    Count

    For array parameters, number of elements in the array

    Optional

    1

    Data structure element

    Nested parameter definitions for each data structure element

    Optional

    None

    Parameter value

    Enter the parameter value.

    Optional

    --

    Ccsid

    Enter CCSID(Character Code Set ID) for particular program call parameter, otherwise default system level CCSID will be used. Only applies to STRING types

    Optional

    0

    Dbcs

    Parameters allows to enable DBCS(Double Byte Character Sets) for particular program call parameter. It will internally recalculate the bytes required to pass into the program or receive from the program

    Optional

    False

Contact Us

Contact us for connector pricing info, trial license, or support questions.

See Also