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 REST or XML virtual service:

• The Entry Protocol Step (REST or XML)

• The Request Processing Step (REST or XML)

• The Response Processing Step (REST or XML)

• The Routing Protocols Step (REST or XML)

The Entry Protocol Step (REST or XML)

The Entry Protocol step specifies:

• The protocol (HTTP or HTTPS) over which the REST or XML virtual service should accept requests.

• The HTTP methods (GET, POST, PUT, DELETE) that the virtual service should be allowed to perform on a REST resource.

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 HTTPS and a consuming application that submits SOAP requests over HTTP. In this situation, you can configure the virtual service's Entry Step to accept HTTP requests and configure its Routing Rule step to route the request to the Web service using HTTPS.

Important:
It is important that the client's requests contain an HTTP Content-Type header. At run time, Mediator determines which message builder to use based on the message’s HTTP method and its Content-Type. If a client does not specify the accept Content-Type in the request, by default Mediator sets the accept Content-Type to application/xml. For a list of valid HTTP method/Content-Type combinations, see The Request Message’s HTTP Methods and Content-Types for REST and XML Services. For information about the JSON Content-Type, see Working With the JSON Content-Type.

To configure the Entry Protocol step for a REST or XML virtual service

1. In CentraSite Control, display the REST or XML virtual service detail page. For procedures, see the section Using the Asset Catalog.

2. Open the Processing Steps profile.

3. Select the Entry Protocol tab. On this tab specify the following fields and click Save.

   In this field...	Specify...
   Protocol	The protocol (HTTP and/or HTTPS) over which the virtual REST service or virtual XML service accepts requests. You can select both HTTP and HTTPS if needed. Note: CentraSite supports HTTP version 1.1 only. 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.)
   HTTP Methods	The HTTP methods (GET, POST, PUT, DELETE) that the virtual service should be allowed to perform on a REST resource. It is important to specify all the HTTP methods that are supported for the service. For example, if the virtual service is deployed to Mediator and you selected only the GET method in its Entry Protocol step, then Mediator will only permit GET invocations. In this case, POST requests will be rejected with a return of statusCode 405 even if the native service happens to support POSTs.

The Request Processing Step (REST or XML)

As long as a consumer sends a REST or XML request with the proper Content-Type (see The Request Message’s HTTP Methods and Content-Types for REST and XML Services), and as long as the HTTP method and endpoint URI are in the expected form, then Mediator can determine the correct service and operation; in this case, no message transformation is required. However, in some cases a virtual REST service or virtual XML service might need to transform XML 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 service.

Specifically, you would need to configure the virtual REST service or virtual XML 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 REST service or virtual XML 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 IS service.

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

To configure the Request Processing step

1. In CentraSite Control, display the virtual REST service or virtual XML service 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 REST service or virtual XML 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:
      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 Response Processing Step (REST or XML)

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 REST or XML 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.

• Transform: 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 REST or XML service.

To configure the Response Processing step

1. In CentraSite Control, display the virtual REST or XML service 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 to 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 screen, 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 response payloads from XML format to the format required by the consumer.
   webMethods IS Service	Configure this step if you want to invoke one or more webMethods IS services 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. For REST service calls, the message is returned inside an </Exception> tag. 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. For REST service calls, the message is returned inside an </Exception> tag.
   $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.

   Note:
   Unlike with SOAP specifications, there is no agreed upon format to suggest an error condition for XML and REST services (there is no element nested in a </soap:Fault> element nested in a </soap:Body>). Mediator assumes that XML and REST services will follow HTTP conventions and return responses with return codes in the 200-299 range when service calls are successful. This is the only way Mediator can determine that a native provider's response should be interpreted as a failure.

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:
   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 Routing Protocols Step (REST or XML)

You can choose to configure one of the following routing protocols for a REST or XML virtual service:

• The "Straight Through" Routing Protocol Step (REST or XML)

• The "Content-based" Routing Protocol Step (REST or XML)

• The "Context-based" Routing Protocol Step (REST or XML)

• The "Load Balancing" Routing Protocol Step (REST or XML)

The "Straight Through" Routing Protocol Step (REST or XML)

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 REST service or virtual XML service will route the requests directly to the native service endpoint you specify. You may specify how to authenticate requests.

To configure "Straight Through" routing

1. In CentraSite Control, display the virtual REST service or virtual XML service detail page. For procedures, see the section Using the Asset Catalog.

