zosConnect-3.0 Configuration elements

Use the following elements in your configuration file to configure IBM z/OS Connect zosConnect-3.0.

zosConnect-3.0 Applies to zosConnect-3.0.

Configuring zosConnect-3.0 elements

This topic contains only those elements that are unique to IBM z/OS Connect. For more information about Liberty configuration elements not listed here, see A launch icon to indicate a link opens a new tab or window. Server configuration in the IBM WebSphere Application Server for z/OS 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 split the configuration into separate files to create the structure that is most useful to you. These separate files can be stored in the /config/configDropins/overrides directory or referenced by using include elements in the server.xml file. For more information, see Overview of IBM z/OS Connect configuration files and A launch icon to indicate a link opens a new tab or window. 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 A launch icon to indicate a link opens a new tab or window. Configuration element merging rules in the IBM WebSphere Application Server for z/OS documentation.

Each configuration element has one or more attributes that are detailed in the following tables with other useful details such as

Data type - each attribute has a data type which will be one of the following:
- string - if the attribute is of type string and is a reference to another element, then that attribute value must match the id attribute value of the element it is referencing. The id attribute is only required on an element if another element references that element. For example, for the zosconnect_authorizationServer configuration element to reference a zosconnect_authData element, the zosconnect_authData element must specify an id attribute value and the zosconnect_authorizationServer element basicAuthRef attribute must specify the same value.
- boolean - true or false
- integer - where applicable, the minimum and maximum integer values are included in the attributes description.
- a period of time with millisecond precision or a period of time with second precision - the default unit of time is either seconds or milliseconds. To set a value for these attributes specify a positive integer followed by a unit of time, which can be hours (h), minutes (m), seconds (s), or milliseconds (ms). For example, specify 30 seconds as 30s. You can include multiple values in a single entry. For example, 1m30s is equivalent to 90 seconds.
Default value - specifies the default value for the attribute where applicable.
Supported values - if there are specific supported values, details of the supported values are provided.

zosconnect_auditInterceptor

Defines the audit interceptor for z/OS Connect to allow request data to be logged in System Management Facility (SMF) 123 subtype 1 and subtype 2 records on z/OS.

Attribute name	Description
apiProviderEarlyFailure	Data type boolean Default value false Description Optional. Indicates whether SMF subtype 1 version 2 records are written for early request failures for API provider.
apiProviderMaxDelay	Data type A period of time with second precision. Default value -1 Description Optional. 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. The default time unit is seconds. The default value of `-1` disables the maximum delay meaning that 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 that an SMF record is written immediately for the request with no delay.
apiProviderRequestHeaders	Data type string Default value Not applicable Description Optional. 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	Data type string Default value Not applicable Description Optional. 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.
apiProviderSmfVersion	Data type integer Default value 1 Description Optional. The version of the SMF type 123 subtype 1 records that you want this audit interceptor to capture. Supported values are: 1 Write SMF type 123 subtype 1 version 1 records for API provider. 2 Write SMF type 123 subtype 1 version 2 records for API provider.
apiRequesterMaxDelay	Data type A period of time with second precision. Default value -1 Description Optional. The maximum time the audit interceptor waits before writing an SMF 123 subtype 2 version 2 record with less than the maximum number of request sections. The default time unit is seconds. The default value of value of `-1` disables the maximum delay meaning that 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 that an SMF record is written immediately for the request with no delay.
apiRequesterRequestHeaders	Data type string Default value Not applicable Description Optional. SMF type 123 subtype 2 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.
apiRequesterResponseHeaders	Data type string Default value Not applicable Description Optional. SMF type 123 subtype 2 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.
apiRequesterSmfVersion	Data type integer Default value 1 Description Optional. The version of the SMF type 123 subtype 1 records that you want this audit interceptor to capture. Supported values are: 1 Write SMF type 123 subtype 1 version 1 records for API requester. 2 Write SMF type 123 subtype 2 version 2 records for API requester.
id	Data type string Default value Not applicable Description Required. A unique configuration ID.
sequence	Data type integer Default value 0 Description Optional. 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 z/OS Connect. Supported values are `0` as a minimum value and `2147483647` as a maximum value.

