Using the Ensemble NHS Interoperability Toolkit
Setting Up the ITK Switchboard
[Back] [Next]
   
Server:docs1
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

The Ensemble ITK Switchboard is a data-driven integration solution that allows ITK-compliant systems to interoperate with a minimum of integration work. This chapter discusses the following topics:

For additional details, see the classes in the EnsLib.ITK packages of the InterSystems Class Reference.
Overview
The Ensemble ITK Switchboard is a specialized Ensemble production that routes messages. The following figure shows its basic architecture:
The production includes two kinds of Ensemble business hosts:
The ITK Switchboard uses the generic term systems or applications to refer collectively to external systems. When you configure the ITK Switchboard, you declare all systems that the Switchboard will use. Note that some systems can both send and receive messages from the switchboard. This means that, for some systems, the production contains both a corresponding listener and a corresponding consumer.
The ITK Switchboard production provides internal, data-driven logic to route messages; the production does not use a business host for this purpose. The routing logic uses the subscription and distribution rules that you define when you configure the Switchboard.
The listeners and consumers communicate via SOAP with the external systems as follows:
You configure the Switchboard to expect specific SOAP actions in specific contexts. The Switchboard uses the following system to handle the wide variety of messages that it routes:
Getting Started
To start to create the ITK Switchboard production:
  1. Use the Management Portal to create a new Ensemble-enabled namespace.
  2. Access the following web page:
    http://localhost:57772/csp/itk/EnsLib.ITK.Setup.UI.RegistryViewer.cls
    Where localhost is the server on which Ensemble is running, 57772 is the web server port that Ensemble is using, and itk is the namespace that you created.
    This page is a specialized version of the standard Ensemble production configuration page. Two buttons at the top let you control whether you are viewing senders or consumers:
    Click this to view systems, senders, and listeners.
    Click this to view consumers, subscription rules, and distribution rules.
  3. Click New.
  4. Specify the following information:
  5. Click OK.
Defining ITK Services
As noted earlier, the Switchboard provides a set of ITK services that match the UK NHS CfH ITK Services. Obtain the configuration data for these services from the InterSystems Worldwide Response Center (WRC) and load it into Ensemble as directed.
Normally you would not edit this data; if you do, your solution might no longer be ITK-compliant. If you do edit this data, specify the following details for each ITK service:
Service Name
Required. Unique, internal name of the ITK service, usually a short name. You may find it convenient to use a short form of the SOAP action. For example: ConfirmMessageReceipt-v1-0
SOAP Action
Required. Unique SOAP action. For example: urn:nhs-itk:201005:ConfirmMessageReceipt-v1-0
Behavior Type
Required. Select one of the following:
The Switchboard automatically mediates the handling of synchronous and asynchronous communications.
Request Class
Do not change the value for this.
Response Class
Do not change the value for this.
Web Client Class
Do not change the value for this.
Web Service Class
Do not change the value for this.
Defining Systems
To define each system, display the basic Switchboard production and then do the following:
  1. Click the View Senders button .
  2. Click the plus sign + next to Systems.
  3. Specify the following details:
    ApplicationName
    Required. Unique name of the system.
    Each system can have an associated consumer, a listener or both. See below for information on choosing suitable names in these cases.
    ApplicationRouter
    Specify the name of a business rule in Ensemble that contains the rules that map the content of the message to consumers for content-based routing.
  4. Click OK.
System Names for Consumers
If the system represents a consumer, the reconciliation process examines the routing rules and creates the needed business operation for that system. The name of the system becomes the name of a business operation.
For pure consumers, the name of the system is not that important and is only used internally. However, note that if the same system uses the queue collection facility (that is, sends requests to get the messages) or it if responds asynchronously (that is, sends responses) then the system is also a listener; see the next heading.
System Names for Listeners
The ITK Switchboard has a limited amount of business services that vary by port numbers and security configurations. It is common to have one business service for internal systems and another for external systems.
For a listener, the name of the system must match the ‘From’ value in the SOAP Header. This allows more than one system to send messages into the same business service, while enabling the Switchboard to route the messages easily based on the sending system.
Defining the Listeners
To define each listener, display the basic Switchboard production and then do the following:
  1. Click the View Senders button .
  2. Click the plus sign + next to Listeners.
  3. Specify a name for the listener, which is a business service.
  4. Click OK.
  5. Click the circle for a sender that sends to this listener.
    With the left mouse down, drag a line from this to the listener.
    When you do so, Ensemble displays a dialog box where you can specify configuration details.
  6. For each service expected from this sender, do the following:
    1. Select a service from the Web Service drop-down list.
    2. Select a value for Invocation Pattern, one of the following:
      This option matters only if the service is a request/response type.
    3. Ignore Validate Payload. This option is for future use.
    4. Click Save.
  7. When you are done specifying services, click OK.
Defining the Consumers
To define consumers, display the basic Switchboard production and then do the following:
  1. Click the View Consumers button .
  2. Click the plus sign + next to Consumers.
  3. For ApplicationName, specify a consumer name.
  4. Click OK.
    Make sure that the new consumer is selected.
  5. On the Settings tab, expand the Consumer Settings section.
  6. Click the search button next to Services.
  7. For each service expected from this sender, do the following:
    1. Select a service from the Web Service drop-down list.
    2. Select a value for Invocation Pattern, one of the following:
      This option matters only if the service is a request/response type.
    3. For Partial Logical Endpoint, specify a logical path to append to the base endpoint of the web service used by this consumer. The base endpoint is configured (later) in the business operation.
    4. For Partial Physical Endpoint, specify an optional physical path to append to the base endpoint, which is configured (later) in the business operation.
    5. Click Save.
  8. When you are done specifying services, click OK.
