Skip to content

MuleSoft Certified Connector

Introduction

The Infoview Systems InfoConnect suite of products eliminates the stress and impact of IBM i legacy system integration on development teams. It minimizes the time and resources spent on building integrations by hand, and it enables non-IBM i developers to unlock legacy business logic and data directly from their modern integration development stack. Certified and rigorously tested by MuleSoft, the connector accelerates IBM i integrations with other systems and services.

Infoview is a global, cross-platform service team with fluency in legacy and modern technology stacks, including MuleSoft and IBM i. A dedicated customer success representative coordinates just-in-time technical assistance and support for your team. Infoview can provide a trial license, take part in discovery sessions, run live demos of typical integration scenarios with the Gateway products, and assist with or perform a proof of concept for your use case.

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

IBM i connector for MuleSoft overview

The IBM AS/400 was first introduced in 1988 and evolved into a stable, modern, all-purpose integrated solution that requires little or no management. The system runs core line-of-business applications securely and predictably, focuses on quality of service and availability, and offers a compelling total cost of ownership for integrated on-premises solutions. IBM changed the server and OS name several times (iSeries, System i, IBM i, Power Systems for i), but most people 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 / email, DB2 interfaces, data queues, and the integrated file system (IFS), as well as a number of products from IBM and third-party vendors. The main benefit of "native" options such as Program Calls and data queues is that the IBM i development team does not have to learn another language or purchase and support another technology to build the integration layer. The team can communicate with external systems using only traditional development tools.

Program Call is the most straightforward, low-code option for surfacing IBM i business logic as a reusable asset. The IBM i connector enables direct program calls from a 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 communication. They are lightweight, persistent queues that support processing by key, FIFO, or LIFO. Most integration use cases can be implemented with a pair of request and response data queues:

  1. The source system places a message on the request data queue and waits for an acknowledgement message on the response data queue.
  2. The target system receives and processes a message from the request data queue, then places the acknowledgement on 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, which makes it fast and easy to develop IBM i code that communicates with Mule.

Prerequisites

  • Familiarity with IBM i operational and development environments and tools. The connector works with IBM i objects (programs, service programs, data queues, and commands).
  • Familiarity with Mule, Anypoint Connectors, and Anypoint Studio.

The examples in this manual use Anypoint Studio, the graphical user interface of Mule ESB, and include the equivalent configuration details for the XML Editor.

Dependencies

  • Access to an 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

Installing the connector

  1. Open the pom.xml file in the project root folder and add the following dependency:

    <dependency>
        <groupId>com.infoview.mule</groupId>
        <artifactId>as400-connector</artifactId>
        <version>2.6.0</version>
        <classifier>mule-plugin</classifier>
    </dependency>
    
  2. Find the AS400 connector in the Mule Palette window.

    Mule Palette window filtered by AS400, listing the Command call, Program call processor, Read data queue, Read data queue processor, and Write data queue operations

License

The IBM i connector requires a license key from Infoview to enable access to specific IBM i systems. Contact the Infoview Systems IBM i Connector support team at (734) 293-2160 or mule400@infoviewsystems.com.

In addition to the Infoview license, the connector runs only on MuleSoft Enterprise runtimes.

IBM i server configuration and requirements

  • Ports 446, 449, 8470, 8472, 8473, 8475, and 8476 must be accessible from the Mule runtime for non-SSL communication. Ports 448, 449, 9470, 9472, 9473, 9475, and 9476 must be accessible for SSL communication.
  • The *CENTRAL, *DTAQ, *RMTCMD, *SIGNON, and *SRVMAP host servers must be running in the QSYSWRK subsystem.
  • If you use a secure TLS connection, apply the TLS certificate to the Central, Data Queue, Remote Command, File, Signon, and DDM / DRDA services in Digital Certificate Manager.
  • The IBM i user ID must be authorized to perform the operations on the intended IBM i objects.
  • If additional security software locks down remote execution, the IBM i user ID defined in the connector configuration must be allowed to execute remote calls and access the database, IFS, and DDM services.

Configuring the IBM i connector

