How to do a single sign-on with the Caredove FHIR API

Introduction:

In this guide, we will walk you through the process of executing a single sign-on (SSO) with Caredove by including a user ID within the cds-service-request payload. This user ID may take the form of an email address, a system ID, or similar identifiers.

This configuration is ideal for customers who wish to receive notifications and updates regarding their referrals within their Caredove accounts.

By following the instructions below, you can launch the Caredove UI in "App mode" whether as an inline app or a new tab. In this mode, you can send the cds-service-request payload to Caredove, taking advantage of features such as single sign-on (SSO) and the pre-loading of contextual registrant data for filling referral forms.

Step 1: Prepare Your cds-service-request Payload:

Create a cds-service-request payload that includes the necessary information for launching Caredove in "App mode".

You can review a full example in the Caredove Developer Portal documentation, section Launch App.

Step 2: Customize the cds-service-request payload to enable single sign-on:

Within ServiceRequest.identifier first element, please include the following information as outlined below:

For the type element, assign the value SSO
In the system element, specify your company's URL that defines the namespace for the ID (value) element.
The value element will hold the actual ID.

See an example example below:

"identifier": [
    {
        "type": "SSO",
        "system": "https://www.referreragencyinc.com/identifiers/your-internal-id-reference",
        "value": "6037aa33-db83-5cb7-bdb0-b029e8c44a77"
    }
]

Caredove will use this information to reconcile the referral with the user's account. Here is a sample code snippet that shows how to include the ServiceRequest.identifier element into the cds-service-request payload:

{
    "resourceType": "Bundle",    
    ...,
    "entry": [
        {
            "resource": {
                "resourceType": "MessageHeader",                
                ...,
                "eventCoding": {
                    "system": "https://ehealthontario.ca/fhir/CodeSystem/message-event-code",
                    "code": "cds-service-request"
                },                
                ...
            }
        },
        {
            "resource": {
                "resourceType": "ServiceRequest",                
                ...,
                "identifier": [
                    {
                        "type": "SSO",
                        "system": "https://www.referreragencyinc.com/identifiers/your-internal-id-reference",
                        "value": "6037aa33-db83-5cb7-bdb0-b029e8c44a77"
                    }
                ],                
                ...
            }
        },        
        ...
    ]
}

Step 3: Submit the Payload

Submit the prepared payload to Caredove and we will process the request, launching Caredove in App mode with the specified configuration according to the instructions stated in our Caredove Developer Portal documentation.

Additional Resources: For more detailed information about launching Caredove in App mode and, in general, the Caredove FHIR API, you can refer to the official documentation available at Caredove Developer Portal, section Launch App.

If you encounter any issues or have further questions, please feel free to reach out to our Caredove support team for assistance.

FHIR Extension: LaunchString

FHIR Extension: HealthcareService Webpage

FHIR Extension: eReferral Form URL

FHIR System: Caredove HealthcareService Identifier