Configuration elements

You can use the following elements in your configuration file to configure IBM z/OS Connect.

This list contains only those elements that are unique to IBM z/OS Connect. For more information about Liberty configuration elements not listed here, see Server configuration in the WebSphere Application Server for z/OS Liberty documentation.

Each server must have a server configuration file that is called server.xml in its server configuration directory ${server.config.dir}. You can choose to keep all your configuration in the single server.xml file, or, you can use include elements to consolidate configurations from separate files to create the structure that is most useful to you. For more information, see Using include elements in configuration files in the IBM WebSphere Application Server for z/OS documentation.

Care is needed to avoid defining multiple instances of the singleton elements, or elements with the same ID value, by understanding the rules that are used to merge these elements. For more details on the rules that are used to merge the multiple instances of the elements see Configuration element merging rules in the IBM WebSphere Application Server for z/OS documentation.

zosconnect_auditInterceptor
Defines the audit interceptor for IBM z/OS Connect to allow request data to be logged in System Management Facility (SMF) 123 subtype 1 records on z/OS.
Attribute name Data type Default value Description
id string   A unique configuration ID.
sequence integer

Minimum: 0

Maximum: 2147483647
0 The sequence in which this interceptor is processed compared to other configured interceptors that implement the com.ibm.wsspi.zos.connect.Interceptor Service Provider Interface (SPI) for IBM z/OS Connect.
apiProviderSmfVersion integer

Minimum: 1

Maximum: 2
1 The version of the SMF type 123 subtype 1 records that you want this audit interceptor to capture.
apiProviderRequestHeaders string   (SMF type 123 subtype 1 version 2 records only) The value of this attribute can be set to a header name or a comma-separated list of header names that might be present on requests.
apiProviderResponseHeaders string   (SMF type 123 subtype 1 version 2 records only) The value of this attribute can be set to a header name or a comma-separated list of header names that might be present on responses as a result of response data mapping.
apiProviderMaxDelay A period of time with second precision -1 The maximum time the audit interceptor waits before writing an SMF 123 subtype 1 version 2 record with less than the maximum number of request sections. Specify a positive integer followed by a unit of time, which can be hours (h), minutes (m), seconds (s) or milliseconds (ms). The default time unit is seconds. For example, specify 30 seconds as 30s. You can include multiple values in a single entry. For example, 1m30s is equivalent to 90 seconds. A value of -1 (the default) disables the maximum delay meaning an SMF record is only written when the maximum number of requests for an SMF record is reached. A value of 0 (or any value less than 1 second) means an SMF record is written immediately for the request with no delay.
apiProviderEarlyFailure boolean false Indicates whether SMF subtype 1 V2 records are written for early request failures for API provider.
zosconnect_authData
Defines the basic authentication data to be used for an IPIC connection or for authenticating with an authorization server.
Attribute name Data type Default value Description
id string   The element identifier.
password string   The password that is passed from IBM z/OS Connect to establish the connection on every request. The value can be in clear text or encoded by xor, aes or hash. Use the WebSphere® Liberty profile server securityUtility command (securityUtility encode <password>) to generate an encoded password. Copy the encoded password into the configuration file. The password can be a password phrase.
user string   The user ID that is passed from IBM z/OS Connect to establish the connection on every request, if no user ID is supplied on the request.
zosconnect_authorizationServer
Allows requests for access tokens or JWTs to be routed from IBM z/OS Connect to an authorization server or an authentication server.
For more information about supported security configuration options for JWT or OAuth 2.0, see How to configure a third-party JWT or How to configure OAuth 2.0 with basic authentication.
Attribute name Data type Default value Description
id string   A unique configuration ID.
tokenEndpoint string   Token endpoint URL that is used for routing a request to get an access token or a JWT from an authorization server or an authentication server. This URL must follow the following format:
"https://host:port/path"
or if using AT-TLS:
"http://host:port/path"
For example,
tokenEndpoint="https://authorization.server.com:8001/
JWTTokenGenerator/getJwtToken"
Contact the authorization/authentication server administrator for details of the path value required for that server.
basicAuthRef Reference
to top level
zosconnect_
authData

