Configuration elements

Each server must have a server configuration file with the name server.xml in its server configuration directory ${server.config.dir}. You can keep all your configurations in a single server.xml file, or use include elements to consolidate configurations from separate files to create the structure that suits your needs. 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 information about 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_apiRequesters
  • apiRequester
• zosconnect_auditInterceptor
• zosconnect_authorizationServer
• zosconnect_authData
• zosconnect_authorizationInterceptor
• zosconnect_authToken
  • zosconnect_authToken>tokenRequest
  • zosconnect_authToken>tokenResponse
• zosconnect_authTokenLocal
  • claims
• zosconnect_bidiConfig
• zosconnect_dbServices
• zosconnect_endpointConnection
• zosconnect_cicsConnectionGroup
• zosconnect_cicsIpicConnection
• zosconnect_localAdaptersConnectService
• zosconnect_mqService
• zosconnect_oAuthConfig
• zosconnect_oAuthTokenConfig
  • claims
• zosconnect_policy
• zosconnect_proxyConfig
• zosconnect_services
  • service
    • property
• zosconnect_zosConnectAPIs
  • zosConnectAPI
• zosconnect_zosConnectDataXform
• zosconnect_fileSystemloggerInterceptor
• zosconnect_zosConnectInterceptors
• zosconnect_zosConnectManager
• zosconnect_zosConnectService
• zosconnect_zosConnectServiceRestClient
  • basicAuth
• zosconnect_zosConnectServiceRestClientConnection
  • basicAuth
• zosconnect_zosConnectServiceRestClientBasicAuth
• zosLocalAdapters (WOLA)

zosconnect_apiRequesters

Defines the directory where API requester archives are stored and how the server is notified about changes in this directory. It also defines other configuration parameters that apply to all API requesters.

Attribute name	Data type	Default value	Description
idAssertion	string	OFF	Controls whether identity assertion is enabled in z/OS Connect for API requesters, and whether a surrogate check is supported if identity assertion is enabled. This value can be overridden for individual API requesters by specifying the idAssertion attribute on the appropriate zosconnect_apiRequesters > apiRequester subelement. Acceptable values are OFF, ASSERT_SURROGATE, ASSERT_ONLY. OFF Identity assertion is not available in z/OS Connect for API requesters. z/OS applications cannot invoke an API requester with an asserted identity that is provided in the application context. ASSERT_SURROGATE Identity assertion is enabled in z/OS Connect for API requesters. z/OS applications can invoke an API requester with an asserted identity that is provided in the application context. With the ASSERT_SURROGATE value specified, z/OS Connect checks whether the identity used for authenticating the z/OS subsystem access to the z/OS Connect server is a surrogate of the asserted identity and whether the asserted identity has the authority to invoke the API requester. ASSERT_ONLY Identity assertion is enabled in z/OS Connect for API requesters. z/OS applications can invoke an API requester with an asserted identity that is provided in the application context. With the ASSERT_ONLY value specified, z/OS Connect directly checks whether the asserted identity has the authority to invoke the API requester. Depending on the values set for the idAssertion and requireAuth attributes, z/OS Connect performs different actions on the asserted identity and the identity that is used for authenticating the z/OS subsystem access to the z/OS Connect server. For more information, see Identity assertion for API requesters.
location	string	${server.config.dir}/resources/ zosconnect/apiRequesters	Path to a directory location where the API requester archive is stored. The value of location cannot be changed while the server is running; the value is set when the server is started.
pollingRate	long (A period with millisecond precision)	5s	Controls how often the server polls the apiRequesters directory. 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 500 ms. You can include multiple values in a single entry. For example, 1s500ms is equivalent to 1.5 seconds.
requireAuth	boolean		Available from V3.0.29.0. Requires that users specify security credentials to be authenticated and that the authenticated user is authorized under the zosConnectAccess role in order to access all API requesters. If the requireAuth attribute is not set, the global setting from the requireAuth attribute on the zosconnect_zosConnectManager element is used instead, unless the requireAuth attribute is overridden on the specific API requester.
requireSecure	boolean		Available from V3.0.45.0. Requests for API requesters are sent over HTTPS. If requireSecure is not set, the global setting from the requireSecure attribute on the zosconnect_zosConnectManager element is used instead. You can override this value for individual API requesters by specifying the requireSecure attribute on the appropriate zosconnect_apiRequesters > apiRequester subelement.
updateTrigger	string	disabled	Controls when the server is notified about changes in the apiRequesters directory. Acceptable values are disabled, polled, or mbean. disabled Polling for updates is disabled. Updates can be triggered by using the MODIFY refresh command, and the RESTful administration interface can be used to deploy API requester archive files. polled The server checks periodically for changes to the directory contents. mbean The server checks for changes when the notifyFileChanges method is invoked on the FileNotificationMBean. If you specify this value, you must also configure your server to use the Java™ Management Extensions (JMX) connector. For more information, see Using an MBean to trigger updates. The value of this attribute is ignored when the MODIFY command is used to refresh the z/OS Connect server artifacts.

Sub elements

zosconnect_apiRequesters > apiRequester

Description: Defines other configuration options for the API requester archive.

Required: false

Attribute name	Data type	Default value	Description
name	string		The name of the API requester. The API requester is named automatically when the API requester archive file is generated. The name of the API requester indicates the name and version of the API to be called, and is associated with the API requester archive file to be used. For more information, see Configuring IBM z/OS Connect to support API requesters.
idAssertion	string		Available from V3.0.45.0. Controls whether identity assertion is enabled in IBM z/OS Connect for this API requester, and, if identity assertion is enabled, whether a surrogate check is supported. If the idAssertion attribute is not set, the setting for all API requesters from the idAssertion attribute on the zosconnect_apiRequesters element is used instead. Acceptable values are OFF, ASSERT_SURROGATE, and ASSERT_ONLY. OFF Identity assertion is disabled in IBM z/OS Connect for this API requester. z/OS applications cannot invoke this API requester with an asserted identity that is provided in the application context. ASSERT_SURROGATE Identity assertion is enabled in IBM z/OS Connect for this API requester. z/OS applications can invoke this API requester with an asserted identity that is provided in the application context. With the ASSERT_SURROGATE value specified, IBM z/OS Connect checks whether the identity used for authenticating the z/OS subsystem access to the IBM z/OS Connect server is a surrogate of the asserted identity and whether the asserted identity has the authority to invoke the API requester. ASSERT_ONLY Identity assertion is enabled in IBM z/OS Connect for this API requester. z/OS applications can invoke this API requester with an asserted identity that is provided in the application context. With the ASSERT_ONLY value specified, IBM z/OS Connect directly checks whether the asserted identity has the authority to invoke the API requester. Depending on the values set in the idAssertion and requireAuth attributes, IBM z/OS Connect performs different actions on the asserted identity and the identity that is used for authenticating the z/OS subsystem access to the IBM z/OS Connect server. For more information, see Identity assertion for API requesters.
requireSecure	boolean		Requires that requests are sent over HTTPS. If the requireSecure attribute is not set, the setting for all API requesters from the requireSecure attribute on the zosconnect_apiRequesters element is used instead. If the requireSecure attribute on the zosconnect_apiRequesters element is also not set, the global setting from the requireSecure attribute on the zosconnect_zosConnectManager element is used instead.
requireAuth	boolean		Requires that users specify security credentials to be authenticated and that the authenticated user is authorized under the zosConnectAccess role to access the specific API requester. If the requireAuth attribute is not set, the setting for all API requesters from the requireAuth attribute on the zosconnect_apiRequesters element is used instead. If the requireAuth attribute on the zosconnect_apiRequesters element is not set either, the global setting from the requireAuth attribute on the zosconnect_zosConnectManager element is used instead.
runGlobalInterceptors	boolean	true	Indicates whether to run global interceptors for requests that are associated with this API requester. Global interceptors are listed in globalInterceptorsRef in the zosconnect_zosConnectManager element. By default, IBM z/OS Connect processes all global and API requester-specific interceptors. If the runGlobalInterceptors attribute is set to false, IBM z/OS Connect processes only the set of interceptors that are listed in the interceptorsRef attribute.
interceptorsRef	string		A reference name that identifies the set of configured interceptors that are associated with this API requester.
connectionRef	string		Reference to the top level zosconnect_endpointConnection element. If set, the connection is made by using the attributes of the zosconnect_endpointConnection element; if not set, or the associated zosconnect_endpointConnection element does not exist, the value of the connectionRef attribute in the build toolkit properties file is used, and if the value of the connectionRef attribute in the build toolkit properties file does not exist either, an error occurs.
adminGroup	string		Identifies the users that are able to use administrative functions on this API requester. The value of this attribute can be set to a group name or a comma-separated list of group names that are defined in the user registry. If globalAdminGroup is also under element zosconnect_zosConnectManager, the value that is defined under adminGroup is used. This group takes precedence over the global group except when controlling authorization to the RESTful administration actions to deploy an API, deploy a service, list all APIs, or list all services. See Note 1 and Note 2.
invokeGroup	string		Identifies the users that are able to invoke this API requester. The value of this attribute can be set to a group name or a comma-separated list of group names that are defined in the user registry. If globalInvokeGroup is also defined under the zosconnect_zosConnectManager element, the value that is defined under invokeGroup is used. See Note 1 and Note 2.
operationsGroup	string		Identifies the users that are able to perm operations such as starting or stopping this API requester. The value of this attribute can be set to a group name or a comma-separated list of group names that are defined in the user registry. If globalOperationsGroup is also defined in the zosconnect_zosConnectManager element, the value that is defined under operationsGroup is used. This group takes precedence over the global group except when controlling authorization to the RESTful administration actions to deploy an API, deploy a service, list all APIs, or list all services. See Note 1 and Note 2.
readerGroup	string		Identifies the users that are able to get information about this API requester, including the Swagger documentation. The value of this attribute can be set to a group name or a comma-separated list of group names that are defined in the user registry. If globalReaderGroup is also defined under the zosconnect_zosConnectManager element, the value that is defined under readerGroup is used. See Note 1 and Note 2.
oAuthResource	string		Available from V3.0.51.0. An OAuth 2.0 resource parameter to be included in the access token request to an OAuth 2.0 authorization server. This parameter is applicable only when API request uses a zosconnect_endpointConnection definition that has an authenticationConfigRef of type zosconnect_oAuthConfig. This value overrides any value that is specified by BAQ-OAUTH-RESOURCE-PTR in the z/OS application.