To use the IBM i connector in your Mule application, configure a global IBM i connection strategy element that all IBM i connectors in the application can use.

  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 Element Properties dialog for AS400 Config with the General tab of the connection settings

    Parameter Description Mandatory Default
    Name Enter a name for the configuration so the flow can reference it later with the config-ref parameter. Optional AS400_Config
    URL Enter the IBM i endpoint. Required --
    UserID Enter the user name that can connect to IBM i. Required --
    Password Enter the password for the IBM i user. Required --
    IASP Enter the independent auxiliary storage pool (IASP) name. Optional --
    LibraryList Enter a comma-separated list of libraries (if any) to add to the library list for Command Call execution. Optional --
    LibraryListMode Select the mode for adding the user libraries defined in LibraryList. Supported modes: ADD_FIRST, ADD_LAST, REPLACE. Optional ADD_FIRST
    AS400JobTrace Adds IBM i job metadata to the predefined local variable attributes.as400JobMetadata. Optional false
    LicenseUrl Enter the fully qualified URL path and name of the license file. See License URL formats. Optional as400-license.lic
    Secure Connection When true, the connector tries to establish a secure SSL / TLS connection with the IBM i endpoint. Optional false
    Socket Timeout Maximum socket timeout for the IBM i connection. The value -1 means the default system value is used. Optional -1
    Connection Retries Number of internal connection retries within the connector configuration before the exception is raised to the MuleSoft runtime and connection management. Optional 3
    Connection TTL Time that a connection stays active (time to live). 0 means no limit. Optional 0
    TLS Configuration Reference to a TLS configuration element. Enables a secure connection for this configuration. Optional --
  4. Click OK to save the global connector configuration.

  5. Return to the Message Flow tab in Studio.

License URL formats

The LicenseUrl parameter supports the following transports and formats:

Transport Format
HTTP http://<path>
HTTPS https://<path>
HTTPS with basic authentication https://<path>?useraname=param1&password=param2
SMB smb://<ip-address>/<path>
SMB with credentials smb://username:password@<ip-address>/<path>
FILE file:/<full-path>
CLASSPATH classpath:<path>
S3 s3://<s3-url>?region=param1&accessKey=param2&secretKey=param3
FTP ftp://<ip-address>/<path>?username=param1&password=param2

TLS configuration

The TLS configuration element has one parameter:

Parameter Description
Truststore Stores the certificates from certificate authorities (CA) that verify the certificate the server presents in an SSL connection.

Truststore

Parameter Description Mandatory Default
Path Location of the trust store, resolved relative to the current classpath and file system if possible. Required --
Password Password that protects the trust store. Required --
Type Type of store used. Optional --
Algorithm Algorithm used by the trust store. Optional --
Insecure If true, the connector performs no certificate validation, which makes connections vulnerable to attacks. Use at your own risk. Optional --

Connector operations

The IBM i connector is an operation-based connector. When you add the connector to your flow, you configure the specific operation that the connector performs. The connector supports the following operations:

Operation Description
Read Data Queue (Message Source) Listens continuously for new messages arriving on a specific data queue.
Read Data Queue (Processor) Reads messages from a specific data queue as part of the Mule flow.
Write to Data Queue Writes messages to a data queue.
Command Call Executes an IBM i command.
Program Call Executes an IBM i program or service program procedure.

Configuring the 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 the following connector parameters:

    Read data queue source properties with the connector configuration, data queue, library, key, and format file settings

    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 created. Required --
    Data Queue Enter the data queue name. Required --
    Library Enter the data queue library name. Required --
    Key Required for keyed data queues. Leave blank for non-keyed data queues. To read any message from the data queue, enter ' '. Optional --
    Key Search Type Required for keyed data queues. To read any message from the data queue, enter Greater or Equal. Optional Empty
    Keep messages in Queue Ensure it is unchecked. Required false
    Format File Name Treats the data queue entry as an externally defined data structure. When defined, the connector dynamically retrieves the record format from the specified IBM i file and parses the received entry into a map of field name / value pairs. The connector performs the type conversion and supports all types, such as packed and date / time. Optional --
    Format File Name Position Gets the format file name dynamically from the data queue entry: 10 characters starting from the given position. If set to -1, the static Format File Name is used. Optional -1
    Format File Library When a format file is specified, you can also specify its library. Otherwise the connector locates the format file using the connection library list. Optional *LIBL
    Format File Library Position Gets the format file library name dynamically from the data queue entry: 10 characters starting from the given position. If set to -1, the static Format File Library is used. Optional -1
    Format Exception Action Defines how to process a message that fails while the data queue entry is treated as an externally defined data structure. Supported values: PLACE_BACK_INTO_QUEUE, DISCARD. Optional DISCARD
    Polling period Time between message reads, in milliseconds. You can use it for crude throttling. 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, in milliseconds. Optional 1000
    Reconnection period time unit Time unit for the reconnection period. Optional MILLISECONDS

When the listener receives a message from the data queue, it places the message text into the payload and saves the message key (if any) into #[attributes.key].

The output payload format depends on whether you specify a format file. With a format file, the output is a Map whose keys are the format field names and whose values are the data for each field. Without a format file, the data queue entry is returned as a String.

