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.

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 Services 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.