Version 9.6	SEARCH   CONTENTS   |   PDF BOOKS   |   HOME   UP   PREV   NEXT

The CentraSite Control user interface enables you to configure the following processing steps for a SOAP-based virtual service:

• The Entry Protocol Step (SOAP)

• The Request Processing Step (SOAP)

• The Response Processing Step (SOAP)

• The Routing Protocols Step (SOAP)

The Entry Protocol Step (SOAP)

The Entry Protocol step specifies the protocol (HTTP, HTTPS or JMS) and SOAP format (1.1 or 1.2) of the requests that the virtual service will accept.

This step allows you to bridge protocols between the consuming application and the native service. For example, suppose you have a native service that is exposed over JMS and a consuming application that submits SOAP requests over HTTP. In this situation, you can configure the virtual service’s Entry Protocol step to accept HTTP requests and configure its Routing Protocols step to route the request to the Web service using JMS.

Besides using the Entry Protocol step to resolve protocol differences between the consumer and the native service, you might use this step to intentionally expose a virtual service over a particular protocol. For example, if you have a native service that is exposed over HTTP, you might expose the virtual service over JMS simply to gain the asynchronous-messaging and guaranteed-delivery benefits that one gains by using JMS as the message transport.

Use the following procedure to configure the Entry Protocol step of a virtual service.

To configure the Entry Protocol step

1. In CentraSite Control, display the virtual service's detail page. For procedures, see the section Using the Asset Catalog.

2. Open the Processing Steps profile.

3. Select the Entry Protocol tab and specify the protocol (HTTP, HTTPS or JMS) for the virtual service to accept requests.

   Note:
   CentraSite supports HTTP version 1.1 only.

   In this field...	Specify...
   Protocol	The protocol (HTTP, HTTPS or JMS) over which the virtual service will accept requests. Note that you can select both HTTP and HTTPS if needed. Important: Before you deploy a service over HTTPS, ensure that the Integration Server on which the Mediator is running has been configured for SSL. In addition, make sure you specify an HTTPS port in the Mediator’s Ports Configuration page. (In the Integration Server Administrator, go to Solutions > Mediator > Administration > General and specify the port in the HTTPS Ports Configuration field.) For details on the Port Configuration page, see the section Configuring Mediator in the document Administering webMethods Mediator.)
   JMS Provider Alias	If you selected JMS, specify the Integration Server's JMS Trigger name. The alias should include the JNDI destination name and the JMS connection factory.
   Format	The SOAP format (SOAP 1.1 or SOAP 1.2) of the requests that the virtual service will accept.

The Request Processing Step (SOAP)

The Request Processing step specifies how the SOAP request message is to be transformed or pre-processed before it is submitted to the native service.

As long as a consumer sends a SOAP request to the correct virtual service endpoint, and the request includes a soapAction header, then Mediator can detect the correct service and operation; in this case, no message transformation is required. However, in some cases a virtual service might need to transform SOAP messages.

For example, you might need to accommodate differences between the message content that a consuming application is capable of submitting and the message content that a native service expects. For example, if the consuming application submits an order record using a slightly different structure than the structure expected by the native service, you can use the Request Processing step to transform the record submitted by the consuming application to the structure required by the Web service.

Specifically, you would need to configure the virtual service to:

• Transform or pre-process the request messages into the format required by the native service, before Mediator sends the requests to the native services. Additionally in this case, the transformation is required if the virtual service has a schema validation policy, which validates the requests.

• Transform or pre-process the native service’s response messages into the format required by the consumer applications, before Mediator returns the responses to the consumer applications.

There are two ways to transform or pre-process a message:

• By passing the message to an XSLT transformation file.

• By passing the message to a webMethods Integration Server service.

Use the following procedure to configure the Request Processing step of a virtual service.

To configure the Request Processing step

1. In CentraSite Control, display the virtual service's detail page. For procedures, see the section Using the Asset Catalog.

2. Open the Processing Steps profile.

