webMethods IS Services in Virtual Services

CentraSite User's Guide : Runtime Governance : Virtual Service Asset Management : webMethods IS Services in Virtual Services

A webMethods Integration Server (IS) service is a user-defined Integration Server flow service that you can invoke in:

Request Processing step: Pre-process the request message before the request is submitted to a Native Service.

Response Processing step: Pre-process the response message from a Native Service before the request is returned to the consuming application.

A webMethods IS service must be running on the same Integration Server as webMethods Mediator. It can call out a C++ or Java or .NET function. It can also call other Integration Server services to manipulate the SOAP message.

The input pipeline for a webMethods IS service should have the following input variables:

proxy.name: This is the name of the virtual service.

SOAPEnvelope: Contains the SOAP envelope. This is of the Java type org.apache.axiom.soap.SOAPEnvelope.

EnvelopeString: Contains the SOAP envelope as a string.

Limitation: EnvelopeString will not be sent to IS services if a request uses the MTOM SOAP Optimization Method and if the Integration Server property watt.server.SOAP.MTOMStreaming.enable is set to true.

MessageContext: Mediator places a MessageContext variable into the pipeline before executing the webMethods IS service call. MessageContext is of the Java type org.apache.axis2.context.MessageContext.

Integration Server users can use the Axis2 MessageContext object to manipulate the incoming SOAP request. The Integration Server provides built-in services (that is, the pub.soap.* services) to work with the MessageContext object to get, set, or modify the SOAP body, header, properties, and so on. Integration Server users should use these services to extract the information they need from the MessageContext to build the necessary business logic. Users do not need to understand Axis2 or Axiom (the xml object model based on StAX) to work with the SOAP request, because if they are familiar with the Integration Server pub.soap services, they can accomplish most of the tasks. For more information about these related Integration Server services, see the webMethods Integration Server Built-In Services Reference.

JSONRESTContentString: Will appear only for REST services with the Content-Type application/json or application/json/badgerfish.

UpdatedJSONRESTContentString: Will appear only for REST services with the Content-Type application/json or application/json/badgerfish.

You can use the following constructs in a webMethods IS service:

Predefined or custom context variables.

The Security API provided by Mediator (for Web services only).

Using the Security API in webMethods IS Services

Note:

This API is for Web services only.

Mediator provides Java services that you can use to support WS-Security functionality in a webMethods IS service that you invoke in the Request Processing step.

pub.mediator.security.ws:AddUsernameToken

Adds the WS-Username Token 1.0 and 1.1 to the request. This service includes the following input parameters:

Note:

For reasons of legibility some of the examples below contain break lines and might not work when pasted into applications or command line tools.

In the parameter descriptions, the data type is listed first, followed by the Java type in parenthesis, for example, “Object (org.apache.axis2.context.MessageContext)”.

Input Parameters

username	String (String). (Required). The value that will be added as the Username element in the token. The default value is: ""
MessageContext	Object (org.apache.axis2.context.MessageContext) (Required) Mediator will place a MessageContext variable into the pipeline before executing the webMethods IS service call. The default value is: org.apache.axis2.context.MessageContext instance
password	String (String). (Optional). The password for the token. You must specify password if the passwordType is set to either TEXT or DIGEST. The default value is: ""
passwordType	String (String). (Optional). Specifies how the password will be added in the token. Specify one of the following values: NONE: The password will not be added. TEXT: The password is added in plain text. DIGEST: The password is added in digested form (as specified in the UsernameToken profile). The default value is: NONE
addNonce	Boolean (Boolean). (Optional). Specifies whether the Nonce element will be added to the token. The default value is: false
addCreated	Boolean (Boolean). (Optional). Specifies whether the Created element will be added to the token The default value is: false
salt	byte[] (byte[]). (Optional). The value for the /wsse11:UsernameToken/wsse:Salt element. Its value is a 128 bit number serialized as xs:base64Binary. The default value is: null
iteration	int (Integer). (Optional). Indicates the number of times the hashing operation is repeated when deriving the key. It is expressed as a xs:unsignedInteger value. If it is not present, a value of 1000 is used for the iteration count. The default value is: 1000
useMac	Boolean (Boolean). (Optional). Indicates if the derived key will be used as a Message Authentication Code (MAC) or as a symmetric key for encryption. The default value is: false
useBasic AuthCredentials	Boolean (Boolean). (Optional). If this parameter is set to true, Mediator will try to use the username and password from the “Authorization” HTTP header. In this case the ‘username’ and ‘password’ fields need not be specified. The default value is: false
actor	String (String). (Optional). Indicates the value of the SOAP actor attribute if a new security header is being added to the SOAP request. If the request already has a security header with the actor specified in it, then this value will not overwrite it. The default value is: ""
mustUnderstand	Boolean (Boolean). (Optional). Specifies whether the security header will have the mustUnderstand attribute set to 0 or 1 (false / true). If the security header already has this attribute set, this value will not overwrite it. The default value is: false