zosconnect_authData

A reference name that identifies the basic authentication data to be used for a connection.

Attribute name	Description
id	Data type string Default value Not applicable Description Required. A unique configuration ID.
password	Data type string Default value Not applicable Description Optional. The password that is passed from the z/OS Connect Server to establish the connection on every request. The value can be stored in clear text or encoded. Typically, the password is encoded. To do so, use the `securityUtility` shipped with WebSphere Liberty profile. The password can be a password phrase. For more information, see securityUtility command in the WebSphere Application Server Liberty documentation.
user	Data type string Default value Not applicable Description Required. The user ID that is passed from the z/OS Connect Server to establish the connection on every request, if no user ID is supplied on the request.

zosconnect_authorizationServer

Defines the connection to an authorization or authentication server to obtain access tokens fused for authentication of requests to API endpoints. For more information about supported security configuration options for JWT or OAuth 2.0, see How to configure access token authentication or How to configure OAuth 2.0 with basic authentication.

Attribute name	Description
basicAuthRef	Data type string Default value Not applicable Description Optional. Reference to the `zosconnect_authData` element 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 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 values 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	Data type A period of time with millisecond precision Default value 30s Description Optional. The `connectionTimeout` specifies the amount of time that the z/OS Connect Server attempts to establish a connection to the authorization and authentication server before it times out. If the timeout value is set to `0`, the z/OS Connect Server attempts to open a connection indefinitely. The default time unit is milliseconds.
id	Data type string Default value Not applicable Description Required. A unique configuration ID.
proxyConfigRef	Data type string Default value Not applicable Description Optional. Reference to the `zosconnect_proxyConfig` element that identifies the proxy through which the request for access token is routed from the z/OS Connect Server to the authorization and authentication server.
receiveTimeout	Data type A period of time with millisecond precision Default value 60s Description Optional. The `receiveTimeout` specifies the amount of time that the 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 z/OS Connect Server waits for a response indefinitely. The default time unit is milliseconds.
sslCertsRef	Data type string Default value Not applicable Description Optional. Reference to an `ssl` repertoire element. Specify the SSL configuration to be used.
tokenEndpoint	Data type string Default value Not applicable Description Required. 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 and authentication server administrator for details of the path value required for that server.

zosconnect_authToken

Defines the configuration for obtaining access tokens from an authentication server.

Attribute name	Description
authServerRef	Data type string Default value Not applicable Description Required. Reference to the `zosconnect_authorizationServer` element that identifies the about the authentication server that is used to obtain access tokens.
cacheTokensWithJti	Data type boolean Default value false Description Optional. Specifies whether tokens issued by the authorization server that contain a jti claim are cached. Applicable only when the token is of type JWT and JWS.
header	Data type string Default value Authorization Description Optional. Specify the name of the header that contains the token on the request to the API endpoint.
id	Data type string Default value Not applicable Description Required. A unique configuration ID.
tokenLifetime	Data type A period of time with millisecond precision Default value 0 Description Optional. Available from 3.0.86.0. Specifies the period of time that tokens that are opaque or of type JWE are cached for. The default time unit is milliseconds. The time that is specified that is rounded down to the nearest second. This token lifetime value is overridden by a value obtained using `tokenLifetimePath` from the authentication server response.
tokenRefreshRate	Data type A period of time with millisecond precision Default value 0 Description Optional: Available from 3.0.70.0. Specifies a period of time after which an attempt is made to obtain a new token even if there is a non-expired cached token. If the attempt to obtain a new token fails, the existing cached token is used. If the time is set to `0`, tokens are cached and refreshed when they have expired. The default time unit is milliseconds.
useBearerScheme	Data type boolean Default value true Description Optional. Indicates whether to include the Bearer scheme in the HTTP header that contains the token on the API request.