2. Open the Processing Steps profile.

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

   Field	Description
   Service Type	Select XML (for a native REST or XML service).
   Routing Type	Specify Straight Through
   HTTP Method	The HTTP method to pass to the native service. Typically you want to pass each request to the native service with the same HTTP method that is contained in the request. For example, if a request contains a GET method, you allow the GET method to be passed to the native service. In this case, select the value Use Context Variable. This variable contains the HTTP method that is contained in the request. However, in other cases you might want to change the HTTP method of a request to a different HTTP method. In this case, you can specify the different method explicitly (by selecting the GET, POST, PUT or DELETE value), or you can specify the different method dynamically on a per-request basis. If you want to specify the method dynamically, select the Use Context Variable option and then write a webMethods IS service to set the value of the context variable. For more information, see Changing the HTTP Method of a REST or XML Request.
   Default To	Click the Endpoint button and select the URL of the native service to route the request to. For example: http://mycontainer/creditCheckService 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: 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	Specify 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.

The "Content-based" Routing Protocol Step (REST or XML)

If your Entry Protocol is HTTP, 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).

To configure "Content-Based" routing

1. In CentraSite Control, display the virtual REST service or virtual XML service detail page. For procedures, see the section Using the Asset Catalog.

2. Open the Processing Steps profile.

3. Select the Routing Protocols tab.

4. Specify values for the remaining fields on the Routing Protocols page as follows:

   Field	Description
   Service Type	Select XML (for a native REST or XML service).
   Routing Type	Select Content Based.
   Routing Rules	You can create one or more routing rules. To create a routing rule, do the following: Click the Endpoint button (next to the Route To column). In the Search for Endpoint dialog that appears, click the Search button to search for the native service endpoint to route the requests to, select a service and click OK. 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: 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. To create an XPath expression for the routing rule, do the following: Click the Edit button (next to the If True column). In the XPath Editor that appears, view the Namespace Map tab, which displays all predefined namespaces (e.g., soapenv, soapenc, etc.). If you want to add custom namespaces, click Add Custom Namespace/prefix, specify a name and value for the namespace and click OK. If you need to add additional rows, use the plus button. In the XPath Editor's All Nodes tab, expand the namespace's node, choose the method you want for the XPath expression, and click OK. In the XPath Editor's XPATH Evaluator tab, evaluate the XPath expression by specifying an argument in the XPath Expression field, and then click Evaluate. After you have evaluated the XPath expression, click OK.
   HTTP Method	The HTTP method to pass to the native service. Typically you want to pass each request to the native service with the same HTTP method that is contained in the request. For example, if a request contains a GET method, you allow the GET method to be passed to the native service. In this case, select the value Use Context Variable. This variable contains the HTTP method that is contained in the request. However, in other cases you might want to change the HTTP method of a request to a different HTTP method. In this case, you can specify the different method explicitly (by selecting the GET, POST, PUT or DELETE value), or you can specify the different method dynamically on a per-request basis. If you want to specify the method dynamically, select the Use Context Variable option and then write a webMethods IS service to set the value of the context variable. For more information, see Changing the HTTP Method of a REST or XML Request.
   Default 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. 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.

The "Context-based" Routing Protocol Step (REST or XML)

If your Entry Protocol is HTTP, 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).

To configure "Context-Based" Routing

1. In CentraSite Control, display the virtual REST service or virtual XML service 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
   Service Type	Select XML (for a native REST or XML service).
   Routing Type	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 Time choose Before or After and enter a time. For IP Address, enter a range of numeric IP addresses in the v4 or v6 format for Between and And. For Date choose Before, After or Equal To and select a date. 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, Equal To or Not Equal To 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 REST service or virtual XML service 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: 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.
   HTTP Method	The HTTP method to pass to the native service. Typically you want to pass each request to the native service with the same HTTP method that is contained in the request. For example, if a request contains a GET method, you allow the GET method to be passed to the native service. In this case, select the value Use Context Variable. This variable contains the HTTP method that is contained in the request. However, in other cases you might want to change the HTTP method of a request to a different HTTP method. In this case, you can specify the different method explicitly (by selecting the GET, POST, PUT or DELETE value), or you can specify the different method dynamically on a per-request basis. If you want to specify the method dynamically, select the Use Context Variable option and then write a webMethods IS service to set the value of the context variable. For more information, see Changing the HTTP Method of a REST or XML Request.
   Default 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. 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.

The "Load Balancing" Routing Protocol Step (REST or XML)

If your Entry Protocol is HTTP, 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 native 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.

Use the following procedure to configure "Load Balancing" routing of a virtual REST service or virtual XML service.

To configure "Load Balancing" routing

1. In CentraSite Control, display the virtual REST service or virtual XML service 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.

www.softwareag.com

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

SEARCH   CONTENTS   |   PDF BOOKS   |   HOME   UP   PREV   NEXT