pub.mediator.security.ws:AddX509Token

Adds a X.509 certificate (or certificate chain) as a BinarySecurityToken (BST) element in the outbound SOAP request. This service includes the following input parameters:

Note:

For reasons of legibility some of the examples below contain break lines and may not work when pasted into applications or command line tools.

In the parameter descriptions, the data type is listed first, followed by the Java type in parenthesis, for example, “Object (org.apache.axis2.context.MessageContext)”.

Input Parameters

MessageContext	Object (org.apache.axis2.context.MessageContext). (Required). Mediator will place a MessageContext variable into the pipeline before executing the webMethods IS service call. The default value is: org.apache.axis2.context.MessageContext instance
keystoreFile	String (String). (Required). The absolute path to a keystore file on the system where Mediator is running. The default value is: ""
keystorePassword	String (String). (Required). The password for the keystore. The default value is: ""
keystoreType	String (String). (Optional). The type of keystore represented by the file (can be JKS, JCEKS, or PKCS12). The default value is: JKS
keyAlias	String (String). (Required). The key alias whose X509 certificate will be sent in the soap request as a BST. The default value is: ""
useCertificatePath	Boolean (Boolean). (Optional). If set to true will use the entire certificate chain represented by the key alias instead of just a single certificate. The default value is: false
actor	String (String). (Optional). Indicates the value of the SOAP actor attribute if a new security header is being added to the SOAP request. If the request already has a security header with the actor specified in it, then this value will not overwrite it. The default value is: ""
mustUnderstand	Boolean (Boolean). (Optional). Specifies whether the security header will have the mustUnderstand attribute set to 0 or 1 (false / true). If the security header already has this attribute set, then this value will not overwrite it. The default value is: false

pub.mediator.security.ws:AddSamlSenderVouchesToken

This service enables a Security Token Service (STS) client to send a WS-Trust request to a configured STS to obtain a SAML v1/v2 assertion. For the details about configuring Mediator to act as an STS client, see Administering webMethods Mediator.

This service adds the obtained SAML assertion to the original request that is sent by the client to the native service, and includes the following parameters:

Note:

For reasons of legibility some of the examples below contain break lines and may not work when pasted into applications or command line tools.

In the parameter descriptions, the data type is listed first, followed by the Java type in parenthesis, for example, “Object (org.apache.axis2.context.MessageContext)”.

Input Parameters

ConfigName	String (String). (Required). References a previously configured STS configuration name. The default value is: ""
MessageContext	Object (org.apache.axis2.context.MessageContext). (Required). Mediator will place a MessageContext variable into the pipeline before executing the webMethods IS service call. The default value is: org.apache.axis2.context.MessageContext instance
addTimeStamp	Boolean (Boolean). (Optional). Adds a Timestamp element (with the duration specified in timeToLive) to the WS-Security header of the request and includes it in the signature. (The other items that are signed are the body and SAML assertion.) The default value is: false
timeToLive	Integer (Integer). (Optional). If addTimeStamp is true, timeToLive specifies the duration (in seconds) for which the request is valid. The default value is: 300 (5 minutes)
actor	String (String). (Optional). Indicates the value of the SOAP actor attribute if a new security header is being added to the SOAP request. If the request already has a security header with the actor specified in it, then this value will not overwrite it. The default value is: ""
mustUnderstand	Boolean (Boolean). (Optional). Specifies whether the security header will have the mustUnderstand attribute set to 0 or 1 (false / true). If the security header already has this attribute set, then this value will not overwrite it. The default value is: false

Example of using AddSamlSenderVouchesToken