Note:

1. If you use an LDAP registry, you must specify each LDAP group's distinguished name (DN) with the commas that are escaped with a backslash. For example, "cn=employees\,ou=groups\,o=intern\,c=fr, cn=managers\,ou=groups\,o=intern\,c=fr". If you specify multiple groups, the commas that separate the groups are not escaped. Specifying LDAP short names is not supported.
2. For information about the authorization levels that are required to perform particular requests, see API requester authorization.

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 and subtype 2 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, see Defining and mapping headers, query parameters, or path parameters.
apiRequesterSmfVersion	integer Minimum: 1 Maximum: 2	1	Available from V3.0.45.0. 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.
apiRequesterRequestHeaders	string		Available from V3.0.45.0. (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	string		Available from V3.0.45.0. (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.
apiProviderMaxDelay	A time period with second precision	-1	Available from V3.0.58.0. 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 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.
apiRequesterMaxDelay	A time period with second precision	-1	Available from V3.0.58.0. The maximum time the audit interceptor waits before writing an SMF 123 subtype 2 version 2 record with less than the maximum number of requests 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 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.
apiProviderEarlyFailure	boolean	false	Available from V3.0.58.0. Indicates whether SMF subtype 1 version 2 records are written for early request failures for API provider.
apiRequesterEarlyFailure	boolean	false	Available from V3.0.58.0. Indicates whether SMF subtype 2 version 2 records are written for early request failures for API requester.

zosconnect_authData

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

Attribute name	Data type	Default value	Description
id	string		The element identifier.
password	string		The password that is passed from the IBM z/OS Connect server 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 server.xml file. The password can be a password phrase.
user	string		The user ID that is passed from the IBM z/OS Connect server to establish the connection on every request, if no user ID is supplied on the request.

zosconnect_authorizationInterceptor

Defines an IBM z/OS Connect authorization interceptor.

Attribute name	Data type	Default value	Description
id	string		A unique configuration ID.
safCacheTimeout	integer Minimum: -1 Maximum: 2147483647	600	Specifies the amount of time in seconds that SAF credentials are kept in the SAF cache that is used by the ID assertion feature. If the timeout value is set to 0, the cache is disabled. If set to -1, SAF credentials are kept indefinitely. Specify -1 or a positive integer in the range 0 - 2147483647. The cache is cleared if the timeout value is changed and the configuration refreshed.
sequence	integer Minimum: 0 Maximum: 2147483647	0	The sequence in which this interceptor is processed compared to other configured interceptors that implement the IBM z/OS Connect com.ibm.wsspi.zos.connect.Interceptor Service Provider Interface (SPI).

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 access token authentication 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 and authentication server administrator for details of the path value required for that server.
basicAuthRef	Reference to top level zosconnect_authData element (string)		A 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 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	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 and 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 the 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 and 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	Available from V3.0.51.0. 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 though 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	Available from V3.0.47.0. 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	Specify 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 that is 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 before this, &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. Before to V3.0.69.0, no Accept header was 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 that are 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 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.
2. 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 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 run time. 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 connectionRef build toolkit property, or API toolkit connection reference property, that is used to generate the .sar files that use this connection group with the CICS service provider.

zosconnect_cicsIpicConnection

Represents a connection to a CICS system.

Note: When an IPIC connection is established with CICS, updates to the authDataRef, transid, transidUsage, preferredSpecificHost and preferredSpecificPort attributes take immediate effect but updates to other attributes that are associated with 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 reestablish 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), 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 this timeout.
heartbeatInterval	A period of time with millisecond precision. Maximum: 3600s.	30s	Optional. 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), 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 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. If using Sysplex Distributor, it is the hostname of the sysplex.
id	string		Required. A unique configuration ID. This must match the value that is specified for the connectionRef build toolkit property that is used to generate the .sar files that use this connection with the CICS service provider.
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 the preferred host is the LPAR on which the z/OS Connect server is running. For more information, see Setting preferredSpecificHost="local".
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.
sendSessions	integer Minimum: 1 Maximum: 999	100	Optional. 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.
sharedPort	boolean	false	Optional. Indicates whether the port attribute specifies a shared port or a specific port.
sslCertsRef	string		Optional. Reference to an SSL repertoire with an ID, a defined keystore and truststore, or an SSL Default repertoire.
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 the z/OS Connect server that is 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 the IBM z/OS Connect server that is 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_bidiConfig

The following table contains all elements that are available for configuring bidi support.

Table 1. zosconnect_bidiConfig Attributes

Attribute	Description
id	Unique ID of the bidi service configuration.
inOrder	Order of the input text received by the service.
inDirection	Direction of the input text, which is either LTR or RTL. The default is LTR.
inHostOrder	The desired order of the transformed input text, which is either LOGICAL or VISUAL. The default is LOGICAL.
inSymmetricSwapping	Indicates whether to replace characters having directional meaning with the opposite direction when transforming the input text. Characters such as [ ] { } ( ) < > all have directional meaning. The default is false.
inArabicShapingOptions	Arabic digit and letter shaping options to apply when transforming the input text. For more information, see Unicode ICU Arabic Shaping documentation.
outHostOrder	Order of the host text, which is either LOGICAL or VISUAL. The default is LOGICAL
outHostDirection	The direction of the host text, which is either LTR or RTL. The default is LTR.
outOrder	The desired order of the output text, which is either LOGICAL or VISUAL. The default is LOGICAL.
outDirection	The desired direction of the output text, which is either LTR or RTL. The default is LTR.
outSymmetricSwapping	Indicates whether to replace characters having directional meaning with the opposite direction when transforming the host text. Characters such as [ ] { } ( ) < > all have directional meaning. The default is false.
outArabicShapingOptions	Arabic digit and letter shaping options to apply when transforming the host text. For more information, see Unicode ICU Arabic Shaping documentation.

