Skip to main content
Previous sectionNext section

Managing the Service Registry

The Service Registry maintains a list of destinations for services. Typically these are URLs for SOAP services, either within your system or for external destinations.

Adding or Modifying a Service

To add a new service or modify an existing service:

  1. Log in to the Management Portal as a user with the %HS_Administrator role.

  2. Select the name of your Foundation namespace.

  3. Click Health > Service Registry.

  4. To add a new service click Add Service. Alternatively, you can click Parse Web Service URL to add a new SOAP service and then enter the URL in the dialog and click OK. The URL will be parsed into the appropriate fields in the Service Registry entry.

  5. To modify an existing service click on the row for the service in the table. Use the Service Type drop-down above the table to filter the list of services shown in the table.

  6. Enter the information for your service and click Save. The settings are documented in the next section.

Service Registry Settings

The data entry screen for services has two portions. The upper portion is fixed and contains nine fields. The contents of the lower portion change, depending on the Service Type selected. The settings for the upper portion are documented below. The settings for the specific service types are documented in the subsections that follow.

The following fields appear in the upper section of the Service Registry data entry screen:

Name

Required. Each service must have a unique name.

Timeout

Optionally enter the number of seconds before this service should time out.

Device

Optionally enter a code from the OID registry to tie this entry to a device OID.

Home Community

Optionally enter a code from the OID registry to tie this entry to a home community OID (for XCA).

Assigning Authority

Optionally enter a code from the OID registry to tie this entry to an assigning authority OID.

Repository

Optionally enter a code from the OID registry to tie this entry to a repository OID.

Device Function

Some Service Registry entries perform the function of a particular device. The entries available depend on the components you installed when you ran the FHIR installer. Standard entries include:

  • XCA.Query — requires that a home community OID is specified as described above. Identifies the URL to direct XCA query transactions to in the specified home community.

  • XCA.Retrieve — requires that a home community OID is specified as described above. Identifies the URL to direct XCA retrieve transactions to in the specified home community.

  • XDSb.Query — identifies the document registry that XDS.b queries should be directed to.

  • XDSb.Retrieve — requires that a repository OID is specified as described above. Identifies the URL to direct XDS.b retrieve transactions to for that repository OID.

  • PDQv3.Supplier — identifies the PDQv3 supplier service.

Service Type

Required. Select a type for this service from the drop-down. The Service Type you select controls which fields appear in the lower portion of the screen. The options are:

  • SOAP

  • File

  • FTP

  • HTTP

  • TCP

  • UDP

The following sections document the settings specific to each service type. None of the settings are marked as required. For each service type, enter as many or as few settings as are needed to successfully perform the communication.

SOAP Service Settings

If you selected a SOAP service, you are presented with the following fields:

Host

Enter the hostname or IP address.

Port

Enter the port number.

SSL Configuration

Enter the name of an existing Secure Socket Layer (SSL) or Transport Layer Security (TLS) configuration to use to authenticate this connection. To create an SSL/TLS configuration, see the section “Creating or Editing an SSL/TLS Configuration” in the Security Administration Guide. The SSL/TLS configuration includes an option called Configuration Name; this is the string to use in this setting. At the end of the SSL Configuration string, you can add a vertical bar (|) followed by the private key password.

URL

Enter the URL of the web service.

Proxy Host

Enter a proxy hostname, if applicable.

Proxy Port

Enter a proxy port number, if applicable.

HTTPCredentialsConfig

Enter the ID of the production credentials that contain the username and password to be used in the HTTP header. For information on creating production credentials, see the section “Configure Credentials” in the book Configuring Productions.

SOAP Version

Enter the SOAP version required. Use one of the following values:

  • "" — Use this value for SOAP 1.1 or 1.2.

  • "1.1" — Use this value for SOAP 1.1. This is the default.

  • "1.2" — Use this value for SOAP 1.2.

Username Token Profile

Specify the ID of the production credentials that contain the username and password to be used in the WS-Security header of the SOAP request.

X509 Token Profile for Encryption

Enter the alias of the X509 credentials to use for encryption of the message body. For information on creating these credentials, see “Creating and Editing InterSystems IRIS Credential Sets” in the book Securing Web Services.

X509 Token Profile for Digital Signing

Enter the alias of the X509 credentials to use for digitally signing the message. For information on creating these credentials, see “Creating and Editing InterSystems IRIS Credential Sets” in the book Securing Web Services.

MTOM

Select this check box if this is an XDS.b repository that accepts MTOM documents as attachments.

XUA Configuration

Select an XUA configuration from the drop-down to identify the SAML creator and SAML processor. See “Managing the XUA Registry” for details on XUA.

Send SAML Assertion

Controls whether SAML tokens should be sent in the security headers of SOAP calls.

