NAV
json

Patient Data Exchange API Extension

This is an extension of the PatientDataExchange API. In that specification, an optional profile_url can be provided. If provided, a single-sign on process can be used to sign on PioneerRx users automatically into the Vendor’s systems.

Change Log

Version Date Change Comments
1 02/14/2017 Initial Document Version for V 1

PioneerRx User Experience

PioneerRx has a ui for editing patients and enrolling them into a vendor’s system via api calls. When a profile URL is provided by a vendor, users can select to open that profile. This will open a browser session within the PioneerRx User Interface. When Single-Sign On is setup, it will allow the logged in user to be signed on automatically, or prompt if information is missing for the SSO function.

PioneerRx Software Configuration

The Vendor must select one of the options below and inform PioneerRx Development of the option to be used. Backend configrations will be used to determine which method is in use and how SSO should work.

Communication

The API will use HTTPS Web Services to communicate between the 2 systems.
Insecure http traffic will not be allowed.

Data Definitions

There are a number of elements that can be exchanged. The table below explain what each of these elements refers to.

Data Element Definition
applicationID A Unique Identifier (preferably a GUID aka UUID) that all PioneerRx locations will send. This is a token that only PioneerRx development will be exposed to, and is authorizing the PioneerRx application. Other systems you interface with can send you a different ID so that you can reuse this interface. This is a form of “shared secret” between the vendor and PioneerRx. This ID will not be shared with any other vendor and will only be used to authorize PioneerRx with the Vendor system.
npi The Pharmacy NPI number (if available)
ncpdp The Pharmacy NCPDP number (if available)
pioneerRxUserID A GUID (36 characters) unique identifier of the logged in user from the PioneerRx pharmacy system. This is the ID of an employee at a specific pharmacy. If a pharmacy is part of a PioneerRx’s optional Central Store Chain, this ID will be the same for this employee across that specific chain, but otherwise, it will be different per employee per pharmacy location. For example if a chain has 5 stores and uses our “Central” product, the userID for a single person that works at both stores will be the same. However, if say a pharmacist works at multiple stores (example could be a relief pharmacist), and those stores are not part of Central – they will have totally different Guids for each store.
vendorUserID The UserID (or if preferred username) of the employee in the vendor system. To use this feature, users would need to pre-define this in the PioneerRx system.
vendorPassword The password for the employee in the vendor system. To use this feature, users would need to pre-define this in the PioneerRx system.
firstName The first name of the employee. Limited to 50 characters.
lastName The last name of the employee. Limited to 50 characters.
workstationName The name of the workstation (aka local computer name) used to access the url. Limited to 15 characters.

Single-Sign-On Method

Token Based

For Token Based SSO, a POST will be sent from PioneerRx to the Vendor’s system. Data will be transmitted to the Vendor in this post, which in turn will respond with a token or an error. This token will then be used to open the profile_url. This will occur everytime the user opens a profile_url. The token provided can, and we recommend that it should, be time limited and expire after a responsable amount of time. We suggest 1 minute.

The Vendor must determine the POST URL to be used and communicate this to PioneerRx prior to integration. In addition, the Vendor must determine if they want to allow PioneerRx to authenticate the users or require the Vendor to authenticate.

PioneerRx Authenticates the User

{
  "applicationID":"F089E5DB-1B5D-4574-8759-FCB9225C252D",
  "npi":"1234567890",
  "ncpdp":"1234567",
  "pioneerRxUserID":"9C2BABC8-A809-42BD-B2DA-9885252EC878",
  "firstName":"John",
  "lastName":"Doe",
  "workstationName":"MyPC"
}

When PioneerRx authenticates the user, the employees will not need to have a vendorUserID and vendorPassword pre-defined in the system, instead the vendor system will authenticate them based on the information provided by the PioneerRx Application.

PioneerRx will transmit the following data fields (using camel casing as shown) in JSON to the POST URL: applicationID, npi, ncpdp, pioneerRxUserID, firstName, lastName, workstationName

Vendor Authenticates the User With UserID

{
  "applicationID":"F089E5DB-1B5D-4574-8759-FCB9225C252D",
  "npi":"1234567890",
  "ncpdp":"1234567",
  "pioneerRxUserID":"9C2BABC8-A809-42BD-B2DA-9885252EC878",
  "vendorUserID":"jdoe",
  "firstName":"John",
  "lastName":"Doe",
  "workstationName":"MyPC"
}

PioneerRx will authenicate the user in its own system, a UserID will be setup per employee in the PioneerRx system that maps to the vendor system. If this is missing, the user will be displayed an error message with instructions on how to correct. The mapped userID will be transmitted in the POST to the vendor system, which in turn will validate it against its system. The vendor system can return a user appropriate error message in the Response’s userErrorMesssage attribute.

