Skip to main content

Configuring an ESB

This topic describes how to configure an InterSystems IRIS® data platform system as an ESB.

Overview of Configuring InterSystems IRIS as an ESB

This section provides an overview of the tasks required to configure InterSystems IRIS as an ESB. Details of each task are provided in other sections.

Defining Roles and Users for the Public Service Registry

You can configure an ESB so that anyone can access the information in the registry or you can limit access by individual registry entries to specific accounts.

To allow open access to some or all entries in the Public Service Registry, do the following:

  1. Create a role by doing the following:

    1. Select System Administration > Security > Roles to display the Roles portal page.

    2. Click Create New Role and name the role, for example, ServReg_Unauthenticated, and click Save.

  2. Edit or create a web application for the Public Service Registry by doing the following:

    1. For Allowed Authentication Methods, select the Unauthenticated check box.

    2. Include the role that you defined in the previous step in the Application Roles.

    See Configuring a Web Application for the Public Service Registry API for details including other roles that you should include.

  3. For each entry in the Public Service Registry that you want to be available to unauthenticated users, add the role that was defined in Step 1 to the Required Roles field, which is a comma-separated list in Internal Information.

To allowed unauthenticated access, you only need to define the role—you do not need to define a user.

To limit access to entries in the Public Service Registry to a one or more users, do the following:

  1. Create a role by doing the following:

    1. Select System Administration > Security > Roles to display the Roles portal page.

    2. Click Create New Role and name the role, for example, ServReg_IDServices, and click Save.

  2. Edit or create a web application for the Public Service Registry specify the following:

    1. Select the Allowed Authentication Methods Password check box.

    2. Do not include the role that you defined in the previous step in the Application Roles.

    See Configuring a Web Application for the Public Service Registry API for details including other roles that you should include.

  3. For each entry in the Public Service Registry that you want to be available to users with this role, add the role to the Allowed Roles field, which is a comma-separated list.

  4. Create or edit a user account and assign the role to the user as follows:

    1. Select System Administration > Security > Users to display the Users portal page.

    2. Click Create New User, name the user, fill in the relevant fields, such as password, and click Save or select an existing user to edit.

    3. On the Roles tab, click the role or roles you created, click the right-arrow button, and click Assign.

    To access the Public Service Registry REST API, you do not have to assign any additional roles to the user. You may need to assign additional roles to provide access to the service itself.

Note:

Restricting or permitting access to a registry entry is entirely independent of restricting or permitting access to the service described by the registry entry. You can control access to the service itself by controlling access to the web application that invokes the service or by using custom code in the service.

Configuring a Web Application for the Public Service Registry REST API

This section describes how to configure a web application for the Public Service Registry REST API.

  1. Define a web application that will handle calls to the Web port. The web application name defines the root of the URL that will call the service. A single web application can support multiple business services but they must all have a class that is the same or a subclass of the web application dispatch class.

    1. Select System Administration > Security > Applications > Web Applications to display the Web Applications portal page. Click Create New Web Application.

    2. Name the web application, such as /services. You must start the name with a / (slash) character. All alphabetic characters in the name should be in lower case.

    3. Set the Namespace to the namespace that the service registry is running in, such as SERVICESNS. Leave the Namespace Default Application unchecked.

    4. Select the Inbound Web Services check box.

    5. Leave the Resource Required and Group By ID fields empty.

    6. If you want the registry to be accessed by users who log in, select the Allowed Authentication Methods Password check box. If you want the registry to be accessed by users without logging on, select the Unauthenticated check box.

    7. Set the Dispatch Class to the Ens.ServiceRegistry.API.REST.QueryOpens in a new tab component class.

    8. Select Save.

    9. Click the Application Roles tab.

    10. In the Available box, select the following roles:

      • %EnsRole_RegistrySelect

      • Roles defined for the namespace’s globals and routines databases, such as %DB_SERVICESNSG and %DB_SERVICESNSR.

      • Any role defined for the Public Service Registry that you want to be available to all users regardless of the account they use to log in. If you are configuring the web application to allow unauthenticated access, you must specify at least one of these roles.

      You can select multiple roles while holding the Ctrl key.

    11. After the roles are highlighted, click the right-arrow button to move them to the Selected text box.

    12. Then click Assign.

