User Guide
Overview
InfoConnect Hub is a lightweight, scalable, easy to implement stand-alone component, that helps to surface 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 on any Java enabled infrastructure, including on-prem and cloud environments as well as directly on IBM i, either as a stand-alone component or in combination with other Infoview products (such as InfoCDC change data capture solution) and other integration services (API manager, messaging or event streaming platforms etc.) to fit customers' specific infrastructure and functional requirements.
Below are sample use cases where InfoConnect Hub 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
- The Hub 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 is 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
- Contact Infoview to get the Hub distribution package and a trial license, or launch the Hub from the participating marketplaces such as AWS Marketplace or Azure Marketplace
- Download and run the Hub on any Java supported on-prem or cloud infrastructure, including IBM i. Note the Hub must be able to reach the target IBM i ports listed above. You can run the Hub using infoConnectHub.sh script for Linux / AIX / IBMi based platforms, and infoConnectHub.bat script for Windows. The script will prompt the user to enter the encryption password, which the Hub uses to encrypt and decrypt sensitive properties. If you want to run it manually or set up the Hub to run as a service, then execute following command from [project-folder]/executable-jars:
java -Djasypt.encryptor.password=<encryption-password> -Dspring.config.location=../config/application.properties -jar info_connect_hub-2.0.2.jar
Once the Hub instance is running, 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 stand-alone binary distribution version of 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. When launching the product from AWS Marketplace, Azure Marketplace, or other marketplaces supporting metered service subscription, there is no separate license required.
Below is a link to Postman collection that includes step-by-step guide for setting up the connection and creating sample program call definitions and DQ Pollers. In order to use this collection, open Postman and import the collection from the URL below, then set the collection variables to include Hub host, port, IBMi endpoint and credentials, and other variables relevant to each use case.
The default API authentication is a basic auth. Please use the hardening instructions below to change the defaults shortly after installation, configuration and evaluation of the product.
- Verify that the instance is running, using GET http://host:8080/admin/connections. You should receive an empty array of connections (as no connections have been configured yet).
-
Configure new IBMi (AS400, iSeries) connection using POST http://host:8080/admin/connections with the sample request similar to below
Sample New Connection request
{ "connectionName": "hubdemo", "endpoint": "your-as400-endpoint", "userId": "userid", "password": "encrypted-password", "libraryList": "comma-separated-list-of-libraries", "libraryListMode": "ADD_LAST", "jobTrace": false, "secureConnection": true, "tlsConfig": { "tlsIsInsecure": false, "tlsKeystoreConfigured": false, "tlsTruststoreConfigured": true, "tlsFileName": "info400.truststore", "truststorePassword": "encrypted-password" }, "transportConfig": { "licenseFileProtocol": "FILE", "truststoreFileProtocol":"S3", "licenseFileName": "as400-license.lic", "FILE": { "filePath": "license-file-location-in-shared-storage" }, "S3": { "s3Bucket":"as400-bucket", "s3Region":"us-east-2", "s3AccessKey": "encrypted-aws-access-key", "s3SecretKey": "encrypted-aws-secret-key" } } }
Note: All credentials like passwords, keys, i.e. should come in encrypted format. To encrypt your secrets use Admin Encryption call to POST http://host:8080/admin/encryption with the sample request as similar to below (you may set as many secrets as you wish in request)
Sample Encrypt all described credentials request
{ "as400password": "plaintext-password", "s3AccessKey": "plaintext-aws-access-key", "s3SecretKey": "plaintext-aws-secret-key", "truststorePassword": "plaintext-password" }-
Verify the connection is successful by GET http://host:8080/admin/connections - now it should show the connection details for the newly created connection, with the status OPEN
-
Then create new program call definition using POST http://host:8080/admin/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
{ "programDefinitionName": "HUBDEMO_POSTORDSP", "programName": "POSTORDSP", "programLibrary": "HUBDEMO", "libraryList": "HUBDEMO", "libraryListMode": "ADD_LAST", "uri": "/custom/uri", "connectionName": "connectionName", "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 } -
Test the REST API that surfaces the program call by using POST http://host:8080/custom/uri, 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 } ] }Or test the REST API that surfaces the program call by using GET http://host:8080/custom/uri, passing parameters as a request query parameters, for example:
Sample New Program Call request
?orderID=12345&orderLines=10&orderItemsIn_0.item=ITEM1&orderItemsIn_0.qty=123.45&orderItemsIn_0.price=321.45&orderItemsIn_1.item=ITEM2&orderItemsIn_1.qty=234.45&orderItemsIn_1.price=987.45&orderItemsIn_2.item=ITEM3&orderItemsIn_2.qty=235.98&orderItemsIn_2.price=123.95&orderItemsIn_3.item=ITEM4&orderItemsIn_3.qty=113.45&orderItemsIn_3.price=221.45&orderItemsIn_4.item=ITEM5&orderItemsIn_4.qty=134.45&orderItemsIn_4.price=587.45&orderItemsIn_5.item=ITEM6&orderItemsIn_5.qty=535.98&orderItemsIn_5.price=323.95&orderItemsIn_6.item=ITEM7&orderItemsIn_6.qty=163.45&orderItemsIn_6.price=324.45&orderItemsIn_7.item=ITEM8&orderItemsIn_7.qty=324.45&orderItemsIn_7.price=557.45&orderItemsIn_8.item=ITEM9&orderItemsIn_8.qty=435.98&orderItemsIn_8.price=423.95&orderItemsIn_9.item=ITEM10&orderItemsIn_9.qty=100.98&orderItemsIn_9.price=323.95
Product Setup and Operations
Most of the InfoConnect Hub functionality can be configured via admin APIs, however there are several hardening configuration steps that must be performed directly on EC2 instance. Once the InfoConnect Hub is configured, it will interact with external services and IBM i components via separate Functional API endpoints.
License Management
InfoConnect Hub, when provisioned as a stand-alone component, 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. When launching InfoConnect Hub from AWS Marketplace or other supported marketplaces, no separate license is required.
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 | s3Bucket=path-to-bucket s3Region=us-east-2 s3AccessKey=encrypted-access-key s3SecretKey=encrypted-secret-key |
| 2 | HTTP/HTTPS | httpUrl=http-URL httpDirPath=license-file-path httpUsername=usernamehttpPassword=encrypted-pwd |
| 3 | FTP | ftpHost=ftp-host ftpDirPath=path ftpUsername=username ftpPassword=encrypted-pwd |
| 4 | FILE/SMB | filePath=path-to-license-file |
Security Hardening
InfoConnect Hub 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
You also can change default authentication system to different OAuth providers using authentication server. Guide: Setting up OAuth authentication
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:
- Configure HTTPS protocol for the API / HTTP listener
- Configure TLS IBM i connection
- Change the encryption key used to encrypt sensitive properties
- Encrypt all credentials and other sensitive API properties using Admin encryption API
- Change the default Admin and Functional API user ID and password
- Restrict access to APIs to specific allowed source IPs only
- 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, we need to create our own self-signed SSL certificate. It is easy to generate the file with java keytool command.
After typing into the terminal command below, you 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.
keytool -genkey -alias selfsigned_localhost_sslserver -keyalg RSA -keysize 2048 -validity 700 -keypass changeit -storepass changeit -keystore ssl-server.jks
We can use command below to view what is inside this keystore.
keytool -list -keystore ssl-server.jks
Spring boot SSL Configuration
Secondly, we need to copy the generated keystore file into the [project-folder]/config folder. Next, we should add the below entries to the application.properties file. Note: [project-folder] is /opt/info-connect-hub for AWS Marketplace Hub instance
server.ssl.key-alias=selfsigned_localhost_sslserver
server.ssl.key-store-password=changeit
server.ssl.key-store=../config/ssl-server.jks
server.ssl.key-store-provider=SUN
server.ssl.key-store-type=JKS
If you want to use keystore password in encrypted form then paste encrypted value in ENC() like this:
server.ssl.key-store-password=ENC(encrypted-value)
At the end restart the Hub
How to change encryption key used to encrypt sensitive properties
Before changing the encryption key make sure that you don't have active connections/pollers/properties configured with the legacy key value that is no longer up-to-date
- If you run Hub distribution package using shell script, then no addition configuration required. Hub will ask you to set encryption key on start
- If you rub Hub distribution package using java command, you will need to set your encryption key in -Djasypt.encryptor.password property
- If you run Hub from AWS Marketplace, you will need to go into [project-folder]/executable-jars and edit -Djasypt.encryptor.password property in info_connect_hub-2.0.2.conf file and then restart the Hub (?) Note: [project-folder] is /opt/info-connect-hub for AWS Marketplace Hub instance
How to change the default user ID and password for admin and functional users
- To change the default user ID and password we should go to application.properties file which is located in [project-folder]/config directory.
- We need to find a section for Basic Authentication.
- If you want to change credentials, then use the User section for Functional operations, and the Admin section for Admin operations.
- If you want to change user ID then find userUsername or adminUsername field and change the value.
- If you want to use userPassword/adminPassword in encrypted format then follow these steps:
- Firstly, we need to encrypt the password using Admin Encryption API POST http://host:8080/admin/encryption.
- Secondly, we paste the password which is encrypted in ENC() in the userPassword/adminPassword field.
- Restart the Hub
Cluster Configuration
Admin API definitions
The InfoConnect Hub 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:
- Encryption API - allows encrypting sensitive data like passwords or other secrets
- Connections - manages IBM i connection definitions. It is possible to configure a single InfoConnect Hub 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,
- Program Calls - manages program call definitions that will be surfaced for the consumers as REST APIs
- 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 and send to the next systems:
- Google (GSP Pub Sub)
- JMS (ActiveMQ, ArtemisMQ, AmazonMQ)
- Azure (ServiceBus, EventHub, EventGrid)
- AWS (SQS, SNS)
- Data Queue Publishers - manages the always-on DQ publisher that are registered to write new message in to the IBMi DQ immediately after they are placed into target system:
- Google (GSP Pub Sub)
- JMS (ActiveMQ, ArtemisMQ)
- Azure (ServiceBus)
- AWS (SQS) For not supported systems you can
- SNS: set up routing to SQS system
- Event Grid: set up routing to Service Bus
- Event Hub: use Kafka publisher with Standard subscription level
Below is a link to the Admin API documentation
Functional API definitions
The InfoConnect Hub comes with the following functional APIs out of the box:
- Execute Command Call API - does not require any admin / configuration
- Publish Data To Data Queue API or read Data Queue entry directly - does not require any admin / configuration
- Execute Program Call API - requires the program call configuration via Admin API (see above)
- Listen for new Data Queue entry with DQ Listener (requires the configuration via Admin API) and send to next systems:
- Google (GSP Pub Sub)
- JMS (ActiveMQ, ArtemisMQ, AmazonMQ)
- Azure (ServiceBus, EventHub, EventGrid)
- AWS (SQS, SNS)
- Listen for new message with DQ Publisher (requires the configuration via Admin API) and write them in to the IBMi DQ:
- Google (GSP Pub Sub)
- JMS (ActiveMQ, ArtemisMQ)
- Azure (ServiceBus)
- AWS (SQS)
Below is a link to the Admin API documentation