element (string)
  Reference name that identifies the basic authentication data to be used for authenticating with an authorization server. The values of the user and password attributes that are set in the associated zosconnect_authData element take precedence over user credentials that are specified in the z/OS application.
When your z/OS application calls an API secured with OAuth 2.0
The value of the user and password attributes set in the associated zosconnect_authData element are used as client ID and client secret to verify the client identity of the IBM z/OS Connect server with an authorization server to obtain an access token.
When your z/OS application calls an API secured with a JWT
The value of the user and password attributes set in the associated zosconnect_authData element are used as username and password to verify the user identity with an authentication server to obtain a JWT.
connectionTimeout A period
of time
with millisecond
precision
30s The connection timeout specifies the amount of time that the IBM z/OS Connect server attempts to establish a connection to the authorization/authentication server before it times out. If the timeout value is set to 0, the IBM z/OS Connect server attempts to open a connection indefinitely. Specify a positive integer followed by a unit of time, which can be hours (h), minutes (m), seconds (s) or milliseconds (ms). The default time unit is milliseconds. For example, specify 500 milliseconds as 500ms. You can include multiple values in a single entry. For example, 1s500ms is equivalent to 1.5 seconds.
receiveTimeout A period
of time
with millisecond
precision
60s The receive timeout specifies the amount of time that the IBM z/OS Connect server waits for a response from the authorization/authentication server before it times out. If the timeout value is set to 0, the IBM z/OS Connect server waits for a response indefinitely. Specify a positive integer followed by a unit of time, which can be hours (h), minutes (m), seconds (s) or milliseconds (ms). The default time unit is milliseconds. For example, specify 500 milliseconds as 500ms. You can include multiple values in a single entry. For example, 1s500ms is equivalent to 1.5 seconds.
proxyConfigRef Reference to
top level
zosconnect_
proxyConfig

element. (string)
  Reference name that identifies the proxy through which the request for access token is routed from the IBM z/OS Connect server to the authorization/authentication server.
sslCertsRef string   An SSL repertoire with an ID, a defined keystore, and truststore.
zosconnect_authToken
Defines the configuration of the JWT that is obtained from the authentication server.
Attribute name Data type Default value Description
authServerRef Reference to
the top level
zosconnect_
authorizationServer

element. (string)
  A reference name that identifies the information about an authentication server that is used for JWT authentication.
cacheTokensWithJti boolean false Specifies whether tokens issued by the authorization server that contain a jti claim are cached.
header string Authorization Specify the name of the header that contains the JWT on the API request.
id string   A unique configuration ID.
tokenRefreshRate A period
of time
with millisecond
precision
0 Available from V3.0.70.0. Specifies a period of time after which an attempt is made to obtain a new JWT even if there is a non-expired cached JWT. If the attempt to obtain a new JWT fails, the existing cached token is used. If the time is set to 0, tokens are cached and refreshed when they have expired. To enable token refresh, specify a positive integer followed by a unit of time, which can be hours (h), minutes (m), seconds (s) or milliseconds (ms). The default time unit is milliseconds. For example, specify 30 minutes as 30m.
useBearerScheme boolean true Indicates whether to include the Bearer scheme in the HTTP header that contains the JWT on the API request.

Sub elements

zosconnect_authToken > tokenRequest
Description: Defines how the user credential is passed from the IBM z/OS Connect server to the authentication server.
Required: true
Attribute name Data type Default value Description
credentialLocation string  
Specifies where the user credentials are included in the request to obtain a JWT from the authentication server. The following values are supported:
header
Include the user credentials in the HTTP header. If this value is set, the header attribute of the tokenRequest element must be specified.
body
Include the user credentials in the request body. If this value is set, the requestBody attribute must be specified.
For both values, the requestMethod attribute must be specified.
header string Authorization Specifies the name of a single header to contain the user credentials. From V3.0.70.0, a comma-separated list of two-header names can be specified to contain the user credentials. The format specification for two-header names is :
<user ID header name>,<password header name>
requestBody string   Specifies the body of the token request sent to the authentication server, as a JSON string.

