Admin GUI User Manual

Overview

The Admin GUI allows CONNECT administrators to monitor gateway statistics, test the gateway implementation and manage users and gateway configurations. This graphical administrative console includes the following:

• Controlled user access
• Basic system overview
• User accounts management
• Certificate management
• Connectivity testing
• Property files management
• Gateway to gateway messaging
• Direct service configuration*

* CONNECT leverages the Direct configuration module from the ONC-sponsored JAVA Direct Reference Implementation (RI) v 3.01.

Login

User names are not case-sensitive but passwords are case sensitive. A default admin user is created during initial deployment.

Gateway Administrative Console - Login 

Gateway Status 

This is the dashboard view since CONNECT 5.1.

The Gateway Status page provides an overview of the gateway health. This page includes two tabs – Dashboard, and Remote Gateway List and will be used by gateway administrators, to monitor gateway configurations.

Gateway Dashboard

The dashboard provides a view of gateway/system specifications

Gateway Status

Gateway status parameters

Alerts and notifications

The dashboard also provides important system alerts and notifications. Currently, only digital certificate status updates are included.

Remote Gateway List (Deprecated as of CONNECT 5.1)

The Remote Gateway page lists all the gateways that the CONNECT instance has been communicating with and displays the total transaction count by service. 

Gateway Status - Remote Gateway

Remote Gateway List Display parameters

Account Management

Access to functionality within the Admin GUI is roles driven. Each user is assigned a role that determines access to pages and hence functions within the Admin GUI. Every role needs to be configured with certain privileges for each page i.e., no access or view/edit access. Implementers should use roles to limit access of certain features to specific users. E.g., a user with say an Admin role can access the Account Management->Create user page and create other users, but a user created with 'User' role should not have such privileges.

User Accounts

Selecting the default User Accounts tab under Accounts Management displays the User Accounts, Create User Page to create a user and Manage User page to delete users. 

Account Management - User Accounts

With CONNECT 5.2 and later, the User Accounts screen has 4 new mandatory fields namely: First name, Middle name or Initial, Last name and Transaction Role. These fields will be used to generate SAML assertion for Cross-Gateway Query client.

Manage Roles

Managing roles allows an admin to set access privileges for each user role. For each of the roles that are configured, access levels for No access, Read only and Read Write can be configured by pages of functionality.

Account Management - Manage Roles Screen

Future releases will allow for creating new roles capability. The default access is defined below, which can be changed  through the Manage User Roles screen.

Default page level access

Manage User Roles screen fields

Access to functionality within the Admin GUI is roles driven. Each user is assigned a role that determines access to pages and hence functions within the Admin GUI. Every role needs to be configured with certain privileges for each page i.e., no access or view/edit access. Implementers should use roles to limit access of certain features to specific users. E.g., a user with say an Admin role can access the Account Management->Create user page and create other users, but a user created with 'User' role should not have such privileges.

User Accounts

Selecting the default User Accounts tab under Accounts Management displays the User Accounts, Create User Page to create a user and Manage User page to delete users. 

Account Management - User Accounts

Certificate Management

Certificate Management interface is for to simplify the process of creating new certificate and managing self-signed certificates, CA-issued SSL certificates within KeyStore and TrustStore. It is divided into three tabs - Manage KeyStore, Manage TrustStore and Import Wizard

Manage KeyStore

Selecting the default Manage KeyStore tab under Certificate Management displays the Manage KeyStore page that shows list of available Keystores from CONNECT configuration. For security purposes, users can only view certificates from KeyStore list.

Certificate Management - Manage KeyStore page

Certificate Management - Manage KeyStore -  View Certificate Details page

Manage TrustStore

The Manage TrustStore page shows list of available Truststores from CONNECT configuration. Users allowed to import a new certificates into Truststore and edit, delete an existing certificates from Truststore.

Certificate Management - Manage TrustStore page

Certificate Management - Manage KeyStore -  Import Certificate page

From the Manage TrustStore tab, click on Import. In Import child window, click Choose and browse to the desired certificate. Be sure to click Upload, change Alias name for the newly uploaded certificate and click Import to complete the import process.

Certificate Management - Manage TrustStore -  Delete Certificate

To delete a certificate from the Truststore, select the certificate and click Delete. Certificate will be deleted once after providing the password. Note that, Certificate manager will not allow deletion of its own public certificate.

Certificate Management - Manage TrustStore -  View and edit Certificate

