Configuration elements
You can use the following elements in your server.xml file to configure IBM® z/OS® Connect.
This list contains only those elements that are relevant to IBM z/OS Connect. For more information about Liberty configuration elements not listed here, see Server configuration in the IBM WebSphere Application Server for z/OS Liberty documentation.
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
- zosconnect_auditInterceptor
- zosconnect_authorizationServer
- zosconnect_authData
- zosconnect_authorizationInterceptor
- zosconnect_authToken
- zosconnect_authTokenLocal
- zosconnect_bidiConfig
- zosconnect_dbServices
- zosconnect_endpointConnection
- zosconnect_cicsConnectionGroup
- zosconnect_cicsIpicConnection
- zosconnect_localAdaptersConnectService
- zosconnect_mqService
- zosconnect_oAuthConfig
- zosconnect_oAuthTokenConfig
- zosconnect_policy
- zosconnect_proxyConfig
- zosconnect_services
- zosconnect_zosConnectAPIs
- zosconnect_zosConnectDataXform
- zosconnect_fileSystemloggerInterceptor
- zosconnect_zosConnectInterceptors
- zosconnect_zosConnectManager
- zosconnect_zosConnectService
- zosconnect_zosConnectServiceRestClient
- zosconnect_zosConnectServiceRestClientConnection
- 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 appropriatezosconnect_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/apiRequestersPath 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 therequireAuth
attribute is not set, the global setting from therequireAuth
attribute on thezosconnect_zosConnectManager
element is used instead, unless therequireAuth
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 therequireSecure
attribute on thezosconnect_zosConnectManager
element is used instead. You can override this value for individual API requesters by specifying therequireSecure
attribute on the appropriatezosconnect_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 theFileNotificationMBean
.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.
- 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: 21474836470 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: 21 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: 21 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: 2147483647600 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: 21474836470 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:
or if using AT-TLS:"https://host:port/path"
For example,"http://host:port/path"
Contact the authorization and authentication server administrator for details of the path value required for that server.tokenEndpoint="https://authorization.server.com:8001
/JWTTokenGenerator/getJwtToken"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.
- zosconnect_authToken > tokenResponse
- Description: Defines how a JWT is passed from the authentication server to the IBM z/OS Connect server.
- 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
- 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
orzosconnect_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: 0Equal 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
andpreferredSpecificPort
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 theport
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 theport
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 attributespreferredSpecificHost
andpreferredSpecificPort
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 ofzosConnectNetworkid
, 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 ofzosConnectApplid
, 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
orRTL
.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 isfalse
.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
orVISUAL
.The default is
LOGICAL
outHostDirection The direction of the host text, which is either LTR
orRTL
.The default is
LTR
.outOrder The desired order of the output text, which is either LOGICAL
orVISUAL
.The default is
LOGICAL
.outDirection The desired direction of the output text, which is either LTR
orRTL
.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 isfalse
.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
orzosconnect_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://
orhttps://
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 protocolhttp://
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.
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.
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. - For basic authentication, it must be associated with the
- 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: 2147483647Number 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
anduseCICSContainer
(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
anduseCICSContainer
(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
anduseCICSContainer
(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
anduseCICSContainer
(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
anduseCICSContainer
(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
anduseCICSContainer
(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
anduseCICSContainer
(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
anduseCICSContainer
(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
anduseCICSContainer
(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 ofZCONHTTPHeaders
. 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.
- Method 1: Use a channel name of IBM-WAS-ADAPTER to
flow a single payload container. Specify the following attributes:
- 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.
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 theconnectionFactory
attribute is used.If a
password
attribute is specified both on the referenced connection factory and on thiszosconnect_mqService
element, the value in thezosconnect_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 theibm-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. IfreplyDestination
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.
Specify one of the following values:replySelection
is used only with two-way services. IfreplySelection
is used with a one-way service, it is ignored.- 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
oribm-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"
'
escaped with'
<
escaped with<
>
escaped with>
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
anduserName
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 theconnectionFactory
attribute is used.If a
userName
attribute is specified on both the referenced connection factory and thiszosconnect_mqService
element, the value in thezosconnect_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 thedestination
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 thereplydestination
attribute.waitInterval
is not supported with HTTP GET requests. IfwaitInterval
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 negativewaitInterval
, 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_
Element. (string)
authorizationServerReference 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
orclient_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 referencedzosconnect_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 thejwtBuilder
element, see JWT Builder (jwtBuilder) in the WebSphere Application Server for z/OS Liberty documentation.Sub elements
- zosconnect_oAuthTokenConfig > claims
- Required: false
- 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/rulesThe 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.
- 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 azosconnect_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/servicesPath 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 theFileNotificationMBean
.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.
- 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/apisPath 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 theFileNotificationMBean
.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.
- 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
element (string).
DataXformReference 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 thezosconnect_zosConnectService
element can be set to false. If APIs do not require global interceptors association, therunGlobalInterceptors
attribute of thezosConnectAPI
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.
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:- 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. - For information about the authorization levels that are required to perform particular requests, see API provider authorization and API requester authorization.
- 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.
- 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 thezosconnect_zosConnectManager
element), IBM z/OS Connect processes both sets of interceptors. If therunGlobalInterceprs
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 elementzosconnect_zosConnectManager
, the value that is defined underoperationsGroup
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 elementzosconnect_zosConnectManager
, the value that is defined underreaderGroup
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 therequireAuth
attribute is not set, the global setting from therequireAuth
attribute on thezosconnect_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 therequireSecure
attribute on thezosconnect_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 neitherasyncRequestTimeout
norasyncTimeoutDefault
are configured, the timeout that is used is theasyncTimeoutDefault
attribute default value (i.e. 30 seconds). IfasyncRequestTimeout
is not configured, but theasyncTimeoutDefault
attribute is, the asyncTimeoutDefault's configured value is used. If configured along with its global counterpart:asyncRequestTimeout
defined under elementzosconnect_zosConnectManager
, the value that is defined underserviceAsyncRequestTimeout
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
levelzosconnect_
zosConnectService
RestClientConnection
element (string)If set, the connection is made using the attributes of the zosconnect_zosConnectServiceRestClientConnection
element. If not set, or thezosconnect_zosConnectServiceRestClientConnection
element does not exist, the values from thezosconnect_zosConnectServiceRestClient
element are used.connectionTimeout A period of
time with
millisecond
precision30s 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
, andDELETE
.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
precision60s 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.
- 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
levelzosconnect_
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 precision30s 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 precision60s 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.
- 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.