We are encountering an issue in our CICS Environment (v5.4) with APIs running against our Liberty Server in CICS.
Specifically we are defining a URIMAP as an application entry point where the URIMAP resource is defined with USAGE(JVMSERVER) using Liberty.
We are using Path Parameters in the URI to pass an identifier into the API call:
DEFINE URIMAP(SU622WS1) GROUP(WSGRESP)
DESCRIPTION(WSG Endpoint)
USAGE(JVMSERVER) SCHEME(HTTP) HOST(*)
PATH(/customer/{id})
TRANSACTION(22SU)
As the characters { and } are not supported in the Path attribute, we are using hexadecimal escape sequences as per the CICS documentation
https://www.ibm.com/docs/en/cics-ts/5.4?topic=resources-urimap-attributes
The PATH attribute is specified in mixed case, and the case is preserved in the URIMAP definition. The PATH attribute must contain only the characters that are allowed in URIs. Specifically, the characters < > # % " { } | \ ^ [ ] ` and embedded blanks must be excluded (except that % is allowed when it introduces a valid hexadecimal escape sequence; that is, when it is followed by two valid hexadecimal digits in uppercase or lowercase). The tilde character ~ cannot be specified in CICS and must be replaced by the corresponding hexadecimal escape sequence (%7E). CICS validates the use of characters at define time.
This results in the following URIMAP definition:
DEFINE URIMAP(SU622WS1) GROUP(WSGRESP)
DESCRIPTION(WSG Endpoint)
USAGE(JVMSERVER) SCHEME(HTTP) HOST(*)
PATH(/customer/%7Bid%7D)
TRANSACTION(22SU)
Based on the CICS documentation, this should be supported. However at run time the process invoked by the API call runs under the default Liberty transaction CJSA indicating that it was unable to match to the URIMAP defined above.
This does work using the wildcard character * in the PATH attribute:
DEFINE URIMAP(SU622WS1) GROUP(WSGRESP)
DESCRIPTION(WSG Endpoint)
USAGE(JVMSERVER) SCHEME(HTTP) HOST(*)
PATH(/customer/*)
TRANSACTION(22SU)
At runtime the API executes under Transaction 22SU.
URIMAPs are limited to a single wildcard entry, and it must be the end of the path. This means URIs such as /customer/{id}/orders/{oid} cannot be represented as /customer/*/orders/* in the URIMAP, but only /customer/*
The downstream effect is that in circumstances where multiple path parameters exist, only a top level single match can occur. So if a custom transaction code is required, then /customer/{id}/orders/{oid} must run under the same transaction code as /customer/{id}. This is not a desirable outcome.
Liberty happily supports the brace syntax for path parameters, but CICS does not in the URIMAP definition, despite compliance with the hexadecimal escape sequence.
Looking to understand if this is a bug in CICS or a design feature? Has anyone else successfully used Path Parameters in the URIMAP Path Attribute?
------------------------------
Ryan Johnson
------------------------------