Select a certificate from the list and click View.  In the view Certificate Details window, user allowed to edit only Alias name and click Update Certificate for changes to take place.

Certificate Management - Manage TrustStore -  Refresh certificates

Truststore list can be refreshed after certificate changes have been made without a server restart. Click on the Refresh button to enable the updates.

Certificate Management - Manage TrustStore -  View Chain of Trust 

View Chain of Trust shows associated chained certificates. Select a record and click View Chain of Trust to view certificates chain.

Import Wizard

Import Wizard interface partly automated the process of creating new certificate and importing CA certs into CONNECT configuration. It is divided into five tabs - Start, Create Certificate, Certificate Signing Request,CA Providers, Import SSL Certificate. Import Wizard functions as below:

• Allow user to create new certificate 
• Allow user to create Certificate Signing Request (CSR/PKCS10)
• User must manually submit the CSR to their Certificate Authority (CA) to get a trusted certificate for their server
• Allow user to import server Certificate (CSR Reply) and CA certificates (chain of trust)
• Creates a backup of KeyStore and TrustStore under CONNECT configuration //importWizard/temp
• Creates a new KeyStore and TrustStore for replacement under CONNECT configuration //importWizard/new
• After successful Import Wizard process completion, the user must manually:
  • Replace CONNECT server configuration KeyStore and TrustStore  with the files under //importWizard/new
  • Restart the Server
  • Verify the AdminGUI functionality works and Manage KeyStore, Manage TrustStore list new certificate

Start Tab

There are three links in the Import Wizard that the user can start:

• Create a new Certificate.
• Generate CSR for an existing Certificate 
• Import SSL Certificate 

Create Certificate Page

Certificate Signing Request (PKCS10) Page

• Select the Alias to generate CSR.
• Generate Certificate Signing Request (CSR) PKCS10
• Copy the CSR Text or Download the CSR File
• Submit your CSR to CA Authority

Verify CSR

There are several ways to verify your CSR:  

• CSR Decoder
• openssl
• Keytool or keystore explorer

Verify CSR details as below: Signature Algorithm: SHA256withRSA, Public Key: RSA(2,048 bits)

CA Providers Page

• Each exchange may have different CA Authority/Provider
• The link(s) provided in the Available CA Providers tab is pulled from the caauthority.properties file.
• The links will point to information needed to get a server certificate from CA Authority.
• Your server certificate (CSR Reply) must be issued by the CA Authority: CA Root and CA Intermediate(s) must be part of chain of trust in your certificate

Getting CSR Reply (server certificate)

Getting your server certificate is a manual process with your CA Authority; At this point you should have

• Created self-signed certificate (X509)
• Created certificate signing request (CSR/PKCS10)

You will need to submit your CSR to your CA Authority to get CSR reply (X509/your server certificate)

You need to view your server certificate with Keystore Explorer or Keytool

Import SSL Certificate Page

This page allows user to import server certificate, CA root and CA intermediate for the selected Alias.

Note# if your CA Certificates (Root and Intermediates) are not expired or still in used you do not need to replace your CA-Root and CA-Intermediate(s)

New Certificates view via KeyStore Explorer

Remote AdminGUI with Shared Certificate

• Exporting the KeyPair (Alias) from gateway-keystore
• Importing the KeyPair (Alias) into admingui-keystore
• Importing the CA certificates (chain of trust) into admingui-truststore

# keystore (gateway.jks) will be know as gateway-keystore.jks
# truststore (cacerts.jks) will be know as gateway-truststore.jks
# keystore (gateway.jks) will be know as admingui-keystore.jks
# truststore (cacerts.jks) will be know as admingui-keystore.jks

# export your KeyPair (server certificate) alias:gateway
$ keytool -importkeystore -srckeystore gateway-keystore.jks -destkeystore server.p12 -deststoretype PKCS12 -alias gateway

# import your KeyPair:server to AdminGUI alias:gateway
# if your alias are not the same under both server; make sure you rename server.p12 (alias)
$ keytool -importkeystore -srckeystore server.p12 -destkeystore admingui-keystore.jks -srcstoretype pkcs12 -alias gateway

# import your CA certificates (chain of trust) under both KeyStore and TrustStore
$ keytool -import -file caIntermediate.pem -keystore admingui-keystore.jks -alias gateway_intermediate
$ keytool -import -file caRoot.pem -keystore admingui-keystore.jks -alias gateway_root

