Configuring Smart Center with QGenda
Integration Overview
Spok’s integration with QGenda, a provider of cloud-based automated physician scheduling solutions, allows physician on-call schedules to be pushed into the Spok Care Connect on-call schedules. This enables Spok to route messages to both people and third-party systems based on scheduling information that resides in QGenda. Because up-to-date schedules are available to physicians, nurses, operators, and other staff looking to coordinate care around the clock, they can be more productive and spend more time with their patients.
The initial implementation with QGenda is a one-way relationship where the data in QGenda is considered the record of truth. This has several important implications for the process flow of the OnCall feature in Smart Center. Most importantly, changes that are made to the OnCall schedule through Smart Center are not pushed to QGenda. For more information, see Schedule Synchronization Workflow below.
- Changes to the OnCall schedule that need to be immediately implemented must be changed in both the QGenda application and in Smart Center.
- Changes that can wait until the next scheduled download from QGenda can be made in just the QGenda application and will be updated in Smart Center after the next QGenda update.
- Changes that are only made in Smart Center will be overwritten after the next QGenda update.
- Someone at the customer site with access to QGenda must make the manual changes to the QGenda system.
Prerequisites
- Spok PSG must provide a list of On-Call Messaging IDs from the Smart Suite database to QGenda.
- The customer's IT department must open port 9722 in their firewall.
- The customer's IT department must allow access to QGenda’s IP address (this is obtained from QGenda).
Integration Process
- Spok Professional Services Group (PSG) provides a list of customer messaging ids to QGenda Customer Success Consultant. This can be obtained from the Listing Report or the DBA.
- QGenda Customer Success Consultant maps the messaging IDs in the QGenda app.
- QGenda Customer Success Consultant works with the customer to confirm their Tasks (On Call Groups) and Staff (People) are set up in QGenda and discuss any irregularities.
This includes configuration of the Task Shifts for Start and End dates. - QGenda Customer Success Consultant sets up the Spok Integration and then confirms with the Spok PSG rep that they can successfully make a connection to port 9722.
-
QGenda Customer Success Consultant initiates a test transaction which adds Task (on call group assignment) to a Staff (person) and the Spok PSG rep confirms that the transaction appears in the Smart Center app.
Smart Suite and QGenda On-Call Fields
The link between Smart Center and QGenda is the Messaging ID. The Messaging ID should not be modified, if a modification is required please work with the QGenda Customer Success Consultant to ensure that the integration is maintained.
Supported On-Call Fields
QGenda supports data for the following On-Call fields:
|
API |
GUI |
|---|---|
|
group_mid |
Messaging ID (On Call Group) |
|
mid |
Messaging ID |
|
start_date |
Start (Date) |
|
end_date |
End (Date) |
|
priority |
Priority |
|
remark |
Remark |
Unsupported On-Call Fields
Currently, QGenda does not support these On-Call fields:
| API | GUI |
|---|---|
|
timezone |
Time Zone |
|
assignment_role |
Title |
Terminology Differences
Smart Suite and QGenda use different terminology for some On-Call fields. The table below shows the difference in the terminology.
To avoid confusion of different names in the data between systems, the best practice is to match the names for Smart Center On-Call Group/Function/Name with the Staff/Task Name in QGenda. This effort must be performed by Spok PSG and the QGenda Customer Success Consultant.
|
Smart Suite |
QGenda |
|---|---|
|
Department |
Company |
|
Person / Function |
Staff |
|
On Call Group |
Task |
Adding People, Functions, and Groups
To add a person, function, or on-call group, you must coordinate with a QGenda Customer Success Consultant to configure the integration with Smart Center.
Send an email to the QGenda Customer Success Consultant that includes the following details:
Person/Function
| Hospital/Clinical Name | Smart Suite Customer |
|---|---|
| Messaging ID | Person /or Function Messaging ID |
| Name | Last Name, First Name |
On-Call Group
| Hospital/Clinical Name | Smart Suite Customer |
|---|---|
| Group Messaging ID | On Call Group Messaging ID |
| Group Name | On Call Group Name |
Schedule Synchronization Workflow
QGenda calls the XML-based Spok Smart Suite API over HTTPS to query the Spok schedule and to add or remove assignments as necessary. This process is repeated every 15 minutes.
Because QGenda is considered the source of truth, this is a one way process in the sense that data is not added to QGenda from the Spok schedule, but rather QGenda only adds assignments to Spok or deletes them from Spok.
However, in terms of data transfer, data will transfer to and from Spok as QGenda makes API calls.
Security Setup
For QGenda to successfully communicate with the Spok server residing in a customer’s infrastructure, you must complete the following steps depending on whether the Spok server is publicly accessible.
Public IP
The Spok server is publicly accessible.
A firewall rule must be added to allow traffic from QGenda’s IP addresses (which is available upon request). The recommended port is 9722. QGenda will configure a public IP in the QGenda UI defining the integration settings.
Private IP
The Spok server is private with no public IP.
QGenda and the client establish a site-to-site IPSec VPN between QGenda’s infrastructure and that of the client’s Spok server. This will require a setup process where details like IPs and certificates from both parties are shared and configured respectively. Once this is done, QGenda will input the private IP of the Spok server into QGenda’s UI. QGenda’s servers will be able to connect to this private IP via the VPN tunnel. The client can configure their network such that QGenda servers should not be able to access any other resource on their infrastructure.
Regardless of whether QGenda accesses the Spok server via a public IP or over VPN, QGenda requires that a valid SSL certificate be installed on the Spok server. If that certificate is signed by the enterprise and not a root-level authority, QGenda needs the public certificate so that it can be installed on QGenda’s servers to establish trust.
QGenda’s servers are configured to support TLS, including version 1.2. If the Spok server also supports TLS 1.2, the integration will automatically use that security protocol during data transmission.
SSL Certificates
QGenda requires that a valid SSL certificate be installed on the Spok API server. The SSL certificate is used when the QGenda integration sends https requests to the Spok API server. It is required regardless of whether a VPN connection is used.
The certificate can either be signed by a universally trusted public top-level issuer or by the customer’s enterprise root certificate authority (CA).
- If using a public top-level issuer, the certificate is already trusted and no sharing of certificates is required.
- If the customer's CA signs the certificate, QGenda needs the public certificate chain in order to trust the root CA (as well as the intermediate certificate, if using one).
You can work with the QGenda Customer Success Consultant to provide this information.
For more information about installing SSL certificates on RHEL, see https://aboutssl.org/how-to-install-ssl-certificate-on-red-hat-linux/.
API
QGenda uses the following API methods:
GetGroupsAssignmentsXml
| Description | Returns all assignments from Spok within a date range for a single task. QGenda currently queries 180 days of data. |
|---|---|
| Parameters | Task ID, Start Date, End Date, Priority, Remark |
| Returns | Array of assignments with staff IDs, start times, end times, Priority, Remarks, and assignment IDs. |
AddOnCallAssignment
| Description | Adds an assignment to Spok. |
|---|---|
| Parameters | Task ID, Staff ID, Start DateTime, End DateTime, Priority, Remark |
| Returns | Assignment ID (if successful). |
DeleteOnCallAssignment
| Description | Removes an assignment from Spok. |
|---|---|
| Parameters | Spok’s assignment ID (sequence number) |
| Returns | Success/Fail code |
For additional details about AmcomAPI, see User Guide Smart Suite AmcomAPI for your version of Smart Suite.
API Troubleshooting
The following features exist for error handling:
- QGenda is alerted on all API transaction errors.
- If a communication error occurs in QGenda, the transactions remain in the queue and are resubmitted until they succeed.
If an error occurs while processing XML requests, use Troubleshooting Guide AmcomAPI to help locate and identify the error.
QGenda Integration Example
The screenshot below shows an example of the QGenda side of the integration.
All QGenda configuration items will be handled by QGenda.
Smart Suite information is available in the Profiles > Integrations tab. In this example, the following displays:
- Host Name: The Smart Suite DB server IP address where the API is running.
- Connection Port (our default of 9722)
- Smart Suite Messaging ID information
Integration Troubleshooting
If a customer reported Smart Center issue is determined to be with QGenda, please email all relevant information to: spokhelp@QGenda.com. The email will serve as an escalation to QGenda.