zosconnect_dbServices

Defines the location for your user type converter libraries for IMS Database services. To learn more, see Configuring user type converter support for IMS database services.

Attribute name	Data type	Default value	Description
imsDbUtcPaths	string		A colon separated list of fully qualified file paths to your .jar files that contain user type converters.

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.
basicAuthRef	Reference to the top level zosconnect_authData element. (string)		A reference name that identifies the basic authentication data to be used for connecting to a request endpoint. This attribute is now deprecated. It is recommended to use the authenticationConfigRef attribute instead.
authenticationConfigRef	Reference to top level zosconnect_authData, zosconnect_oAuthConfig, zosconnect_authToken or zosconnect_authTokenLocal element. (string)		A 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. For using a JWT that is locally generated by the IBM z/OS Connect server, it must be associated with the zosconnect_authTokenLocal 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	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.
requestCompression	string	identity	Specifies the type of request payload compression used on an endpoint request. Valid options are: gzip - Content is compressed with gzip encoding. identity - Content is not compressed. For more information, see Enabling payload compression.
responseCompression	string	identity	Specifies the type of response payload compression that is accepted from the endpoint. Valid options are: gzip - Content is compressed with gzip encoding. identity - Content is not compressed. For more information, see Enabling payload compression.
sslCertsRef	string		An SSL repertoire with an ID, a defined keystore, and truststore.
proxyConfigRef	Reference to the 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_localAdaptersConnectService

Represents a WOLA service:

The following table lists the attributes that are applicable to both COMMAREA and channel payloads.

Attribute name	Data type	Default value	Description
connectionFactoryRef	string		Reference to the configured connection factory element that contains the JNDI name of the WOLA resource adapter connection factory to be used.
connectionWaitTimeout	integer Minimum: 0 Maximum: 2147483647		Number of seconds to wait for an external address space application that matches the registration name to issue a WOLA Receive Request or Host Service API and become active.
id	string		A unique configuration ID.
serviceName	string		Name of the WOLA target service. This service name must match the name an external address space application is using for the service name on a WOLA Receive Request or Host Service API call, or the program name used for SVC with a WOLA CICS Link Server.
registerName	string		Name of the WOLA target register. This name must match the name an external address space application is using for the register name on a WOLA Register API call, or the name used for Register Name with a WOLA CICS Link Server.
linkTaskTranID	string		When using the WOLA CICS Link Server, specifies the name of the WOLA CICS Link Server link invocation task transaction ID.
useCICSContainer	boolean	false	When using the WOLA CICS Link Server, defines the mechanism to use for data propagation. When set to true, the payload is passed to the target CICS application program using CICS containers. When set to false (default), the payload is passed the target CICS application program using a COMMAREA. See the following tables for a description of the additional attributes required for channel payloads.
useGenericError	boolean	false	When enabled, all error cases from the service return an HTTP status code of 500 Internal Server Error. This option is retained for compatibility with previous versions of IBM z/OS Connect.

There are two different methods of specifying the channel and container attributes. These methods are mutually exclusive:

• Method 1: Use a channel name of IBM-WAS-ADAPTER to flow a single payload container. Specify the following attributes:

  Attribute name	Data type	Default value	Description
  linkTaskReqContID	string		When using the WOLA CICS Link Server and the linkTaskRspContID and useCICSContainer (true) attributes are also configured, specifies the name of the request, or input, container. The default CICS channel name is IBM-WAS-ADAPTER. The container name must not include blank characters.
  linkTaskReqContType	integer Minimum: 0	0	When using the WOLA CICS Link Server and the linkTaskReqContID and useCICSContainer (true) attributes are also configured, specifies the type of the request container (0=CHAR, 1=BIT). The default CICS channel name is IBM-WAS-ADAPTER.
  linkTaskRspContID	string		When using the WOLA CICS Link Server and the linkTaskReqContID and useCICSContainer (true) attributes are also configured, specifies the name of the response, or output container. The container name must not include blank characters.
  linkTaskRspContType	integer Minimum: 0	0	When using the WOLA CICS Link Server and the linkTaskRspContID and useCICSContainer (true) attributes are also configured, specifies the type of response container (0=CHAR, 1=BIT).

• Method 2: Use a channel name of your choice to flow a single payload container with the HTTP context containers. Specify the following attributes:

  Attribute name	Data type	Default value	Description
  linkTaskChanID	string		When using the WOLA CICS Link Server and the useCICSContainer (true) attribute is also configured, specifies the CICS channel name to use for delivering messages and receiving payloads using CICS containers. The channel name must not include blank characters.
  linkTaskChanType	integer Minimum: 0	0	When using the WOLA CICS Link Server and the linkTaskChanID and useCICSContainer (true) attributes are also configured, specifies the type of the CICS containers (0=CHAR, 1=BIT) that are to be associated with the configured channel ID. When set to 0(default), the encoding of the character data in the input/output containers are expected/returned in ASCII (CCSID 819) and the data is converted to or from EBCDIC (cp037) before/after it is sent to/from the destination program. Use the BIT type to avoid data type and encoding expectations.
  linkTaskChanReqContID	string	ZCONReqData	When using the CICS Link Server and when the linkTaskChanID and useCICSContainer (true) attributes are also configured, specifies the name of the request container. The container name must not include blank characters.
  linkTaskChanRespContID	string	ZCONRespData	When using the CICS Link Server and when the linkTaskChanID and useCICSContainer (true) attributes are also configured, specifies the name of the response container. The container name must not include blank characters.
  linkTaskChanCtxContEncoding	string	cp819	When using the CICS Link Server and when the linkTaskChanID and useCICSContainer (true) attributes are also configured, specifies the encoding of the data in all context containers that are sent to the destination program.
  linkTaskChanCtxContHttpHeaders	string		When using the CICS Link Server and the linkTaskChanID and useCICSContainer (true) attributes are also configured, specifies the HTTP header name or list of comma-separated and case-sensitive HTTP header names that are passed to the destination program using the context container with the name of ZCONHTTPHeaders. The information that is contained in this context container is in JSON format: {httpHeaders:{"header1":"header1Value", ...,"header-n":"headerValue-n"}}. If the request contains multiple headers with the same name, the value that is used is the one for the first header in the request.

zosconnect_mqService

Defines a one or two-way service for the IBM MQ Service Provider.

Note: This element is for users who have already created services from the IBM MQ service provider that is shipped with IBM MQ. Users who want to create new services should use service archive files. For more information, see Migrating a service to the IBM MQ service provider in IBM z/OS Connect.

