Skip to main content
Older versions of Internet Explorer will not support certain site features. Chrome, Safari, Firefox, and Edge will provide the best experience.
Resources

 

Spok

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

  1. 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.
  2. QGenda Customer Success Consultant maps the messaging IDs in the QGenda app.
  3. 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.
  4. 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.
  5. 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)

Unsupported On-Call Fields

Currently, QGenda does not support these On-Call fields:

API GUI

priority

Priority

timezone

Time Zone

remark

Remark

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
Returns Array of assignments with staff IDs, start times, end times, and assignment IDs.
AddOnCallAssignment
Description Adds an assignment to Spok.
Parameters Task ID, Staff ID, Start DateTime, End DateTime
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 7.0.

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.