3. Select the Request Processing tab. On this tab you can specify one or more Transform steps and one or more webMethods IS Service steps as follows.

   1. Click Add Step, select one of the following kinds of request processing steps and click OK.

      Request Processing Step	Description
      Transform	Configure this step if you want to perform an XSLT message transformation on the request message before it is submitted to the native service. Important: The XSL file uploaded by the user should not contain the XML declaration in it (e.g., xml version="1.0" encoding="UTF-8"). This is because when the virtual service is deployed to Mediator, Mediator embeds the XSL file in the virtual service definition (VSD), and since the VSD itself is in XML format, there cannot be an XML declaration line in the middle of it. This can lead to unexpected deployment issues which can be avoided by making sure the XSL file does not contain the declaration line.
      webMethods IS Service	Configure this step if you want to invoke a webMethods IS service to preprocess the request before it is submitted to the native service. For more information, see Invoking webMethods IS Services in Virtual Services.

   2. In the Step list, click the step (Transform or webMethods IS Service) and complete the appropriate dialog box as follows.

      For this step...	Do the following...
      Transform	Click Browse, select the XSLT transformation file from your file system and click OK. Note: If you make changes to the XSLT file in the future, you must re-deploy the virtual service.
      webMethods IS Service	Type the fully qualified service name or, to display a list of webMethods IS services that are published to CentraSite, type a keyword phrase in the Service field. The wildcard character * is supported. For example, to return all IS services that start with Test, type Test*. (The list that appears also identifies the application server instance on which each service is located.) Then select one or more services to be used to manipulate the request (the axis2 MessageContext instance) and click OK. Mediator will pass to the invoked IS service the request message context (the axis2 MessageContext instance), which contains the request-specific information. Thus, you can use the public IS services that accept MessageContext as input to manipulate the response contents. For more information, see Invoking webMethods IS Services in Virtual Services. Note: The webMethods IS service must be running on the same Integration Server as Mediator.

   3. Configure additional request processing steps if desired, and click Save.

      Note:
      Specify the steps in the order in which they should be invoked. Use the arrow buttons to rearrange the sequence of steps. To delete a step, select the check box next to the step and click Delete.

The Response Processing Step (SOAP)

The Response Processing step is similar to the Request Processing step. This step specifies how the response message from the native service provider is to be transformed or processed before it is returned to the consuming application.

Note:
You may configure and test a virtual service without specifying response processing. You can go back later and specify response processing, if desired.

All steps are optional. You can configure the following steps:

• Error Messaging: Configure this step to return a custom error message (and/or the native provider’s service fault content) to the consuming application when the native provider returns a service fault. In addition, you can invoke one or more webMethods IS services to process the error message before and/or after the custom error message is added to the response.

• Transformation: Configure this step to perform message transformations using a specified XSLT file.

• webMethods IS Service: Invoke a user-defined webMethods IS service that processes the response message.

Use the following procedure to configure the Response Processing step of a virtual service.

To configure the Response Processing step

1. In CentraSite Control, display the virtual service's detail page. For procedures, see the section Using the Asset Catalog.

2. Open the Processing Steps profile.

3. Select the Response Processing tab.

1. Click Add Step, select the first step you want configure and click OK.

   You can select only one step at a time, but you can go back and select one or more Transform steps, one or more webMethods IS Service steps, but only one Error Messaging step.

   Step	Description
   Error Messaging	You use this step to configure error responses for this particular virtual service. Alternatively, you can configure global error responses for all virtual services, using Mediator's Service Fault Configuration page, as described in the document Administering webMethods Mediator. The precedence of the Error Messaging instructions is as follows: If you configure an Error Messaging step for a virtual service, the error messaging step takes precedence over any settings on the global Service Fault Configuration page. If you do not create an Error Messaging step for a virtual service, the settings on the Service Fault Configuration page take precedence.
   Transform	Configure this step if you want to invoke an XSLT transformation file to transform the SOAP response payloads from XML format to the format required by the consumer.
   webMethods IS Service	Configure this step if you want to invoke a webMethods IS service to process the response message from the native service before it is returned to the consuming application. For more information, see Invoking webMethods IS Services in Virtual Services.

