Configuration elements

You can use the following elements in your server.xml file to configure z/OS® Connect EE.

This list contains only those elements that are unique to z/OS Connect EE. For details of Liberty configuration elements not listed below, see Server configuration in the IBM WebSphere Application Server for z/OS Liberty documentation.

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

Care is needed to avoid defining multiple instances of the singleton elements, or elements with the same id value, by understanding the rules used to merge these elements. For more details on the rules 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
Defines the directory where API requester archives are stored and how the server is notified about changes in this directory. It also defines additional configuration which applies to all API requesters.
Attribute name Data type Default value Description
idAssertion string OFF

Controls whether identity assertion is enabled in z/OS Connect EE for API requesters, and whether a surrogate check is supported if identity assertion is enabled. Acceptable values are OFF, ASSERT_SURROGATE, ASSERT_ONLY.

OFF

Identity assertion is disabled in z/OS Connect EE 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 EE 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 EE checks whether the identity used for authenticating the z/OS subsystem access to the z/OS Connect EE 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 EE 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 EE directly checks whether the asserted identity has the authority to invoke the API requester.

Depending on the values set to the idAssertion and requireAuth attributes, z/OS Connect EE performs different actions on the asserted identity and the identity used for authenticating the z/OS subsystem access to the z/OS Connect EE server. For more information, see Identity assertion for API requesters.

location string ${server.config.dir}/resources/zosconnect/apiRequesters Path to a directory location where 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 of time 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). 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.
requireAuth boolean   This is available from V3.0.29.0. Require 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.
updateTrigger string disabled Controls when the runtime 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 using the MODIFY refresh command, and API requester archive files can be deployed using the RESTful administration interface.
polled
The server will periodically check for changes to the directory contents.
mbean
The server will check 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 EE server artifacts.

Sub elements

zosconnect_apiRequesters > apiRequester
Description: Defines additional configuration for the API requester archive.
Required: false
Attribute name Data type Default value Description
name string   A 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 z/OS Connect EE to support API requesters.
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   Requires that users specify security credentials to be authenticated and that the authenticated user is authorized under the zosConnectAccess role, in order 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 global interceptors should run for requests that are associated with this API requester. Global interceptors are listed in globalInterceptorsRef in the zosconnect_zosConnectManager element. By default, z/OS Connect EE processes all global and API requester-specific interceptors. If the runGlobalInterceptors attribute is set to false, z/OS Connect EE processes only the set of interceptors that are listed in the interceptorsRef attribute.
interceptorsRef string   Reference name that identifies the set of configured interceptors that are associated with this API requester.
connectionRef string   A reference to top level zosconnect_endpointConnection element. If set, the connection will be made 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 will be used, and if the value of the connectionRef attribute in the build toolkit properties file does not exist either, an error will occur.
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 defined under element zosconnect_zosConnectManager, the value defined under adminGroup is used. See Note 1.
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 element zosconnect_zosConnectManager, the value defined under invokeGroup is used. See Note 1.
operationsGroup string   Identifies the users that are able to perform 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 under element zosconnect_zosConnectManager, the value defined under operationsGroup is used. See Note 1.
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 element zosconnect_zosConnectManager, the value defined under readerGroup is used. See Note 1.

 Note 1:  If using an LDAP registry, you must specify each LDAP group's distinguished name (DN) with the commas 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_auditInterceptor
Defines the audit interceptor for z/OS Connect EE to allow request data to be logged in System Management Facility (SMF) 123 subtype 1 records on z/OS.
Attribute name Data type Default value Description
id string   A unique configuration ID.
sequence integer

Minimum: 0