Sub elements

zosconnect_authToken > tokenRequest

Description:

Required. Defines how the user credential is passed from the z/OS Connect Server to the authentication server.

Attribute name	Description
credentialLocation	Data type string Default value Not applicable Description Required. Specifies where the user credentials are included in the request to obtain a token from the authentication server. Supported values are: 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	Data type string Default value Authorization Description Optional. Specifies the name of a single header to contain the user credentials. From 3.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	Data type string Default value Not applicable Description Optional. Specifies the body of the token request that is sent to the authentication server, as a JSON string. Required when `credentialLocation` is set to body. From 3.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 3.0.70.0, custom parameter values set by the client application can also be substituted. Example A `"{"credentials":{ "username":"jwtuser", "password":"jwtpassword" } }"` In this example, the user credentials `"jwtuser"` and `"jwtpassword"` are directly included in the specified JSON string. Example B `"{"apiuser":"${userid}", "apipassword":"${password}"}"` 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 before this, `"` 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 `<` `>` escaped with `>` `&` escaped with `&`
requestMethod	Data type string Default value Not applicable Description Required. Specify the method of the HTTP request to the authentication server. Supported values are GET, PUT, or POST.

zosconnect_authToken > tokenResponse

Description:

Required. Defines how an access token is passed from the authentication server to the z/OS Connect Server.

Attribute name	Description
header	Data type string Default value Authorization Description Optional. Specify the name of the header that contains the token.
responseFormat	Data type string Default value Not applicable Description Optional. Specify the method of the HTTP request to the authentication server. Supported values are GET, PUT, or POST.
tokenLifetimePath	Data type string Default value Not applicable Description Optional. Available from 3.0.86.0. Applies only to tokens that are opaque or of type JWE. Specify the path to where the token lifetime is located in the JSON response body string when the `responseFormat` attribute is set to JSON. The value of this attribute must be a valid JSONPath expression. For example, if the token response is: `{ "access_token":"2YotnFZFEjr1zCsicMWpAA", "expires_in":3600 }` you must set the `tokenLifetimePath` attribute to `"$.expires_in"`.
tokenLocation	Data type string Default value Not applicable Description Required. Specify where the generated JWT is returned in the response from the authentication server to the z/OS Connect Server. Supported values are: header The token is returned in a header to z/OS Connect. If this value is set, the `header` attribute of the `tokenResponse` element must be specified. body The token is returned in the response body to z/OS Connect. If this value is set, the `responseFormat` and `tokenPath` attributes must be specified.
tokenPath	Data type string Default value Not applicable Description Optional. Specify the path to where the token is located in the JSON response body 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, you must set the `tokenPath` attribute to `"$.JWTinfo.tokenname"`. `{"JWTinfo":{ "tokenname": "eyJ0eXAiOiJKV1" } }`

zosconnect_authTokenLocal

Defines the locally generated JWT configuration in z/OS Connect.

Attribute name	Description
id	Data type string Default value Not applicable Description Required. A unique configuration ID.
header	Data type string Default value Authorization Description Optional. 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	Data type string Default value Not applicable Description Required. Reference to the id attribute value of a `jwtBuilder` element. For more information about the `jwtBuilder` element, see JWT Builder (jwtBuilder) in the WebSphere Application Server Liberty documentation.

Sub elements

zosconnect_authTokenLocal > claims

Data type:

A string or CDATA section.

Description:

Optional. 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:

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_authTokenLocal element. If the "sub" claim is specified on the claims subelement, its value is overwritten by the z/OS Connect Server to be the z/OS application asserted user ID. Registered claims are defined in the IANA JSON Web Token Claims Registry.
If the JSON string value of the claims subelement contains XML markup characters, such as <, >, or &, then include the JSON string inside a CDATA section so that those characters are treated as literals. For example, if one of the preceding private claims 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 3.0.59.0. Defines a group of CICS® connections that are used for workload distribution.