2. If you selected Error Messaging above, click Error Messaging in the Step list and configure it as follows.

   You use this step to configure error responses for this particular virtual service. Select one or both of the following options:

   Send Native Provider Fault: When you select this option, Mediator returns the native service provider's fault content (if available) to the consuming application. Mediator will send whatever content it received from the native service provider. If you select this option, the Response option is ignored when a fault is returned by the native service provider. (Faults returned by internal Mediator exceptions will still be handled by the Response option.)

   Response: When you select this option, Mediator returns the following fault response to the consuming application:

   Mediator encountered an error:$ERROR_MESSAGE while executing operation:$OPERATION service:$SERVICE at time:$TIME on date:$DATE. The client ip was:$CLIENT_IP. The current user:$USER. The consumer application:$CONSUMER_APPLICATION".

   This fault response is returned in both of the following cases:

   • When a fault is returned by the native service provider.

     In this case, the $ERROR_MESSAGE variable in the fault response will contain the message produced by the provider's exception that caused the error. This is equivalent to the getMessage call on the Java Exception. This maps to the faultString element for SOAP 1.1 or the Reason element for SOAP 1.2 catch. Mediator discards the native service provider's fault and does not return this content to the web service caller since it could be considered a security issue, especially if the native provider is returning a stack trace with its response.

   • When a fault is returned by internal Mediator exceptions (such as policy violation errors, timeouts, etc.).

     In this case, $ERROR_MESSAGE will contain the error message generated by Mediator.

   The default fault response contains predefined fault handler variables ($ERROR_MESSAGE, $OPERATION, etc.) which are described in the table below.

   You can customize the default fault response using the following substitution variables, where Mediator replaces the variable reference with the real content at run time:

   • The predefined context variables listed in The Predefined Context Variables.

   • Custom context variables that you declare using Mediator's API (see The API for Context Variables).

     Note:
     If you want to reference a custom context variable that you have already defined in a context-based routing rule (as opposed to one you have declared using Mediator's API), then you must add the prefix $mx to the variable name in order to reference the variable. For example, if you defined the variable TAXID, you would reference it as $mx:TAXID.

   The fault handler variables are described below.

   Note:
   If no value is defined for a fault handler variable, then the returned value will be the literal string "null". For example, $CONSUMER_APPLICATION will always be "null" if the service's policy does not contain the Identify Consumer action.

   Fault Handler Variable	Description
   $ERROR_MESSAGE	The error message produced by the exception that is causing the error. This is equivalent to the getMessage call on the Java Exception. This maps to the faultString element for SOAP 1.1 or the Reason element for SOAP 1.2 catch.
   $OPERATION	The operation that was invoked when this error occurred.
   $SERVICE	The service that was invoked when this error occurred.
   $TIME	The date (as determined on the Container side) at which the error occurred.
   $DATE	The date (as determined on the Container side) at which the error occurred.
   $CLIENT_IP	The IP address of the client invoking the service. This might be available for only certain invoking protocols, such as HTTP(S).
   $USER	The currently authenticated user. The user will be present only if the Transport/SOAP Message have user credentials.
   $CONSUMER_APPLICATION	The currently identified consumer application.

   Pre-Processing: Optional. Configure this step if you want to invoke one or more webMethods IS services to manipulate the response message before the Error Messaging step is invoked. The IS service will have access to the response message context (the axis2 MessageContext instance) before it is updated with the custom error message. For example, you might want to send emails or perform custom alerts based on the response payload. For more information, see Invoking webMethods IS Services in Virtual Services.

   Post-Processing: Optional. Configure this step if you want to invoke one or more webMethods IS services to manipulate the service fault after the Error Messaging step is invoked. The IS service will have access to the entire service fault and the custom error message. You can make further changes to the fault message structure, if needed. For more information, see Invoking webMethods IS Services in Virtual Services.

3. If you selected Transform above, click Transform in the Step list, click Browse and select the XSLT transformation file from your file system, then click OK. If you make changes to the XSLT file in the future, you must re-deploy the virtual service.

4. If you selected webMethods IS Service above, click webMethods IS Service in the Step list and configure it as follows.

   Type the fully qualified service name or, to display a list of webMethods IS services that are published to CentraSite, type a keyword phrase in the Service field. The wildcard character * is supported. For example, to return all IS services that start with Test, type Test*. (The list that appears also identifies the application server instance on which each service is located.) Then select one or more services to be used to manipulate the response (the axis2 MessageContext instance) and click OK.

   Mediator will pass to the invoked IS service the response message context (the axis2 MessageContext instance), which contains the response-specific information. Thus, you can use the public IS services that accept MessageContext as input to manipulate the response contents. For more information, see Invoking webMethods IS Services in Virtual Services.

   Note:
   The webMethods IS service must be running on the same Integration Server as Mediator.

5. Configure additional response processing steps if desired, and click Save.

   Note:
   Arrange the steps in the order in which they should be invoked. Use the arrow buttons to rearrange the sequence of steps. To delete a step, select the check box next to the step and click Delete.

The Routing Protocols Step (SOAP)

You can choose to configure one of the following routing protocols for a SOAP-based virtual service:

• "Straight Through" Routing (SOAP)

• "Content-based" Routing (SOAP)

• "Context-based" Routing (SOAP)

• "Load Balancing" Routing (SOAP)

• The Routing Protocol For Services Exposed over JMS (SOAP)

"Straight Through" Routing (SOAP)

If your Entry Protocol is HTTP or HTTPS, you can choose to use the "Straight Through" routing protocol. (Alternatively, you can choose "Content-based", "Context-based" or "Load Balancing" routing.)

When you select the "Straight Through" routing protocol, the virtual service will route the requests directly to the native service endpoint you specify. You may specify how to authenticate requests (as with all routing protocols).

Alternatively, you can choose the "Content-Based", "Context-Based" or "Load Balancing" routing protocol.

To configure "Straight Through" routing

1. In CentraSite Control, display the virtual service's detail page. For procedures, see the section Using the Asset Catalog.

2. Open the Processing Steps profile.

3. Select the Routing Protocols tab, specify the following fields, and click Save.

   Field	Description
   HTTP or JMS	Select HTTP.
   Routing Type	Select Straight Through
   Default To	Click the Endpoint button and select the URL of the native service to route the request to. Alternatively, Mediator offers "Local Optimization" capability if the native service and the virtual service (in Mediator) are located on the same machine. With local optimization, service invocation happens in-memory and not through a network hop. In the Default To field, specify the native service in either of the following forms: local://<service_full_path> OR local://<server>:<port>/ws/<service_full_path> For example: local://MediatorTestServices:NewMediatorTestServices_Port which points to the endpoint service NewMediatorTestServices_Port which is present under the folder MediatorTestServices in Integration Server. This works for HTTP endpoints only, for all types of Routing Protocols.
   Configure Endpoint Properties icon	This icon displays a dialog box that enables you to configure a set of properties for the endpoint as follows: SOAP Optimization Method: Optional. Mediator can accept the following optimization methods to optimize the payloads of SOAP requests: MTOM: Indicates that Mediator expects to receive a request with a Message Transmission Optimization Mechanism (MTOM) attachment, and will forward the attachment to the native service. SwA: Indicates that Mediator expects to receive a "SOAP with Attachment" (SwA) request, and will forward the attachment to the native service. None (the default). Notes: Bridging between SwA and MTOM is not supported. If a consumer sends an SwA request, Mediator can only forward SwA to the native provider. The same is true for MTOM, and applies to responses received from the native provider. That is, an SwA or MTOM response received by Mediator from a native provider will be forwarded to the caller using the same format it received. When sending SOAP requests that do not contain a MTOM or SWA attachment to a virtual service for a native provider endpoint that returns an MTOM or SWA response, the request 'Accept' header must be set to 'multipart/related' (or the virtual service's Request Processing Step should include an IS service callout that sets the BUILDER_TYPE context variable to 'multipart/related'). This is necessary so Mediator knows how to parse the response properly. WSS Header Customization: Indicates whether Mediator should pass the WS-Security headers of the incoming requests to the native service. Pass all security headers: Passes the security header, even if it is processed by Mediator (i.e., even if Mediator processes the header according to the virtual service's security run-time policy). Note: If the virtual service does not contain a security run-time policy, and the mustUnderstand attribute of the security header is 0/false, then Mediator will always forward the security header to the native service. Remove processed security header from request before routing: Removes the security header if it is processed by Mediator (i.e., if Mediator processes the header according to the virtual service's security run-time policy). Note that Mediator will not remove the security header if both of the following conditions are true: 1) Mediator did not process the security header, and 2) the mustUnderstand attribute of the security header is 0/false). HTTP Connection Timeout: The time interval (in seconds) after which a connection attempt will timeout. If a value is not specified (or if the value 0 is specified), Mediator will use the value of the global property pg.endpoint.connectionTimeout located in the file Integration Server_directory\instances\instance_name\packages\WmMediator\config\resources\pg-config.properties . The default of that property is 30 seconds. Read Timeout: The time interval (in seconds) after which a socket read attempt will timeout. If a value is not specified (or if the value 0 is specified), Mediator will use the value of the global property pg.endpoint.readTimeout located in the file Integration Server_directory\instances\instance_name\packages\WmMediator\config\resources\pg-config.properties . The default of that property is 30 seconds. SSL Options: To enable SSL client authentication for the endpoint, you must specify values for both the Client Certificate Alias field and the IS Keystore Alias field. If you specify a value for only one of these fields, a deployment error will occur. Note: SSL client authentication is optional; you may leave both fields blank. Client Certificate Alias: The client's private key to be used for performing SSL client authentication. If you specify a client certificate alias, you must also include in the virtual service's policy the "Require SSL" action and select that action's "Client Certificate Required" option. The "Client Certificate Required" option specifies whether client certificates are required for the purposes of: 1) Verifying the signature of signed SOAP requests or decrypting encrypted SOAP requests, and 2) Signing SOAP responses or encrypting SOAP responses. IS Keystore Alias: The keystore alias of the instance of Integration Server on which Mediator is running. This value (along with the value of Client Certificate Alias) will be used for performing SSL client authentication.
   HTTP Authentication	Authentication Scheme: Specify the mode of authentication: Basic Authentication (default), NTLM (Windows only), OAuth2 or None. Basic Authentication. Select one of the following options: Use credentials from incoming request: (default): Authenticates requests based on the credentials specified in the HTTP header. Mediator passes the “Authorization” header present in the original client request to the native service. Use specified credentials: Authenticates requests according to the values you specify in the User, Password and Domain fields. NTLM (Currently Windows only). Note that if Mediator is used to access a native service protected by NTLM (which is typically hosted in IIS), then the native service in IIS should be configured to use NTLM as the authentication scheme. If the authentication scheme is configured as "Windows", then "NTLM" should be in its list. The "Negotiate" handshake will be supported in the near future. This note applies to all three of the following options for NTLM: Use credentials from incoming request: Default. Mediator uses the user credentials passed in the request header for an NTLM handshake with the server. Use specified credentials: Mediator uses the values you specify in the User, Password and Domain fields for an NTLM handshake with the server. Transparent: If the property watt.pg.disableNtlmAuthHandler is set to false (the default), then Mediator will behave in "pass by" mode, allowing an NTLM handshake to occur between the client and server. If the property watt.pg.disableNtlmAuthHandler is set to true, then Mediator performs the Kerberos Windows authentication (and not NTLM Windows authentication). This property is located in Integration Server_directory\instances\instance_name\config\server.cnf. Note: If the client is a WCF application, then the client should be configured with clientCredentialType set to NTLM. OAuth2. Select one of the following options: Use credentials from incoming request: Default. This is known as "pass through" mode, in which the consumer includes an OAuth2 access token (a "Bearer" type token) in the request. Mediator then passes the access token unchanged to the native OAuth server. Use specified token: In this mode, the consumer does not include an OAuth2 access token in the request. Instead, the provider generates an OAuth2 access token for each consumer, and Mediator stores the access tokens in Passman. When consumers send requests, Mediator obtains the OAuth2 access tokens from Passman and uses them to access the native services. Specify an OAuth access token to be deployed by Mediator by clicking the Show Token button and selecting an OAuth access token. Users who do not have the permissions to create and manage virtual services will not see this button. For more information, see Who Can Create and Manage Virtualized Services?. Notes: You must set the Integration Server property watt.server.auth.skipForMediator to "true" and then restart Integration Server for the change to take effect. This property is located in the server configuration file (server.cnf), which is located in the Integration Server_directory\instances\instance_name\config directory. For details, see the webMethods Integration Server Administrator's Guide. The run-time actions "Require HTTP Basic Authentication" and "Identify Consumer" (with the value HTTP Authentication Token as the identifier) will not be enforced when using the authentication scheme OAuth2. None. Select the following option: Invoke Service Anonymously: Does not authenticate requests.
   HTTP Headers	The HTTP headers that you want to use to authenticate the requests. Use Existing: Use the HTTP headers that are contained in the requests. Customize: Use the HTTP headers that you specify in the Name and Value columns below. If you need to specify multiple headers, use the plus button to add rows.

