Configuring ESB Services and Operations
This chapter describes how to configure the services and operations in the ESB production and how to use the services provided by them. This chapter contains the following sections:
Configuring Pass-through Business Services
To add a pass-through business service, Select the + sign for adding a new service in the Production Configuration page, then:
Select the class based on the protocol used and whether SAML security is being used. Choose a class from the following:
Decide if the pass-through service is to be called through the Web port or a special port. For live productions, you should use the Web port in conjunction with a robust web server software so that you have a secure, fully configurable system that can handle heavy loads. The web server installed with InterSystems IRIS® is a limited system intended for use on development systems, but not on fully-loaded live systems. The special port is a light-weight listener that provides minimal configuration and security. Although it is possible to configure a service to accept calls on both ports, we do not recommend this configuration.
If your pass-through service is to be called on the Web port:
Leave the Port field blank.
Select the Enable Standard Requests check box in the Connection Settings field on the Settings tab.
On the Additional Settings section, set the Pool Size to 0. This suppresses the pass-through service from listening on the special port. If you omit this step and leave the Port field blank, InterSystems IRIS displays an error message.
If your pass-through service is to be called from a special port:
Specify a port number.
Clear the Enable Standard Requests check box in the Connection Settings field on the Settings tab.
Set the Target to point to the pass-through operation.
To optimize performance for pass-through services that use the Web port, you can configure the pass-through business service to keep the connection open between calls. You can do this by checking the Keep Standard Request Partition check box.
See Using SAML Validation in Pass-through Services for information on using SAML validation on SOAP and REST pass-through services.
To use the Web port to access the pass-through business service, you also need to define a web application. See “Configuring a Web Application” for details.
Configuring Pass-through Business Operations
To add a pass-through business operation, Select the + sign for adding a new operation in the Production Configuration page, then:
Select the class based on the protocol used and whether you want to suppress storing the messages in the database. See Suppressing Persistent Messages in Pass-through Services and Operations for more information. Choose a class from the following:
EnsLib.HTTP.GenericOperationInProcOpens in a new window—suppresses storing messages.
EnsLib.REST.GenericOperationInProcOpens in a new window—suppresses storing messages.
Configure the pass-through operation HTTP Server, HTTP Port, and URL settings. You can either configure these settings directly or use the external service registry to configure them. To set them via the external service registry, set the value of the External Registry ID property. See “Using the External Service Registry to Configure ESB Hosts” for details on setting External Registry ID. After you apply the External Registry ID setting, InterSystems IRIS reads the current values from the registry and uses them to set the other properties and marks them as read-only.
You can either explicitly set the URL or set it to be derived from the incoming URL sent to the generic service. You can do this either through the service registry or directly through the URL property. To derive it from the incoming URL, set either the URL segment of the external service registry Endpoint field or the URL property as follows:
empty string: Use the URL from the GenericMessage, which is typically the URL passed into the generic service. Typically, you use this if the pass-through service is called from a special port and the URL does not contain the web application name and the service component name.
| (vertical bar): Remove the web application name and configuration name from the URL value in the GenericMessage and use the remainder as the URL. Typically, you use this when the GenericService is called using the standard Web port. The web application name and the configuration name of the business service are needed to route the call to the GenericService but are not needed by the external server.
The URL is compared to web application name and the configuration name with a case-sensitive compare. All alphabetic characters in the web application name must be in lower case and the segment of the URL corresponding to the configuration name must match the case in the configuration name as defined in the production.
^ (caret): Remove the web application name from the URL value in the GenericMessage and use the remainder as the URL. Typically, this is only used if the GenericService is called using the standard Web port and the pass-through operation component has a name that is identical to the first part of the URL expected by the external server. All alphabetic characters in the web application name in the URL must be in lower case.
If the URL property specifies a string that is not empty and does not contain either a vertical bar or caret, then the incoming URL is not used to generate the outgoing URL.
Although the pass-through operations typically do not change the contents of the pass-through message, you can specify that the EnsLib.HTTP.GenericOperationOpens in a new window and EnsLib.REST.GenericOperationOpens in a new window operations perform character set translation. For example, you could have the operation perform character translation so that accented characters are displayed correctly in a web browser. To set the HTTP or REST generic operation to perform character set translation, clear the Read Raw Mode check box in Additional Settings.
Using SAML Validation in Pass-through Services
Pass-through services validates the SAML token but does not check it to see if it provides access to the resources on the external server. The external server must check if the SAML token permits the requested access. The Validation field controls the level of SAML token validation done by the pass-through business service. The following flags specify the kind of validation that is done:
t—Must contain an Authorization header SAML token with key 'access_token='
a—Token must contain an Assertion.
r—Requires Assertions to contain NotBefore/NotOnOrAfter time conditions
v—Verifies Assertion signatures using a Trusted X.509 certificate and, if present, NotBefore/NotOnOrAfter conditions.
o—Validates other signed nodes such as TimeStamp.
By default, validation has a value of 1, which is equivalent to specifying tarvo. If you specify a value of 0, the pass-through service performs no validation.
When checking the NotBefore and NotOnOrAfter time conditions, the default clock skew allowance is 90 seconds. To change the skew allowance, set the global ^Ens.Config("SAML","ClockSkew"). To set the default clock skew for all components to 180 seconds, enter the following command:
To change the skew allowance for a specific component to 180 seconds, enter the following command:
Suppressing Persistent Messages in Pass-through Services and Operations
To obtain maximum efficiency using pass-through services and operations, you can suppress the use of persistent messages. The pass-through service sends the call directly to the pass-through operation without creating a persistent message. The operation sends the reply message to the service in the same way. This allows you to achieve high throughput levels and eliminates the need to purge messages, but has the following limitations:
No persisted record of the pass-through call is maintained. You cannot view the message in the message viewer or view a message trace. This makes it challenging to troubleshoot problems.
No retry mechanism is available. If the first attempt to contact the server fails, the failure is returned to the application calling the pass-through service.
This mode is available only if a pass-through service targets a pass-through operation directly. If the message passes through any other production component, such as a business process router, then persisted messages are used throughout the process.
To suppress the use of persistent messages for a pass-through service and pass-through operation pair, choose one of the specialized classes for the pass-through operation:
In addition, to suppress persistent messages, you must clear the Persist Messages Sent InProc check box in the pass-through business service configuration.
If the pass-through service is using the standard Web port, you can further improve efficiency by configuring the service to keep the TCP connection open between calls. To do this, in the pass-through service configuration, check the Keep Standard Request Partition check box.
Using Other Business Services, Processes, and Operations
Although the simplest ESB systems can consist of a production with only pass-through services and operations, some requirements can only be met with more complex production components. For example, if your ESB must do any of the following, you need other kinds of business services and operations:
Route calls from a single incoming service to multiple external services depending on the content of the call.
Modify the parameters or protocol used for a service.
Expose a single service that is implemented by combining the capabilities of two or more external services.
Provide the service directly on the ESB.
Provide security other than one based on SAML tokens.
For more information on using other business services, processes, and operations to handle REST and SOAP service requests, see Creating Web Services and Web Clients with InterSystems IRIS.
Tracking Performance Statistics of Pass-through Services and Operations
To ensure that your ESB system continues to meet the needs of your users, it is important to monitor and track its performance. By performing this monitoring regularly, you can manage any increase in workload by adding resources to handle the increased load. If your pass-through services and operations are using persistent messages, you can use InterSystems IRIS’s monitoring facilities to track and report on performance, but the Activity Volume monitoring provides a mechanism to produce summary performance statistics that are useful for the following:
Tracking overall system performance.
Ensuring that the system is meeting Service-Level Agreements (SLAs).
Identifying potential problems.
If you have suppressed storing persistent messages (see “Suppressing Persistent Messages in Pass-through Services and Operations”), these summary statistics are your main tool for tracking performance.
The summary statistics consists of the following information for each pass-through service and operation:
Total number of messages that completed during a fixed time interval (10 seconds)
Total elapsed time to complete processing these messages
As generally true for monitoring performance, it is important to monitor and record performance statistics on a regular basis. This allows you to detect trends and compare current performance to a baseline. This can be useful in determining whether the cause of performance problems is increased load, network issues, problems with the servers providing the services, or ESB performance issues.
The summary statistics mechanism for pass-through services and operations consists of the following components:
Configurations and Global settings to enable pass-through services and operations to generate the statistics.
Daemons to get the statistics from the pass-through services and operations and send them to a daemon to store the statistics.
User interface to monitor and explore the statistics.
For details, see “Monitoring Activity Volume” in Monitoring Productions.