Note:

If your web application allows both unauthenticated and authenticated service, then it will prompt for a password, but if you do not enter a password, the web applications grants you unauthenticated access.

Using the External Service Registry to Configure ESB Hosts

If the ESB production and the External Service Registry are in the same namespace, you can use the registry to configure ESB hosts. This allows you to centralize the information about external services in the registry. In most cases, you can use this to set the properties of the business operations that are accessing the external services, but you can also use it for business services, such as services based on the FTP incoming adapter that retrieve the incoming message from an FTP server.

You can use the External Service Registry to set the properties for hosts that implement any of the following adapters:

  • EnsLib.FTP.InboundAdapter

  • EnsLib.FTP.OutboundAdapter

  • EnsLib.File.InboundAdapter

  • EnsLib.File.OutboundAdapter

  • EnsLib.HTTP.OutboundAdapter

  • EnsLib.SOAP.OutboundAdapter

  • EnsLib.SQL.InboundAdapter

  • EnsLib.SQL.OutboundAdapter

  • EnsLib.TCP.OutboundAdapter

To configure a host to get its settings from the External Service Registry, set the External Registry ID field to the key value of the registry entry. The key value consists of the service Name, Domain, and Version concatenated together with || (two vertical bars) separating the elements. For example, to get the property values from the External Service Registry entry with the name GetDaily, the domain Weather, and Version 1.0, set the External Registry ID property to the following:

GetDaily||Weather||1.0

The following describes how the Endpoint value is used to set the adapter properties for each protocol:

  • HTTP and REST—The Endpoint sets the HTTPServer, HTTPPort, and URL properties. For example if the Endpoint is:

    http://newsrvcs.example.com:57781/csp/samples/docserver/namespaces

    Then the business operation properties are set as follows:

    HTTPServer: newsrvcs.example.com

    HTTPPort: 57781

    URL: /csp/samples/docserver/namespaces

    If the business operation is a pass-through business operation, then the special characters * (asterisk), ^ (caret), and | (vertical bar) describe how to build the endpoint from the incoming URL. See Configuring Pass-through Business Operations for details.

  • FTP—The Endpoint sets the FTPServer, FTPPort, FilePath, and SSLConfig properties. For example, if the Endpoint is:

    ftp://newftp.example.com/filestore/docs/

    Then the business operation properties are set as follows:

    FTPServer: newftp.example.com

    FTPPort: 21

    FilePath: /filestore/docs/

    If the protocol is sftp://, then SSLConfig is set to "!SFTP" and the FTPPort is set to 22.

  • SQL—The Endpoint is used to set the DSN property.

  • SOAP—The Endpoint is used to set the WebServiceURL property. The EnsLib.SOAP.GenericOperationOpens in a new tab and EnsLib.SOAP.GenericOperationInProcOpens in a new tab pass-through operations are considered HTTP operations, not SOAP operations for this purpose.

  • File—The Endpoint is used to set the FilePath property.

  • TCP—The Endpoint is used to set the IPAddress and Port properties. For example, if the Endpoint is:

    102.23.10.1:4500

    Then the business operation properties are set as follows:

    IPAddress: 102.23.10.1

    Port: 4500

  • HL7 and X12—The beginning of the Endpoint string specifies the underlying protocol: File, TCP, FTP, or HTTP. For File and TCP, the file: and tcp: are removed from the string Endpoint before parsing it.

The business operation settings from the External Service Registry entry override any settings from System Default Settings, production definition, and business host class definition.

Configuring ESB Services and OperationsNext section
Previous sectionAdministering the Public Service and External Service Registries
FeedbackOpens in a new tab