Product Guide
StatusSupport

TOC Lens Implementation Guide

Read Transition of Care Lens episodes through GraphQL or REST, and set up Zushooks to get notified about new episodes.

API Access

The Transition of Care lens can be accessed via GraphQL or via REST API

GraphQL

The GraphQL endpoint allows you to fetch only the information you need for a given Episode of Care resource. Below are two examples:

By ID

 query {
  EpisodeOfCareList(
    id: "040bf4e1-6b25-4d9c-a5d6-6177a3aab921"
    filter: {
      tag: {
        allmatch: ["https://zusapi.com/summary", "TransitionsOfCare"]
      }
    }
  ) 
  {
     id
     meta {
        tag {
            system
            code
        }
     }
     period {
        start
        end
     }
     extension {
        url
        extension {
            url
            valueReference {
                reference
            }
        }
        valueCodeableConcept {
            coding {
                code
                system
                display
            }
        }
        valueString
        valueReference {
            reference
        }

    
     }
  }
}

By UPID

query {
  EpisodeOfCareList(
    upid: "b88cb6e7-4312-4f0f-b356-a5f4b2d0ed1e"
    filter: {
      tag: {
        allmatch: ["https://zusapi.com/summary", "TransitionsOfCare"]
      }
    }
  ) 
  {
     id
     meta {
        tag {
            system
            code
        }
     }
     period {
        start
        end
     }
     extension {
        url
        extension {
            url
            valueReference {
                reference
            }
        }
        valueCodeableConcept {
            coding {
                code
                system
                display
            }
        }
        valueString
        valueReference {
            reference
        }

    
     }
  }
}

REST API

The REST API allows for both look up by ID as well as UPID. Below are some examples

  • By ID: GET request to https://fqs.zusapi.com/rest/EpisodeOfCare/{{RESOURCE_ID}}
  • By UPID: GET request to https://fqs.zusapi.com/rest/EpisodeOfCare?upid={{UPID}}
🚧

Filtering

As of this writing, the REST API does not support filtering by tags. To ensure that you receive only the Transition of Care Lens, you will need to filter post query for resources with a meta.tag value of {"system": "https://zusapi.com/summary", "code": "TransitionsOfCare" } . See example resource and output details in previous section.

ZusHooks

This section details how to leverage ZusHooks to automate workflows as data is updated in Zus.

  1. Create a HTTP endpoint in your system with the following attributes:
    1. If desired, OAuth2 or Basic HTTP authentication
    2. Handles the expected payload being sent (see documentation for more examples)
  2. As a Builder Admin, make the following request to the Zus API:
PUT https://api.zusapi.com/subscriptions/A_UNIQUE_NAME_FOR_YOUR_SUBSCRIPTION

{
    "data": {
        "type": "zushooks/subscription",
        "attributes": {
            "filter": {
                "resource": "EpisodeOfCare",
                "fieldComparator": "JQ",
                "query": ".period.start != null and ((.period.start[0:10] + \"T00:00:00Z\") | fromdateiso8601) > (now - 604800) and (reduce .extension[] as $item ({}; . or $item.url == \"https://zusapi.com/fhir/identifier/universal-id\")) and (reduce .meta.tag[] as $item ({}; . or $item.system == \"https://zusapi.com/summary\" and $item.code == \"TransitionsOfCare\"))" 
            },
            "webhook": {
                "authType": "basic",
                "username": "a_username",
                "password": "a_password"
            }
        }
    }
}

Note the JQ query filters for only episodes of care that started within the past week.

  1. The payload that Postman will receive is something like this:
{
    "message_id": "123",
    "source": "com.zushealth.zushooks",
    "time": "2023-07-17T13:48:32Z",
    "resourceId": "EpisodeOfCare/5cdaa19b-fb1c-4c68-80f3-9bccce216bdc",
    "ownerId": "builder/abc",
    "resourceIncluded": false
}
  1. As an authenticated user or application, run a query against FQS to get the resource as well as the associated UPID:
GET https://fqs.zusapi.com/rest/EpisodeOfCare/5cdaa19b-fb1c-4c68-80f3-9bccce216bdc

Including the resource in the ZusHook Message

🚧

Be mindful of PHI

Sending the message in the ZusHook requires you, as the implementer, to ensure your messages are sent to the correct endpoint. Misconfiguration can result in PHI data leakage.

Zus recommends to query for the resource ID in FQS upon receiving a ZusHook message in lieu of sending the entire resource in the message.

  1. (Optional) As a builder admin, create a new app client through the Zus API. This will allow for the Zus Hook message to include the actual resource
{
    "data": {
        "type": "auth/app-clients",
        "attributes": {
            "name": "Client - Zus Custom M2M Client",
            "type": "machine_to_machine",
            "userType": "builder"
        },
        "relationships": {
            "auth/builders": {
                "data": {
                    "type": "auth/builders",
                    "id": "asdfasdfasdf"
                }
            },
            "auth/roles": {
                "data": {
                    "type": "auth/roles",
                    "id": "02d9cc02-539b-4d5f-a45b-8d55c13cfff6"
                }
            }
        }
    }
}
  1. As a Builder Admin, make the following request to the Zus API:
PUT https://api.zusapi.com/subscriptions/A_UNIQUE_NAME_FOR_YOUR_SUBSCRIPTION


{
    "data": {
        "type": "zushooks/subscription",
        "attributes": {
            "filter": {
                "resource": "EpisodeOfCare",
                "fieldComparator": "JQ",
                "query": ".period.start != null and ((.period.start[0:10] + \"T00:00:00Z\") | fromdateiso8601) > (now - 604800) and (reduce .extension[] as $item ({}; . or $item.url == \"https://zusapi.com/fhir/identifier/universal-id\"))" 
            },
            "webhook": {
                "authType": "oauth2",
                "webhookUrl": "HTTPS_ENDPOINT_URL",
                "clientId": "FROM_STEP_1",
                "clientSecret": "FROM_STEP_1", 
                "tokenUrl": "https://auth.zusapi.com/oauth/token",
                "audience": "https://api.zusapi.com"
            }
        }
    }
}
  1. The payload that Postman will receive is something like this:
{
    "message_id": "123",
    "source": "com.zushealth.zushooks",
    "time": "2023-07-17T13:48:32Z",
    "resourceId": "EpisodeOfCare/c020d8eb-ea59-492b-862f-c27f9556f628",
    "ownerId": "builder/abc",
    "resourceIncluded": true,
    "resource": {
       // the episode of care FHIR resource
    }
}
📘

Notes

  • Note the JQ query filters for only episodes of care that started within the past week

Related pages

Updated 15 days ago

Did this page help you?