Creating or Updating Connections using the REST API

This document covers the following topics:

Introduction

You can create or update connections, adapter services and listeners, using the REST API.

Start of instruction setTo create a connection, adapter service or listener

  • Send the request to the Integration Server to the following URL:

    http://hostname:port/restv2/wmentirex/createConnection

    Example:

    http://localhost:5555/restv2/wmentirex/createConnection

Start of instruction setTo update a connection, adapter service or listener

  • Send the request to the Integration Server to the following URL:

    http://hostname:port/restv2/wmentirex/updateConnection

    Example:

    http://localhost:5555/restv2/wmentirex/updateConnection

Configuring your Input Parameters

Start of instruction setTo configure your input parameters

  • Use a JSON request document. Parameters valid for all connection types and parameters for specific connection types are described in the sections below.

    Sample JSON file createConnection.json: 

    {
     "connectionType": "RpcConnection",
     "folderName": "rpcConnection",
     "connectionName": "RpcConnection",
     "packageName": "Default",
     "brokerID": "localhost:1971",
     "serverAddress": "RPC/Test/CALLNAT",
     "idlSourceBase64":"KioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKi
                        oqKioqKioqKioqKioqKioqDQoqKg0KKiogVGhpcyBJREwgZmlsZSBjb250YWlucyB0aGUg
                        SURMIGRlZmluaXRpb25zIGZvciB0aGUNCioqIEVudGlyZVggYmFzaWMgUlBDIGV4YW1wbG
                        UuDQoqKg0KKiogQ29weXJpZ2h0IChjKSAxOTk3IC0gMjAxOSBTb2Z0d2FyZSBBRywgRGFy
                        bXN0YWR0LCBHZXJtYW55IGFuZC9vciANCioqICBTb2Z0d2FyZSBBRyBVU0EsIEluYy4sIF
                        Jlc3RvbiwgVkEsIFVuaXRlZCBTdGF0ZXMgb2YgQW1lcmljYSwgDQoqKiAgYW5kL29yIHRo
                        ZWlyIGxpY2Vuc29ycy4NCioqDQoqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKi
                        oqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioNCg0KTGlicmFyeSAnRVhB
                        TVBMRScgSXMNClByb2dyYW0gJ0NBTEMnIElzDQpEZWZpbmUgRGF0YSBQYXJhbWV0ZXINCi
                        AgICAgIDEgT3BlcmF0aW9uICAgICAgIChBMSkgIEluDQogICAgICAxIE9wZXJhbmQxICAg
                        ICAgICAoSTQpICBJbg0KICAgICAgMSBPcGVyYW5kMiAgICAgICAgKEk0KSAgSW4NCiAgIC
                        AgIDEgRnVuY3Rpb25fUmVzdWx0IChJNCkgIE91dA0KICAgIEVuZC1EZWZpbmUNCg0KICBQ
                        cm9ncmFtICdTUVVBUkUnIElzDQogICAgRGVmaW5lIERhdGEgUGFyYW1ldGVyDQogICAgIC
                        AxIE9wZXJhbmQgICAgICAgICAoSTQpICBJbg0KICAgICAgMSBSZXN1bHQgICAgICAgICAg
                        KEk0KSAgT3V0DQogICAgRW5kLURlZmluZQkgIA=="
}

Connection Parameters for All Connection Types

The following parameters apply to all connection types:

Parameter Opt/
Req 		Description Note
connectionType R Must be one of the following connection types:
RpcConnection RPC Connection
DirectRpcConnection Direct RPC Connection
ReliableRpcConnection Reliable RPC Connection
RpcListenerConnection RPC Listener Connection
DirectRpcListenerConnection Direct RPC Listener Connection
ReliableRpcListenerConnection Reliable RPC Listener Connection
DirectReliableRpcListenerConnection Direct Reliable RPC Listener Connection
ImsConnection IMS Connect Connection
CicsConnection CICS ECI Connection
CicsIpicConnection CICS IPIC Connection
CicsSocketListenerConnection CICS Socket Listener Connection
ACIConnection ACI Server Connection
CobolConverterConnection COBOL Converter Connection
AS400Connection AS/400 Connection
ApplinXConnection ApplinX Connection
See EntireX Adapter Connections for a detailed description of all connection types.
packageName R The package must exist in the Integration Server.  
folderName R If the folder does not exist, it will be created.  
connectionName R The name of the connection to be created.  
idlSourceBase64 R The Base64-encoded IDL source. See Base64 Resources for information on Base64 encoding/decoding tools.
serverMappingBase64 O The Base64-encoded CVM source.
mapToString O Map all IS data types to string. Valid values: true (default), false.  
resourceName O Name of a REST resource to create in the format "folderName:RESTResourceName". Only for connections with adapter services. See Step 4b: Create or Update a REST Resource in the Integration Server Wrapper documentation.

The parameter resourceName produces a REST resource with flow services for each related API (IDL program). Typically all entries in a REST resource require an HTTP POST method and a payload for the data. The following services are available to additionally create simplified REST APIs without a payload, just using the HTTP GET method:

  • Java Service
    pub.wmentirex.service.generateSimplifiedRestApi
  • REST Service
    wmentirex/generateSimplifiedRestApi

    For example, to send a POST command to endpoint URL: 

    https://localhost:5555/restv2/wmentirex/generateSimplifiedRestApi

    with payload:

    { "restResourceName": "<folderName:RESTResourceName>" }

Note:
Applies only to APIs where input signature parameters do not contain arrays.

Connection Parameters for RPC and Reliable RPC Connections

Note:
Parameters marked R are required when you create a connection and optional for updates.

Parameter Opt/
Req 		Description
brokerID Broker ID R The ID of the broker you want to connect to. This ID consists of a host and an optional port. Default for the port is "1971".
serverAddress Server Address R The address of the RPC server registered to the broker above. The address is given in the format <class>/<server>/<service>.
userid Logon User O The name of the user to log on to the broker.
password Logon Password O Deprecated. Use parameter password_e instead. The plain text password for the user above.
password_e Logon Password O The encrypted password for the user above. Follow the steps in section Password Encryption below.
encoding Encoding O The character encoding used for the RPC connection to the EntireX Broker. Default: the encoding of the Integration Server.

Enable character conversion in the broker by setting the service-specific attribute CONVERSION to "SAGTRPC". See also Configuring ICU Conversion under z/OS | Linux | Windows | BS2000. More information can be found under Internationalization with EntireX.

Connection Parameters for RPC and Reliable RPC Listener Connections

Note:
Parameters marked R are required when you create a connection and optional for updates.

Parameter Opt/
Req 		Description
brokerID Broker ID R The ID of the broker you want to connect to. This ID consists of a host and an optional port. Default for the port is "1971".
serverAddress Server Address R The address of the RPC server registered to the broker above. The address is given in the format <class>/<server>/<service>.
userid Logon User O The name of the user to log on to the broker.
password Logon Password O Deprecated. Use parameter password_e instead. The plain text password for the user above.
password_e Logon Password O The encrypted password for the user above. Follow the steps in section Password Encryption below.
encoding Encoding O The character encoding used for the RPC connection to the EntireX Broker. Default: the encoding of the Integration Server.

Enable character conversion in the broker by setting the service-specific attribute CONVERSION to "SAGTRPC". See also Configuring ICU Conversion under z/OS | Linux | Windows | BS2000. More information can be found under Internationalization with EntireX.

listenerName Listener Name R Name of the generated listener object.
serviceNames Service Names O Comma-separated list of IS services.

  • If not set, service names will be generated as: <library name>:<program name>Service. Example:
    Library EXAMPLE and subprogram CALC will be generated to service EXAMPLE:CALCService.

  • If set, the number of elements must be identical to the number of subprograms in the library.

Connection Parameters for Direct RPC Connections

Note:
Parameters marked R are required when you create a connection and optional for updates.

Parameter Opt/
Req 		Description
serverAddress Server Address R The address of the RPC server registered to the broker above. The address is given in the format <class>/<server>/<service>.