PioneerRx will transmit the following data fields (using camel casing as shown) in JSON to the POST URL: applicationID, npi, ncpdp, pioneerRxUserID, vendorUserID, firstName, lastName, workstationName

Vendor Authenticates the User With UserID and Password

{
  "applicationID":"F089E5DB-1B5D-4574-8759-FCB9225C252D",
  "npi":"1234567890",
  "ncpdp":"1234567",
  "pioneerRxUserID":"9C2BABC8-A809-42BD-B2DA-9885252EC878",
  "vendorUserID":"jdoe",
  "vendorPassword":"Password*",
  "firstName":"John",
  "lastName":"Doe",
  "workstationName":"MyPC"
}

PioneerRx will authenicate the user in its own system, a UserID and Password will be setup per employee in the PioneerRx system that maps to the vendor system. If this is missing, the user will be displayed an error message with instructions on how to correct. The mapped userID and password will be transmitted in the POST to the vendor system, which in turn will validate it against its system. The vendor system can return a user appropriate error message in the Response’s userErrorMesssage attribute.

PioneerRx will transmit the following data fields (using camel casing as shown) in JSON to the POST URL: applicationID, npi, ncpdp, pioneerRxUserID, vendorUserID, vendorPassword, firstName, lastName, workstationName

Results

Example Token:
23i9ujdpoijd2893jpdoijpo3ij2

If the POST was successful, it will return a status code of 200. If unsuccessful, it should return a code other than 200, for example 500.

The Response Data should be a JSON string with the following fields

StatusCode: 200
{
  "token":"23i9ujdpoijd2893jpdoijpo3ij2"
}

StatusCode: 500
{
  "debugErrorMessage":"Unable to login, Internal Error Code 3452.89",
  "userErrorMesssage":"Unable to login, please contact support for assistance."
}
Field Description
token The token returned by the service. This should be null or empty if it was unsuccessful.
debugErrorMessage An optional error message that give technical details about the error and will be logged if errored.
userErrorMesssage An optional error message that is meant for end users and will be shown to the logged on user.

Token in profile_url

The Token from the POST will be applied to the profile_url, as follows:

If a {TOKEN} string is present (case sensitive), it will be replaced with the token.

If {TOKEN} is NOT present, a “token” parameter will be appended to the Query String of the URL.

Browser Support

Once a token is obtained, PioneerRx will either open the profile_url inside a popup window of the PioneerRx application, or open using the default browser of the workstation. PioneerRx may change between these based on the interactions made by the user and both should be assumed can occur at a pharmacy.

Due to technical requirements of the .net framework, Internet Explorer is used when PioneerRx opens the URL as a popup within the application. In addition, most pharmacies do not alter their workstation’s default browser, and being Windows based, the default is most commonly Internet Explorer. PioneerRx’s currently requires Internet Explorer 8 or higher. We do not support lower versions of IE.

If your product cannot support current versions of alternative browsers (such as Edge, Chrome, Firefox, Opera, etc), please notify PioneerRx Development during your onboarding so that we can discuss options for forcing Internet Explorer.

PioneerRx Contact Information

For all technical and business questions, concerns, or issues, please email PioneerRxDataPrograms@PioneerRx.com.

This email is monitored by our data integration team and someone will be in contact once reviewed. If a call is needed, please email us your topics and questions and we will setup a call with the appropriate individuals.

This is not meant to be given to users (ie, pharmacies). The most appropriate solution for them, if to use the PioneerRx Support Request features we have to ask for assistance.

If not contacted in the appropriate ways, persons may have to wait longer than necessary as requests then have to be internally re-routed at PioneerRx.

Questions To Answer for Integration

The following is a recap of the questions PioneerRx will need to have each Vendor answer for the integration to make sure they are configured correctly:

  1. What type of User Validation will be used? PioneerRx Authenticates the User, Vendor Authenticates the User With UserID, Vendor Authenticates the User With UserID and Password

  2. What is the POST URL that PioneerRx will call to transmit the token request information? e.g. https://www.mydomain.com/api/PioneerRxTokenRequest

  3. What browser(s) and version(s) do you support? e.g. IE (9+), Chrome (current)

  4. If issues occur in vendor system, who should users contact for assistance (name, email, phone, etc)? e.g. Vendor Support, support@vendor.com, 1-555-555-1234

  5. Who is the technical contact for the integration with PioneerRx at the Vendor (name, email, phone, etc)? i.e. this is the person(s) that PioneerRx technical team can reach for future issues, this will not be shared with users.

json