Using Ensemble as an ESB
Administering the Public Service and External Service Registries
This chapter describes how to administer the public service registry and the external service registry. Although the registries have different purposes, they have a similar structure and user interface. This chapter contains:
Administering the Public Service Registry
Administering the External Service Registry
Fields in both the Public and the External Service Registries
This section describes the fields in the public and external service registries. Most fields are identical in the public and external service registries. In addition to these fields that are common to both registries, the public Service Registry has some private fields. These fields are only accessible to the registry administrator and are not accessible through the public REST API.
Name identifies the service. The other attributes identifying the service are the Domain
. Each registry should adopt conventions on how these attributes are used. The Domain
typically identifies the category of the service and Version
is a string representing a version number. Name in combination with Domain and Version must be unique for each entry. For example, two or more entries may have the same name as long as the domains are different or the versions are different.
Version identifies the version of the service.
Domain specifies the category of the service.
Service Protocol describes the protocol used by the client to access the service. It can have any of the following values: File
, and any custom value. In the External Service Registry, the Service Protocol determines how the Endpoint is used to set the business operation properties. You can explicitly enter TCP as the service protocol but it is not listed in the drop-down choices.
Description provides a brief explanation of the service
Endpoint specifies the location of the service. On the public Service Registry, the endpoint is typically a URL of a business service on the ESB. On the External Service Registry, the endpoint provides information about the location of the data or service and is used to set the properties of the ESB host.
Response Style describes how the service returns a value. It may have one of the following values: Sync
, Remote Deposit
, or a blank value.
Topics allow you to define search terms to aid in searching for registry entries from the administrator page and from the public API. You cannot enter values when you create a registry entry but can add them by entering the values in the Details
panel. You can specify topics by entering a list of terms, separated by commas, or by checking one or more topics from the drop-down menu. The drop-down menu lists topics that have already been defined for registry entries.
The Schema describes the structure of the service messages. Schema contains subfields that describe or contain the structure definition. You cannot specify a schema when you create a registry entry but can add them by entering the values in the Details panel. Schema contains the following subfields:
Specifies the name of the schema definition mechanism used to describe the schema. You can select WSDL, XSD, HL7, SEF, X12, AST, or EDF, or you can enter the name of any other schema definition mechanism.
Specifies the URL of the schema definition.
Provides supplementary information about the schema.
Provides a brief text excerpt from the schema.
Provides the full text content of the schema definition.
Actions specify the SOAP actions or the REST HTTP request methods that can be used with the specified URL. SOAP actions provide a summary of the information defined in the WSDL. You cannot add an action when you create a registry entry, but you can add actions by Selecting the Actions plus sign in the Details panel. An action contains the following subfields:
Specifies the name used by the Registry to identify this action.
Identifier for the action or web method.
Specifies the HTTP request method. Typically, this is GET, PUT, POST, or DELETE, but you can enter any HTTP request method.
If checked, specifies that the call does not make any changes to the state of the server.
If checked, specifies that making multiple identical calls have the same impact on the server as making a single call.
Specifies a text explanation of the action.
Specifies the format of the incoming message body and consists of the following subfields: Type, Reference, Notes, Thumbnail, and Content.
Specifies the format of the response message body and consists of the following subfields: Type, Reference, Notes, Thumbnail, and Content.
Attributes specify a list of name-value pairs that allow you to specify any arbitrary field in the registry entry. You cannot add an attribute when you create a registry entry, but you can add attributes by Selecting the Attributes + (plus sign) in the Details panel. Each attribute consists of a name and a string value. Once you have defined an attribute, you can update the value or delete the attribute, but cannot change the name of the attribute.
Contacts specify people or organizations that support or use the service. You cannot add a contact when you create a registry entry, but you can add contacts by Selecting the Contacts plus sign on the Details panel. A contact contains the following subfields:
Specifies the name or other identity of the person or organization.
Provides a link to the Ensemble business partner object, which provides contact information such as address and phone numbers. Note that the public API only provides the business partner name and does not include any of the contact information from the business partner object.
Specifies details about the contact, for example you could enter phone numbers, email addresses, or other contact information that can be accessible through the public API.
Specifies supplementary information about the contact.
Once you have defined a contact, you can update any of the subfields except for the Identity
. You can also delete the contact by selecting the red X.
Files provide a way to store any text or binary file in a registry entry. For example, you can store files that contain documentation on the service or large schema definitions. You cannot add a file when you create a service, but you can add a file by Selecting the Files plus sign on the Details
panel. You can add a file either located on your local system or located on the Ensemble server. A File contains the following subfields:
Provides the name of the file. The name of the file in the registry does not have to be the same as the name of the original file on your local file system or on the Ensemble server.
Provides information on the format and purpose of the file. This field is set by the last part of the file name.
Provides information on the application used to access the file.
Provides the file size. This field is calculated from the file contents.
When you create a file, this subfield is set to the contents of the file.
Internal Fields in the Public Service Registry
The following are internal attributes, which are only present on the public Service Registry. These internal attributes are only accessible to administrators who are using the management portal. These attributes are not accessible through the public API to the service registry.
This checkbox controls whether the information about this service is available through the Registry’s public API. If Public
is true (the box is checked) then the API returns information about this service if the user is authorized to see it based on the Required Roles
setting. If Public
is false, no information about this service is returned by the public API.
identifies the Ensemble instance that is providing the service at the specified endpoint. Typically, this is the Ensemble instance used for the ESB and service registries. In cases where the endpoint service is not provided by an Ensemble business service, leave this field blank.
identifies the Ensemble namespace that is providing the service at the specified endpoint. Typically, this is the Ensemble namespace used for the ESB and service registries. In cases where the endpoint service is not provided by an Ensemble business service, leave this field blank.
identifies the Ensemble production that is providing the service at the specified endpoint. Typically, this is the ESB Ensemble production. In cases where the endpoint service is not provided by an Ensemble business service, leave this field blank.
identifies the Ensemble configuration item that is providing the service at the specified endpoint. Typically, this is configuration item is a business service in the ESB Ensemble production. In cases where the endpoint service is not provided by an Ensemble business service, leave this field blank.
Creating and Maintaining a Service Registry Entry
To create a new Public Service Registry or External Service Registry entry, select New Service
. If you create a new service entry in the Public Service Registry, Ensemble displays the following Register Service form:
If you create a new service entry in the External Service Registry, Ensemble displays a similar form that omits the Internal Information
fields and the Visible field
When you are creating a new service entry, you must enter values in the Name
, and Version
required fields before selecting the Save
button. You cannot change the values in these three fields after saving the registry entry. You can create a copy of the registry entry with new values in these fields by selecting the registry entry and then selecting Save As
in the Actions
You can enter values in the Register Service form for the other properties:
When creating a Public Service Registry entry, you can also enter values for the Internal Information fields:
Once you have saved a registry entry, you can select the registry entry from the list and use the Details
pane to modify any of these fields except for the three required fields. You can also enter or modify the following fields on the Details
. and Files
fields take multiple values. To add a new item, select the Add Action, Add Attribute, Add Contact, or Add File plus sign. Fill in the form and then select Apply
. You can update an existing item by selecting the clipboard for that item. You can delete an item by selecting the red X for that item.
panel allows you to delete a registry entry or save a copy with changes to one or more of the required fields: Name
, and Version
Searching and Viewing the Service Registry
buttons and the search panel allow you to view the registry entries. If there are more registry entries than will fit on a single page, the Next
buttons allow you to scroll through the entries. The search panel allows you to find the registry entries that match your query.
The search panel allows you to do the following:
Specify the Page Size
, which specifies the maximum number of registry entries that can be displayed in a page.
Sort the registry entries by Name, Domain, Version, Service Protocol, Lifecycle Stage, and Last Time Modified. You can sort in ascending order (the default) or descending order.
You can select the registry entries to display by specifying any of the following criteria:
Visible or invisible entries
Text in Word Match
in any of the following fields: Name, Domain, Description, Endpoint, or Topics
Any of the selected service protocols
Any of the selected lifecycle stages
Extended criteria that specify conditions based on attribute values
You can also display the values of specific attributes in the list of services by using the Modify Display