Skip to content

User Guide

Overview

AS400Gateway for AWS is a lightweight, scalable, easy to implement component, delivered as pre-built AWS AMI, that helps surfacing IBM i business logic as standards based REST API, and enables bi-directional event streaming and data replication use cases with little to no custom development required. The product can be deployed natively in customers' AWS environment, either as a stand-alone component or in combination with other Infoview products (such as InfoCDC change data capture solution) and AWS services (API manager, SNS, Lambdas etc) to fit customers' specific infrastructure and functional requirements.

Below are sample use cases where AS400Gateway for AWS could be a good fit:

  • provide a REST API that shows stock balances, estimated delivery date and other availability and fulfillment details for various commerce channels
  • detect and send order fulfillment status changes from the IBM i ERP or WMS system to the CRM, ecommerce or third party partners
  • propagate product details from IBM i based ERP to external MDM and PIM solutions
  • send customer details from IBM i based solution to external Customer Data Platform

IBM i Prerequisites

  • IBM i OS version:V5R4 and higher
  • AWS VPC where the AMI is running must be able to reach the IBM i servers on ports 446, 449, 8470, 8472,8473,8475 and 8476 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

Quick Start Guide

Once the AWSGateway for AWS EC2 instance is running in your AWS VPC connected to your IBM i environment, and security rule allows access to port 8080 of the newly launched instance, use Postman or CURL or any other REST API client to configure and test the IBM i operations, referencing the API documentation below. Note that the product will work without a valid license for the first 15 min after the instance startup then any config and API attempts will fail due to no license error. Please reach out to Infoview sales team at sales@infoviewsystems.com or call +1(734)293-2160.

API Reference