"Content-based" Routing (SOAP)

If your Entry Protocol is HTTP or HTTPS, you can choose to use the "Content-based" routing protocol. (Alternatively, you can choose "Straight Through", "Context-based" or "Load Balancing" routing.)

If you have a native service that is hosted at two or more endpoints, you can use the "Content-Based" routing protocol to route specific types of messages to specific endpoints.

You can route messages to different endpoints based on specific values that appear in the request message. You might use this capability, for example, to determine which operation the consuming application has requested, and route requests for complex operations to an endpoint on a fast machine.

The requests are routed according to the content-based routing rules you create. That is, they are routed based on the successful evaluation of one or more XPath expressions that are constructed utilizing the content of the request payload. For example, a routing rule might allow requests for half of the methods of a particular service to be routed to Service A, and the remaining methods to be routed to Service B.

You may also specify how to authenticate requests (as with all routing protocols).

If a SOAP request contains a WS-Security header, Mediator passes it to the native service.

To configure "Content-Based" routing

1. In CentraSite Control, display the virtual service's detail page. For procedures, see the section Using the Asset Catalog.

2. Open the Processing Steps profile.

3. Select the Routing Protocols tab, specify the following fields and click Save.

"Context-based" Routing (SOAP)

If your Entry Protocol is HTTP or HTTPS, you can choose to use the "Context-based" routing protocol. (Alternatively, you can choose "Straight Through", "Content-based" or "Load Balancing" routing.)

