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.
Administering the Public Service Registry
To administer the Public Service Registry, select Interoperability > Configure > Public-Service Registry. The Public Service Registry is protected by row-level security; consequently, you must have the %EnsRole_RegistryManager role in order to access the Public Service Registry.
For information on the fields in the public registry, see Fields in both the Public and the External Service Registries and Internal Fields in the Public Service Registry. For information on creating and maintaining entries in the service registries, see Creating and Maintaining a Service Registry Entry. For information on searching the service registries, see Searching and Viewing the Service Registry.
Administering the External Service Registry
To administer the External Service Registry, select Interoperability > Configure > External-Service Registry.
For information on the fields in the external registry, see Fields in both the Public and the External Service Registries. For information on creating and maintaining entries in the service registries, see Creating and Maintaining a Service Registry Entry. For information on searching the service registries, see Searching and Viewing the 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 and Version. 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.
Lifecycle Stage describes the development state of the service. It can have one of the following values: Concept, Development, Test, Staging, Live, Deprecated, and Defunct.
Service Protocol describes the protocol used by the client to access the service. It can have any of the following values: File, FTP, HL7, HTTP, REST, SOAP, SQL, X12, 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.
The format of the endpoint in the External Service Registry is dependent on the service protocol. For details on how the Endpoint is used for each type of service protocol, see “Using the External Service Registry to Configure ESB Hosts.”
Response Style describes how the service returns a value. It may have one of the following values: Sync, Callback, 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:
Type—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.
Reference—Specifies the URL of the schema definition.
Notes—Provides supplementary information about the schema.
Thumbnail—Provides a brief text excerpt from the schema.
Content—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:
Name—Specifies the name used by the Registry to identify this action.
Reference—Identifier for the action or web method.
Verb—Specifies the HTTP request method. Typically, this is GET, PUT, POST, or DELETE, but you can enter any HTTP request method.
Read Only—If checked, specifies that the call does not make any changes to the state of the server.
Idempotent—If checked, specifies that making multiple identical calls have the same impact on the server as making a single call.
Description—Specifies a text explanation of the action.
Request Schema—Specifies the format of the incoming message body and consists of the following subfields: Type, Reference, Notes, Thumbnail, and Content.
Response Schema—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:
Identity—Specifies the name or other identity of the person or organization.
Contact Type—Specifies whether the contact is the service Author, Consumer, Provider, Operator, Manager, or Sponsor.
Business Partner—Provides a link to the 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.
Details—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.
Notes—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 InterSystems IRIS® server. A File contains the following subfields:
Filename—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 InterSystems IRIS® server.
File Extension—Provides information on the format and purpose of the file. This field is set by the last part of the file name.
MIMEType—Provides information on the application used to access the file.
CharEncoding—Provides the character encoding information.
File Size—Provides the file size. This field is calculated from the file contents.
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 check box 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.
Required Roles specifies a list of roles that provide public API access to the registry entry. In order for a user to retrieve information about a registry entry, the user must have one of the roles listed in Required Roles. The user may have this role by either being logged into InterSystems IRIS or by using a web application with this role. See “Defining Roles and Users for the Public Service Registry” for details on how to define these roles.
Instance identifies the InterSystems IRIS instance that is providing the service at the specified endpoint. Typically, this is the InterSystems IRIS instance used for the ESB and service registries. In cases where the endpoint service is not provided by a business service, leave this field blank.
Namespace identifies the interoperability-enabled namespace that is providing the service at the specified endpoint. Typically, this is the interoperability-enabled namespace used for the ESB and service registries. In cases where the endpoint service is not provided by a business service, leave this field blank.
Production identifies the production that is providing the service at the specified endpoint. Typically, this is the ESB production. In cases where the endpoint service is not provided by a business service, leave this field blank.
ConfigName identifies the production configuration item that is providing the service at the specified endpoint. Typically, this is configuration item is a business service in the ESB production. In cases where the endpoint service is not provided by a 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, InterSystems IRIS displays the following Register Service form:
If you create a new service entry in the External Service Registry, InterSystems IRIS 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, Domain, 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 panel.
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 panel:
The Actions, Attributes, Contacts. 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.
The Actions panel allows you to delete a registry entry or save a copy with changes to one or more of the required fields: Name, Domain, and Version.
Searching and Viewing the Service Registry
The Next and Previous 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 and Previous 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
Specified Required Role
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 field.