The default API authentication is a basic auth per Postman collection. Please use the hardening instructions below to change the defaults shortly after installation, configuration and evaluation of the product.

  1. Verify that the instance is running, using GET http://public-DNS-provided-by-Amazon:8080/admin/connections. You should receive an empty array of connections (as no connections have been configured yet).
  2. Configure new IBMi (AS400, iSeries) connection using POST http://public-DNS-provided-by-Amazon:8080/admin/connections with the sample request similar to below

    Sample New Connection request

     {
        "connectionName": "test",
        "endpoint": "your-as400-endpoint",
        "userId": "userid",
        "password": "password",
        "libraryList": "comma-separated-list-of-libraries",
        "libraryListMode": "ADD_LAST",
        "jobTrace": false,
        "secureConnection": true,
    
        "tlsIsInsecure": false,
        "tlsKeystoreConfigured": false,
        "tlsTruststoreConfigured": true,
        "tlsFileName": "info400new.truststore",
    
        "licenseFileProtocol": "FILE"
        "filePath" : "license-file-location-in-instance"
        "licenseFileName": "as400-license.lic"
     }
    
  3. Verify the connection is successful by GET http://public-DNS-provided-by-Amazon:8080/admin/connections - now it should show the connection details for the newly created connection, with the status OPEN

  4. Then create new program call definition using POST http://public-DNS-provided-by-Amazon:8080/admin/connections/{connection-name}/program-calls with the sample request similar to below (the parameter definitions, i.e. type and length and sequence, would depend on the specific RPG or Cobol program you are trying to call)

    Sample New Program Call request

     {
        "programName": "POSTORDSP",
        "programLibrary": "MULEDEMOS",
        "libraryList": "MULE400DEV",
        "libraryListMode": "ADD_LAST",
        "programCallParameters": {
           "params": [
              {
              "parameterName": "orderId",
              "sourceFieldName": "$['orderID']",
              "dataType": "PACKED",
              "length": 8,
              "decimalPositions": 0,
              "usage": "INOUT",
              "count": 1,
              "dataStructureElements": []
              },
              {
              "parameterName": "orderLines",
              "sourceFieldName": "$['orderLines']",
              "dataType": "PACKED",
              "length": 4,
              "decimalPositions": 0,
              "usage": "INOUT",
              "count": 1,
              "dataStructureElements": []
              },
              {
              "parameterName": "orderLinesIn",
              "sourceFieldName": "$['orderItemsIn']",
              "dataType": "STRUCTURE",
              "length": 0,
              "decimalPositions": 0,
              "usage": "INOUT",
              "count": 10,
              "dataStructureElements": [
                 {
                    "parameterName": "item",
                    "sourceFieldName": "$['item']",
                    "dataType": "STRING",
                    "length": 35,
                    "decimalPositions": 0,
                    "usage": "INOUT",
                    "count": 1,
                    "dataStructureElements": []
                 },
                 {
                    "parameterName": "qty",
                    "sourceFieldName": "$['qty']",
                    "dataType": "PACKED",
                    "length": 11,
                    "decimalPositions": 3,
                    "usage": "INOUT",
                    "count": 1,
                    "dataStructureElements": []
                 },
                 {
                    "parameterName": "price",
                    "sourceFieldName": "$['price']",
                    "dataType": "PACKED",
                    "length": 14,
                    "decimalPositions": 4,
                    "usage": "INOUT",
                    "count": 1,
                    "dataStructureElements": []
                 }
              ]
              },
              {
              "parameterName": "orderLinesOut",
              "sourceFieldName": "",
              "dataType": "STRUCTURE",
              "length": 0,
              "decimalPositions": 0,
              "usage": "OUT",
              "count": 10,
              "dataStructureElements": [
                 {
                    "parameterName": "item",
                    "sourceFieldName": "$['item']",
                    "dataType": "STRING",
                    "length": 35,
                    "decimalPositions": 0,
                    "usage": "INOUT",
                    "count": 1,
                    "dataStructureElements": []
                 },
                 {
                    "parameterName": "qty",
                    "sourceFieldName": "$['qty']",
                    "dataType": "PACKED",
                    "length": 11,
                    "decimalPositions": 3,
                    "usage": "INOUT",
                    "count": 1,
                    "dataStructureElements": []
                 },
                 {
                    "parameterName": "price",
                    "sourceFieldName": "$['price']",
                    "dataType": "PACKED",
                    "length": 14,
                    "decimalPositions": 4,
                    "usage": "INOUT",
                    "count": 1,
                    "dataStructureElements": []
                 }
              ]
              }
           ]
        },
        "procedureName": "POSTORDERS",
        "procedureReturnsValue": false,
        "threadSafe": false
     }
    
  5. Test the REST API that surfaces the program call by using POST http://public-DNS-provided-by-Amazon:8080/api/connections/{connection-name}/program-calls/{program-call-name}, passing parameters as a request payload, for example:

    Sample New Program Call request

        {
        "orderID": 12345,
        "orderLines": 3,
        "orderItemsIn": [
           {
              "item": "ITEM1",
              "qty": 123.45,
              "price": 321.45
           },
           {
              "item": "ITEM2",
              "qty": 234.45,
              "price": 987.45
           },
           {
              "item": "ITEM3",
              "qty": 235.98,
              "price": 123.95
           }
        ]
        }
    

Product Setup and Operations

Most of the AS400Gateway for AWS functionality can be configured via admin APIs, however there are several hardening configuration steps that must be performed directly on EC2 instance. Once the AS400Gateway for AWS is configured, it will interact with external services and IBM i components via separate Functional API endpoints.

License Management

AS400Gateway for AWS requires a valid license authorized to access specific IBM i servers. The product will work without any license for the first 15 minutes after the AMI launch. Please contact to Infoview Systems Inc.

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

The product supports several internal or shared locations to place and maintain the license, including the AMI file system, S3 bucket, HTTP/HTTPS, FTP, and SMB. The license location, necessary credentials and other attributes are defined as part of Connection configuration via Admin API. Please refer the API documentation for details. Below is a summary of protocol details required for referencing the license files

# Protocol Name Properties
1 S3 s3.bucket=path-to-bucket
s3.region=us-east-2
s3.accessKey=access-key
s3.secretKey=secret-key
2 HTTP/HTTPS http.url=url-URL
http.dir.path=license-file-path
http.username=username
http.password=encrypted-pwd
3 FTP ftp.host=ftp-host
ftp.dir.path=path
ftp.username=username
ftp.password=encrypted-pwd
4 FILE/SMB file.Path=path-to-license-file