If you have a native service that is hosted at two or more endpoints, you can use the Context-Based protocol to route specific types of messages to specific endpoints.

The requests are routed according to the context-based routing rules you create. A routing rule specifies where requests should be routed, and the criteria by which they should be routed there. For example, requests can be routed according to certain consumers, certain dates/times, or according to requests that exceed/fall below a specified metric (Total Count, Success Count, Fault Count, etc.). You can create one or more rules.

You may also specify how to authenticate requests (as with all routing protocols).

If a SOAP request contains a WS-Security header, Mediator passes it to the native service.

To configure "Context-Based" Routing

1. In CentraSite Control, display the virtual service's detail page. For procedures, see the section Using the Asset Catalog.

2. Open the Processing Steps profile.

3. Select the Routing Protocols tab, specify the following fields, and click Save.

   Field	Description
   HTTP or JMS	Select HTTP.
   Routing Type	Select Context Based.
   Routing Rules	To create a routing rule, click the Add Rule button and complete the Add Routing Rule dialog box as follows. In the Variable column, select Time, IP Address, Date, Consumer, Predefined Context Variable or Custom Context Variable. For more information, see Using Context Variables in Virtual Services. In the Value column, specify an applicable value. For Date choose Before, After or Equal To and enter a date. For Time choose Before or After and enter a time. For IP Address, enter numeric values for Between and And. For Consumer, click Browse and select a consumer application name. For Predefined Context Variable or Custom Context Variable, choose the String or Integer data type. Select a predefined variable name or custom variable name from the drop-down list. For String, choose Equal To or Not Equal To and enter a value. For Integer, choose Greater Than, Less Than, Not Equal To, Equal To or and enter a value. Notes: For the list of the predefined context variables, see Using Context Variables in Virtual Services. The predefined context variable PROTOCOL_HEADER is not available in the drop-down list; to include PROTOCOL_HEADER in the rule, define the variable as Custom Context Variable. For more information, see The API for Context Variables. If you define a custom context variable in the routing rule, you must write a webMethods IS service and invoke it in the virtual service's Request Processing step. In this Integration Server service, use the API to get/set the custom context variable. For more information, see The API for Context Variables. If you need to specify multiple variables, use the plus button to add rows. In the Combination Uses field, choose an operator for the expression: AND (the default) or OR. In the Route To field, click the Endpoint button and choose the URL of the native service to route the request to, if the rule criteria are met. Click the Configure Endpoint Properties icon (next to the Endpoint button) if you want to configure a set of properties for each endpoint individually. In the dialog box, click the endpoint you want to configure and specify the following fields: SOAP Optimization Method: Optional. Mediator can accept the following optimization methods to optimize the payloads of SOAP requests: MTOM: Indicates that Mediator expects to receive a request with a Message Transmission Optimization Mechanism (MTOM) attachment, and will forward the attachment to the native service. SwA: Indicates that Mediator expects to receive a "SOAP with Attachment" (SwA) request, and will forward the attachment to the native service. None (the default). Notes: Bridging between SwA and MTOM is not supported. If a consumer sends an SwA request, Mediator can only forward SwA to the native provider. The same is true for MTOM, and applies to responses received from the native provider. That is, an SwA or MTOM response received by Mediator from a native provider will be forwarded to the caller using the same format it received. When sending SOAP requests that do not contain a MTOM or SWA attachment to a virtual service for a native provider endpoint that returns an MTOM or SWA response, the request 'Accept' header must be set to 'multipart/related' (or the virtual service's Request Processing Step should include an IS service callout that sets the BUILDER_TYPE context variable to 'multipart/related'). This is necessary so Mediator knows how to parse the response properly. WSS Header Customization: Indicates whether Mediator should pass the WS-Security headers of the incoming requests to the native service. Pass all security headers: Passes the security header, even if it is processed by Mediator (i.e., even if Mediator processes the header according to the virtual service's security run-time policy). Note: If the virtual service does not contain a security run-time policy, and the mustUnderstand attribute of the security header is 0/false, then Mediator will always forward the security header to the native service. Remove processed security header from request before routing: Removes the security header if it is processed by Mediator (i.e., if Mediator processes the header according to the virtual service's security run-time policy). Note that Mediator will not remove the security header if both of the following conditions are true: 1) Mediator did not process the security header, and 2) the mustUnderstand attribute of the security header is 0/false). HTTP Connection Timeout: The time interval (in seconds) after which a connection attempt will timeout. If a value is not specified (or if the value 0 is specified), Mediator will use the value of the global property pg.endpoint.connectionTimeout located in the file Integration Server_directory\instances\instance_name\packages\WmMediator\config\resources\pg-config.properties . The default of that property is 30 seconds. Read Timeout: The time interval (in seconds) after which a socket read attempt will timeout. If a value is not specified (or if the value 0 is specified), Mediator will use the value of the global property pg.endpoint.readTimeout located in the file Integration Server_directory\instances\instance_name\packages\WmMediator\config\resources\pg-config.properties . The default of that property is 30 seconds. SSL Options: To enable SSL client authentication for the endpoint, you must specify values for both the Client Certificate Alias field and the IS Keystore Alias field. If you specify a value for only one of these fields, a deployment error will occur. Note: SSL client authentication is optional; you may leave both fields blank. Client Certificate Alias: The client's private key to be used for performing SSL client authentication. If you specify a client certificate alias, you must also include in the virtual service's policy the "Require SSL" action and select that action's "Client Certificate Required" option. The "Client Certificate Required" option specifies whether client certificates are required for the purposes of: 1) Verifying the signature of signed SOAP requests or decrypting encrypted SOAP requests, and 2) Signing SOAP responses or encrypting SOAP responses. IS Keystore Alias: The keystore alias of the instance of Integration Server on which Mediator is running. This value (along with the value of Client Certificate Alias) will be used for performing SSL client authentication. Click OK.
   Route To	A native service endpoint to route the request to in case all routing rules evaluate to False. Click the Endpoint button and select the URL of the native service to route the request to. To specify additional services, use the plus button next to the field to add rows. Alternatively, Mediator offers "Local Optimization" capability if the native service and the virtual service (in Mediator) are located on the same machine. With local optimization, service invocation happens in-memory and not through a network hop. In the Default To field, specify the native service in either of the following forms: local://<service_full_path> OR local://<server>:<port>/ws/<service_full_path> For example: local://MediatorTestServices:NewMediatorTestServices_Port which points to the endpoint service NewMediatorTestServices_Port which is present under the folder MediatorTestServices in Integration Server. This works for HTTP endpoints only, for all types of Routing Protocols.
   HTTP Authentication	Authentication Scheme: Specify the mode of authentication: Basic Authentication (default), NTLM (Windows only), OAuth2 or None. Basic Authentication. Select one of the following options: Use credentials from incoming request: (default): Authenticates requests based on the credentials specified in the HTTP header. Mediator passes the “Authorization” header present in the original client request to the native service. Use specified credentials: Authenticates requests according to the values you specify in the User, Password and Domain fields. NTLM (Currently Windows only). Note that if Mediator is used to access a native service protected by NTLM (which is typically hosted in IIS), then the native service in IIS should be configured to use NTLM as the authentication scheme. If the authentication scheme is configured as "Windows", then "NTLM" should be in its list. The "Negotiate" handshake will be supported in the near future. This note applies to all three of the following options for NTLM: Use credentials from incoming request: Default. Mediator uses the user credentials passed in the request header for an NTLM handshake with the server. Use specified credentials: Mediator uses the values you specify in the User, Password and Domain fields for an NTLM handshake with the server. Transparent: If the property watt.pg.disableNtlmAuthHandler is set to false (the default), then Mediator will behave in "pass by" mode, allowing an NTLM handshake to occur between the client and server. If the property watt.pg.disableNtlmAuthHandler is set to true, then Mediator performs the Kerberos Windows authentication (and not NTLM Windows authentication). This property is located in Integration Server_directory\instances\instance_name\config\server.cnf. Note: If the client is a WCF application, then the client should be configured with clientCredentialType set to NTLM. OAuth2. Select one of the following options: Use credentials from incoming request: Default. This is known as "pass through" mode, in which the consumer includes an OAuth2 access token (a "Bearer" type token) in the request. Mediator then passes the access token unchanged to the native OAuth server. Use specified token: In this mode, the consumer does not include an OAuth2 access token in the request. Instead, the provider generates an OAuth2 access token for each consumer, and Mediator stores the access tokens in Passman. When consumers send requests, Mediator obtains the OAuth2 access tokens from Passman and uses them to access the native services. Specify an OAuth access token to be deployed by Mediator by clicking the Show Token button and selecting an OAuth access token. Users who do not have the permissions to create and manage virtual services will not see this button. For more information, see Who Can Create and Manage Virtualized Services?. Notes: You must set the Integration Server property watt.server.auth.skipForMediator to "true" and then restart Integration Server for the change to take effect. This property is located in the server configuration file (server.cnf), which is located in the Integration Server_directory\instances\instance_name\config directory. For details, see the webMethods Integration Server Administrator's Guide. The run-time actions "Require HTTP Basic Authentication" and "Identify Consumer" (with the value HTTP Authentication Token as the identifier) will not be enforced when using the authentication scheme OAuth2. None. Select the following option: Invoke Service Anonymously: Does not authenticate requests.
   HTTP Headers	The HTTP headers that you want to use to authenticate the requests. Use Existing: Use the HTTP headers that are contained in the requests. Customize: Use the HTTP headers that you specify in the Name and Value columns below. If you need to specify multiple headers, use the plus button to add rows.