Attribute name	Data type	Default value	Description
connectionFactory	A JNDI name (string).		Required. Specifies the JNDI name of an IBM MQ messaging provider connection factory. The IBM MQ service provider uses the connection factory to connect to IBM MQ. For more information, see JMS Connection Factory (jmsConnectionFactory) in the WebSphere Application Server for z/OS Liberty documentation.
destination	A JNDI name (string).		Required. Specifies the JNDI name of an IBM MQ messaging provider destination. For a one-way service, the target for HTTP POST, HTTP GET, and HTTP DELETE requests. Queue destinations are supported for all three request types whereas topic destinations are supported only with HTTP POST requests. For a two-way service, destination must be a queue destination that represents the request queue that is used by the back-end service. Two-way services support only HTTP POST requests. For more information, see JMS Queue (jmsQueue) and JMS Topic (jmsTopic) in the WebSphere Application Server for z/OS Liberty documentation.
expiry	integer	-1	Optional. Specifies the length of time, in thousandths of a second, that messages that are sent that are by the MQ service provider are valid. Messages become eligible to be discarded if they have not been removed from the destination queue before this period of time elapses. A negative value means that messages never expire. REST clients can override expiry by specifying an ibm-mq-md-expiry HTTP header with a valid 64-bit integer.
id	string		Required. Must be unique across all elements in server.xml. id is used by the zosConnectService element to refer to a target service provider instance.
mqmdFormat	string		Optional. Used to set the value of the MQMD format field in messages that are sent by the IBM MQ service provider. Only used when the IBM MQ service provider is configured to use IBM z/OS Connect data transformations, otherwise it is ignored. If you do not specify this attribute, and data transformations are used, messages are sent with the MQMD format field set to "MQSTR". The length of this attribute must be less than, or equal to, 8 characters.
password	string		Optional. The password that the IBM MQ service provider presents to IBM MQ for authentication and authorization purposes. You can specify the password in plain text, but the best practice is to encode the password using the securityUtility tool that is provided with IBM z/OS Connect, with the encode option. For more information, see Liberty: securityUtility command. If you do not specify this attribute, the value in the password attribute that is specified in the Connection Factory referred to by the connectionFactory attribute is used. If a password attribute is specified both on the referenced connection factory and on this zosconnect_mqService element, the value in the zosconnect_mqService element is used. If you specify this attribute, you must also specify the userName attribute.
persistence	boolean	false	Optional. Specifies the persistence of messages that are sent by a service and is equivalent to setting the MQMD Persistence field. The value must be one of the following: false Means that messages are non-persistent. true Means that messages are persistent. You can override persistence by setting one of these values in the ibm-mq-md-persistence HTTP header.
receiveTextCCSID	integer	37	Optional. The CCSID that is used to transform the data in a javax.jms.TextMessage message. For example, an HTTP GET or HTTP DELETE with a one-way service, or when retrieving a response message for a two-way service. The text in the message is converted into the CCSID specified by receiveTextCCSID.
replyDestination	A JNDI name (string).		Optional. Specifies the JNDI name of an IBM MQ messaging provider queue where the back-end service sends reply messages. If replyDestination is not specified, the service is a one-way service. If replyDestination is specified, the service is a two-way service.
replySelection	string	msgIDToCorrelID	Optional. Describes the mechanism that is used to match reply messages with request messages. replySelection is used only with two-way services. If replySelection is used with a one-way service, it is ignored. Specify one of the following values: msgIDToCorrelID Reply messages are assumed to be generated with the correlation ID set to the value of the message ID from the request message. The service generates a suitable message selector based on this information. correlIDToCorrelID Reply messages are assumed to be generated with the correlation ID set to the value of the correlation ID from the request message. The service generates a suitable message selector based on this information. If the request message does not have a correlation ID specified, the service generates a random correlation ID for the request message. none No mechanism is used to correlate reply messages with request messages. The service gets the first available message on the reply queue.
selector	string		Optional. Used on HTTP GET and HTTP DELETE requests to select which message is returned. Must be set to a valid JMS message selector as described by the JMS specification. If ibm-mq-md-msgID or ibm-mq-md-correlID headers are specified, selector is ignored. selector is only used with one-way services and is optional. If selector is specified on a two-way service it is ignored. Some characters in the attribute value must be escaped in order to be embedded in server.xml because these special characters cannot be directly used in XML. For example, " escaped with &quot; ' escaped with &apos; < escaped with &lt; > escaped with &gt;
useCallerPrincipal	boolean	false	Optional. When set to true, the name of the authenticated principal of a request to IBM z/OS Connect, is passed on to IBM MQ for authentication and authorization purposes. The name of the principal, but not the password, is used when connecting to IBM MQ. Any values that are specified in the password and userName attributes are ignored.
userName	string		The user name that the IBM MQ service provider presents to IBM MQ for authentication and authorization purposes. If you do not specify this attribute, the value of the userName attribute that is specified in the connection factory referred to by the connectionFactory attribute is used. If a userName attribute is specified on both the referenced connection factory and this zosconnect_mqService element, the value in the zosconnect_mqService element is used. If you specify this attribute, you must also specify the password attribute.
waitInterval	integer		This attribute is optional for one-way services, required for two-way services. For HTTP DELETE requests to one-way services, waitInterval specifies the number of milliseconds that the service waits for a matching message on the queue specified by the destination attribute. For HTTP POST requests to two-way services, waitInterval specifies the number of milliseconds that the service waits for a matching message on the queue that is specified by the replydestination attribute. waitInterval is not supported with HTTP GET requests. If waitInterval is zero, the service does not wait. A waitInterval of zero is not supported with two-way services. If waitInterval is negative, the service waits for ever until a message is available. REST clients can override this value by specifying an ibm-mq-gmo-waitInterval HTTP header with a valid 64 bit integer. Note: Specifying a large, or negative waitInterval, is likely to result in transaction timeouts and asynchronous service request timeouts. If these events occur, you can increase the timeout, reduce the wait interval, or do both.

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 Calling an OAuth 2.0 authorization server.

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	Available from V3.0.49.0. 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	Available from V3.0.51.0. 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).		Available from V3.0.51.0. 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

Available from V3.0.51.0. Defines the configuration that is used to generate a JWT for authentication when 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 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_policy

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

Attribute name	Data type	Default value	Description
id	string		Required. Unique name to identify this policy.
location	string	${server.config.dir}/resources/ zosconnect/rules	The directory where the rule set file is located.
pollingRate	long (A period of time with millisecond precision)	1m	For dynamic configuration, controls how often the server polls the directory that contains the ruleset files. 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.
updateTrigger	string	disabled	Controls when the runtime is notified about changes in the ruleset directory. Acceptable values are disabled or polled. 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 IBM z/OS Connect server artifacts.

Sub elements

zosconnect_policy > ruleset

Description: Defines the name of the rule set file.

Required: true

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

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.
password	string		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 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.
port	integer		Required. Port that is used by the proxy server for routing HTTP or HTTPS requests.
type	string		Required. The proxy type. Set the value to HTTP or SOCKS. If this element is referenced from a zosconnect_authorizationServer element that is referenced from a zosconnect_authToken element, the value must be HTTP.
user	string		Available from version 3.0.81.0. The user ID passed from z/OS Connect to the proxy server for proxy authentication.

zosconnect_services

Defines the directory where service archive files are stored and how the server is notified about changes in this directory. This element must be defined for service archive files to be processed at server start up, even if all the attributes use their default values.

Note: This element is only for specific services that are defined by service archive files (.sar files)

Attribute name	Data type	Default value	Description
location	string	${server.config.dir} /resources /zosconnect/services	Path to a directory location where service archive (.sar) files are stored. This location is referred to as the services directory. The value of location cannot be changed while the server is running; the value is set when the server is started.
pollingRate	A period of time with millisecond precision	5s	Controls how often the server polls the services directory. 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.
updateTrigger	string	disabled	Controls when the server is notified about changes in the services directory. Acceptable values are disabled, polled or mbean. disabled Polling for updates is disabled. Updates can be triggered using the MODIFY refresh command, and service archive files can be deployed using the RESTful administration interface. polled The server periodically checks for changes to the directory contents. mbean The server checks for changes when the notifyFileChanges method is invoked on the FileNotificationMBean. If you specify this value, you must also configure your server to use the Java Management Extensions (JMX) connector. For more information, see Using an MBean to trigger updates. The value of this attribute is ignored when the MODIFY command is used to refresh the IBM z/OS Connect server artifacts.

Sub elements

zosconnect_services > service

Description: Defines additional configuration for the service.

Required: false