Attribute name	Description
cicsConnectionRefs	Data type string Default value Not applicable Description Required. List of references to a `zosconnect_cicsIpicConnection` or `zosconnect_cicsConnectionGroup` elements. 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	Data type Comma-separated list of integers. Default value Equal ratios Description 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. Minimum integer value is `0`. A value of zero indicates that no requests are to be sent over the corresponding connection.
id	Data type string Default value Not applicable Description Required. A unique configuration ID. This must match the value that is specified for the CICS connection that is 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	Description
authDataRef	Data type string Default value Not applicable Description 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	Data type string Default value Not applicable Description 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	Data type string Default value Not applicable Description 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	Data type A period of time with millisecond precision. Maximum: 3600s. Default value 30s Description Optional. Available from 3.0.59.0. This attribute applies only to IPIC connections that are configured within a CICS connection group element. The time interval at which z/OS Connect attempts to reestablish a failed connection to CICS, as a background task. Maximum value is `3600s`.
connectionTimeout	Data type A period of time with millisecond precision. Default value 30s Description Optional. The maximum amount of time that is allowed for the socket to establish a connection to CICS.
heartbeatInterval	Data type A period of time with millisecond precision. Default value 30s Description Optional. This attribute sets the time that the connection must be inactive before heartbeats are sent to CICS. A value of `0` disables IPIC heartbeats.
host	Data type string Default value Not applicable Description 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	Data type string Default value Not applicable Description Required. A unique configuration ID. This must match the value that is specified for the CICS connection that is selected when the z/OS Asset was created in the z/OS Connect Designer.
port	Data type integer Default value Not applicable Description 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. The minimum supported value is `1` and the maximum supported value is `65535`.
preferredSpecificHost	Data type string Default value Not applicable Description Optional. Available from 3.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 3.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 z/OS Connect Server is running. For more information, see Setting preferredSpecificHost="local".
preferredSpecificPort	Data type integer Default value Not applicable Description Optional. Available from 3.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. The minimum supported value is `1` and the maximum supported value is `65535`.
reconnectInterval	Data type A period of time with millisecond precision. Default value Not applicable Description Optional. Available from 3.0.56.0 and applicable only when `sharedPort="true"`. The time interval at which 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. A value of 0 disables the reconnect interval. The maximum value is `3600s`.
requestTimeout	Data type A period of time with millisecond precision. Default value 30s Description 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. A value of `0` disables this timeout.
sendSessions	Data type integer Default value 100 Required Optional Description This attribute sets the maximum number of simultaneous requests over the connection. The actual number of send sessions that are established depends on the value of sendSessions and the value in the RECEIVECOUNT parameter of the IPCONN definition in the CICS region. The minimum supported value is `1` and the maximum supported value in `999`.
sharedPort	Data type boolean Default value false Description Optional. Indicates whether the port attribute specifies a shared port or a specific port.
sslRef	Data type string Default value Not applicable Description Optional. Reference to an `ssl` repertoire element. Specify the SSL configuration to be used. Note: For compatibility with an earlier version with z/OS Connect zosConnect-2.0, 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	Data type string Default value CSMI Description Optional. A CICS transaction name; the transidUsage parameter specifies how the value is used.
transidUsage	Data type string Default value EIB_AND_MIRROR Description Optional. Specifies how the value of the transidUsage parameter is used. Supported values are: EIB_ONLY The transidUsage 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 transidUsage 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 transidUsage parameter is available to the called CICS program for querying the transaction ID. The value of the transidUsage parameter also appears in the EIBTRNID field of the CICS EIB.
zosConnectApplid	Data type string Default value Not applicable Description Optional. The APPLID of 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	Data type string Default value Not applicable Description Optional. The network ID of 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 z/OS Connect and CICS APPLID's 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_cicsJcicsConnection

