Using a Production as an ESB
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:
If your pass-through service is to be called from a special port:
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
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:
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.
^ (circumflex): 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 circumflex, 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.GenericOperation
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:
Must contain an Authorization header SAML token with key 'access_token='
Token must contain an Assertion.
Requires Assertions to contain NotBefore/NotOnOrAfter time conditions
Verifies Assertion signatures using a Trusted X.509 certificate and, if present, NotBefore/NotOnOrAfter conditions.
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
checkbox 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
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.
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.
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.