Required when credentialLocation is set to body. From V3.0.70.0, is optional when credentialLocation is set to header.

Either explicitly specify values in the request body, as in Example A or allow substitution of username and password values set by the client application, or in the server.xml file, as in Example B. From V3.0.70.0, custom parameter values set by the client application can also be substituted.

Example A

"{&quot;credentials&quot;:{
    &quot;username&quot;:&quot;jwtuser&quot;,
    &quot;password&quot;:&quot;jwtpassword&quot;
    }
}"

In this example, the user credentials "jwtuser" and "jwtpassword" are directly included in the specified JSON string.

Example B

"{&quot;apiuser&quot;:&quot;${userid}&quot;,
&quot;apipassword&quot;:&quot;${password}&quot;}"

In this example, the variables ${userid} and ${password} are replaced with the user credentials that you include in the z/OS application or set on the zosconnect_authData element that is referenced by the zosconnect_authorizationServer element basicAuthRef attribute.

Important:
  • Typically, you use the Example B syntax. When the Example B syntax is used with the user credentials set on the zosconnect_authData element, the password in the server.xml file can be encoded to ensure confidentiality. The Example A syntax is provided to allow more flexibility in the request payload that is required by the authentication server.
  • As shown in the examples above, &quot; must be used to escape the double quotation mark (") inside the attribute value, because the attribute value is already surrounded by double quotation marks to indicate it is a string value. And the following characters must also be escaped if they are contained in the attribute value because these special characters cannot be directly used in XML:
    • < escaped with &lt;
    • > escaped with &gt;
    • & escaped with &amp;
requestMethod string   Specify the method of the HTTP request to the authentication server. Acceptable values are GET, PUT, or POST.
zosconnect_authToken > tokenResponse
Description: Defines how a JWT is passed from the authentication server to the IBM z/OS Connect server.
Required: true
Attribute name Data type Default value Description
header string Authorization Specify the name of the header that needs to contain the JWT.
responseFormat string   Specify the format of the HTTP response from the authentication server when the JWT is returned in the response body. Valid values are Text, JSON, or JWT. JWT is supported from V3.0.69.0. Prior to V3.0.69.0, no Accept header is set on the JWT request. From V3.0.69.0, an Accept header is set to "application/json" for JSON, "text/plain” for Text and "application/jwt” for JWT.
tokenLocation string  
Specify where the generated JWT is returned in the response from the authentication server to the IBM z/OS Connect server. The following values are supported:
header
The JWT is returned in a header to IBM z/OS Connect. If this value is set, the header attribute of the tokenResponse element must be specified.
body
The JWT is returned in the response body to IBM z/OS Connect. If this value is set, the responseFormat and tokenPath attributes must be specified.
tokenPath string  

Specify the path to where the token is located in the JSON string when the responseFormat attribute is set to JSON. The value of this attribute must be a valid JSONPath expression.

For example, if the generated token is included in the following JSON string:

{"JWTinfo":{
    "tokenname": "eyJ0eXAiOiJKV1"
    }
}
you must set the tokenPath attribute to "$.JWTinfo.tokenname".
zosconnect_authTokenLocal
Defines the locally generated JWT configuration in IBM z/OS Connect.
Attribute name Data type Default value Description
header string Authorization Specify the name of the HTTP header that contains the JWT on the API request. The HTTP header includes the "Bearer" scheme keyword followed by the JWT.
tokenGeneratorRef Reference to a jwtBuilder element. (string)   The id attribute value of a JWT builder element. For more information about the jwtBuilder element, see JWT Builder (jwtBuilder) in the WebSphere Application Server for z/OS Liberty documentation.

Sub elements

zosconnect_authTokenLocal > claims
Required: false
Data type: a string or CDATA section
Description: Specify the public and private claims to be included in the JWT. If specified, write the claims as a JSON string. For example,

<zosconnect_authTokenLocal id="myLocalJWTConfig" 
    ...>
    <claims>{"branch":"Eastern",
             "dept":"insurance"}</claims>
</zosconnect_authTokenLocal>
Note:
  1. The claims subelement is intended to specify only public and private claims. If registered claims, such as the aud (Audience) claim, are specified on the claims subelement, then these values overwrite the corresponding values configured on the jwtBuilder element referenced by the tokenGeneratorRef attribute of the zosconnect_authTokenLocal element. If the "sub" claim is specified on the claims subelement, its value is overwritten by the IBM z/OS Connect server to be the authenticated user ID for the request. Registered claims are defined in the IANA JSON Web Token Claims Registry.
  2. If the JSON string value of the claims subelement contains XML markup characters, such as <, > and &, then include the JSON string inside a CDATA section so that those characters are treated as literals. For example, if one of the private claims above was "branch":"East&West" then the claims subelement value must be specified as:
    
    <claims><![CDATA[{"branch":"East&West", 
                      "dept":"insurance"}]]></claims> 
    For more information about the CDATA section, see CDATA.
zosconnect_cicsConnectionGroup
Available from V3.0.59.0. Defines a group of CICS® connections that are used for workload distribution.
Attribute name Data type Default value Description
cicsConnectionRefs List of
references to
top level
zosconnect_
cicsIpicConnection

or zosconnect_
cicsConnectionGroup

elements (comma
-separated list of strings)
  Required. A comma-separated list of references to IPIC connection elements or other CICS connection group elements, or a mixture of both. The inclusion of IPIC HA connections (definitions with sharedPort="true") is not supported in CICS connection groups.
connectionRatios Comma-separated
list of
integers
Minimum integer
value: 0
Equal ratios Optional. A list of the relative weights for the connections specified by the cicsConnectionRefs attribute. A value must be specified for each connection in the list. Values can be dynamically updated to alter the distribution of requests at runtime. A value of zero indicates that no requests are to be sent over the corresponding connection.
id string   Required. A unique configuration ID. This must match the value that is specified for the CICS connection selected when the z/OS Asset was created in the z/OS Connect Designer.
zosconnect_cicsIpicConnection
Defines a connection to a CICS region.
Note: When an IPIC connection is established with CICS, updates to the authDataRef, requestTimeout, transid and transidUsage attributes take immediate effect but updates to other attributes of this element do not take effect until the connection is released and acquired again. To release the connection in CICS, change the status of the corresponding IPCONN in CICS to Released.
Attribute name Data type Default value Description
authDataRef string   Optional. Reference to a zosconnect_authData element that contains the basic authentication data to be used for the connection if no credentials are supplied on a request. For more information, see zosconnect_authData.
cicsApplid string   Optional. The APPLID of the target CICS region. If specified, the value of cicsApplid is used, together with the value of cicsNetworkid, to verify that the connected CICS region is the expected region.
cicsNetworkid string   Optional. The network ID of the target CICS region. The default value is 9UNKNOWN. If specified, the value of cicsNetworkid is used, together with the value of cicsApplid, to verify that the connected CICS region is the expected region. The network ID of the target CICS region is either its z/OS Communications Server NETID or, for VTAM®=NO systems, the value of its UOWNETQL system initialization parameter, or defaults to 9UNKNOWN.
connectionRetryInterval A period
of time
with
millisecond precision.

Maximum: 3600s.

30s Optional. Available from V3.0.59.0. This attribute applies only to IPIC connections that are configured within a CICS connection group element. The time interval at which IBM z/OS Connect attempts to re-establish a failed connection to CICS, as a background task. Specify a positive integer followed by a unit of time, which can be hours (h), minutes (m), seconds (s) or milliseconds (ms). The default time unit is milliseconds. For example, specify 30 seconds as 30s. You can include multiple values in a single entry. For example, 1m30s is equivalent to 90 seconds.
connectionTimeout A period of time with millisecond precision. 30s Optional. The maximum amount of time that is allowed for the socket to establish a connection to CICS. Specify a positive integer followed by a unit of time, which can be hours (h), minutes (m), or seconds (s). For example, specify 30 seconds as 30s. You can include multiple values in a single entry. For example, 1m30s is equivalent to 90 seconds. A value of 0 disables this timeout.
heartbeatInterval A period of time with millisecond precision.

Maximum: 3600s.

30s Optional. This attribute sets the time that the connection must be inactive before heartbeats are sent to CICS. Specify a positive integer followed by a unit of time, which can be hours (h), minutes (m), or seconds (s). For example, specify 30 seconds as 30s. You can include multiple values in a single entry. For example, 1m30s is equivalent to 90 seconds. A value of 0 disables IPIC heartbeats.
host string   Required. The IP address, domain name server (DNS) hostname with domain name suffix, or just the DNS hostname, of the host on which the CICS region is running.
id string   Required. A unique configuration ID. This must match the value that is specified for the CICS connection selected when the z/OS Asset was created in the z/OS Connect Designer.
port integer

Minimum: 1

Maximum: 65,535

  Required. The port number on which the target CICS region is listening. This must match the port number of a TCPIPSERVICE definition in the CICS region that is configured with the PROTOCOL parameter set to IPIC.
preferredSpecificHost string   Optional. Available from V3.0.56.0 and applicable only when sharedPort="true". The primary IP address, or the DNS name, of the preferred CICS region for this connection. This must match the host name of a CICS region that is configured to listen on the shared port specified by the port attribute of this connection. The primary IP address of a CICS region can be found from message BAQR0680I, issued when an IPIC connection is established to that region.

From V3.0.57.0, this attribute can be set to a value of local to indicate that the preferred host is the LPAR on which the IBM z/OS Connect server is running.

preferredSpecificPort integer

Minimum: 1

Maximum: 65,535

  Optional. Available from V3.0.56.0 and applicable only when sharedPort="true". The port number of the preferred CICS region for this connection. This must match the port number of a specific TCPIPSERVICE definition of a CICS region that is configured to listen on the shared port specified by the port attribute of this connection.
reconnectInterval A period of time with millisecond precision.

Maximum: 3600s.

  Optional. Available from V3.0.56.0 and applicable only when sharedPort="true". The time interval at which IBM z/OS Connect attempts to reconnect to CICS. If either or both of the attributes preferredSpecificHost and preferredSpecificPort are also specified, reconnection is attempted only if the already established connection is not the configured preference. Specify a positive integer followed by a unit of time, which can be hours (h), minutes (m), seconds (s) or milliseconds (ms). The default time unit is milliseconds. For example, specify 30 seconds as 30s. You can include multiple values in a single entry. For example, 1m30s is equivalent to 90 seconds. A value of 0 disables the reconnect interval.
requestTimeout A period of time with millisecond precision. 30s Optional. The maximum amount of time that is allowed for a request to be sent to CICS and for the response to be received. For the initial request over a connection, this includes the time that is taken to establish the connection. Specify a positive integer followed by a unit of time, which can be hours (h), minutes (m), or seconds (s). For example, specify 30 seconds as 30s. You can include multiple values in a single entry. For example, 1m30s is equivalent to 90 seconds. A value of 0 disables this timeout.
sendSessions integer

Minimum: 1

Maximum: 999

100 Optional. This attribute sets the maximum number of simultaneous requests over the connection. The actual number of send sessions established depends on the value of sendSessions and the value in the RECEIVECOUNT parameter of the IPCONN definition in the CICS region.
sharedPort boolean false Optional. Indicates whether the port attribute specifies a shared port or a specific port.
sslRef string   Optional. Reference to an SSL repertoire with an ID, a defined keystore and truststore, or an SSL Default repertoire.
Note: For backwards compatibility with IBM z/OS Connect OpenAPI 2 support, the sslCertsRef attribute can be used as an alternative to the sslRef attribute. The behavior is identical. If both attributes are specified, the sslRef attribute takes precedence.
transid string CSMI Optional. A CICS transaction name; the transidUsage parameter specifies how the value is used.
transidUsage
  • EIB_ONLY
  • EIB_AND_MIRROR
EIB_AND_MIRROR Optional. Specifies how the value of the transid parameter is used.
EIB_ONLY
The transid parameter specifies the name of the CICS transaction that appears in the CICS exec interface block (EIB); the EIBTRNID field contains the value of the transid parameter. The called CICS program runs under the default mirror transaction CSMI.
EIB_AND_MIRROR
The transid parameter specifies the name of the CICS transaction under which the called CICS program runs. The transaction must be defined in the CICS region, and the transaction definition must specify the mirror program, DFHMIRS. The value that is specified by the transid parameter is available to the called CICS program for querying the transaction ID. The value of the transid parameter also appears in the EIBTRNID field of the CICS EIB.
zosConnectApplid string   Optional. The APPLID of IBM z/OS Connect passed to CICS.

If specified, this value of zosConnectApplid is used, together with the value of zosConnectNetworkid, to match a predefined IPCONN definition in CICS or reject the request if no match is found and the CICS system has not been configured to autoinstall IPCONN connections.

If you configure CICS to not allow autoinstall of IPCONN connections, only requests that have APPLIDs set on a predefined IPCONN definition are able to connect.

zosConnectNetworkid string   Optional. The network ID of IBM z/OS Connect passed to CICS. The default value is 9UNKNOWN.

If specified, this value of zosConnectNetworkid is used, together with the value of zosConnectApplid, to match a predefined IPCONN definition in CICS or reject the request if no match is found and the CICS system has not been configured to autoinstall IPCONN connections.

If a zosConnectNetworkid value is not specified and the NETWORKID in the CICS IPCONN definition is left blank, a match might not occur even if the IBM z/OS Connect and CICS APPLIDs match because CICS defaults the blank NETWORKID to the local network ID. This local network ID is specified by the z/OS Communications Server NETID or for VTAM=NO systems, the value of its UOWNETQL system initialization parameter and is only defaulted to 9UNKNOWN if no local network ID is set.

zosconnect_credential
Defines the basic authentication data to be used for a Db2® connection.
Attribute name Data type Default value Description
id string   A unique configuration ID.
password Reversably
encoded
password
(string)
  Password of the user under which the request will be routed. The value can be stored in clear text or encoded. It is recommended that the password is encoded. To do so, use the securityUtility shipped with WebSphere Liberty profile.
user string   Name of the user under which the request will be routed.
zosconnect_db2Connection
Defines a connection to a Db2 endpoint.
Attribute name Data type Default value Description
credentialRef Reference to
zosconnect_
credential

element (string).
  Reference name that identifies the basic authentication data to be used for connecting to a Db2 endpoint.
host string   IP address, domain name server (DNS) host name with domain name suffix, or just the DNS host name, used to route the request.
id string   A unique configuration ID.
port string   Port that is used for routing HTTP or HTTPS requests.
sslRef string   An SSL repertoire with an ID, a defined keystore, and truststore.
zosconnect_endpointConnection
Allows requests to be routed from IBM z/OS Connect to a request endpoint.
Attribute name Data type Default value Description
allowChunking boolean true Available from V3.0.66.0. Allow chunking on messages greater than 4 KB.
authenticationConfigRef Reference to
top level zosconnect_
authData
,
zosconnect_
oAuthConfig
, or zosconnect_
authToken

element. (string)
  Reference name that identifies the authentication data that is used for basic authentication, OAuth 2.0 or JWT when the IBM z/OS Connect establishes a connection to a remote REST endpoint:
  • For basic authentication, it must be associated with the zosconnect_authData element.
  • For OAuth 2.0, it must be associated with the zosconnect_oAuthConfig element.
  • For using a JWT that is obtained from an authentication server, it must be associated with the zosconnect_authToken element.
Note: The authenticationConfigRef attribute can reference more than one element to support the combined use of basic authentication, OAuth 2.0 or JWT. For more information, see Calling an API secured with multiple authentication and authorization methods.
connectionTimeout A period
of time with
millisecond precision.
30s The connection timeout specifies the amount of time that the IBM z/OS Connect server attempts to establish a connection to the request endpoint before it times out. If the timeout value is set to 0, the IBM z/OS Connect server attempts to open a connection indefinitely. Specify a positive integer followed by a unit of time, which can be hours (h), minutes (m), seconds (s) or milliseconds (ms). The default time unit is milliseconds. For example, specify 500 milliseconds as 500ms. You can include multiple values in a single entry. For example, 1s500ms is equivalent to 1.5 seconds.
host string   The address that is used to route the request to the request endpoint. The value can be the protocol http:// or https:// followed by the IP address, the domain name server (DNS) hostname with domain name suffix, or just the DNS hostname. If the protocol is not specified, the default protocol http:// is used.
id string   A unique configuration ID.
port string   Port that is used for routing HTTP or HTTPS requests.
receiveTimeout A period
of time with
millisecond precision.
60s Specifies the amount of time that the IBM z/OS Connect server waits for a response from the request endpoint before it times out. If the timeout value is set to 0, the IBM z/OS Connect server waits for a response indefinitely. Specify a positive integer followed by a unit of time, which can be hours (h), minutes (m), seconds (s) or milliseconds (ms). The default time unit is milliseconds. For example, specify 500 milliseconds as 500ms. You can include multiple values in a single entry. For example, 1s500ms is equivalent to 1.5 seconds.
sslCertsRef string   An SSL repertoire with an ID, a defined keystore, and truststore.
proxyConfigRef Reference to
top level
zosconnect_
proxyConfig

element. (string)
  Reference name that identifies the proxy via which the request is routed from the IBM z/OS Connect server to the request endpoint.
domainBasePath string   An additional path that is added between the {host}:{port} and {basePath} field in an API URL to identify domain-related information.
zosconnect_imsConnection
Defines a connection to an IMS endpoint.
Attribute name Data type Default value Description
id string Specify a unique ID for this IMS connection. This ID is the IMS connection selected within the z/OS Connect Designer.
connectionFactoryRef string Set this value to the ID of the connectionFactory element. For more information, see Configuring connections to IMS.
pingIMSConnectOnInvoke boolean Ping IMS Connect before the transaction is invoked to ensure that the connection that is retrieved from the connection pool is not stale. Throw an exception if z/OS Connect is unable to ping IMS before the service is invoked.
commitMode boolean Specify the commit mode. A value of 0 means commit-then-send (CM0); 1 means send-then-commit (CM1).
imsConnectTimeout A period of time with millisecond precision 30000 Specify the time in milliseconds to wait for a reply after sending a message to IMS Connect. The default value is 30000, which means to wait for 30 seconds.
Tip: The imsConnectTimeout value should be equal or larger than the value for interactionTimeout.
imsDatastoreName string Specify the name of the IMS data store (IMS Connect).
interactionTimeout A period of
time with
millisecond precision
-1 Specify the time in milliseconds for the transaction to be processed by IMS. After sending a message to IMS, IMS Connect waits for a reply from IMS until this timeout value is reached.
  • Valid values are -1, 0, or between 1 and 3600000 (one hour), inclusively.
  • A value of 0 means the timeout value is determined by IMS Connect.
  • A value of -1 (the default) means to wait indefinitely.
tranExpiration Boolean Sets the TMRA IMSInteractionSpec property transExpiration. Accepted values for this attribute are “true” or “false”.

To learn what these properties control, see the TMRA section of the IMS documentation.

propagateNetworkSecurityCred true Specify whether to propagate the network security credential if the IMS Connect is V15 or later. The default is true.

The credential consists of the user ID and the network session ID (the realm) that are registered in the basic registry or SAF registry. For more information, see Configuring distributed identity propagation to IMS.

syncLevel Specify the sync level. A value of 0 means None; 1 means Confirm. A commitMode value of 0 (CM0, Commit-then-send) is invalid with sync level 0 (None).
imsConnectCodepage Specify the code page to use for character string conversion with IMS Connect. The default is Cp1047.
ltermOverrideName Optional. Specify a LTERM name to override the value in the LTERM field of the IMS application program's I/O PCB.
zosconnect_monitoring
Defines the list of interceptors to run for APIs.
Attribute name Data type Default value Description
id string - A unique configuration ID.
apiProviderInterceptorsRef string - Reference name that identifies the list of configured interceptors that are called for all APIs.
zosconnect_oAuthConfig
Defines the OAuth 2.0 configuration in IBM z/OS Connect. For more information about supported security configuration options when using OAuth 2.0, see How to configure OAuth 2.0 with basic authentication.
Attribute name Data type Default value Description
authServerRef Reference to
top level
zosconnect_
authorizationServer

element. (string)
  Reference name that identifies the information of an authorization server that is used for authentication and authorization.
clientSecretInBody boolean false Not applicable when using JWT authentication or there is no client secret. Indicates whether to send the client credentials to the authorization server in the Authorization header or in the request body. If only a client ID is specified, it is always sent to the authorization server in the request body.
grantType Either
password
or
client_credentials
(string)
  Specifies the OAuth 2.0 grant type. In IBM z/OS Connect, only two grant types are supported. If set to password, the Resource Owner Password Credential grant type is used. If set to client_credentials, the Client Credentials grant type is used.
header string Authorization Available from V3.0.66.0. The name of the header that contains the OAuth 2.0 access token on the API request.
id string   A unique configuration ID.
jwtAuthenticationSetClientId boolean false Applicable only when using JWT authentication. Indicates whether to include the client ID, specified by the tokenSubject attribute of the referenced zosconnect_oAuthTokenConfig element, in the request body sent to the authorization server.
jwtAuthenticationTokenRef Reference to
top level
zosconnect_
oAuthTokenConfig

element (string).
  Reference that identifies the data to be used for generating a JWT to be used for authentication with the authorization server. If both JWT authentication and basic authentication are configured for the authorization server, JWT authentication is used.
useBearerScheme boolean true Available from V3.0.66.0. Indicates whether to include the Bearer scheme in the HTTP header that contains the OAuth 2.0 access token on the API request.
zosconnect_oAuthTokenConfig
Defines the configuration that is used to generate a token for use in obtaining an OAuth 2.0 access token.
Attribute name Data type Default value Description
id string   A unique configuration ID.
tokenSubject string   The client ID to be used as the subject claim "sub" in the generated JWT token.
tokenGeneratorRef Reference
to a
jwtBuilder
element. (string)
  The id attribute value of a jwtBuilder element. For more information about the jwtBuilder element, see JWT Builder (jwtBuilder) in the WebSphere Application Server for z/OS Liberty documentation.

Sub elements

zosconnect_oAuthTokenConfig > claims
Required: false
Data type: a string or CDATA section
Description: Specify the public and private claims to be included in the JWT. If specified, write the claims as a JSON string. For example,

<zosconnect_oAuthTokenConfig id="myOAuthJWTConfig" 
    ...>
    <claims>{"branch":"Eastern",
             "dept":"insurance"}</claims>
</zosconnect_oAuthTokenConfig>
Note:
  1. The claims subelement is intended to specify only public and private claims. If registered claims, such as the aud (Audience) claim, are specified on the claims subelement, then these values overwrite the corresponding values that are configured on the jwtBuilder element that is referenced by the tokenGeneratorRef attribute of the zosconnect_oAuthTokenConfig element. If the "sub" claim is specified on the claims subelement, its value is overwritten by the value of the value of the tokenSubject attribute. Registered claims are defined in the IANA JSON Web Token Claims Registry.
  2. If the JSON string value of the claims subelement contains XML markup characters, such as <, > and &, then include the JSON string inside a CDATA section so that those characters are treated as literals. For example, if one of the private claims above was "branch":"East&West" then the claims subelement value must be specified as:
    
    <claims><![CDATA[{"branch":"East&West", 
                      "dept":"insurance"}]]></claims> 
    For more information about the CDATA section, see CDATA.
zosconnect_proxyConfig
Allows requests to be routed from IBM z/OS Connect to an endpoint via a proxy.
Attribute name Data type Default value Description
id string   Required. A unique configuration ID.
host string   Required. The IP address, domain name server (DNS) host name with domain name suffix, or just the DNS host name of the proxy server, used to route the request.
port integer   Required. Port that is used by the proxy server for routing HTTP or HTTPS requests.
type string   Required. Proxy type, the value should be HTTP or SOCKS.
zosconnect_zosConnectInterceptors
List of 1 to N interceptors.
Attribute name Data type Default value Description
id string - A unique configuration ID.
interceptorRef comma-separated string - List of references to interceptor elements.