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:
-
Log in to the Management Portal as a user with the %HS_Administrator role.
-
Select the name of your Foundation namespace.
-
Click Health > Service Registry.
-
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.
-
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.
-
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:
Required. Each service must have a unique name.
Optionally enter the number of seconds before this service should time out.
Optionally enter a code from the OID registry to tie this entry to a device OID.
Optionally enter a code from the OID registry to tie this entry to a home community OID (for XCA).
Optionally enter a code from the OID registry to tie this entry to an assigning authority OID.
Optionally enter a code from the OID registry to tie this entry to a repository OID.
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.
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:
Enter the hostname or IP address.
Enter the port number.
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 Create or Edit a TLS Configuration. 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.
Enter the URL of the web service.
Enter a proxy hostname, if applicable.
Enter a proxy port number, if applicable.
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 Configure Credentials.
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.
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.
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.
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.
Select this check box if this is an XDS.b repository that accepts MTOM documents as attachments.
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.
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.
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.BaseOpens in a new tab and override the AddSecurity() class method.
File Service Settings
If you selected a File service, you are presented with the following fields:
Enter the name of the file on the local system.
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.
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:
Enter the name of the file to write on the FTP server.
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.
Select this check box to overwrite the existing file. If this is not selected, new data will be appended to the existing file.
Enter the IP address or server name of the FTP server.
Enter the TCP port number to use on the FTP server. The default is 21.
Enter the production credentials that can authorize a connection to the FTP server. For information on creating production credentials, see Configure Credentials.
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:
Enter the IP address or hostname of the server.
Enter the TCP port on the server. This defaults to 80 (or 443 if SSL Configuration is specified).
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 Create or Edit a TLS Configuration. 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.
Enter the URL path (not including http:// or the server address).
Enter the IP address or hostname of the proxy server, if applicable.
Enter a proxy port number, if applicable, This defaults to 8080.
Enter the ID of the production credentials that can authorize a connection to the given destination URL. For information on creating production credentials, see Configure Credentials.
If your client uses this setting, make sure this value is the same as that for your client.
If your client uses this setting, make sure this value is the same as that for your client.
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:
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.
Enter the TCP port to connect to. TCP port numbers have a maximum value of 65535.
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 Create or Edit a TLS Configuration. 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.
-
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:
Enter the IP address to make a UDP connection to.
Enter the UDP port to connect to.
Enter the desired UDP sender command.
Deleting a Service
To delete an existing service:
-
Open the Management Portal.
-
Select the name of your Foundation namespace.
-
Click Service Registry.
-
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.
-
Click Delete at the bottom of the screen.
-
Click OK in the confirmation dialog box.