Invoke webMethods IS policy in API Gateway 10.2

[Clench_Paign_James3 (Clench Paign James)]

webMethods API Gateway tutorial

Author: Chandrasekaran, Vallab (vac@softwareag.com)
Supported Versions: 10.2 and above

For details on the usage of Invoke webMethods IS policy in versions 10.1 and below please refer Invoke webMethods IS policy in API Gateway 10.1 and below

Overview of the tutorial

API Gateway ships with a number of mediation policies that are enough to accomplish most of the use cases in the API management world. But in some cases the API Provider wants to do some custom operation apart from the out of the box policy support. API Gateway helps to accomplish this by letting the Provider create a custom logic using IS services and configure them using the Invoke webmethods IS policy for an API. Among the many use cases, one important and demanding use case would be to read and transform the contents of a request or response in a webMethods IS service to implement the custom logic. In this tutorial, we shall see how to read and transform the contents from a request or response, such as headers, query parameters, path parameters, HTTP method, payload, status code, status message, etc using Invoke webMethods IS policy in API Gateway 10.2 and above versions.

Required knowledge

The reader is expected to:

• have a basic understanding of API Gateway and policy enforcement
• have knowledge on Software AG Designer to create and modify services

Why?

API Gateway forwards the incoming requests from the client to the native service, and forwards the response from the native service back to the client. Now when the API Provider wants to read the contents of the request and/or response to do some audit logging, or trigger a notification based on the contents of the request, the Provider can configure the Invoke webMethods IS policy to read the contents of the request/response using IS Service. In another case, if the API Provider wants to modify the request before forwarding the request to Native service as the native service wants to identify all incoming requests from API Gateway. In such case the Provider can configure the Invoke webMethods IS policy to add a header to all requests before they get routed to the native service.

Prerequisite steps

• Install API Gateway 10.2 advanced edition
• Install the attached IS package 101EsbServices.zip, which is used as the sample in this tutorial

Details

Use cases

The following sections explain the use cases of Invoke webmethods IS policy in detail.

Use case 1: Transformation of request contents

The Invoke webMethods IS policy can be used to modify the contents of an incoming request such as headers, payload, query parameters, path parameters, HTTP method, payload using an IS Service. The design time and run-time workflows are explained below.

Design time flow

• API Provider creates an IS Service in Integration Server (in which API Gateway is running). The provider configures the IS Service to transform the request contents as per their need
• The API Provider configures the Invoke webMethods IS policy in Request processing stage of API Gateway, with the IS Service created in previous step

Run time flow

• The Client sends the request to API Gateway
• API Gateway invokes the webMethods IS Service configured by the API Provider. The IS Service transforms the request contents as defined by the API Provider
• API Gateway sends the transformed request to the native service
• Native server processes the transformed request and sends the response to API Gateway
• API Gateway forwards the response to client

Use case 2: Transformation of response contents

The Invoke webMethods IS policy can be used to modify the contents of an outgoing response such as headers, payload, status code, status message using an IS Service.
The below diagram represents the flow of Invoke webMethods IS policy usage for transforming the response contents. 

Design time flow

• API Provider creates an IS Service in Integration Server (in which API Gateway is running). The provider configures the IS Service to transform the response contents as per their need
• The API Provider configures the Invoke webMethods IS policy in Response processing stage of API Gateway, with the IS Service created in previous step

Run time flow

• The Client sends the request to API Gateway
• API Gateway forwards the request to native service
• Native service processes the request and sends response to API Gateway
• API Gateway invokes the webMethods IS Service configured by the API Provider. The IS Service transforms the response contents as defined by the API Provider
• API Gateway sends the transformed response to the client

3. Other use cases

Other than the transformation of request and response contents, some other user cases of Invoke webMethods IS policy are listed below.