Maximum: 2147483647
0 The sequence in which this interceptor is processed with respect to other configured interceptors implementing the com.ibm.wsspi.zos.connect.Interceptor Service Provider Interface (SPI) for z/OS Connect EE.
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 may 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 may be present on responses as a result of response data mapping, see Defining and mapping headers, query parameters, or path parameters.
zosconnect_authData
Reference name that identifies the basic authentication data to be used for a connection. The credentials are overridden by any values supplied on a request.
Attribute name Data type Default value Description
id string   The element identifier.
password string   The password that is passed from the z/OS Connect EE 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 z/OS Connect EE server to establish the connection on every request, if no user ID is supplied on the request.
zosconnect_authorizationInterceptor
Defines a z/OS Connect EE 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, cache is disabled. If set to -1, SAF credentials are kept indefinitely. Specify -1 or a positive integer in the range 0 to 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 with respect to other configured interceptors implementing z/OS Connect's com.ibm.wsspi.zos.connect.Interceptor Service Provider Interface (SPI).
zosconnect_authorizationServer
Allows requests for access tokens or JWTs to be routed from z/OS Connect EE to an authorization server or an authentication server. For more information about supported security configuration options when using JWT or OAuth 2.0, see How to configure JWT or How to configure OAuth 2.0.
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"
For example,
tokenEndpoint="https://authorization.server.com:8001/JWTTokenGenerator/getJwtToken"
Contact the authorization/authentication server administrator for details of the path value required for that server.
basicAuthRef Reference to top level zosconnect_authData element (string)   Reference name that identifies the basic authentication data to be used for authenticating with an authorization server. The values of the user and password attributes that are set in the associated zosconnect_authData element take precedence over user credentials specified in the z/OS application.
When your z/OS application calls an API secured with OAuth 2.0
The values of the user and password attributes set in the associated zosconnect_authData element are used as client ID and client secret to verify the client identity of the z/OS Connect EE 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 user name 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 z/OS Connect EE server will attempt to establish a connection to the authorization/authentication server before it times out. If the timeout value is set to 0, the z/OS Connect EE server will attempt 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). 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 z/OS Connect EE server will wait for a response from the authorization/authentication server before it times out. If the timeout value is set to 0, the z/OS Connect EE server 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). 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 A reference to top level zosconnect_proxyConfig element. (string)   Reference name that identifies the proxy via which the request for access token is routed from the z/OS Connect EE server to the authorization/authentication server.
sslCertsRef string   An SSL repertoire with an ID, a defined keystore, and truststore.
zosconnect_authToken
Defines the JWT configuration in z/OS Connect EE.
Attribute name Data type Default value Description
id string   A unique configuration ID.
authServerRef A 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.
header string Authorization Specify the name of the header that contains the JWT on the API request.

Sub elements

zosconnect_authToken > tokenRequest
Description: Defines how the user credential is passed from the z/OS Connect EE server to the authentication server.
Required: true
Attribute name Data type Default value Description
credentialLocation string  
Specify where the user credential is 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 the header that needs to contain the user credentials.
requestBody string  

Specify a JSON string that contains the information about user credentials when the user credentials are included in the request body. The JSON string must contain the key-value pair that explicitly indicates the user name and password values like Example A or contain the key-value pair that uses the $ character like Example B.

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 it is recommended that you use the Example B syntax. When the Example B syntax is used with the user credentials set on the zosconnect_authData element, the password in the server.xml file can be encoded to ensure confidentiality. The Example A syntax is provided to allow more flexibility in the request payload that is required by the authentication server.

  • As shown in the examples above, &quot; must be used to escape the double quote characters (") inside the attribute value, because the attribute value is already surrounded by double quote characters (") 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 z/OS Connect EE 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. Acceptable values are Text or JSON.
tokenLocation string  
Specify where the generated JWT is returned in the response from the authentication server to the z/OS Connect EE server. The following values are supported:
header
The JWT is returned in a header to z/OS Connect EE. 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 z/OS Connect EE. 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_cicsIpicConnection
Represents a connection to a CICS® system.
Note: When an IPIC connection is established with CICS, updates to the authDataRef, transid and transidUsage attributes take immediate effect but updates to other attributes that are associated with this element will 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. A 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.
connectionTimeout A period of time with millisecond precision. 30s Optional. The maximum amount of time that is allowed for the socket to establish a connection to CICS. Specify a positive integer followed by a unit of time, which can be hours (h), minutes (m), or seconds (s). For example, specify 30 seconds as 30s. You can include multiple values in a single entry. For example, 1m30s is equivalent to 90 seconds. A value of 0 disables this timeout.
heartbeatInterval A period of time with millisecond precision.

Maximum: 3600s.

30s Optional. This attribute sets the time that the connection must be inactive before heartbeats are sent to CICS. Specify a positive integer followed by a unit of time, which can be hours (h), minutes (m), or seconds (s). For example, specify 30 seconds as 30s. You can include multiple values in a single entry. For example, 1m30s is equivalent to 90 seconds. A value of 0 disables IPIC heartbeats.
host string   Required. The IP address, domain name server (DNS) host name with domain name suffix, or just the DNS host name, of the host on which the CICS region is running.
id string   Required. A unique configuration ID. This must match the value that is specified for the 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.
sendSessions integer

Minimum: 1

Maximum: 999

100 Optional. This attribute sets the maximum number of simultaneous requests over the connection. The actual number of send sessions established depends on the value of sendSessions and the value in the RECEIVECOUNT parameter of the IPCONN definition in the CICS region.
sharedPort boolean false Optional. Indicates whether the port attribute specifies a shared port or a specific port.
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 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 EE server 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 z/OS Connect EE server passed to CICS. The default value is 9UNKNOWN.

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