"Load Balancing" Routing (SOAP)

If your Entry Protocol is HTTP or HTTPS, you can choose to use the "Load Balancing" routing protocol. (Alternatively, you can choose "Straight Through", "Content-Based" or "Context-Based" routing.)

If you have a Web service that is hosted at two or more endpoints, you can use the Load Balancing option to distribute requests among the endpoints.

Requests are distributed across multiple endpoints. The requests are intelligently routed based on the "round-robin" execution strategy. The load for a service is balanced by directing requests to two or more services in a pool, until the optimum level is achieved. The application routes requests to services in the pool sequentially, starting from the first to the last service without considering the individual performance of the services. After the requests have been forwarded to all the services in the pool, the first service is chosen for the next loop of forwarding.

Load-balanced endpoints also have automatic Failover capability. If a load-balanced endpoint is unavailable (for example, if a connection is refused), then that endpoint is marked as "down" for the number of seconds you specify in the "Suspend the Failed Endpoint" field (during which the endpoint will not be used for sending the request), and the next configured endpoint is tried. If all the configured load-balanced endpoints are down, then a SOAP fault is sent back to the client. After the suspension period expires, each endpoint marked will be available again to send the request.

To configure "Load Balancing" routing

1. In CentraSite Control, display the virtual service's detail page. For procedures, see the section Using the Asset Catalog.