Attribute name	Data type	Default value	Description
name	string		The name of the service.
requireSecure	boolean		Require that requests are sent over HTTPS. If the requireSecure attribute is not set, the global setting from the requireSecure attribute on the zosconnect_zosConnectManager element that is referenced is used instead.
requireAuth	boolean		Require that users specify security credentials to be authenticated and that the authenticated user is authorized under the zosConnectAccess role, in order to access the service. If the requireAuth attribute is not set, the global setting from the requireAuth attribute on the zosconnect_zosConnectManager element is used instead.
runGlobalInterceptors	boolean	true	Indicates whether global interceptors should run for requests that are associated with this service. Global interceptors are listed in globalInterceptorsRef in the zosconnect_zosConnectManager element. By default, IBM z/OS Connect processes all global and service endpoint-specific interceptors. If the runGlobalInterceptors is set to false, IBM z/OS Connect processes only the set of interceptors that are listed in the interceptorsRef attribute.
interceptorsRef	string		A reference name that identifies the set of configured interceptors that are associated with this service. Note: If the service is called by an API, only the interceptors that are configured for that API are processed. Interceptors that are defined for the service are ignored.
adminGroup	string		Identifies the users that are able to use administrative functions on this service. The value of this attribute can be set to a group name or a comma-separated list of group names, that are defined in the user registry. If globalAdminGroup is also defined under element zosconnect_zosConnectManager, the value that is defined under adminGroup is used. This group takes precedence over the global group except when controlling authorization to the RESTful administration actions to deploy an API, deploy a service, list all APIs, or list all services. See Note 1 and Note 2.
invokeGroup	string		Identifies the users that are able to invoke this service. The value of this attribute can be set to a group name or a comma-separated list of group names, that are defined in the user registry. If globalInvokeGroup is also defined under element zosconnect_zosConnectManager, the value that is defined under invokeGroup is used. See Note 1 and Note 2.
operationsGroup	string		Identifies the users that are able to perform operations such as starting or stopping this service. The value of this attribute can be set to a group name or a comma-separated list of group names, that are defined in the user registry. If globalOperationsGroup is also defined under element zosconnect_zosConnectManager, the value that is defined under operationsGroup is used. This group takes precedence over the global group except when controlling authorization to the RESTful administration actions to deploy an API, deploy a service, list all APIs, or list all services. See Note 1 and Note 2.
readerGroup	string		Identifies the users that are able to get information about this service, including the Swagger documentation. The value of this attribute can be set to a group name or a comma-separated list of group names, that are defined in the user registry. If globalReaderGroup is also defined under element zosconnect_zosConnectManager, the value that is defined under readerGroup is used. See Note 1 and Note 2.
property	A list of property elements.		The property elements define the override properties for the service archive file.

Note:

1. If using an LDAP registry, you must specify each LDAP group's distinguished name (DN) with the commas that are escaped with a backslash. for example "cn=employees\,ou=groups\,o=intern\,c=fr, cn=managers\,ou=groups\,o=intern\,c=fr". If specifying multiple groups, the commas separating the groups are not escaped. Specifying LDAP short names is not supported.
2. For information about the authorization levels that are required to perform particular requests, see API provider authorization

zosconnect_services > service > property

Description: Optional properties for the service provider. These values take precedence over equivalent values specified in the service archive file.

Required: false

Attribute name	Data type	Default value	Description
name	string		The name of the property
value	string		The value of the property

The values that can be specified for the name attribute are specific to the service provider being used by the service. The following name attribute values are supported:

• CICS service provider:

  Attribute name	Description
  connectionRef	Available from version 3.0.81.0. Overrides the CICS IPIC connection reference specified in the service archive file.
  transid	Overrides the transaction ID specified in the service archive file.
  transidUsage	Overrides the transaction ID usage value specified in the service archive file.

• Db2 service project

  Attribute name	Description
  collectionId	Overrides the value of Collection ID that was entered in the project editor.
  connectionRef	Overrides the value of Connection Reference that was entered in the project editor.

• REST client service provider: does not support optional properties.
• WOLA service provider: tranId.
• IMS service provider:

  Attribute name	Default value	Description
  imsTranCodeOverride		Overrides the transaction code that the service invokes at run time.
  imsConnectionRef		Name of the connection profile to use at service invocation. This value overrides the connection profile that is specified in the API toolkit during service archive file generation.
  imsInteractionRef		Name of the interaction profile to use at service invocation. This value overrides the interaction profile that is specified in the API toolkit during service creation.
  imsDatastoreOverride		Overrides the IMS datastore name that specifies the IMS subsystem against which to invoke the service.
  trimOutputLeadingWhitespace	false	Trims the leading white space from JSON property values in the output messages. By default, leading white space is not trimmed.
  trimOutputTrailingWhitespace	true	Trims trailing white space from JSON property values in output messages. By default, trailing white space is trimmed.
  escapeOutputControlCharacters	false	Escapes non-printable control characters, such as tokens or control blocks, in JSON property values as \uNNNN for necessary internal processing, instead of removing them. By default, control characters are omitted, not escaped.
  initializeInputFields	false	Initializes fields in the input data structure according to their type if a default is not specified for the field and either the field is omitted from the input interface or the field is included but the respective JSON tag is not received at run time. By default, fields are not initialized.
  omitOutputFieldsByValue	false	Omits the JSON name-value pair for a non-numeric field from the JSON output message when the data for the field is composed of the same byte value that is repeated throughout, such as all 0x00 or all 0xFF. By default, this option is set to false.
  omitOutputFieldsByValueByte	00	Specifies the hexadecimal value that all bytes in a non-numeric field must contain to be omitted. The default value is 00.
  omitOutputEmptyTags	false	Omits JSON tags that contain an empty string ("tag":"") from JSON output messages after white space and control characters are processed. By default, empty tags are not omitted.
  enforceMinArrayOccurrence	true	Enforces the minimum number of array occurrences in the input data structure as defined in the copybook. By default, minimum number of array occurrences is enforced.

• IBM MQ service provider:

  Property name	Default value	Description
  connectionFactory		Defines a JNDI name that is used to locate a connection factory that connects to a z/OS queue manager on the same LPAR as the IBM z/OS Connect server or on a different LPAR. For more information, see JMS connection factory in the WebSphere Application Server for z/OS Liberty documentation.
  destination		Defines a JNDI name that is used to locate an IBM MQ queue or topic. For one-way services for sending messages, the queue or topic that messages are put to. For one-way services for receiving messages, this value is the name of the queue where messages are destructively got. For two-way services, this value is the name of the queue where request messages are put. For more information, see the following topics in the WebSphere Application Server for z/OS Liberty documentation: JMS Queue (jmsQueue) if the destination is a queue or JMS Topic (jmsTopic) if the destination is a topic.
  expiry	-1	Specifies the expiry time in milliseconds of messages that are sent by the IBM MQ service provider. If set, the value is an integer that describes how long the message is available before it expires. By default, messages do not expire. expiry is equivalent to setting the MQMD Expiry field. Negative values mean that messages never expire. REST clients can override expiry by specifying an ibm-mq-md-expiry HTTP header with a valid 64-bit integer.
  mqmdFormat		Completes the format field of the MQMD header in messages that are sent by the IBM MQ service provider. Only supported when the language property is specified. If not specified, then messages are sent with a blank format.
  password		The password that the IBM MQ service provider presents to IBM MQ for authentication and authorization purposes. The password can be provided in plain text, but this is not good practice. Instead, encode the password by using the securityUtility tool that is provided with IBM z/OS Connect, using the encode option. For more information, see securityUtility command in the WebSphere Application Server for z/OS Liberty documentation. If this property is specified, the userName property must also be specified. If this property is not specified, the password property in the connection factory that is referred to by the connectionFactory property is used. If a password property is specified in both the referenced connection factory and this service property subelement, the service property value is used.
  persistence	false	Describes the persistence of messages that are sent to the queue referenced by the destination property. If set to true, messages are sent as persistent.
  replyDestination		Defines a JNDI name that is used to locate a queue that contains response messages for two-way services. If specified, the service is a two-way service. This property is configured in the same way as the destination property. Can be set only if replyDestination is already set in the service archive file.
  replySelection	msgIDToCorrelID	Defines how a two-way service locates reply messages on the queue that is referenced by the replyDestination property. If replySelection is used with a one-way service, it is ignored. The following values are valid: msgIDToCorrelID Reply messages are assumed to be generated with the correlation ID set to the value of the message ID from the request message. The service generates a suitable message selector based on this information. none No mechanism is used to correlate reply messages with request messages. The service gets the first available message on the reply queue. correlIDToCorrelID Reply messages are assumed to be generated with the correlation ID set to the value of the correlation ID from the request message. The service generates a suitable message selector based on this information. If the request message has no correlation ID specified, the service generates a random correlation ID for the request message. For more information, see ibm-mq-md-correlID.
  selector		Defines a valid JMS message selector that is used to locate messages from the queue that is referenced by the destination attribute. Only valid with one-way services for receiving messages. For more information, see Message selectors in JMS in the IBM MQ documentation. Some characters in the attribute value must be escaped in order to be embedded in server.xml because these special characters cannot be directly used in XML. For example, " escaped with &quot; ' escaped with &apos; < escaped with &lt; > escaped with &gt;
  useCallerPrincipal		When a request is made to IBM z/OS Connect, the caller authenticates with the IBM z/OS Connect server. The name of the authenticated principal can be passed onto IBM MQ for authentication and authorization purposes by setting the value of useCallerPrincipal to true. The name of the principal, but no password, is used to connect to IBM MQ. Any values that are specified in the password and userName attributes are ignored.
  userName		The user name that the IBM MQ service provider presents to IBM MQ for authentication and authorization purposes. If this property is not specified, the userName property in the connection factory that is referred to by the connectionFactory property is used. If a userName property is specified both in the referenced connection factory and this service property subelement, the service property value is used. If this property is specified, the password property must also be specified.
  waitInterval		Specifies a time, in milliseconds that the IBM MQ service provider waits for messages to arrive on a queue. This property is only valid for two-way services, or one-way services for receiving messages. If replyDestination is set, then waitInterval must be a positive number. If messagingAction=mqget, then waitInterval can be negative, which means that the IBM MQ service provider waits forever until a message is available. If waitInterval is 0, the IBM MQ service provider does not wait.