Defines a connection to a local CICS region.

Attribute name	Description
id	Data type string Default value Not applicable Description Required. A unique configuration ID. This must match the value that is specified for the CICS connection that is selected when the z/OS Asset was created in the z/OS Connect Designer.

zosconnect_credential

Defines the basic authentication data to be used for a Db2® connection.

Attribute name	Description
id	Data type string Default value Not applicable Description A unique configuration ID.
password	Data type string Default value Not applicable Description The password of the user under which the request will be routed. The value can be stored in clear text or encoded. Typically, the password is encoded. To do so, use the `securityUtility` shipped with WebSphere® Liberty profile. For more information, see securityUtility command in the WebSphere Application Server Liberty documentation.
user	Data type string Default value Not applicable Description The name of the user under which the request will be routed.
applName	Data type string Default value Not applicable Description Name of the application that requests and uses the PassTickets.

zosconnect_db2Connection

Defines a connection to a Db2 endpoint.

Attribute name	Description
credentialRef	Data type string Default value Not applicable Description Reference to `zosconnect_credential` element that identifies the basic authentication data to be used for connecting to a Db2 endpoint.
host	Data type string Default value Not applicable Description IP address, domain name server (DNS) host name with domain name suffix, or just the DNS host name, used to route the request.
id	Data type string Default value Not applicable Description A unique configuration ID.
port	Data type string Default value Not applicable Description Port that is used for routing HTTP or HTTPS requests.
sslRef	Data type string Default value Not applicable Description Reference to an `ssl` repertoire element. Specify the SSL configuration to be used.

zosconnect_endpointConnection

Allows requests to be routed from z/OS Connect to an API endpoint.

Attribute name	Description
allowChunking	Data type boolean Default value true Description Available from 3.0.66.0. Allow chunking on messages greater than 4 KB.
authenticationConfigRef	Data type string Default value Not applicable Description Reference to a `zosconnect_authData`, `zosconnect_oAuthConfig`, or `zosconnect_authToken` element that identifies the authentication data that is used for basic authentication, OAuth 2.0 or JWT when the 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 Using API requester to call an API secured with multiple authentication and authorization methods.
connectionTimeout	Data type A period of time with millisecond precision. Default value 30s Description The connection timeout specifies the amount of time that the 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 z/OS Connect Server attempts to open a connection indefinitely.
domainBasePath	Data type string Default value Not applicable Description An extra path that is added between the `{host}:{port}` and `{basePath}` field in an API URL to identify domain-related information.
host	Data type string Default value Not applicable Description 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	Data type string Default value Not applicable Description A unique configuration ID.
port	Data type string Default value Not applicable Description Port that is used for routing HTTP or HTTPS requests.
proxyConfigRef	Data type string Default value Not applicable Description Reference to a `zosconnect_proxyConfig` element that identifies the proxy through which the request is routed from the z/OS Connect Server to the request endpoint.
receiveTimeout	Data type A period of time with millisecond precision. Default value 60s Description Specifies the amount of time that the 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 z/OS Connect Server waits for a response indefinitely. The default time unit is milliseconds.
requestCompression	Data type string Default value identity Description Specifies the type of request payload compression that is used on an endpoint request. Supported values are: gzip Content is compressed with gzip encoding. identity Content is not compressed. For more information, see Enabling payload compression.
responseCompression	Data type string Default value identity Description Specifies the type of response payload compression that is accepted from the endpoint. Supported values are: gzip Content is compressed with gzip encoding. identity Content is not compressed. For more information, see Enabling payload compression.
sslCertsRef	Data type string Default value Not applicable Description Reference to an `ssl` repertoire element. Specify the SSL configuration to be used.

zosconnect_libertyUserData

Defines the data into the System Management Facility (SMF) records for z/OS Connect that writes correlation information to the SMF 120 subtype 11 record User Data section. SMF 120 subtype 11.