$ keytool -import -file caIntermediate.pem -keystore admingui-truststore.jks -alias gateway_intermediate
$ keytool -import -file caRoot.pem -keystore admingui-truststore.jks -alias gateway_root

Remote AdminGUI with Self-sign Certificate

• Import CA Certificates into admingui-truststore

replacing the AdminGUI (certificate)

• Export certificate from admingui-keystore
• Import certificate into gateway-truststore
• Import certificate into admingui-truststore

#import ca certificate into admingui-truststore (only if the ca certificate need to be replace)
$ keytool -import -file caIntermediate.pem -keystore admingui-truststore.jks -alias gateway_intermediate 
$ keytool -import -file caRoot.pem -keystore admingui-truststore.jks -alias gateway_root

#if you are replacing the self-sign certificate it must be trusted by the gateway and admingui
$ keytool -v -export -rfc -keystore admingui-keystore.jks -alias gateway -file adminguiCert.pem
$ keytool -import -file adminguiCert.pem -keystore gateway-truststore.jks -alias admingui_gateway
$ keytool -import -file adminguiCert.pem -keystore admingui-truststore.jks -alias admingui_gateway

Test Data Loader

Creating and managing test data for use with the CONNECT reference implementation can be handled directly through the Admin GUI. This feature manipulates data in the CONNECT database tables that were created as part of the initial CONNECT setup and deployment process. Future enhancements for converting and exporting the data for use in other test systems are under consideration.

Patient data

Patients that have already been created are listed based on the defined patient identifier (note that this is not the database logical ID). 

Creating and editing patient data is intuitive via the Admin GUI. Click New to add a new patient or select an existing patient and click View/Edit to view and/or edit the data. Be sure to save the data entered in each accordion section separately.

To delete a patient record, simply select the patient and click Delete.

Document data

Documents that have already been created are listed based on the defined document identifier (note that this is not the database logical ID). 

Creating and editing document data is intuitive via the Admin GUI. Click New to add a new document or select an existing document and click View/Edit to view and/or edit the data. Be sure to save the data entered in each accordion section separately.

To delete a document record, simply select the document and click Delete.

Direct Configuration

Several aspects of the Direct configuration from domains to certificate storage locations are defined in the Admin UI. Certificates, trust anchors, and trust bundles themselves can be stored using the Admin GUI tool in the configuration service and accessed through the web service interface. CONNECT has leveraged the Direct RI's config web service for these features.

Configuration is separated into five component:

• Domains - The list of domains managed by the STA agent.
• Certificates - Private and optionally public certificate storage.
• Trust Anchors - Trust anchor certificate storage for coarse grain anchor configuration.
• Trust Bundles - Collections of anchors published by trust communities.
• Settings - Configuration settings for numerous components of a HISP. These are generally higher level configuration settings. 

NOTE - Domains, certificates, trust anchors, and trust bundles have specific configuration elements stored in the settings component.

Domains

The Domains page under Direct Configuration menu on the left navigation pane describes the list of domains that will be managed by the HISP/STA and allows for managing and updating domain configurations.

Fig 6: Direct Configuration - Domains screen

The domains list displays all domains associated with the HISP.

Table 6 - Domain List screen display

Create New Domain

Create new domains for the HISP that are managed by the STA

Direct Configuration - Create Domain screen

Edit Domain

View or edit the configurations for a selected domain.

Domain Name

Edit the domain name associated with the domain.

Direct Configuration - Edit Domain -> Domain Name screen

Addresses

Edit the email addresses associated with the domain.

Direct Configuration - Edit Domain -> Addresses screen

Anchors

Anchors stored in the configuration service are added and maintained in the Anchors tab of the configuration service Edit Domain page.

Direct Configuration - Edit Domain -> Anchor screen

Edit Domain - Stored Anchors

Edit Domain - Add Another Anchor

Trust Bundles

Configured trust bundles can be added to a domain from the Trust Bundles tab of the configuration service Manage Domains page. Each anchor in the bundle is used to create trust between the domain and the system represented by the anchor. Similar to configuring anchors, each bundle can be set to incoming or outgoing to control the direction of trust.

Direct Configuration - Edit Domain -> Trust Bundles screen

Assigned Trust Bundles panel lists the trust bundles that are associated with the selected domain

Edit Domain - Assigned Trust Bundles 

Edit Domain - Add Another Trust Bundle

Agent Settings

Direct Configuration - Agent Settings Screen

Agent Settings

Anchor Store Agent Settings