2. Open the Processing Steps profile.

3. Select the Routing Protocols tab, specify the following fields, and click Save.

The Routing Protocol For Services Exposed over JMS (SOAP)

You can use the Routing Protocols step to specify a JMS queue to which the Mediator is to submit the request, and the destination to which the native service is to return the response.

To configure the Routing Protocols step for virtual services exposed over JMS

1. In CentraSite Control, display the virtual service's detail page. For procedures, see the section Using the Asset Catalog.

2. Open the Processing Steps profile.

3. Select the Routing Protocols tab and select the JMS button. On this tab specify the following JMS routing protocol fields, and click Save.

   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 this field...	Specify...
   JMS URI	A connection alias for connecting to the JMS provider (e.g., an Integration Server alias or a JNDI URL). For example, a JNDI URL of the form: jms:queue:dynamicQueues/MyRequestQueue? wm-wsendpointalias=MediatorConsumer &targetService=vs-jms-in-echo Note that the wm-wsendpointalias parameter is required for Integration Server/Mediator to look up the JMS consumer alias to send the request to the specified queue (e.g., MyRequestQueue), which is a dynamic queue in ActiveMQ. Also, the targetService parameter is required if sending to another virtual service that uses JMS as the entry protocol.
   Priority	Optional. A numeric value that specifies the priority of the JMS message in the queue.
   Reply to Destination	Optional. A queue name for the incoming JMS request.
   Time to Live	Optional. A numeric value (in milliseconds) that specifies the lifespan of the JMS message.
   Delivery Mode	Optional. The type of message delivery to the endpoint. None (default). Persistent: The message is stored by the JMS server before delivering it to the consumer. Non-Persistent: The message is not stored before delivery.
   Message Properties	The message properties to use. Use Existing (default): Use existing properties. Customize: Specify one or more property names and values. To add additional rows, use the plus button.
   JMS Headers	The JMS headers that you want to use to authenticate the requests. Use Existing (default): Use existing headers. Customize: Specify one or more header names and values. To add additional rows, use the plus button.

www.softwareag.com

Copyright © 2005-2014 Software AG, Darmstadt, Germany.

SEARCH   CONTENTS   |   PDF BOOKS   |   HOME   UP   PREV   NEXT