Attribute name	Description
apiProviderEnabled	Data type boolean Default value true Description Optional. Indicates that z/OS Connect is acting as an API provider. When z/OS Connect functions as an API provider, the User Data is added to the WebSphere Application Server Liberty.
apiRequesterEnabled	Data type boolean Default value true Description Optional. Indicates that z/OS Connect is acting as an API requester. When z/OS Connect functions as an API requester, the User Data is added to the WebSphere Application Server Liberty.

zosconnect_imsConnection

Defines a connection to an IMS endpoint.

Attribute name	Description
id	Data type string Default value Not applicable Description Specify a unique ID for this IMS connection. This ID is the IMS connection that is selected within the z/OS Connect Designer.
`connectionFactoryRef`	Data type string Default value Not applicable Description Set this value to the ID of the `connectionFactory` element. For more information, see Configuring a z/OS Connect zosConnect-3.0 connection to IMS.
`pingIMSConnectOnInvoke`	Data type boolean Default value false Description Ping IMS Connect before the transaction is invoked to help 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`	Data type boolean Default value Not applicable Description Specify the commit mode. Supported values are: 0 Commit-then-send (CM0). 1 Send-then-commit (CM1).
`imsConnectTimeout`	Data type A period of time with millisecond precision Default value 30000 Description 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`	Data type string Default value Not applicable Description Specify the name of the IMS data store (IMS Connect).
`interactionTimeout`	Data type A period of time with millisecond precision Default value -1 Description 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. Supported values are -1, 0, or between 1 and 3600000 (one hour), inclusively. A value of 0 means that the timeout value is determined by IMS Connect. A value of -1 (the default) means to wait indefinitely.
`tranExpiration`	Data type boolean Default value false Description 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`	Data type boolean Default value true Description Optional. Specify whether to propagate the network security credential if the IMS Connect is V15 or later. 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`	Data type integer Default value 0 Description Optional. Specify the sync level. Specify the commit mode. Supported values are: 0 A value of 0 means None. A `commitMode` value of 0 (CM0, Commit-then-send) is invalid with `syncLevel` 0 (None). 1 A value of 1 means Confirm.
`imsConnectCodepage`	Data type string Default value Cp1047 Description Optional. Specify the code page to use for character string conversion with IMS Connect.
`ltermOverrideName`	Data type string Default value Not applicable Description Optional. Specify an 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	Description
id	Data type string Default value Not applicable Description A unique configuration ID.
apiProviderInterceptorsRef	Data type string Default value Not applicable Description Reference name that identifies the list of configured interceptors that are called for all API provider APIs.
apiRequesterInterceptorsRef	Data type string Default value Not applicable Description Reference name that identifies the list of configured interceptors that are called for all API requester APIs.

zosconnect_oAuthConfig