zosconnect_zosConnectAPIs

Defines the directory where API archive files are stored and how the server is notified about changes in this directory. It also defines additional configuration that applies to all APIs

Attribute name	Data type	Default value	Description
location	string	${server.config.dir} /resources /zosconnect/apis	Path to a directory location where API archive files are stored. The value of location cannot be changed while the server is running; the value is set when the server is started.
policyRef	string		A reference name that identifies the zosconnect_policy element that is active for these APIs.
pollingRate	long (A period of time with millisecond precision)	5s	Controls how often the server polls the apis directory. 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.
updateTrigger	string	disabled	Controls when the server is notified about changes in the apis directory. Acceptable values are disabled, polled or mbean.. disabled Polling for updates is disabled. Updates can be triggered using the MODIFY refresh command, and API archive files can be deployed by using the RESTful administration interface. polled The server periodically checks for changes to the directory contents. mbean The server checks for changes when the notifyFileChanges method is invoked on the FileNotificationMBean. If you specify this value, you must also configure your server to use the Java Management Extensions (JMX) connector. For more information, see Using an MBean to trigger updates. The value of this attribute is ignored when the MODIFY command is used to refresh the IBM z/OS Connect server artifacts.

Sub elements

zosconnect_zosConnectAPIs > zosConnectAPI

Description: Defines additional configuration for the API.

Required: true

Attribute name	Data type	Default value	Description
name	string		A name of the API.
requireSecure	boolean		Require that requests are sent over HTTPS. If the requireSecure attribute is not set, the global setting from the requireSecure attribute on the zosconnect_zosConnectManager element is used instead.
requireAuth	boolean		Require that users specify security credentials to be authenticated and that the authenticated user is authorized under the zosConnectAccess role, in order to access the API. If the requireAuth attribute is not set, the global setting from the requireAuth attribute on the zosconnect_zosConnectManager element is used instead.
runGlobalInterceptors	boolean	true	Indicates whether global interceptors should run for requests that are associated with this API. Global interceptors are listed in globalInterceptorsRef in the zosconnect_zosConnectManager element. By default, IBM z/OS Connect processes all global and endpoint-specific interceptors. If the runGlobalInterceptors is set to false, IBM z/OS Connect processes only the set of interceptors that are listed in the interceptorsRef attribute.
interceptorsRef	string		A reference name that identifies the set of configured interceptors that are associated with this API. Note: If an API operation is invoked, only the interceptors that are configured for the API are processed. The service-specific interceptor that is configured on the related service is never called.
adminGroup	string		Identifies the users that are able to use administrative functions on this API. The value of this attribute can be set to a group name or a comma-separated list of group names, that are defined in the user registry. If globalAdminGroup is also defined under element zosconnect_zosConnectManager, the value that is defined under adminGroup is used. This group takes precedence over the global group except when controlling authorization to the RESTful administration actions to deploy an API, deploy a service, list all APIs, or list all services. See Note 1 and Note 2.
invokeGroup	string		Identifies the users that are able to invoke this API. The value of this attribute can be set to a group name or a comma-separated list of group names, that are defined in the user registry. If globalInvokeGroup is also defined under element zosconnect_zosConnectManager, the value that is defined under invokeGroup is used. See Note 1 and Note 2.
operationsGroup	string		Identifies the users that are able to perform operations such as starting or stopping this API. The value of this attribute can be set to a group name or a comma-separated list of group names, that are defined in the user registry. If globalOperationsGroup is also defined under element zosconnect_zosConnectManager, the value that is defined under operationsGroup is used. This group takes precedence over the global group except when controlling authorization to the RESTful administration actions to deploy an API, deploy a service, list all APIs, or list all services. See Note 1 and Note 2.
policyRef	string		A reference name that identifies the zosconnect_policy element that is active for this API.
readerGroup	string		Identifies the users that are able to get information about this API, including the Swagger documentation. The value of this attribute can be set to a group name or a comma-separated list of group names, that are defined in the user registry. If globalReaderGroup is also defined under element zosconnect_zosConnectManager, the value that is defined under readerGroup is used. See Note 1 and Note 2.

Note:

1. If you use an LDAP registry, you must specify each LDAP groups distinguished name (DN) with the commas that are escapedthat are with a backslash. for example "cn=employees\,ou=groups\,o=intern\,c=fr, cn=managers\,ou=groups\,o=intern\,c=fr". If specifying multiple groups, the commas separating the groups are not escaped. Specifying LDAP short names is not supported.
2. For information about the authorization levels that are requiredtoto perform particular requests, see API provider authorization.

zosconnect_zosConnectDataXform

Defines an IBM z/OS Connect data transformer.

Attribute name	Data type	Default value	Description
bindFileLoc	string		File system path where the bind files are located.
bindFileSuffix	string		Suffix name that is associated with the bind files.
id	string		A unique configuration ID.
pollingRate	A period of time with millisecond precision	2s	The rate at which the server checks for updates to data transformation-related files such as bind or schema files. 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.
requestSchemaLoc	string		File system path where the request schema files are located.
requestSchemaSuffix	string		Suffix name that is associated with the request schema files.
responseSchemaLoc	string		File system path where the response schema files are located.
responseSchemaSuffix	string		Suffix name that is associated with the response schema files.
updateTrigger	disabled polled mbean	polled	Controls when the server is notified about changes to data transformation files such as bind and schema files. Acceptable values are disabled, polled or mbean. disabled Polling for updates is disabled. Updates can be triggered using the MODIFY refresh command. polled The server scans for changes at the polling interval and reloads any files that have detectable changes. mbean The server reloads data transformation files when prompted by an MBean called by an external program such as an integrated development environment or a management application. If you specify this value, you must also configure your server to use the Java Management Extensions (JMX) connector. For more information, see Using an MBean to trigger updates. The value of this attribute is ignored when the MODIFY command is used to refresh the IBM z/OS Connect server artifacts.

zosconnect_fileSystemloggerInterceptor

Defines an IBM z/OS Connect File System logger interceptor.