Security Hardening

AS400Gateway for AWS by default is bundled with pre-defined credentials, HTTP listener, and no IBM i connection.

  • The default authentication for Admin APIs is Basic Auth with user ID = Admin and pwd = Password
  • The default authentication for Functional API is Basic Auth with user ID = User and pwd = Password@123

As part of the product evaluation, likely the most basic security settings and non-secure IBM i connection are created. Below is a security hardening checklist to execute early in the trial / evaluation process:

  1. Configure HTTPS protocol for the API / HTTP listener
  2. Configure TLS IBM i connection
  3. Change the encryption key used to encrypt sensitive properties
  4. Encrypt all credentials and other sensitive API properties using Admin encryption API
  5. Change the default Admin and Functional API user ID and password
  6. Restrict access to APIs to specific allowed source IPs only
  7. Add rate limiting and other security policies to protect the functional APIs and

How to set up HTTPS

Create our own self-signed SSL certificate

First of all, we need to create our own self-signed SSL certificate. It is easy to generate the file with java keytool command.

After typing "keytool -genkey -alias selfsigned_localhost_sslserver -keyalg RSA -keysize 2048 -validity 700 -keypass changeit -storepass changeit -keystore ssl-server.jks " into the terminal, we will be asked a couple of questions. This will generate the ssl-server.jks keystore file containing our certificates in the directory from where keytool command has been executed.

We can use "keytool -list -keystore ssl-server.jks" command to view what is inside this keystore.

Spring boot SSL Configuration

Secondly, We need to copy the generated keystore file into the resources folder. Next, we should add the below entries to the application.properties file.

server.port=8443
server.ssl.key-alias=selfsigned_localhost_sslserver
server.ssl.key-password=changeit
server.ssl.key-store=classpath:ssl-server.jks
server.ssl.key-store-provider=SUN
server.ssl.key-store-type=JKS

We finished setting up HTTPS.

How to change the default user ID and password for admin and functional users

  1. To change the default user ID and password we should go to application-dev.properties file which is located in /opt/as400-common-api/config directory.
  2. We need to find a section for Basic Authentication.
  3. If you want to change credentials, then use the User section for Functional operations, and the Admin section for Admin operations.
  4. If you want to change user ID then find userName field and change the value.
  5. userPassword requires encryption format.
  6. Firstly, we need to encrypt the password using Admin encryption API(http://{...}/admin/encryption).
  7. Secondly, we paste the password which is encrypted in ENC() in the userPassword field.

Cluster Configuration

Cluster Configuration

Admin API definitions

The AS400Gateway for AWS comes with the following admin APIs that can be used to setup the product, either manually (via CURL / Postman / any other API client) or as part of CI / CD flow:

  1. Encryption API - allows to encrypt sensitive data like passwords or other secrets
  2. Connections - manages IBM i connection definitions. It is possible to configure a single AS400Gateway for AWS instance to connect to multiple back-end systems, however in most scenarios dedicated 1 - 1 relationship would work best to ensure the proper segregation of access rules,
  3. Program Calls - manages program call definitions that will be surfaced for the consumers as REST APIs
  4. Data Queue Listeners - manages the always-on DQ listeners that are registered to receive new DQ messages immediately after they are placed into IBMi DQ

Below is a link to the Admin API documentation

API Reference

Functional API definitions

The AS400Gateway for AWS comes with the following functional APIs out of the box:

  1. Execute Command Call API - does not require any admin / configuration
  2. Publish Data To Data Queue API or read Data Queue entry directly - does not require any admin / configuration
  3. Execute Program CAll API - requires the program call configuration via Admin API (see above)
  4. Listen for new Data Queue entry and copy to AWS SNS topic - requires the DQ Listener configuration via Admin API (see above)

Below is a link to the Admin API documentation

API Reference

Data Replication with AS400Gateway for AWS and InfoCDC

InfoCDC and AS400Gateway for AWS Data Replication Guide