Anchors define the certificates that create trust between domains. Each domain must have at least one outgoing or incoming trust anchors. Anchors can be retrieved from different source mediums including the configuration service.

The anchor storage medium is configured in the settings page of the configuration UI. All settings are configured as simple name/value pairs as defined below

Note – Trust bundles are defined using web services ONLY. Trust anchors can be configured using WS and LDAP, Keystore

Anchor Store Agent Settings parameters

Web Service Anchor storage

Anchors stored in the configuration service are added and maintained in the Anchors tab of the configuration service Manage Domains page.

Non Web Service Anchor Storage

Anchors stored in non web service mediums such as LDAP or a keystore require a list of aliases or search criteria to locate the certificates in the anchor store. Each domain requires one of two entries in the settings component: one for a list of outgoing anchors and/or one for a list of incoming anchors. The settings use the following format:

• <domainName>IncomingAnchorAliases
• <domainName>OutgoingAnchorAliases

The value for each setting is a comma delimited list of the aliases or search criteria that identify the anchor in the anchor store. 

Example settings for the domain direct.connectopensource.org using a keystore:

Public Certificate Store Agent Settings

Similar to anchors, public certificates can be retrieved from different source mediums. The public certificate storage medium is configured in the Agent settings page.

Public Certificate Store Agent  Settings parameters

Private Certificate Store Agent Settings

The private certificate storage medium is configured in the Agent settings page 

Private Certificate Store Agent  Settings parameters

Add New Agent Setting

Selecting Add New Agent Setting option in the Agent Settings page opens up this page for adding key value pairs for agent settings.

Direct Configuration - Add New Agent Setting

Trust Bundles

Trust bundles are a collection of trust anchors that are intended to represent a trust community and generally meet a common set of criteria to be included in the bundle. Trust bundles are packaged into a single file using the PKCS7 standard and distributed via a known URL (the location is discovered out of band). Trust bundles are configured in the Trust Bundles tab of the configuration UI tool.

These bundles as wholistic objects and CONNECT does not support exclusion of anchors within the bundle. This is partly because the definition of a bundle indicates that each anchor within the bundle meets the same minimal requirements. The decision to include a bundle becomes a simple binary decision, you either trust the bundle or you don't.

Bundles are configured separately from domains as opposed to the importing of anchors per domain. Each bundle is identified by a name and it’s URL.

Select Trust Bundles tab to display a list of bundles that are imported into the configuration.

Direct Configuration - Trust Bundles screen

Trust Bundles

Add New Trust Bundle

Direct Configuration - Add New Trust Bundle screen

The Add New Trust Bundle dialog will display the following information:

Add New Trust Bundles screen fields

Edit Trust Bundle

Direct Configuration - Edit Selected Trust Bundle screen

The Edit Trust Bundle dialog will display the following information:

Edit Selected Trust Bundle screen fields

Certificates

Similar to anchors, public certificates can be retrieved from different source mediums.

The public certificate storage medium is configured in the settings page of the configuration UI.

The private certificate storage medium is configured in the settings page of the configuration UI.

 Private and public certificates stored in the configuration service (WS StoreType) are added and maintained in the Certificates tab of the Direct Configuration page       

Direct Configuration - Certificates screen     

Edit Selected Trust Bundle screen fields                  

Add New Certificate

Direct Configuration - Add New Certificate screen 

Add New Certificate screen fields

MessageSettings

The following settings describe the location where processed messages should be stored. This is intended for debug purposes only and should not be set in a production environment.

MessageTypes:

• Raw: The raw message that entered the SMTP agent.
• Outgoing: If the message is determined to be an outgoing message, the security and trust processed outgoing message.
• Incoming: If the message is determined to be an incoming message, the security and trust processed incoming message.
• Bad: Messages that failed to be processed or caused other errors to be the thrown.

Table 20 - Message Setting values

Connection Management

Connection Management provides the administrator the option to view and manage connections to remote partners/gateways. The View External Connections screen as shown below is a view of the connections that are configured in the Web services registry or the exchangeInfo file organized by the Business entity i.e., the remote gateway organization. This screen allows for a ping utility that pings a particular service to determine if the service is up and running. This will help system administrators test service endpoints and troubleshoot firewall issues, certification validation issues and other connectivity both before functional testing with remote gateways and organizations and to investigate any issues that may arise in production due to changes in the local or exchange partner's gateway.

Connection Management -> View External Connections screen 

External Connection screen fields

Exchange Management