Connection Parameters for Direct RPC and Direct Reliable RPC Listener Connections

Note:
Parameters marked R are required when you create a connection and optional for updates.

Parameter Opt/
Req 		Description
serverAddress Server Address R The address of the RPC server registered to the broker above. The address is given in the format <class>/<server>/<service>.
serviceNames Service Names O Comma-separated list of IS services.

  • If not set, service names will be generated as: <library name>:<program name>Service. Example:
    Library EXAMPLE and subprogram CALC will be generated to service EXAMPLE:CALCService.

  • If set, the number of elements must be identical to the number of subprograms in the library.

Connection Parameters for Connections to IMS Connect

Note:
Parameters marked R are required when you create a connection and optional for updates.

Parameter Opt/
Req 		Description
host Host R Hostname of IMS Connect.
port Port R IMS Connect port.
datastoreid IMS Connect Data Store ID R Name of the data store, as defined in the IMS Connect configuration member.
encoding Encoding O Specify the appropriate EBCDIC encoding used by your IMS Connect.

Connection Parameters for COBOL Converter Connections

Parameter Opt/
Req 		Description
encoding Encoding O The character encoding of the COBOL binary data.

Connection Parameters for CICS Socket Listener Connections

Note:
Parameters marked R are required when you create a connection and optional for updates.

Parameter Opt/
Req 		Description
host Host R Hostname of CICS Socket Listener.
port Port R CICS Socket Listener Port.
transactionName CICS Transaction ID R Name of the CICS transaction. Default is "XRFE", which is the default dispatching transaction for CICS Socket Listener.
encoding Encoding O Specify the appropriate EBCDIC encoding used by your CICS Socket Listener. Default is codepage cp037 with full Latin-1 character set.
userid RACF User ID O The user ID (max. 8 chars) as defined in your underlying mainframe security system (e.g. RACF).
password RACF Password O Password/passphrase as defined in your underlying mainframe security system (e.g. RACF).
password_e RACF Password O The encrypted password for the user above. Follow the steps in section Password Encryption below.

Connection Parameters for CICS ECI Connections

Note:
Parameters marked R are required when you create a connection and optional for updates.

Parameter Opt/
Req 		Description
host Host R Hostname of CICS.
port Port R CICS port.
transactionName CICS Mirror Transaction ID R Name of the CICS mirror transaction. Default is "CPMI", which is the default dispatching transaction for ECI.
encoding Encoding O Specify the appropriate EBCDIC encoding used by your CICS installation. Default is codepage cp037 with full Latin-1 character set.
userid RACF User ID O The user ID (max. 8 chars) as defined in your underlying mainframe security system (e.g. RACF).
password RACF Password O Password (max. 8 chars) as defined in your underlying mainframe security system (e.g. RACF).
password_e RACF Password O The encrypted password for the user above. Follow the steps in section Password Encryption below.

Connection Parameters for CICS IPIC Connections

Note:
Parameters marked R are required when you create a connection and optional for updates.

Parameter Opt/
Req 		Description
host Host R Host name or IP address where CICS is running.
port Port R TCP or SSL port number (1-65535) of CICS IPIC.
transactionName Transaction ID R Transaction ID (1-4 chars). Name of the CICS mirror transaction that will receive transactions.
encoding Encoding O Specify the appropriate EBCDIC encoding used by your CICS installation. Default is codepage cp037 with full Latin-1 character set.
userid RACF User ID O The user ID (max. 8 chars) as defined in your underlying mainframe security system (e.g. RACF).
password RACF Password O Password/passphrase as defined in your underlying mainframe security system (e.g. RACF).
password_e RACF Password O The encrypted password for the user above. Follow the steps in section Password Encryption below.
applid Application ID O Client Application ID (max. 8 chars) to match target IPCONN. See your IBM documentation for more information.
networkid Network ID O Client Network ID (max. 8 chars) to match target IPCONN. See your IBM documentation for more information.

Connection Parameters for ACI Server Connections

Note:
Parameters marked R are required when you create a connection and optional for updates.