There are several options:

  • No — do not create a SAML assertion or forward any SAML assertions found in the request message.

  • Forward — use the SAML creator class specified in the XUA configuration to forward any SAML assertion found in the request message. Do not create a SAML assertion.

  • Create — use the SAML creator class specified in the XUA configuration to create a new SAML assertion based on the data in the request message. Do not forward any SAML assertion found in the request message.

  • Create then Forward and Forward then Create — use the SAML creator class specified in the XUA configuration to create a SAML assertion and forward any SAML assertion found in the request message. The order that they are appear in the security header depends on the specific option chosen. If either the create or forward fails, an error is generated.

  • Forward or Create — use the SAML creator class specified in the XUA configuration to forward any SAML assertion found in the request message. If no SAML assertion is found, create one. Only if both operations fail is an error generated.

Security Class

An optional class that overrides the default security code for signatures and encryption used in SOAP messages. Your security class should extend HS.Util.SOAPClient.Base and override the AddSecurity() class method.

File Service Settings

If you selected a File service, you are presented with the following fields:

File Name

Enter the name of the file on the local system.

File Path

Enter the full pathname of the directory for the specified file. This directory must exist, and it must be accessible through the file system on the local machine.

Overwrite Existing File

Select this check box to overwrite the existing file. If this is not selected, new data will be appended to the existing file.

FTP Service Settings

If you selected an FTP service, you are presented with the following fields:

File Name

Enter the name of the file to write on the FTP server.

File Path

Enter the full pathname of the directory on the FTP server for the specified file. This directory must exist, and it must be accessible using the Credentials provided.

Overwrite Existing File

Select this check box to overwrite the existing file. If this is not selected, new data will be appended to the existing file.

Host

Enter the IP address or server name of the FTP server.

Port

Enter the TCP port number to use on the FTP server. The default is 21.

User Credentials Config

Enter the production credentials that can authorize a connection to the FTP server. For information on creating production credentials, see the section “Configure Credentials” in the book Configuring Productions.

Use Passive

Select this check box to use passive FTP mode, where the server returns a data port address and the client connects to it. Most firewalls are more tolerant of passive mode FTP because both the control and data TCP connections are initiated by the client.

HTTP Service Settings

If you selected an HTTP service, you are presented with the following fields:

Host

Enter the IP address or hostname of the server.

Port

Enter the TCP port on the server. This defaults to 80 (or 443 if SSL Configuration is specified).

SSL Configuration

Enter the name of an existing Secure Socket Layer (SSL) or Transport Layer Security (TLS) configuration to use to authenticate this connection. To create an SSL/TLS configuration, see the section “Creating or Editing an SSL/TLS Configuration” in the Security Administration Guide. The SSL/TLS configuration includes an option called Configuration Name; this is the string to use in this setting. At the end of the SSL Configuration string, you can add a vertical bar (|) followed by the private key password.

URL

Enter the URL path (not including http:// or the server address).

Proxy Host

Enter the IP address or hostname of the proxy server, if applicable.

Proxy Port

Enter a proxy port number, if applicable, This defaults to 8080.

HTTPCredentialsConfig

Enter the ID of the production credentials that can authorize a connection to the given destination URL. For information on creating production credentials, see the section “Configure Credentials” in the book Configuring Productions.

Proxy HTTPS

If your client uses this setting, make sure this value is the same as that for your client.

Proxy Tunnel

If your client uses this setting, make sure this value is the same as that for your client.

Proxy HTTPS SSLConnect

If your client uses this setting, make sure this value is the same as that for your client.

TCP Service Settings

If you selected a TCP service, you are presented with the following fields:

Host

Enter the IP address to make a TCP connection to. If the address starts with a ! character, the adapter will wait for a connection from a remote system. If no IP address follows the ! character, any remote system may connect; otherwise only the listed IP addresses (and ports) will be allowed to connect.

Port

Enter the TCP port to connect to. TCP port numbers have a maximum value of 65535.

SSL Configuration

Enter the name of an existing Secure Socket Layer (SSL) or Transport Layer Security (TLS) configuration to use to authenticate this connection. To create an SSL/TLS configuration, see the section “Creating or Editing an SSL/TLS Configuration” in the Security Administration Guide. The SSL/TLS configuration includes an option called Configuration Name; this is the string to use in this setting. At the end of the SSL Configuration string, you can add a vertical bar (|) followed by the private key password.

Stay Connected
  • Set this to a positive value to stay connected to the remote system for this number of seconds after completing an operation.

  • Set this to zero to disconnect immediately after every operation.

  • Set this to –1 (the default) to stay permanently connected, even during idle times.

UDP Service Settings

If you selected a UDP service, you are presented with the following fields:

Host

Enter the IP address to make a UDP connection to.

Port

Enter the UDP port to connect to.

UDP Sender Command

Enter the desired UDP sender command.

Deleting a Service

To delete an existing service:

  1. Open the Management Portal.

  2. Select the name of your Foundation namespace.

  3. Click Service Registry.

  4. Click on the row for the service in the table. Use the Service Type drop-down above the table to filter the list of services shown in the table.

  5. Click Delete at the bottom of the screen.

  6. Click OK in the confirmation dialog box.