API Gateway 10.5 | Using API Gateway | Policies | System-defined Stages and Policies | Request Processing | Invoke webMethods IS
 
Invoke webMethods IS
This policy pre-processes the request messages and transforms the message into the format required by the native API or performs some custom logic, before API Gateway sends the requests to the native APIs.
For example, you might need to accommodate differences between the message content that a client is capable of submitting and the message content that a native API expects. For example, if the client submits an order record using a slightly different structure than the structure expected by the native API, you can use this action to process the record submitted by the client to the structure required by the native API.
If Comply to IS Spec parameter is configured as true, API Gateway invokes the IS Service with IS specification in the path pub.apigateway.invokeISService.specifications:RequestSpec for Request Processing
The following are the input and output parameters for REST, SOAP, and WebSocket APIs as specified in the above IS specification. Input parameters can be used to access the existing values of the request while output parameters can be used to modify/write the values to the request.
Parameter name
Description
Input parameters
headers
Headers in incoming request.
Data type: Document
query
Query parameters in incoming request (this is applicable for REST API only).
Data type: Document
path
Path parameter of the incoming request (this is applicable for REST API only).
Data type: String
httpMethod
HTTP Method of the incoming request (this is applicable for REST API only).
Data type: String
payload
Payload of the incoming request.
Data type: String
payloadObject
The payload for binary content types like multi-part / form-data.
Data type: Object
MessageContext
The message context object of the request.
Data type: Object
apiName
Name of the API invoked by the request.
Data type: String
apiVersion
Version of the API invoked by the request.
Data type: String
requestUrl
URL of the request.
Data type: String
ipInfo
Contains IP information of the request.
Data type: Document
websocketInfo
Websocket related information of the request.
Data type: Document
correlationID
Correlation ID of the request/response. This is unique and same for a request and response.
Data type: String
customFieldsMap
Custom transactional fields can be added to the transactional events using this field. For more information, see Adding Custom Fields to Transactional Events section.
Data type: Document
authorization
Authorization information of the request. For more information, see Accessing authorization values hidden after IAM policy section.
Data type: Document
Output parameters
headers
Headers in incoming request.
Data type: Document
query
Query parameters in incoming request (this is applicable for REST API only).
Data type: Document
path
Path parameter of the incoming request (this is applicable for REST API only).
Data type: String
httpMethod
HTTP Method of the incoming request (this is applicable for REST API only).
Data type: String
payload
Payload of the incoming request.
Data type: String
payloadObject
The payload for binary content types like multi-part / form-data.
Data type: Object
MessageContext
The message context object of the request.
Data type: Object
customFieldsMap
Custom transactional fields can be added to the transactional events using this field. For more information, see Adding Custom Fields to Transactional Events section.
Data type: Document
By default the "query" pipeline variable is a key value pair, where the value is of type string. But, if the incoming request contains multiple values for the same query parameter and if you want to access those multiple values using webMethods IS Service, you have to ensure two things:
1. Make sure that you have checked the Repeat check box for query parameter in the Add Resource Parameter section of the API details screen.
2. To access or transform multiple values of that query parameter, you have to insert string list (instead of string) under the "query" pipeline variable in the webMethods IS Service.
Note: 
*For SOAP to REST APIS, the payload contains the transformed SOAP request.
*Payload transformation does not happen automatically for content-type transformation. When you change the content type, ensure to do payload transformation also as part of IS Service. For example, if you change the content-type header from application/xml to application/json using IS service, you must also change the respective payload from application/xml to application/json
*Only Method Transformation happens when configured, but you have to take care of adding payload during transformations involving method change like GET to POST, and so on.
*When Comply to IS spec is true, you can change the values of headers, query, payload, and so on, programatically using Message Context, as well as using the pipeline variables given. Software AG recommends you do not change those values directly in Message Context, as the values in output pipeline variables are written to Message Context after the invocation of IS Service.
If Comply to IS Spec parameter is set to false, API Gateway invokes the IS Service with the same input and output parameters supported in 10.1 and the earlier versions:
*proxy.name
*JSONRESTContentString (REST only)
*SOAPEnvelope (SOAP only)
*EnvelopeString (SOAP only)
The table lists the properties that you can specify for this policy:
Parameter
Description
Invoke webMethods Integration Server Service
Add invoke webMethods Integration Server service
Specifies the webMethods IS service to be invoked to pre-process the request messages and the authentication mode for the IS service.
Provide the following information:
*webMethods IS Service. Specify the webMethods IS service to be invoked to pre-process the request messages.
The webMethods IS service must be running on the same Integration Server as API Gateway.
Note:
If an exception occurs when invoking the webMethods IS service, by default API Gateway displays the status code as 500 and error message as Internal Server Error.
You can set custom status code and error message by setting the following properties in the message context of the webMethods IS service:
*service.exception.status.code
*service.exception.status.message
You must add the WmAPIGateway package as dependent to IS service to get access to the class used to set the custom status code and message.
The sample code is given below:

import org.apache.synapse.MessageContext
IDataCursor idc = pipeline.getCursor();
MessageContext context = (MessageContext)IDataUtil.get(idc,"MessageContext");
if(context != null)
{
context.setProperty("service.exception.status.code", 404);
context.setProperty("service.exception.status.message", "Object Not Found");
throw new ServiceException();
}
Note:
If ServiceException or FlowException occurs when invoking webMethods IS Service, the message given in the exception is displayed to the client. If any other exception occurs, a generic error message is displayed to the client.
*Run as User. Specifies the authentication mode to invoke the IS service. If this field is left blank the incoming credentials of the user, identified by API Gateway, are used to authenticate and invoke the IS service. You can also specify a particular user, you want API Gateway to invoke the IS service.
Note:
It is the responsibility of the user who activates the API to review the value configured in Run as User field to avoid misuse of this configuration.
*Comply to IS Spec. Mark this as true if you want the input and the output parameters to comply to the IS Spec present in pub.apigateway.invokeISService.specifications folder in wmAPIGateway package.
Note:Software AG recommends users to configure the policy with Comply to IS Spec as true, as you can read or change the values of headers, and so on, without having to read from or write to the message context.
webMethods IS Service alias
Specifies the webMethods IS service alias to be invoked to pre-process the request messages.
Start typing the webMethods alias name, select the alias from the type-ahead search results displayed and click to add one or more aliases.
You can use the delete icon to delete the added aliases from the list.
Adding Custom Fields to Transactional Events
This section explains you how to add custom fields to the transactional events.
1. Create webMethods IS service by specifying the pub.apigateway.utils:customFieldInTransactionEventSpec as a specification reference.
2. In the webMethods IS service, set the required custom fields in the customFieldsMap output variable.
3. Once when customFieldsMap gets created, the custom fields will be available in the transactional events.
4. Invoke the API with the Invoke webMethods IS policy.
Accessing authorization values hidden after IAM policy
By default, API Gateway removes all the authorization related information from client request (for example authorization header) once the IAM policy is engaged. The information like authorization header can be added back to the request sent to native API using "Outbound Authentication" policy in the Routing stage. However, if the you want to extract the authorization information at the request processing stage for sending the authorization values using a different header to the native API for audit purposes, or performing some business logic in IS Service based on the authorization values, then you can access the authorization values using the "authorization" pipeline variable.
The following table lists the supported authorization values:
Name
Type
Description
clientId
String
clientId identified after the OAuth / JWT / OpenID token is authenticated.
userName
String
Name of the user identified after the IAM policy.
issuer
String
Issuer identified from the JWT token.
authHeader
String
Value of the incoming "authorization" header sent by client.
Note:
If the authorization header has bearer tokens ( such as OAuth, OpenID, or JWT), then the "authHeader" pipeline variable will be empty. For such cases, Software AG recommends to use the "incomingToken" pipeline variable.
incomingToken
String
Value of the token in case the incoming authorization header contains a bearer token.
audience
String
Audience identified from the incoming JWT token.
apiKey
String
API Key sent from client.
claims
Document
(Key-value pair)
Contains the claims present in the JWT token. You can provide the claim name to access the claim value.
certificates
Object List
Client certificates used for SSL connectivity.
Note:
All the above mentioned authorization values except certificates can be accessed using authorization pipeline variable.
Accessing client certificates used for SSL connectivity
You can now access the client certificates used for SSL Connectivity in the Invoke webMethods IS Service (comply to IS Spec = true) using pipeline authorization > certificates.
Since certificates are not string data type, you need to write JAVA code to convert the pipeline variable certificates into accessible certificate format (Java X509Certificate) and you can read the values using the methods supported by X509Certificate.
The below sample code converts the pipeline variable certificates to X509Certificate:
import java.security.cert.X509Certificate;
IDataCursor cursor = pipeline.getCursor();
IData authIData = IDataUtil.getIData(cursor, "authorization");
IDataCursor authCursor = authIData.getCursor();
X509Certificate[] certificates = (X509Certificate[]) IDataUtil.getObjectArray(authCursor, "certificates");
The following watt parameters control the certification verification
*watt.net.ssl.client.hostnameverification
When API Gateway server acts as a HTTPS client, this parameter specifies whether API Gateway should restrict outbound HTTPS connections only when a valid hostname is found in the server’s certificate. If you set this parameter to true, API Gateway verifies if the hostname is present in the server’s certificate. If this verification fails, an error is logged and the connection is aborted. If you set this parameter to false, API Gateway skips the hostname verification. By default, this parameter is set to false.
*watt.security.ssl.ignoreExpiredChains
This parameter specifies whether API Gateway server ignores expired CA certificates in a certificate chain it receives from an Internet resource (that is, a web server, another API Gateway server). If you set this parameter to true, API Gateway, ignores the expired CA certificates. However, API Gateway allows SSL connection to be established, even if the certificate is expired. Note that this is less secure than denying connections when a certificate is expired. If you set this parameter to false, API Gateway does not ignore the expired CA certificates and a connection cannot be established, if a certificate is expired. By default, this parameter is set to false.
*watt.security.ssl.client.ignoreEmptyAuthoritiesList
When API Gateway acts as a client, this parameter specifies if API Gateway sends a certificate chain, after a remote SSL server returns an empty list of trusted authorities. If you set this parameter to true, API Gateway ignores the empty trusted authorities list and sends its chain anyway. If you set this parameter to false, API Gateway requires presentation of trusted certificates before sending out its certificate chain. By default, this parameter is set to false.