Configuring the Data Queue Reader (message processor)

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

    Read data queue processor properties with the data queue, library, key, key search type, and format file settings

    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 created. Required --
    Data Queue Enter the data queue name. Required --
    Library Enter the data queue library name. Required --
    Key Required for keyed data queues. Leave blank for non-keyed data queues. To read any message from the data queue, enter ' '. Required --
    Key Search Type Required for keyed data queues. To read any message from the data queue, enter Greater or Equal. Required Empty
    Keep messages in Queue Ensure it is unchecked unless you want to leave the message in the queue after reading. Required false
    Format File Name Treats the data queue entry as an externally defined data structure. When defined, the connector dynamically retrieves the record format from the specified IBM i file and parses the received entry into a map of field name / value pairs. The connector performs the type conversion and supports all types, such as packed and date / time. Optional --
    Format File Name Position Gets the format file name dynamically from the data queue entry: 10 characters starting from the given position. If set to -1, the static Format File Name is used. Optional -1
    Format File Library When a format file is specified, you can also specify its library. Otherwise the connector locates the format file using the connection library list. Optional *LIBL
    Format File Library Position Gets the format file library name dynamically from the data queue entry: 10 characters starting from the given position. If set to -1, the static Format File Library is used. Optional -1
    Format Exception Action Defines how to process a message that fails while the data queue entry is treated as an externally defined data structure. Supported values: PLACE_BACK_INTO_QUEUE, DISCARD. Optional DISCARD

When the processor receives a message from the data queue, it places the message text into the payload and saves the message key (if any) into #[attributes.key].

The output payload format depends on whether you specify a format file. With a format file, the output is a Map whose keys are the format field names and whose values are the data for each field. Without a format file, the data queue entry is returned as a String.

Configuring the Data Queue Writer

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

    Write data queue properties with the data queue, library, data entry, key, and format file settings

    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 created. Required --
    Data Queue Enter the data queue name. Required --
    Library Enter the data queue library name. Required --
    Data Entry Enter the data queue message text. Optional --
    Key Required for keyed data queues. Leave blank for non-keyed data queues. To read any message from the data queue, enter ' '. Optional --
    Format File Name Treats the data queue entry as an externally defined data structure. When defined, the connector expects a JSON string as the data queue entry. It dynamically retrieves the record format from the specified IBM i file and converts the JSON string into a binary byte array that IBM i can interpret as a data structure. The JSON string must contain a list of elements, each with an element name that matches a format file column name and its value. The connector performs the type conversion and supports all types, such as packed and date / time. Optional --
    Format File Library When a format file is specified, you can also specify its library. Otherwise the connector locates the format file using the connection library list. Optional *LIBL
    DQ Entry Length Maximum data queue entry length. When greater than 0, the value is truncated to fit the maximum length. Optional 0
    DQ Key Length Maximum data queue key length. When greater than 0, the connector uses this value instead of retrieving it dynamically from the data queue definition on the server. Optional 0

Configuring the Command Call

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

    Command call properties with the connector configuration and the command to run

    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 created. Required --
    Command Enter the IBM i command. Optional #[payload]

Configuring the Program Call and Service Program procedure call

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

    Program call processor properties with the program, library list, timeout settings, and an inline parameter list

    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 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) to add to the library list. Optional --
    LibraryListMode Select the mode for adding the user libraries defined in the program call LibraryList. Supported modes: ADD_FIRST, ADD_LAST, REPLACE. Optional ADD_FIRST
    Reset Library List on Each Call If true, the library list is reset for each program call. Otherwise the library list is set only on the first call and then reused. Optional false
    Service Program Procedure Name Enter the name of the service program procedure. Optional --
    Procedure Returns Value Indicates whether the service program procedure returns a value. Optional false
    Thread safe Indicates whether the program is thread safe. Optional false
    Call Timeout Timeout of the program call. A value of 0 or a negative value means no specific call timeout. Optional -1
    Call Timeout Unit Time unit for the call timeout. Optional MILLISECONDS
    Parameters List of definitions and value references of the program parameters. Optional None
  3. To run a program with arguments, set Parameters to Expression or Edit inline, then specify the list of program parameter definitions and value references.

    Parameter dialog for the orderID parameter with data type, length, usage, count, and value

    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, in bytes. Optional 0
    Decimal positions Number of decimal positions. Optional 0
    Usage In, Out, or Inout. Required Empty
    Count For array parameters, the 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 the CCSID (Character Code Set ID) for a particular program call parameter. Otherwise the default system-level CCSID is used. Applies only to STRING types. Optional 0
    Dbcs Enables DBCS (double-byte character set) for a particular program call parameter. The connector internally recalculates the bytes required to pass into or receive from the program. Optional false

Service Program procedure call limitations

The IBM i external Service Program call API (QZRUCLSP) imposes the following limitations on Service Program procedure calls:

  • A call can have a maximum of 7 parameters. Each parameter can be a data structure or an array of data structures.
  • If the procedure returns a value, it must be an integer.

Contact us

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

See also