Defines the OAuth 2.0 configuration in 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	Description
authServerRef	Data type string Default value Not applicable Description Required. Reference to a `zosconnect_authorizationServer` element that identifies the information of an authorization server that is used for authentication and authorization.
clientSecretInBody	Data type boolean Default value false Description Optional. 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	Data type string Default value Not applicable Description Required. Specifies the OAuth 2.0 grant type. Supported values are: password The Resource Owner Password Credential grant type is used. client_credentials The Client Credentials grant type is used.
header	Data type string Default value Authorization Description Optional. The name of the header that contains the OAuth 2.0 access token on the API request.
id	Data type string Default value Not applicable Description Required. A unique configuration ID.
jwtAuthenticationSetClientId	Data type boolean Default value false Description Optional. 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	Data type string Default value Not applicable Description Optional. Reference to a `zosconnect_oAuthTokenConfig` element 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.
tokenPath	Data type string Description Optional. Optional. Available from 3.0.97.0.Specify the path to where the required token is located in the JSON response body string. The value of this attribute must be a valid JSONPath expression. For example, to retrieve the token from the `id_token` field in the following JSON string, set the `tokenPath` attribute to `"$.id_token"`. `{ "access_token": {access-token}, "token_type": "Bearer", "expires_in": 3600, "id_token": {identity-token} }` Default value `$.access_token`
tokenRetryCheckLevel	Data type string Default value 3 Description Optional. Specifies the checks to make before retrying a failed request to the API endpoint with a new OAuth 2.0 access token. Supported value are: 1 Retry the request if HTTP status code 401 is returned. 2 Not implemented. 3 Default value - Retry the request if HTTP status code 401 and a WWW_Authenticate header containing invalid_token are returned.
useBearerScheme	Data type boolean Default value true Description Optional. 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	Description
id	Data type string Default value Not applicable Description Required. A unique configuration ID.
tokenGeneratorRef	Data type string Default value Not applicable Description Required. Reference to the id attribute value of a `jwtBuilder`. For more information about the `jwtBuilder` element, see JWT Builder (jwtBuilder) in the WebSphere Application Server Liberty documentation.
tokenSubject	Data type string Default value Not applicable Description Required. The client ID to be used as the subject claim `"sub"` in the generated JWT token.

Sub elements

zosconnect_oAuthTokenConfig > claims

Data type:

A string or CDATA section

Description:

Optional. 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:

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 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.
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_policy`

Defines the z/OS Connect policy rules to be applied to API requests.

Attribute name	Description
id	Data type string Default value Not applicable Description Required. A unique configuration ID.
location	Data type string Default value ${server.config.dir}/resources/zosconnect/rules Description Optional. The directory where the rule set file is located.
pollingRate	Data type A period of time with millisecond precision Default value 1m Description Optional. For dynamic configuration, controls how often the server polls the directory that contains the ruleset files. The default time unit is milliseconds.
updateTrigger	Data type string Default value disabled Description Optional. Controls when the runtime is notified about changes in the ruleset directory. Supported values are: disabled Polling for updates is disabled. Updates can be triggered using the MODIFY refresh command. polled The server will periodically check for changes to the ruleset directory contents. The value of this attribute is ignored when the MODIFY command is used to refresh the z/OS Connect Server artifacts.

Sub elements

zosconnect_policy > ruleset

Attribute name	Description
file	Data type string Default value Not applicable Description Required. The file name of the rule set. Note: Do not include the path.

`zosconnect_proxyConfig`

Allows requests to be routed from z/OS Connect to an endpoint via a proxy.

Attribute name	Description
id	Data type string Default value Not applicable Description Required. A unique configuration ID.
host	Data type string Default value Not applicable Description 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.
password	Data type string Default value Not applicable Description Optional. Available from version 3.0.81.0. The password that is passed from z/OS Connect to the proxy server for proxy authentication. The value can be stored in clear text or encoded. Typically, the password is encoded. To do so, use the `securityUtility` shipped with WebSphere Liberty profile. For more information, see securityUtility command in the WebSphere Application Server Liberty documentation.
port	Data type integer Default value Not applicable Description Required. Port that is used by the proxy server for routing HTTP or HTTPS requests.
type	Data type string Default value Not applicable Description Required. The proxy type. Supported values are: HTTP Uses the HTTP internet protocol. If this element is referenced from a `zosconnect_authorizationServer` element that is referenced from a `zosconnect_authToken` element, the value must be HTTP. SOCKS Uses the SOCKS internet protocol.
user	Data type string Default value Not applicable Description Optional. Available from version 3.0.81.0. The user ID passed from z/OS Connect to the proxy server for proxy authentication.

zosconnect_zosConnectInterceptors

List of 1 to N interceptors.

Attribute name	Description
id	Data type string Default value Not applicable Description A unique configuration ID.
interceptorRef	Data type string Comma-separated string Default value Not applicable Description List of references to interceptor elements.