Defining Subscription Rules
A subscription rule sends all messages for given service from a given sender to a specific consumer.
To define subscription rules, display the basic Switchboard production and then do the following:
  1. Click the View Consumers button .
  2. Click the circle for a sender that sends to this consumer.
    With the left mouse down, drag a line from this to the consumer.
    When you do so, Ensemble displays a dialog box where you can specify configuration details for the subscription rule.
  3. Select a service and click OK.
Currently it is an error to set up more than one subscriber for a request/response service from the same application.
Defining Distribution Rules
A distribution rule applies to requests that are wrapped in a distribution envelope, which can contain logical addresses. A distribution rule describes how to dispatch the payload to the systems specified by the addresses.
To define distribution rules, display the basic Switchboard production and then do the following:
  1. Click the View Consumers button .
  2. Select a consumer.
  3. On the Settings tab, expand the Consumer Settings section.
  4. Click the search button next to DistributionRules.
  5. For each distribution rule for this consumer, do the following:
    1. Select a service from the Web Service drop-down list.
    2. Select a value for Distribution Mode, one of the following:
      This option refers to the mode needed for the distribution rule to be effective. The distribution mode is set by the business service.
      Authoritative means that the Switchboard should deliver this service to this component only if we are acting authoritatively. The best way to look at this is to think about the ITK Switchboard at the edge of a data center. We might for example communicate with external systems outside of our data center, but we should only communicate with these external systems when processing a message from one of our internal systems (we call this authoritatively).
      In contrast, if we receive a message from one of the external systems we may expect that this external system has already spoken to any other external systems. In such a case, we should not relay the message on (i.e. we would not send the message on to these systems when we are acting non-authoritatively).
    3. For Logical Address, specify an address inside the distribution envelope of a SOAP message.
    4. Click Save.
  6. When you are done specifying rules, click OK.
Reconciling the ITK Switchboard Production
The reconciliation process examines the routing rules and creates any needed business services and business operations.
To reconcile the production, display the production configuration in the Management Portal and click the Reconcile button.
Completing the Configuration of the ITK Switchboard Production
After performing reconciliation, complete the configuration by specifying settings for the business services and business operations.
Configuring the Business Services (Listeners)
Each listener is an instance of EnsLib.ITK.Framework.Service.SOAPRequestHandler and uses the adapter class EnsLib.SOAP.InboundAdapter.
For each listener, specify the following settings:
Endpoint URL
Specify the same value that is in the To element in the SOAP header, for SOAP messages received by this business service.
Distribution Mode
This setting applies only when processing address inside an incoming distribution envelope using distribution rules. If the service receives from internal applications, use the value authoritatively. If the service receives from external applications, use the value non-authoritatively.
Fault Vocabulary
Vocabulary to use for faults. For ITK, use the value 2.16.840.1.113883.2.1.3.2.4.17.268
WWSecurityPassword
Password for the user. Ensure that the caller is a registered Caché user.
SignedHeaders
Indicates which parts of the header are expected to be signed by the digital signature provided.
SOAPBodyEncrypted
Turn on if this service should check the body is encrypted. Useful if receiving from an external system over unsecure connection. Typically do not encrypt the messages.
TargetConfigName
Specify ITKMEssageRouter
Port
Specify the port number on which Ensemble should listen.
Specify other settings as wanted; see other Ensemble documentation.
Configuring the Business Operations (Consumers)
Each consumer is an instance of EnsLib.ITK.Framework.Operation.SOAPOperation and uses the adapter class EnsLib.SOAP.OutboundAdapter.
For each consumer, specify the following settings:
Endpoint Base URL
Specify the base logical endpoint for the web service. The actual endpoint is this endpoint plus the partial logical endpoint specified in the consumer registry.
Application Name
Name of the sending application, typically the name of the consumer.
UserNameToken
If you are not signing the messages (see the Sign Headers setting), then specify the username to place in the username field in the outbound messages.
Fault Vocabulary
Vocabulary to use for faults. For ITK, use the value 2.16.840.1.113883.2.1.3.2.4.17.268
Use ITK Extensions
Set this to true.
Throttle
Specifies an optional throttle on the business operation. This value is the time in seconds between requests.
Sign Headers
The standard ITK signing level is 2, which signs the timestamp. In a trusted environment, you can use 0, which means that the messages do not need to be signed. Use higher values if needed; for details, see the tooltip for this setting.
X509CertificateSign
The username in a pre-installed X509 certificate with which to sign the request. Load this certificate into Caché as described in the chapter Setup and Other Common Activities in Securing Caché Web Services.
Encryption Standard
If you want to encrypt the request body, then determines if this is 128–bit or 256–bit encryption. Keep None for no encryption.
X509CertificateEncrypt
Same as X509CertificationSign but for the encryption. If used typically the same as signing certificate. Do not encrypt unless there is a good reason to do so.
Subscription Pull
Set to true if this consumer will call in at a time of its choosing to collect the messages. In this case, the business operation saves the message away.
Subscription Pull Limit
Specifies the maximum number of messages that the consumer can subsequently request if using subscription pull. Specify –1 for no limit.
Specify other settings as wanted; see other Ensemble documentation.