The sample service shown below is configured by providing the MessageContext and ConfigName parameters. The value of ConfigName must be the name of a previously configured STS name, which is configured on the Mediator Configuration page.

pub.mediator.security.ws:AddTimestamp

Adds a timestamp to the outbound SOAP request WS-Security header. This service includes the following input parameters:

Note:

For reasons of legibility some of the examples below contain break lines and may not work when pasted into applications or command line tools.

In the parameter descriptions, the data type is listed first, followed by the Java type in parenthesis, for example, “Object (org.apache.axis2.context.MessageContext)”.

Input Parameters

timeToLive

Integer (Integer). (Optional). Specifies the duration (in seconds) for which the request is valid.

The default value is: 300 (5 minutes)

signTimestamp

Boolean (Boolean). (Optional). Indicates whether the generated timestamp must be signed by Mediator using the configured keystore and signing alias.

Note:

For signTimestamp to work, you must ensure that a valid IS keystore and signing alias are configured in Mediator. For details, see Administering webMethods Mediator.

The default value is: false

useMilliSecond Precision

Boolean (Boolean). (Optional). Indicates whether the generated timestamp must have millisecond precision.

The default value is: true

MessageContext

Object (org.apache.axis2.context.MessageContext). (Required). Mediator will place a MessageContext variable into the pipeline before executing the webMethods IS service call.

The default value is: org.apache.axis2.context.MessageContext instance

actor

String (String). (Optional). Indicates the value of the SOAP actor attribute if a new security header is being added to the SOAP request. If the request already has a security header with the actor specified in it, then this value will not overwrite it.

The default value is: ""

mustUnderstand

Boolean (Boolean). (Optional). Specifies whether the security header will have the mustUnderstand attribute set to 0 or 1 (false / true). If the security header already has this attribute set, then this value will not overwrite it.

The default value is: false

pub.mediator.addressing:AddWSAddressingHeaders

Adds WS-Addressing headers to a SOAP request sent by the client before Mediator forwards the request to the native service.

This service includes the following input parameters:

Note:

For reasons of legibility some of the examples below contain break lines and may not work when pasted into applications or command line tools.

In the parameter descriptions, the data type is listed first, followed by the Java type in parenthesis, for example, “Object (org.apache.axis2.context.MessageContext)”.

Input Parameters

isVersion Submission	Boolean (Boolean). (Optional). The WS-Addressing version that should be used. If true, the WS-Addressing submission namespace will be used. http://schemas.xmlsoap.org/ws/2004/08/addressing If false, the Final specification namespace will be used. http://www.w3.org/2005/08/addressing The default value is: false
To	String (String). (Optional). This value corresponds to the /wsa:To addressing header. You must specify a value that corresponds to the destination of the request message. If this value is not specified, the default value depends on the isVersionSubmission property value. One of the following anonymous EPR values will be sent: If isVersionSubmission is set to true, the anonymous EPR value is: http://schemas.xmlsoap.org/ws/2004/08/addressing/role/ anonymous If isVersionSubmission is set to false, the anonymous EPR is: http://www.w3.org/2005/08/addressing/anonymous
From	String (String). (Optional). This value corresponds to the /wsa:From addressing header and refers to the source of the message. The default value is: ""
Action	String (String). (Optional). This value corresponds to the /wsa:Action addressing header. By default, this property has the same value as the operation on the virtual service being invoked (which will usually correspond to the same operation on the native service). But the user can specify a different value corresponding to the native service being called. The default value is: URI identifying input operation corresponding to a WSDL port type being called on the virtual service
MessageContext	Object (org.apache.axis2.context.MessageContext). (Required). Mediator will place a MessageContext variable into the pipeline before executing the webMethods IS service call. The default value is: org.apache.axis2.context.MessageContext instance
actor	String (String). (Optional). Indicates the value of the SOAP actor attribute if a new security header is being added to the SOAP request. If the request already has a security header with the actor specified in it, then this value will not overwrite it. The default value is: ""
mustUnderstand	Boolean (Boolean). (Optional). Specifies whether the security header will have the mustUnderstand attribute set to 0 or 1 (false / true). If the security header already has this attribute set, this value will not overwrite it. The default value is: false

Example of using AddWSAddressingHeaders

The sample service shown below is configured by providing the MessageContext parameter.

Contact Support | Community | Feedback