Attribute name	Data type	Default value	Description
apiProviderRequestHeaders	string	-	Available from V3.0.74. Comma-separated list of request headers to log.
apiProviderResponseHeaders	string	-	Available from V3.0.74. Comma-separated list of response headers to log.
bufferSize	integer	8192	Buffer size in bytes to be used when the bufferLogging attribute is set to true.
bufferedLogging	boolean	false	Indicates whether entries to the log are buffered before they are written the log file.
encoding	string	UTF-8	Encoding that is used when writing the log file.
id	string		A unique configuration ID.
logName	string		Log file name pattern that is used for payload logging.
logOption	RESPONSE REQUEST ALL	ALL	Log option that controls what is logged. RESPONSE Indicates that only response data is logged. REQUEST Indicates that only request data is logged. ALL Indicates that both request and response data are logged.
logPath	string		File system location where the log file is created. By default, the log files are created in the ${server.config.dir}/logs/zosConnect directory. For example, if you use the default value of /var/zosconnect for the WLP_USER_DIR environment variable, then the file system logger interceptor writes the logs to /var/zosconnect/servers/serverName/logs/zosConnect.
maxPayloadSize	integer	524288	Maximum payload size in characters that are allowed to be written to the log file.
requestUrl	boolean	false	Available from V3.0.74. Control whether request URL and method information is logged.
rollOffLogPolicy	SIZE DURATION	SIZE	Indicates that a log file is rolled off based on size or duration. SIZE Indicates that the log file is roll-off based on the size of the log. DURATION Indicates that the roll-off log policy is based on the elapsed time since the active log file was created.
rollOffLogPolicyDuration	integer	1440	Roll off policy duration in minutes.
rollOffLogPolicySize	integer	52428800	Roll off policy size in bytes.
sequence	integer Minimum: 0 Maximum: 2147483647	0	Sequence in which the interceptor is processed with respect to others.

zosconnect_zosConnectInterceptors

Bundles 1 to N interceptors.

Attribute name	Data type	Default value	Description
id	string		A unique configuration ID.
interceptorRef	List of references to top-level interceptor elements (comma-separated string).		The identifier of one or more interceptors.

zosconnect_zosConnectManager

Defines global configuration settings for IBM z/OS Connect.

Attribute name	Data type	Default value	Description
id	string		A unique configuration ID.
asyncRequestTimeout	A period of time with millisecond precision	30s	Timeout value that is associated with every HTTP request (services and APIs) when processing asynchronous work. This does not apply to API requester calls. It specifies the time in milliseconds in which requests must complete. This timeout value overrides the web container's asyncTimeoutDefault attribute value. If neither asyncRequestTimeout nor asyncTimeoutDefault are configured, the timeout that is used is the asyncTimeoutDefault attribute default value (i.e. 30 seconds). If asyncRequestTimeout is not configured, but the asyncTimeoutDefault attribute is, the value that is defined in asyncTimeoutDefault is used. A timeout might occur at any time during processing of the request IBM z/OS Connect. The request might still be active after the timeout is detected and a response is sent to the client. 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. An asyncRequestTimeout value of zero means do not time out. From V3.0.8, requests that timeout receive a 503 HTTP response code instead of a 500 HTTP response code.
globalAdminGroup	string		Identifies the users that are able to use administrative functions on all APIs, services, service endpoints and API requesters. The value of this attribute can be set to a group name or a comma-separated list of group names, that are defined in the user registry. See Note 1 and Note 2.
globalDataXformRef	Reference to top level zosconnect_zosConnect DataXform element (string).		Reference name that identifies the data transformation handler that is associated with all service endpoints.
globalInterceptorsRef	string		A reference name that identifies the set of configured interceptors that is associated with all APIs and services. If services do not require global interceptors association, the runGlobalInterceptors attribute of the zosconnect_zosConnectService element can be set to false. If APIs do not require global interceptors association, the runGlobalInterceptors attribute of the zosConnectAPI element can be set to false. See Note 1, Note 3, and Note 4.
globalInvokeGroup	string		Identifies the users that are able to invoke all APIs, services, service endpoints and API requesters. The value of this attribute can be set to a group name or a comma-separated list of group names, that are defined in the user registry. See Note 1 and Note 2.
globalOperationsGroup	string		Identifies the users that are able to perform operations such as starting, stopping, or obtaining the status of all APIs, services, service endpoints, and API requesters. The value of this attribute can be set to a group name or a comma-separated list of group names, that are defined in the user registry. See Note 1 and Note 2.
globalReaderGroup	string		Identifies the users that are able to get lists of, or information about, all APIs, services, service endpoints, and API requesters, including Swagger documentation. The value of this attribute can be set to a group name or a comma-separated list of group names, that are defined in the user registry. See Note 1 and Note 2.
operationMode	SYNC ASYNC	ASYNC	Specifies the mode in which IBM z/OS Connect requests are processed. SYNC Synchronous mode of operation. Requests use the same thread. ASYNC Asynchronous mode of operation. Multiple threads are used to manage requests. Use SYNC when running IBM z/OS Connect embedded in CICS and ASYNC when running standalone.
preserveJsonObjectPayloadOrder	boolean	false	When enabled, the order of entries in a JSON object payload is preserved.
preserveJsonPayloadCharFormat	boolean	false	Indicates whether the characters in the JSON payload should flow unchanged through IBM z/OS Connect during request handling such as API invocation, service invocation and schema retrievals. When set to false, UTF-8 encoded characters might be converted to their respective escaped Unicode representation. For this attribute to take effect, the attribute definition setUTF8ResponseEncoding must be set to true.
requireAuth	boolean	true	Require that users specify security credentials to be authenticated and that the authenticated user is authorized under the zosConnectAccess role, in order to access APIs, services and API requesters, unless overridden on the specific resource definitions.
requireSecure	boolean	true	Require that requests are sent over HTTPS. The requireSecure attribute can be overridden on the specific resource definitions.
useJsonErrorResponses	boolean	true	When enabled, all error responses from the server are in JSON format. This option is retained for compatibility with previous versions of IBM z/OS Connect.
setUTF8ResponseEncoding	boolean	false	Indicates whether the character encoding in the HTTP response is set to UTF-8. The default encoding is ISO-8859-1. Set this attribute to true if your service or API contains double-byte character set (DBCS) characters. For compatibility with previous versions of IBM z/OS Connect, this option defaults to false. Set this value to true to conform to the standard JSON encoding of UTF-8.

Note:

1. If you use an LDAP registry, you must specify each LDAP group's distinguished name (DN) with the commas that are escaped with a backslash. for example "cn=employees\,ou=groups\,o=intern\,c=fr, cn=managers\,ou=groups\,o=intern\,c=fr". If specifying multiple groups, the commas separating the groups are not escaped. Specifying LDAP short names is not supported.
2. For information about the authorization levels that are required to perform particular requests, see API provider authorization and API requester authorization.
3. If a service is called by an API, only the interceptors that are configured for the API are processed. Interceptors that are defined for the service are ignored.
4. The set of configured interceptors that are referenced by globalInterceptorsRef is run for every HTTP request (services and APIs).

zosconnect_zosConnectService

Defines the configuration settings for a service endpoint.

Note: This element is for services that are not defined by service archive files.