If a zosConnectNetworkid value is not specified and the NETWORKID in the CICS IPCONN definition is left blank, a match might not occur even if the z/OS Connect EE 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_endpointConnection
Allows requests to be routed from z/OS Connect EE to a request endpoint.
Attribute name Data type Default value Description
basicAuthRef A reference to top level zosconnect_authData element. (String)   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 A reference to top level zosconnect_authData, zosconnect_oAuthConfig or zosconnect_authToken element. (string)   Reference name that identifies the authentication data used for basic authentication, OAuth 2.0 or JWT when the z/OS Connect EE 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 JWT, it must be associated with the zosconnect_authToken element.
Note: The authenticationConfigRef attribute can reference more than one element to support the combined use of basic authentication, OAuth 2.0 or JWT. For more information, see Calling an API secured with multiple authentication and authorization methods.
connectionTimeout A period of time with millisecond precision 30s The connection timeout specifies the amount of time that the z/OS Connect EE server will attempt to establish a connection to the request endpoint before it times out. If the timeout value is set to 0, the z/OS Connect EE server will attempt 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). 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) host name with domain name suffix, or just the DNS host name. If the protocol is not specified, the default protocol http:// is used.
id string   A unique configuration ID.
port string   Port 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 z/OS Connect EE server will wait for a response from the request endpoint before it times out. If the timeout value is set to 0, the z/OS Connect EE server 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). For example, specify 500 milliseconds as 500ms. You can include multiple values in a single entry. For example, 1s500ms is equivalent to 1.5 seconds.
sslCertsRef string   An SSL repertoire with an ID, a defined keystore, and truststore.
proxyConfigRef A reference to top level zosconnect_proxyConfig element. (string)   Reference name that identifies the proxy via which the request is routed from the z/OS Connect EE 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 containing 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 tables below for a description of the additional attributes required for channel payloads.
useGenericError boolean false When enabled, all error cases from the service will return a HTTP status code of 500 Internal Server Error. This option is retained for compatibility with previous versions of z/OS Connect EE.
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 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 MQ Service Provider.
Note: This element is for users who have already created services from the MQ service provider that is shipped with 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 z/OS Connect EE.
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 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 which 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 sent 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 has been configured to use z/OS Connect EE 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, eight 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 best practice is to encode the password using the securityUtility tool that is provided with z/OS Connect EE, 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 sent by a service and is equivalent to setting the MQMD Persistence field.
The value must be one of the following:
false
Means messages are non-persistent.
true
Means 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 z/OS Connect EE, 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 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 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 z/OS Connect EE. For more information about supported security configuration options when using OAuth 2.0, see How to configure OAuth 2.0.
Attribute name Data type Default value Description
id string   A unique configuration ID.
grantType Either password or client_credentials (string)   Specifies the OAuth grant type. In z/OS Connect EE, 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.
authServerRef Refrence to top level zosconnect_authorizationServer Element. (string)   Reference name that identifies the information of an authorization server that is used for authentication and authorization.
zosconnect_policy
Defines the z/OS Connect EE 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). 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 z/OS Connect EE 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 z/OS Connect EE to an endpoint via a proxy.
Attribute name Data type Default value Description
id String   Required. A unique configuration ID.
host String   Required. The IP address, domain name server (DNS) host name with domain name suffix, or just the DNS host name of the proxy server, used to route the request.
port Integer   Required. Port used by the proxy server for routing HTTP or HTTPS requests.
type String   Required. Proxy type, the value should be HTTP or SOCKS.
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 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). 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 services directory. Acceptable values are disabled, polled or mbean. The default value is disabled.
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 will periodically check for changes to the directory contents.
mbean
The server will check 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 EE 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 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, z/OS Connect EE processes all global and service endpoint-specific interceptors. If the runGlobalInterceptors is set to false, z/OS Connect EE processes only the set of interceptors that are listed in the interceptorsRef attribute.
interceptorsRef string   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 configured for that API are processed. Interceptors 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 defined under adminGroup is used. See Note 1.
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 defined under invokeGroup is used. See Note 1.
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 defined under operationsGroup is used. See Note 1.
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 defined under readerGroup is used. See Note 1.
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 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_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: transid and transidUsage.
  • 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 whitespace from JSON property values in the output messages. By default, leading whitespace is not trimmed.
    trimOutputTrailingWhitespace true Trims trailing whitespace from JSON property values in output messages. By default, trailing whitespace 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 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 whitespace and control characters are processed. By default, empty tags are not omitted.
    enforceMinArrayOccurrence true Enforces the minimum number of array occurrence in the input data structure as defined in the copybook. By default, minimum number of array occurrence 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 z/OS Connect EE 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 z/OS Connect EE, 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 z/OS Connect EE, the caller authenticates with the z/OS Connect EE 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 which 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   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). 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 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 using the RESTful administration interface.