Parameter Opt/
Req 		Description
brokerID Broker ID R The ID of the broker you want to connect to. This ID consists of a host and an optional port. Default for the port is "1971".
serverAddress Server Address R The address of the RPC server registered to the broker above. The address is given in the format <class>/<server>/<service>. The address may contain an asterix ( '*') as a wildcard that is substituted by the IDL program name at runtime. This helps you to use only one connection for multiple IDL programs or adapter services.
userid Logon User O The name of the user to logon on to the broker.
password Logon Password O Deprecated. Use parameter password_e instead. The plain text password for the user above.
password_e Logon Password O The encrypted password for the user above. Follow the steps in section Password Encryption below.
encoding Encoding O The character encoding used for the ACI connection to the EntireX Broker. Default: the encoding of the Integration Server.

Enable character conversion in the broker by setting the service-specific attribute CONVERSION to "SAGTCHA". See also Configuring ICU Conversion under z/OS | Linux | Windows | BS2000. More information can be found under Internationalization with EntireX.

Connection Parameters for AS/400 Connections

Note:
Parameters marked R are required when you create a connection and optional for updates.

Parameter Opt/
Req 		Description
host Host R Hostname of the AS/400 (IBM i) system.
encoding Encoding O Specify the appropriate EBCDIC encoding which corresponds to the CCSID (Coded Character Set Identifier) of your AS/400 system.
userid User ID O The user profile name to use to authenticate to the system.
password Password O Deprecated. Use parameter password_e instead. The user profile plain text password to use to authenticate to the system.
password_e Password O The user profile encrypted password to use to authenticate to the system. Follow the steps in section Password Encryption below.

Connection Parameters for ApplinX Connections

Note:
Parameters marked R are required when you create a connection and optional for updates.

Parameter Opt/
Req 		Description
host Host R Hostname of ApplinX server.
port Port R Port of ApplinX server.

Response Codes

The HTTP response is in JSON format and contains two parameters, infos and error.

  • Successful Request
    If a request is successful, infos contains a comma-separated list of objects that were created or updated, and the error parameter is empty. Example: 

    {
  "infos": [
    "Connection rpc:RpcConnection created",
    "Adapter Service rpc:CALC created",
    "Adapter Service rpc:SQUARE created"
  ],
  "error": null
}

    The HTTP response code is 200 (OK).

  • Unsuccessful Request
    If a request is not successful, the infos parameter is empty, and the error parameter contains the reason for the failure. Example: 

    {
  "infos": null,
  "error": "Required parameter connectionName is missing"
}

    The HTTP response code is 500 (internal server error).

  • Invalid Syntax
    If the JSON input file has a syntax error (invalid input), the error parameter contains the reason for the JSON parser failure: 

    {
  "idlSourceBase64": null,
  "error": {
  "$errorDump": "com.fasterxml.jackson.core.JsonParseException:Unexpected character
  (';' (code 59)): was expecting comma to separate Object entries\n at [Source:
  (com.wm.net.HttpInputStream); line: 1, column: 36]",
...
}

    The HTTP response code is 400 (bad request).

Base64 Resources

Base64 encoding/decoding is used to keep the source file formatting inside the JSON format. Base64 encoding/decoding tools are available for several environments, for example:

Password Encryption

With sensitive data such as passwords/passphrases, we strongly recommend using encryption inside a JSON document, as well as secure communication (SSL). To generate such an encrypted password, use one of the following Integration Server services, located in the package WmEntireX to transform plain text passwords into encrypted passwords:

  • Java Service
    pub.wmentirex.service.encryptPassword
  • REST Service
    wmentirex/encryptPassword

    For example, send a POST command to endpoint URL:

    https://localhost:5555/restv2/wmentirex/encryptPassword

    with payload:

    {"plainText" : "<plainTextPassword>"}

Call these services once manually. You can then store the service result in a JSON document as the value for parameter password_e. If you specify both parameters password and password_e, an error is given.

Note:
Passwords/passphrases for RACF still have some restrictions (for example max. length 8 characters for passwords and 100 characters for passphrases) that apply to the input for the services mentioned above.