• Invoke webMethods IS Service can be used to route a request to a dynamically generated native endpoint. The IS service can be used by providers to identify the routing endpoint dynamically at runtime, and set the dynamic endpoint in message context. If Dynamic Routing policy is configured in API Gateway, then API Gateway reads the dynamic endpoint set by the IS Service from message context and routes the request to the dynamic endpoint. For more details about this, refer Dynamic Routing in API Gateway
• Accessing authorization related information which are populated after the IAM policy is executed in API Gateway. For more details refer section "Accessing authorization values hidden after IAM policy in this article."
• Using Invoke IS Service policy, you can add custom fields to transaction events. This can be useful when user wants to log additional fields other than the default fields logged by API Gateway. Please refer the section "Add custom field to transaction events via Invoke IS Service" for more details.
• Logging the content of the request or response to a database or file, which can be used for audit at a later point
• Triggering a notification based on the content

Accessing client certificate used for SSL Connectivity

For accessing the client certificate used for SSL Connectivity, you can use the IS Service "ssl:traceCertificates" in the attached invokeISDemo.zip IS package. Use the code in the getTransportCertificates() method in the above IS Service, to get the client certificates used for SSL Connectivity. 

Transformation in action

There are two approaches for transforming the contents of a request/response using Invoke IS Service policy.

1. Transforming the contents using pipeline parameters by complying to IS Spec provided by API Gateway
2. Transforming the contents programmatically by creating an IS service (either flow service or Java service) to read/write the contents from/to the message context

Approach 1: Transform the contents using pipeline parameters

In this approach, you can easily read/write the contents using the input/output pipeline variables provided in the Spec. You need not write java code to read/write the contents from the message context. This approach is introduced in API Gateway 10.2 and Software AG recommends you to use this approach to transform the contents from version 10.2. The following sections provide a detailed view of this approach.

Configuring the webMethods IS Service policy in UI

For request processing, add the Invoke webMethods IS policy in "Request Processing" stage. Similarly for response processing, add it in the "Response Processing" stage.

• Choose a "webMethods IS Service Alias", if you have created an alias for the webMethods IS configuration. For more details about this, refer the section Using webMethods IS Service Alias
• Click on "add webMethods IS Service" if you want to add configuration for webMethods IS Service at policy level

The configuration includes:

• webMethods IS Service - The IS Service that will be invoked
• Run As User - Invoke the IS Service as a particular user. The value entered here should be an existing IS User. (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 your input parameters and the output parameters comply to the spec present in pub.apigateway.invokeISService.specifications in WmAPIGateway package

Use pub.apigateway.invokeISService.specifications.RequestSpec for the IS Services invoked at Request Processing stage.

Use pub.apigateway.invokeISService.specifications.ResponseSpec for the IS Services invoked at Response/Fault Processing stage.

To add the above Spec to your IS Service, click on the "Input/Output" tab and click on the "..." on the right end of "Specification Reference" text box. In the popup window that opens navigate to the "pub.apigateway.invokeISService.specifications" folder under wmApiGateway package and select your specification and click "OK"

Header Transformation

In this section, let us see how to do header transformation (reading the value of a header, adding a header, modifying the value of a header, removing a header) using Invoke IS Service pipeline variables. 

Applicable Stages:  Request Processing, Response Processing, Error Handling
Applicable Types:   SOAP, REST, ODATA

Reading the headers

Let us use the "pub.flow:debugLog" service in the WmPublic package to read our pipeline variables and write to the IS server log. 

• Add the "pub.flow:debugLog" service to your IS Service
• To read the value of a particular header (for example Accept header), in the pipeline view, right click on the pipeline variable "headers" at the "Pipeline In" section, insert String
• Name it to the header name (in our case, 'Accept')
• Click on the newly created string ("Accept") and drag to "message" which is the input pipeline variable of "pub.flow:debugLog" service
• Now, when the IS Service is invoked during the request/response stage, the value of the Accept header will be printed in the IS Server log
• In this way, you can also pass the value of a particular header to another iS service and do more processing based on the header value

Add/modify a header

• Drag the "MAP" flow step from palette to the IS Service
• To add a new header or modify the value of an existing header, right click on the pipeline variable "headers" at the Pipeline Out section and insert String
• Name it to the header name you want to add/modify (example: 'Accept')
• Right click on the added string and click on "Set Value"
• In the new window that opens, set the value of the header and save
• Now, when the IS Service is invoked during the request/response stage, the value of the headers in the request/response will be modified after the invocation of the IS service

Remove a header

• Drag the "MAP" flow step from palette to the IS Service
• To remove a header, right click on the pipeline variable "headers" at the Pipeline In section and insert String
• Name it to the header name you want to remove (example, 'Content-Type'. Note that API Gateway will add default Content-Type in request/response if this header is removed here)
• Right click on the added string and click on "Drop". Save the IS Service
• Now, when the IS Service is invoked during the request/response stage, the header in the request/response will be removed after the invocation of the IS service

Query Parameters Transformation

In this section, let us see how to do query parameters transformation (reading the value of a query parameter, adding a query parameter, modifying the value of a query parameter, removing a query parameter) using Invoke IS Service pipeline variables.

Applicable Stages:  Request Processing
Applicable Types:    REST

Reading a query parameter

• Add the "pub.flow:debugLog" service to your IS Service
• To read the value of a particular query parameter (for example var1), in the pipeline view, right click on the pipeline variable "query" at the "Pipeline In" section, insert String. Name it to the query parameter name you want to read  (in our case, 'var1')
• Click on the newly created string ("var1") and drag to "message" which is the input pipeline variable of "pub.flow:debugLog" service
• Now, when the IS Service is invoked during the request stage, the value of the var1 query parameter will be printed in the IS Server log. In this way, you can also pass the value of the query parameter to another iS service and do more processing based on the value

Add/modify a query parameter

• Drag the "MAP" flow step from palette to the IS Service
• To add a new query parameter or modify the value of an existing query parameter, right click on the pipeline variable "query" at the "Pipeline Out" section and insert String. Name it to the query parameter name you want to add/modify (example, 'var1')
• Right click on the added string and click on "Set Value"
• In the new window that opens, set the value of the query parameter and save
• Now, when the IS Service is invoked during the request stage, the value of the query parameter in the request will be modified after the invocation of the IS service

Remove a query parameter

• Drag the "MAP" flow step from palette to the IS Service
• To remove a query parameter, right click on the pipeline variable "query" at the "Pipeline In" section and insert String. Name it to the query parameter you want to remove (example, 'var1')
• Right click on the added string and click on "Drop". Save the IS Service
• Now, when the IS Service is invoked during the request stage, the query parameter in the request will be removed after the invocation of the IS service

Handling repeat query parameters

When Invoke IS Service (comply to IS spec) is configured, if the incoming request contains multiple values for same query parameter name, then only one value of the query param will be passed to the native service by default. This is because, in above examples, as we saw, we are handling the query parameter as a key-value pair where the value is a single string - so multiple values are not possible for the same key in this approach.

To override this default behavior and configure few query parameters as repeat query parameters (i.e., parameters that support multiple values), you need to do the following.

• In Rest API, under “Resources → Resource Parameters” and “Resources → Methods → Method Parameters” section, API Gateway provides options to specify the query parameter definition as “repeat” or non-repeat.

• Only if repeat is set as “yes” for any query parameter, API Gateway will treat that particular query parameter as array. i.e., read/write should be done using string-list data type insted of string data type in the Invoke IS Service.

• If the value for the repeat checkbox is not defined for a query parameter or defined as “repeat=no”, API Gateway will continue to handle that query param as string.

• For example, in above screenshot, var1 is non-repeat and var2 is repeat query parameter.
  To access/modify the value of var1 - continue to use the “Insert → string” option in previous sections, but to access/modify the value of query param “var2”, use “Insert → String List” after clicking the “query” pipeline variable.

Path parameter transformation

In this section, let us see how to do path parameter transformation (reading the value of path parameter, modifying the value of path parameter, removing the path parameter) using Invoke IS Service pipeline variables.

Applicable Stages:  Request Processing
Applicable Types:    REST

Reading the path

• Add the "pub.flow:debugLog" service to your IS Service. 
• To read the value of path, in the pipeline view, click on the pipeline variable "path" at the "Pipeline In" section, and drag to "message" which is the input pipeline variable of "pub.flow:debugLog" service.
• Now, when the IS Service is invoked during the request stage, the value of the path will be printed in the IS Server log. In this way, you can also pass the value of the path to another iS service and do more processing based on the value. 

Modify path

• Drag the "MAP" flow step from palette to the IS Service
• To modify the value of path, right click on the pipeline variable "path" at the "Pipeline Out" section and click on "Set Value"
• In the new window that opens, set the value of the path parameter and save
• Now, when the IS Service is invoked during the request stage, the value of the path parameter in the request will be modified after the invocation of the IS service

Remove path

If you want to remove the path totally, follow the "Modify path" step and set the value of path as empty in the "Set Value" step.
Note that you cannot achieve this by dropping the pipeline variable "path".

HTTP Method transformation

In this section, let us see how to do HTTP method transformation (reading the value of HTTP method, modifying the value of HTTP method) using Invoke IS Service pipeline variables.

Applicable Stages:  Request Processing
Applicable Types:    REST

Reading the value of HTTP Method

• Add the "pub.flow:debugLog" service to your IS Service. 
• To read the value of the HTTP Method, in the pipeline view, click on the pipeline variable "httpMethod" at the "Pipeline In" section, and drag to "message" which is the input pipeline variable of "pub.flow:debugLog" service.
• Now, when the IS Service is invoked during the request stage, the value of the method will be printed in the IS Server log. In this way, you can also pass the value of the method to another iS service and do more processing based on the value. 

Modify HTTP Method

• Drag the "MAP" flow step from palette to the IS Service. 
• To modify the value of HTTP Method, right click on the pipeline variable "httpMethod" at the "Pipeline Out" section and click on "Set Value"
• In the new window that opens, set the value of the HTTP Method and save. Applicable values are GET, POST, PUT, DELETE.
• Now, when the IS Service is invoked during the request stage, the native service is invoked with the modified HTTP Method.

Payload transformation

In this section, let us see how to do payload transformation (reading the value of the payload, modifying the value of payload, removing the existing payload) using Invoke IS Service pipeline variables.

Applicable Stages:  Request Processing, Response Processing, Error Handling
Applicable Types:    SOAP, REST, ODATA, WebSocket

Applicable Content-Types

• For string content types like application/json, application/xml, text/xml, text/plain, text/html use the pipeline variable "payload" to read/modify the payload.
• For binary content types like multipart/form-data use the pipeline variable "payloadObject" to read/modify the payload.
• In case of WebSocket API, when message type is "Text", use the pipeline variable "payload" and when message type is "Binary", use the pipeline variable "payloadObject". In the examples below, we will use the pipeline variable "payload". You can modify it for "payloadObject" based on the Content-Type.

Reading the payload

• Add the "pub.flow:debugLog" service to your IS Service
• To read the payload, in the pipeline view, click on the pipeline variable "payload" at the "Pipeline In" section, and drag to "message" which is the input pipeline variable of "pub.flow:debugLog" service
• Now, when the IS Service is invoked during the request/response stage, the payload will be printed in the IS Server log. In this way, you can also pass the payload to another iS service and do more processing based on the payload

Modify payload

• Drag the "MAP" flow step from palette to the IS Service
• To modify the payload, right click on the pipeline variable "payload" at the "Pipeline Out" section and click on "Set Value"
• In the new window that opens, set the value of payload and save
• If you want to set payload containing more than one line, click on the 3 dots in the value field of payload as shown in image below
• 
• In the new popup that opens you can set the entire payload (containing multiple lines) and click ok, and save the IS Service
• 
• Now, when the IS Service is invoked during the request/response stage, the request/response payload will be modified after the invocation of the IS service

Remove payload

If you want to remove the payload, follow the "Modify payload" step and set the value of payload as empty in the "Set Value" step.
Note that you cannot achieve this by dropping the pipeline variable "payload".

Status code transformation

In this section, let us see how to do status code transformation (reading the value of status code, modifying the value of status code) using Invoke IS Service pipeline variables.

Applicable Stages:  Response Processing, Error Handling
Applicable Types:    SOAP, REST, ODATA

Reading the status code

• Add the "pub.flow:debugLog" service to your IS Service
• To read the value of status code, in the pipeline view, click on the pipeline variable "statusCode" at the "Pipeline In" section, and drag to "message" which is the input pipeline variable of "pub.flow:debugLog" service
• Now, when the IS Service is invoked during the response stage, the value of the statusCode will be printed in the IS Server log. In this way, you can also pass the value of the status code to another iS service and do more processing based on the value

Modify status code

• Drag the "MAP" flow step from palette to the IS Service
• To modify the value of status code, right click on the pipeline variable "statusCode" at the "Pipeline Out" section and click on "Set Value"
• In the new window that opens, set the value of the status code and save
• Now, when the IS Service is invoked during the response stage, the value of the status code in the response will be modified after the invocation of the IS service

Status message transformation

In this section, let us see how to do status message transformation (reading the value of status message, modifying the value of status message) using Invoke IS Service pipeline variables.

Applicable Stages:  Response Processing, Error Handling
Applicable Types:    SOAP, REST, ODATA

Reading the status message

• Add the "pub.flow:debugLog" service to your IS Service
• To read the value of status message, in the pipeline view, click on the pipeline variable "statusMessage" at the "Pipeline In" section, and drag to "message" which is the input pipeline variable of "pub.flow:debugLog" service
• Now, when the IS Service is invoked during the response stage, the value of the status message will be printed in the IS Server log. In this way, you can also pass the value of the status message to another iS service and do more processing based on the value

Modify status message

• Drag the "MAP" flow step from palette to the IS Service
• To modify the value of status message, right click on the pipeline variable "statusMessage" at the "Pipeline Out" section and click on "Set Value"
• In the new window that opens, set the value of the status message and save
• Now, when the IS Service is invoked during the response stage, the value of the status message in the response will be modified after the invocation of the IS service

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. These info like authorization header can be added back to the request sent to native server using “Outbound Authentication” policy in Routing stage. However, if the API Provider wants to extract the authorization information at the request processing stage for reasons like sending the authorization values via a different header to the native server for audit purposes, or do some business logic in IS Service based on those values, then they can access the authorization values via the “authorization” pipeline variable.

Note: This authorization pipeline variable is supported from 10.3 fix 21 onwards, 10.5 fix 10 onwards and 10.7 fix 1 onwards. On major versions later than 10.7, this will be supported from fix 0.

Supported Authorization values

Name	Type	Description
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
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

Accessing string types (clientId, userName, issuer, authHeader, incomingToken, audience, apiKey)

As a sample usecase, let us use the “pub.flow:debugLog” service in the WmPublic package to read our authorization pipeline variables and write to the IS server log.
Based on your usecase, you can use some other IS Service instead of debugLog service to pass the value of the authorization element(s) to your IS service and do more processing in your IS service.

1. Add the spec “pub.apigateway.invokeISService.specifications.RequestSpec” in the specifications of the IS Service.
2. Add the “pub.flow:debugLog” service to your IS Service.
3. To access the value of a particular authorization element (say clientId), in the pipeline view, expand the “Authorization” pipeline variable and click on the clientId child variable and drag to “message” which is the input pipeline variable of “pub.flow:debugLog” service (Service In).
4. Now, when the IS Service is invoked during the request stage, the value of the authorization element you chose will be printed in the IS Server log.

Accessing claims from authorization pipeline variable

As a sample usecase, let us use the “pub.flow:debugLog” service in the WmPublic package to read the value of a claim and write to the IS server log.
Based on your usecase, you can use some other IS Service instead of debugLog service to pass the value of one or more claims to your IS service or loop through all claims in your IS servicce and do more processing based on that.

1. Add the spec “pub.apigateway.invokeISService.specifications.RequestSpec” in the specifications of the IS Service.
2. Add the “pub.flow:debugLog” service to your IS Service.
3. To access the value of a particular claim (say claim1), in the pipeline view, expand the “Authorization” pipeline variable and click on the claims child variable and insert string and name it as your claim name (claim1).
4. Click on the newly created string (claim1) under claims and drag it to “message” which is the input pipeline variable of “pub.flow:debugLog” service (Service In).
5. Now, when the IS Service is invoked during the request stage, the value of the claim1 will be printed in the IS Server log.

Accessing client certificates used for SSL connectivity

As mentioned in above sections, you can now access the client certificates used for SSL Connectivity in Invoke IS Service (comply to IS Spec = true) using pipeline “authroization” → “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 .
Code block to convert the certificates pipeline variable to X509Certificate is given below.

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" );

Loop through the certificates array (in the final line of code) and use methods supported by X509Certificate to access the values you need from each certificate.

Add custom field to transaction events via Invoke IS Service

Using Invoke IS Service policy, you can add custom fields to transaction events. This can be useful when user wants to log additional fields other than the default fields logged by API Gateway.

1. Create webMethods IS service by specifying the “pub.apigateway.invokeISService.specifications.RequestSpec ” or “pub.apigateway.invokeISService.specifications.ResponseSpec” as a specification reference based on your policy stage.
2. In the webMethods IS service, set the required custom fields in the customFieldsMap “pipeline out” variable.
3. The “customFieldsMap” is of type string table. You need to insert each custom field key-value pairs in one new row. You need to add one column (0) for key and one column (1) for value as shown in the below screenshot.
4. Invoke the API configureing this IS service in the Invoke webMethods IS policy. Verify the fields got added in analytics.

Approach 2: Transform the contents programmatically

In this approach you need to programmatically extract the contents from message context. However Software AG recommends you to use the first approach from version 10.2. To know more about this approach refer Usage of “Invoke webMethods IS” policy in versions 10.1 and below. 

Configuring the webMethods IS Service policy

If “Comply to IS Spec” parameter is not marked as selected (false), the transformation continues to work similar to version 10.1, except for few code changes (refer the next section).

Code changes in 10.2

Note: Refer Usage of “Invoke webMethods IS” policy in versions 10.1 and below before reading further.

If you are using java code to programmatically modify the payload in REST APIs in version 10.1 (or below), the code will not work from 10.2, as there are some changes in the internal APIs. You need to modify the code to adapt to the internal API changes as below. 

For modification of payload using IS Service programmatically (comply to IS Spec = false) in request processing stage in Version 10.2, you can use the below code block.

//Read the payload from Message Context

IContent iContent = restMessageContext.getRequestContent();

String payload = iContent.getAsString();

//Modify the payload

//Write the payload back to Message Context

iContent.convertFromString(payload);

For modification of payload using IS Service programmatically (comply to IS Spec = false) in response processing stage in Version 10.2, you can use the below code block.

//Read the payload from Message Context

IContent iContent = restMessageContext.getResponseContent();

String payload = iContent.getAsString();

//Modify the payload

//Write the payload back to Message Context

iContent.convertFromString(payload);

Using webMethods IS Service Alias

This section explains about the usage of alias for an IS service in Invoke webmethods IS policy instead of configuring the service in policy configuration itself. You can configure one or more webMethods IS Service aliases. The values for the various parameters in Invoke webMethods IS policy can be added to the alias. Then, you can configure those aliases in the Invoke webMethods IS policy to invoke the IS Service configured in the aliases. 

Step 1: Create a webMethods IS Service Alias

• To create a webMethods IS Service Alias, Click on Aliases → Create Alias
• In the Create Alias page, configure the name of the alias, and select type as "webMethods IS Service alias"
  
• Click on "Continue to technical information"
• The configurations in the "Technical Information" section of the webMethods IS Service alias, are same as the configurations in the policy
  

The configuration includes:

• Service Name - Name of the webMethods IS Service that will be invoked
• Run As User - Invoke the IS Service as a particular user. The value entered here should be an existing IS User. (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 your input parameters and the output parameters comply to the spec present in pub.apigateway.invokeISService.specifications in WmAPIGateway package

Step 2: Using webMethods IS Service Alias in Invoke webMethods IS policy

• Add Invoke webMethods IS policy 
• Start typing the alias name in the "webMethods IS Service Alias" Section. The alias you created will be shown in the suggestions from the type-ahead
• 
• Click on the suggested alias name to add the alias name. Add one or more aliases in this way. Click save.The IS Services configured in the added aliases will be invoked in the runtime during policy execution

Achieving transformation use cases using Transformation policy

The transformation use cases (1 and 2 in Use cases section) can be achieved by Invoke IS Service as well as using Request Transformation or Response Transformation policy in API Gateway. For more details about the Transformation policies, refer Request and Response Transformation policies in API Gateway.

When to use Transformation policy and when to use Invoke IS Service policy

You can use transformaiton policies to achieve use cases that can be easily configured in API Gateway UI. However there may be some use cases that cannot be solved by transformation policies. You can use Invoke IS Service policy to achieve all use cases of transformation, but you need to write an Invoke IS Service to do so, which might take some effort.

Below are some guidelines about when to use these two policies.

• When you need to do simple transformations that can be configured easily in API Gateway UI, you can use the transformation policy. For example, 

  • Add/Modify a header to some constant value (eg: headers.Accept  = application/json)

  • Add/Modify a query parameter by reading another content (say reading a header and set it in a query parameter, for example, query.var1 = headers.var1)

  • Remove a header in request or response. 

  • Modify the status code/status message/HTTP Method

• Use Invoke IS Service policy to achieve complex use cases of transformation by writing an Invoke IS Service. When you need to write some custom logic (using Java code) to do the transformation, you can use Invoke IS Service policy. Using Java code in IS Service, you can do these complex transformations

• For transforming the payload using XSLT transformation, use Payload transformation section under Transformation policy. For payload transformation without XSLT, use Invoke IS Service

• For executing transformations based on conditions, use conditions in the transformation policy. For example, When status code = 200, execute the transformation configured. Note: You can configure conditions as well as configure Invoke IS Service in Advanced Transformation section of Transformation policy to conditionally invoke an IS Service

Limitations

• If you transform the contents of request/response programmatically (i.e, Comply to IS Spec = false), then you need to adapt your code to reflect internal API changes. Software AG recommends you to do the transformations by “Complying to IS Spec” from version 10.2. When using this approach, you need not write code to view/modify headers, payload, etc and hence you won't have to adapt your code to reflect internal API changes

• When you transform the contents of request/response programmatically (i.e, Comply to IS Spec = false), then you need to set the build path referring to API Gateway jars. Also you need to mark the wmAPIGateway package in the package dependencies of your IS service package. Software AG recommends you to use the first approach (comply to IS Spec= true) from version 10.2. Use this second approach (comply to IS Spec= false) only if you want to reuse the same IS Services you have written in versions 10.1 or before

References

• For developing IS services using designer please refer https://documentation.softwareag.com/webmethods/wmsuites/wmsuite10-2/Designer/10-2_Service_Development_Help.pdf

Downloadable artifacts

The IS package for the sample IS services:

• invokeISDemo.zip

The below videos provide a detailed demonstration of Invoke webmethods IS policy use cases in API Gateway. Please find the video files in the attachments.

• requestProcessing.mp4
• responseProcessing.mp4
• errorHandling.mp4

Learn more

• For a detailed understanding about the usage of Invoke webMethods IS policy in Dynamic Routing, refer Dynamic Routing in API Gateway
• For details on the usage of Invoke webMethods IS policy in versions 10.1 and below refer Invoke webMethods IS policy in API Gateway 10.1 and below
• For details on using transformation policies to transform request and response contents refer Request and Response Transformation policies in API Gateway

errorHandling.mp4 (20.5 MB)

responseProcessing.mp4 (15 MB)

requestProcessing.mp4 (52 MB)

invokeISDemo.zip (62.9 KB)