polled
The server will periodically check for changes to the directory contents.
mbean
The server will check 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 EE 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, z/OS Connect EE processes all global and endpoint-specific interceptors. If the runGlobalInterceptors is set to false, z/OS Connect EE processes only the set of interceptors that are listed in the interceptorsRef attribute.
interceptorsRef string   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 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 defined under adminGroup is used. See Note 1.
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 defined under invokeGroup is used. See Note 1.
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 defined under operationsGroup is used. See Note 1.
policyRef string   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 defined under readerGroup is used. See Note 1.

 Note 1:  If using an LDAP registry, you must specify each LDAP group's distinguished name (DN) with the commas 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_zosConnectDataXform
Defines a z/OS Connect EE 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 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). 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
  • mbean
  • polled
  • disabled
polled Update trigger for data transformation files such as bind and schema files.
mbean
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.

polled
Server scans for changes at the polling interval and reload any files that have detectable changes.
disabled
Polling for updates is disabled. Updates can be triggered using the MODIFY refresh command.

The value of this attribute is ignored when the MODIFY command is used to refresh the z/OS Connect EE server artifacts.

zosconnect_fileSystemloggerInterceptor
Defines a z/OS Connect EE File System logger interceptor.
Attribute name Data type Default value Description
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 to the log file.
encoding string UTF-8 Encoding that is used when writting to 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 will write 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.
rollOffLogPolicy
  • SIZE
  • DURATION
SIZE Indicates that 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 z/OS Connect EE.
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 have to complete. This timeout value overrides the web container's asyncTimeoutDefault attribute value. If neither asyncRequestTimeout nor asyncTimeoutDefault are configured, the timeout used is the asyncTimeoutDefault attribute default value (i.e. 30 seconds). If asyncRequestTimeout is not configured, but the asyncTimeoutDefault attribute is, the value defined in asyncTimeoutDefault is used. A timeout might occur at any time during processing of the request z/OS Connect EE. 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). 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.
globalDataXformRef A reference to top level zosconnect_zosConnectDataXform element (string).   Reference name that identifies the data transformation handler that is associated with all service endpoints.
globalInterceptorsRef tokenType   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.
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.
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.
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.
operationMode
  • SYNC
  • ASYNC
ASYNC Specifies the mode in which z/OS Connect EE requests will be 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 z/OS Connect EE 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 if the characters in the JSON payload should flow unchanged through z/OS Connect EE 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 z/OS Connect EE.
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 z/OS Connect EE, this option defaults to false. Set this value to true to conform to the standard JSON encoding of UTF-8.

 Note 1:  If using an LDAP registry, you must specify each LDAP group's distinguished name (DN) with the commas 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.

Sub elements

zosconnect_zosConnectManager > globalInterceptorsRef
Description: 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.
Note:
  1. If a service is called by an API, only the inteceptors configured for the API are processed. Interceptors defined for the service are ignored.
  2. The set of configured interceptors referenced by globalInterceptorsRef is run for every HTTP request (services and APIs).
Required: false
Data type: tokenType
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 defined under adminGroup is used. See Note 1.
dataXformRef string   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 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 defined under invokeGroup is used. See Note 1.
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 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/*", z/OS Connect EE 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 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 z/OS Connect EE 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 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 defined under serviceAsyncRequestTimeout is used. A timeout might occur at any time during z/OS Connect's processing of the request. 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). 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 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.

Sub elements

zosconnect_zosConnectService > interceptorsRef
Description: 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), z/OS Connect EE processes both sets of interceptors. If the runGlobalInterceptors attribute for the service endpoint is set to false, z/OS connect will only process the set of interceptors configured for the service endpoint.
Required: false
Data type: tokenType
zosconnect_zosConnectServiceRestClient
Allows requests to be routed from z/OS Connect EE to a remote REST endpoint.
Attribute name Data type Default value Description
basicAuthRef A reference to top level zosconnect_zosConnectServiceRestClientBasicAuth element (string).   Reference name that identifies the basic authentication data to be used for connecting to a remote REST endpoint.
connectionRef A reference to top level zosconnect_zosConnectServiceRestClientConnection element (string)   If set, the connection will be 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 will be used.
connectionTimeout A period of time with millisecond precision 30s The connection timeout specifies the amount of time that the client will attempt to establish a connection to the remote endpoint before it times out. If the timeout value is set to 0, the client will attempt 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). 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 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 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 will wait 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). 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: 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)   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   Name of the user under which the request will be routed.
zosconnect_zosConnectServiceRestClientConnection
Allows requests to be routed from z/OS Connect EE to a remote REST endpoint.
Attribute name Data type Default value Description
allowChunking boolean true Allow chunking on messages greater than 4KB.
basicAuthRef A reference to top level zosconnect_zosConnectServiceRestClientBasicAuth element (string).   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 will attempt to establish a connection to the remote endpoint before it times out. If the timeout value is set to 0, the client will attempt 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). 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 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 will wait 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). 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: 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)   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   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)   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   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 z/OS Connect EE 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.