Attribute name	Data type	Default value	Description
adminGroup	string		Identifies the users that are able to use administrative functions on this service endpoint. The value of this attribute can be set to a group name or a comma-separated list of group names, that are defined in the user registry. If it is configured along with its global counterpart, globalAdminGroup defined under element zosconnect_zosConnectManager, the value that is defined under adminGroup is used. See Note 1.
dataXformRef	string		A reference name that identifies the data transformation handler that is associated with a service endpoint. If configured along with its global data transformation handler counterpart (globalDataXformRef defined under element zosconnect_zosConnectManager), the data transformer that is defined for the service endpoint is used.
id	string		A unique configuration ID.
invokeGroup	string		Identifies the users that are able to invoke this service endpoint. The value of this attribute can be set to a group name or a comma-separated list of group names, that are defined in the user registry. If it is configured along with its global counterpart, globalInvokeGroup defined under element zosconnect_zosConnectManager, the value that is defined under invokeGroup is used. See Note 1.
interceptorsRef	string		A reference name that identifies the set of configured interceptors that is associated with a service endpoint. If it is configured along with its global interceptors counterpart (globalInterceptorsRef defined under the zosconnect_zosConnectManager element), IBM z/OS Connect processes both sets of interceptors. If the runGlobalInterceprs attribute for the service endpoint is set false, IBM z/OS Connect will only process the set of interceptors that are configured for the service endpoint.
invokeURI	string		URI or list of comma-separated URIs to associate with a service endpoint. InvokeURIs can end with a wildcard character in the form /a/b/* or x/y* to generically match a service endpoint invocation. Specifying multiple wildcard characters (i.e. /a/b/**) or wildcard characters in the middle of the requestURI (i.e. /a/*/c) is not supported. If service endpoints with configured invokeURIs using the wildcard character are associated with overlapping invokeURIs, the service endpoint that is associated with the most specific invokeURI is matched. For instance, if a service endpoint request is issued with the following: https://host:port/a/b/c going to a server with the following configuration: service1 -> invokeURI="/a/b/c/*" and service2 -> invokeURI="/a/b/*", IBM z/OS Connect will match the request to service1. Configured invokeURI entries must start with the / character. The use of an invokeURI is equivalent to a service request where the action=invoke query parameter is specified.
operationsGroup	string		Identifies the users that are able to perform operations such as starting, stopping, or obtaining the status of this service endpoint. The value of this attribute can be set to a group name or a comma-separated list of group names, that are defined in the user registry. If it is configured along with its global counterpart, globalOperationsGroup defined under element zosconnect_zosConnectManager, the value that is defined under operationsGroup is used. See Note 1.
readerGroup	string		Identifies the users that are able to get information about this service endpoint, including the Swagger documentation. The value of this attribute can be set to a group name or a comma-separated list of group names, that are defined in the user registry. If globalReaderGroup is also defined under element zosconnect_zosConnectManager, the value that is defined under readerGroup is used. See Note 1.
requireAuth	boolean		Require that users specify security credentials to be authenticated and that the authenticated user is authorized under the zosConnectAccess role, in order to access the service. If the requireAuth attribute is not set, the global setting from the requireAuth attribute on the zosconnect_zosConnectManager element is used instead.
requireSecure	boolean		Require that requests are sent over HTTPS. If the requireSecure attribute is not set, the global setting from the requireSecure attribute on the zosconnect_zosConnectManager element is used instead.
runGlobalInterceptors	boolean	true	Indicates whether global interceptors run for requests that are associated with a service endpoint. By default IBM z/OS Connect processes all global and service endpoint-specific interceptors.
serviceAsyncRequestTimeout	A period of time with millisecond precision	30s	Timeout value that is associated with a service endpoint when processing asynchronous work. It specifies the time in milliseconds in which requests must complete. This timeout value overrides the web container's asyncTimeoutDefault attribute value. If neither asyncRequestTimeout nor asyncTimeoutDefault are configured, the timeout that is used is the asyncTimeoutDefault attribute default value (i.e. 30 seconds). If asyncRequestTimeout is not configured, but the asyncTimeoutDefault attribute is, the asyncTimeoutDefault's configured value is used. If configured along with its global counterpart: asyncRequestTimeout defined under element zosconnect_zosConnectManager, the value that is defined under serviceAsyncRequestTimeout is used. A timeout might occur at any time during processing of the request by IBM z/OS Connect. The request might still be active after the timeout is detected and a response is sent to the client. 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. From V3.0.8, requests that timeout receive a 503 HTTP response code instead of a 500 HTTP response code. This timeout applies only to direct requests to this service endpoint and not if this service endpoint is invoked via an API.
serviceDescription	string		Description that is associated with a service endpoint.
serviceGroupingName	string		Name that can be used to group or associate a set of service endpoints together.
serviceName	string		Name that is associated with a service endpoint. This name identifies a service endpoint to a client.
serviceRef	string		Reference name that identifies the service endpoint that is registered with z/OS Connect.

 Note 1:  If using an LDAP registry, you must specify each LDAP group's distinguished name (DN) with the commas that are escaped with a backslash. for example "cn=employees\,ou=groups\,o=intern\,c=fr, cn=managers\,ou=groups\,o=intern\,c=fr". If specifying multiple groups, the commas separating the groups are not escaped. Specifying LDAP short names is not supported.

zosconnect_zosConnectServiceRestClient

Allows requests to be routed from IBM z/OS Connect to a remote REST endpoint.

Attribute name	Data type	Default value	Description
basicAuthRef	Reference to top level zosconnect_ zosConnectService RestClientBasicAuth element (string).		A reference name that identifies the basic authentication data to be used for connecting to a remote REST endpoint.
connectionRef	Reference to top level zosconnect_ zosConnectService RestClientConnection element (string)		If set, the connection is made using the attributes of the zosconnect_zosConnectServiceRestClientConnection element. If not set, or the zosconnect_zosConnectServiceRestClientConnection element does not exist, the values from the zosconnect_zosConnectServiceRestClient element are used.
connectionTimeout	A period of time with millisecond precision	30s	The connection timeout specifies the amount of time that the client attempts to establish a connection to the remote endpoint before it times out. If the timeout value is set to 0, the client 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		IP address, domain name server (DNS) host name with domain name suffix, or just the DNS host name, used to route the request.
httpMethod	string		Name of the HTTP method to be used when routing HTTP requests. If no method is specified, the method that is used is the one in the original request. The valid methods are GET, PUT, POST, OPTIONS, and DELETE.
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	The receive timeout specifies the amount of time that the client waits for a response from the remote endpoint before it times out. If the timeout value is set to 0, the client will wait 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.
uri	string		URI that identifies the resource to contact when routing HTTP requests. If no URI is specified everything after the port number from the original request is used.

Sub elements

zosconnect_zosConnectServiceRestClient > basicAuth

Description: A reference name that identifies the basic authentication data to be used for connecting to a remote REST endpoint.

Required: false

Attribute name	Data type	Default value	Description
password	Reversably encoded password (string)		The 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 be encoded. To do so, use the securityUtility shipped with WebSphere Liberty profile.
userName	string		The name of the user under which the request will be routed.

zosconnect_zosConnectServiceRestClientConnection

Allows requests to be routed from IBM z/OS Connect to a remote REST endpoint.

Attribute name	Data type	Default value	Description
allowChunking	boolean	true	Allow chunking on messages greater than 4KB.
basicAuthRef	Reference to top level zosconnect_ zosConnectService RestClientBasicAuth element (string).		A reference name that identifies the basic authentication data to be used for connecting to a remote REST endpoint.
connectionTimeout	A period of time with millisecond precision	30s	The connection timeout specifies the amount of time that the client attempts to establish a connection to the remote endpoint before it times out. If the timeout value is set to 0, the client 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		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.
receiveTimeout	A period of time with millisecond precision	60s	The receive timeout specifies the amount of time that the client waits for a response from the remote endpoint before it times out. If the timeout value is set to 0, the client will wait 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.

Sub elements

zosconnect_zosConnectServiceRestClientConnection > basicAuth

Description: A reference name that identifies the basic authentication data to be used for connecting to a remote REST endpoint.

Required: false

Attribute name	Data type	Default value	Description
password	Reversably encoded password (string)		The 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 be encoded. To do so, use the securityUtility shipped with WebSphere Liberty profile.
userName	string		The name of the user under which the request will be routed.
applName	string		The name of the application that requests and uses the PassTickets.

zosconnect_zosConnectServiceRestClientBasicAuth

Basic authentication data for connecting to a remote REST endpoint.

Attribute name	Data type	Default value	Description
id	string		A unique configuration ID.
password	Reversably encoded password (string)		The 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 be encoded. To do so, use the securityUtility shipped with WebSphere Liberty profile.
userName	string		The name of the user under which the request will be routed.
applName	string		The name of the application that requests and uses the PassTickets.

zosLocalAdapters (WOLA)

WebSphere Optimized Local Adapters.

Attribute name	Data type	Default value	Description
useCicsTaskUserId	boolean	false	If security is enabled in the WOLA client, this setting controls which user ID is propagated to this IBM z/OS Connect server when a WOLA request is sent from the client to the server. If you enable this setting, the user ID of the task that makes the request is propagated. If you do not enable this setting, the user ID of the client address space is propagated. This setting is applicable only to CICS clients.
wolaGroup	string		The WOLA group name is the first part of the 3-part WOLA name. The name cannot contain lowercase letters.
wolaName2	string		The 2nd part of the 3-part WOLA name. The name cannot contain lowercase letters.
wolaName3	string		The 3rd part of the 3-part WOLA name. The name cannot contain lowercase letters.