Exchange Management provides a way for user to view/edit Exchange information, refresh/download Exchange information and to view and manage connections to remote partners/gateways. The View Exchange Servcies screen as shown below is a view of the exchange information that are configured in the exchangeInfo file organized by the general exchange information and Organizations  i.e., the remote gateway organization. This screen allows users to configure exchange refresh process, initiate Refresh Exchange, add/delete an Exchange, enable/disable Exchange and to provides a ping utility that pings a particular service/or all services to determine if the service(s) is up and running. This will help system administrators test service endpoints and troubleshoot firewall issues, certification validation issues and other connectivity both before functional testing with remote gateways and organizations and to investigate any issues that may arise in production due to changes in the local or exchange partner's gateway.

External Connection screen fields

Exchanges Refresh - Schedule, Manual and Locked

The exchanges refresh automatically on the Refresh-Interval and can be force to refresh manually; during Status:Refresh-in-Progress a lock is placed upon the exchange-manager to prevent the modification to ExchangeInfo.xml.

When the Exchange-Manager is Status:Refresh-in-Progress the following functions will be disable:

• Delete
• Save
• Refresh Exchanges
• Enabled
• Disabled

Refresh Exchanges

Clicking on Refresh Exchanges will initiate the Refresh Exchanges process. This will download web services information for all Enabled Exchanges. Below is a screenshot of Exchange Refresh status. 

If Refresh Exchange for an exchange is not successful for any reason, the Exchange name will be displayed in Red.

Following is a list of  Refresh Exchange Stages and the associated statues displayed on Exchange Refresh Status screen:

Adding an Exchange

User can add an Exchange by clicking on New button in Exchanges section. Following information is required for adding an exchange:

• Name
• Type
• URL

Deleteing an Exchange

User can delete an Exchange by selecting one from Exchanges list.

Configuration Management

CONNECT provides various property files that manage gateway configuration. Traditionally these property files are manually updated by the system administrators by locating these files deployed at time of installation in the server directory and then editing these files. With the new Configuration Management tool under the Admin GUI, system administrators with limited technical knowledge will be able to update these property files through a GUI interface that both allows them to view the current set of the properties along with descriptions of appropriate values and update them instantly. This simplifies the overall process for the system administrator.

A list of the gateway and adapter properties that are configured in CONNECT can be found here - Gateway properties and Adapter properties

Gateway Properties

Configuration Management -> Gateway Properties screen 

Gateway Properties screen fields

Adapter Properties

Properties -> Adapter Properties Screen

Adapter Properties screen fields

Audit Properties   

Configuration Management -> Audit Properties screen 

Audit Properties screen fields

Internal Endpoints

This interface allows system administrators to edit internal web-services hosted by CONNECT.

Internal Endpoints Properties screen fields

Cross-Gateway Query Client

The Cross-Gateway Query Client is a testing tool that is used to validate and test data exchange services like Patient Discovery, Query for Documents and Retrieve Documents. The client allows the system administrator to run preliminary tests to ensure that a particular remote gateway is up and running and can respond to service requests. The client tool allows the users to search for patients in a targeted remote community and retrieve documents.

Search patient

The Patient Search tab is the default tab on this screen which allows the user to search patients by demographics. 

Patient Search Screen

Patient Search screen fields                  

Patient Search Results

Patient Search results fields                  

Search/View documents

Selecting the View Details option on the Patient Search screen opens up the Document Search screen where the user can enter in search criteria for the documents. The screen displays the Current Patient Details from the PD response and provides the ability to search documents by document type and creation date ranges.

Document Search screen

Document Search screen fields                  

Document Query Results

Document Query results 

View Document Metadata 

View Document 

Logging

User can search Audit and Failure events through Logging GUI.

Audit Search

Audit search is a tool to view and search/filter audit logging events from the Admin GUI without logging into database to track events. Adopters can take advantage of the Audit Search from the System Administrative Module if they choose the Database Audit Logging Implementation. 

The audit search on this screen which allows the user to search audit events by providing Audit query parameters.

Audit Search Screen

Audit Search screen fields                  

Audit Search Results

Audit Search Results

View Audit Message XML details:

Failure Logging

The failure logging screen allows user to search for a failure event in a service workflow. The user may then view the details of a given error event to learn more about the cause of the service failure.

Failure Logging Screen

Failure Logging – Search Results

Error Event – full technical details

This view will show various details about the Error Event, such as the time in which the exception was caught, the exception message, the class and method that the failure occurred in, as well as the exception thrown accompanied by the full stack trace.