Overview

To set up and test Signal workflows in Sandbox, you will need to follow the same steps required to configure Signal in production. The one key difference is that you will need to trigger Signal Alert webhook notifications to your callback endpoint in Sandbox, in order to simulate the experience of receiving an ADT or Network Alert, or identifying a new patient encounter, referral, or discharge summary in production.

We have established a suite of Postman collections that enable you to configure and test Signal workflows in our Sandbox environment.

Create Patients, Subscriptions, & Referral Organizations in Sandbox

As in Production, in order to set up and test Signal in Sandbox, you will first need to create patients and subscriptions for your patients in Sandbox, via the following steps:

1. Generate a JSON web token using Authentication.

2. Create patients

Submit demographics via the Patients API and store the Particle Patient ID returned for each patient.

📘

There are specific test patients (Elvira Valadez) and organizations available in Sandbox to test Signal workflows. See details below.

POST /api/v1/patients

Sample Request

{
    "address_city": "Boston",
    "address_lines": [
        "703 Ankunding Trail Unit 45"
    ],
    "address_state": "MA",
    "date_of_birth": "1970-12-26",
    "email": "[email protected]",
    "family_name": "Valadez",
    "gender": "Female",
    "given_name": "Elvira",
    "npi": "1234",
    "postal_code": "02215",
    "purpose_of_use": "TREATMENT",
    "ssn": "123-45-6789",
    "telephone": "1-234-567-8910",
    "patient_id": "test-external-patient-id"
}

Sample Response

{
    "given_name": "Elvira",
    "family_name": "Valadez",
    "date_of_birth": "1970-12-26",
    "gender": "FEMALE",
    "ssn": "123-45-6789",
    "email": "[email protected]",
    "address_lines": [
        "703 Ankunding Trail Unit 45"
    ],
    "address_state": "MA",
    "address_city": "Boston",
    "postal_code": "02215",
    "telephone": "(234) 567-8910",
    "patient_id": "test-external-patient-id",
    "particle_patient_id": "d939196d-0c80-4e82-b0e1-19f9ee271085",
    "consent": null
}

3. Subscribe patients to Signal notifications - Optional

NOTE this step is only necessary if you want to specify a subset of patients to monitor. If you want to monitor ALL of your patients, you can reach out to your Particle representative to automatically enable Signal for all patients for your organization.

Subscribe your patient(s) to Signal notifications via the Subscriptions API. Refer to guide for detailed setup steps.

1. Cohort of Patients: POST /api/v1/patients/subscriptions
2. Individual Patient: POST /api/patients/{particle_patient_id}/subscriptions

Sample Request for Individual Patient

{
  "subscriptions": [
    {
      "type": "MONITORING",
    }
  ]
}

Sample Response

{
  "subscriptions": [
    {
      "id": "39774a2f-b6fb-46a0-88c9-30843a5127b7",
      "type": "MONITORING",
      "state": "SUBSCRIBED"
    }
  ]
}

3.a Register Referral Organizations - Referral Management Only

If you are looking to test out receiving Referral Alerts for Referral Management, you will also need to register the Referral Organization supported in Sandbox, to be able to configure monitoring for patient referrals to the organization. See details on test organizations below.

POST /api/v1/referrals/organizations/registered\

Sample Request

{  
    "organizations": [  
        {  
            "oid": "2.16.840.1.113883.3.8391.5.710576"  
        }  
    ]  
}

Test Patients & Organizations for Signal

Test Patients

You can subscribe a full cohort of any patients that you have created in Sandbox to monitor. However, it is important to note that you will only be able to test out end-to-end Signal Alert notifications and data delta retrieval workflows for the synthetic patient Elvira Valadez (see patient details here), as this is the only patient for whom we currently have synthetic data to support end-to-end Referral Management and Discharge Summary workflows in Sandbox.

📘

If you want to test out end-to-end Signal workflows, you will need to test with test patient Elvira Valadez (patient details here), in order to do so.

Test Organizations

In addition, if you are testing out Referral Management, you will need to register the Referral Organization that you want to monitor for Referral Alerts. There is one Referral Organization currently supported in Sandbox. You will need to register this Referral Organization in order to trigger and receive Referral Alerts:

See guide for more details on how to configure Referral Management.

Configure Callback URLs for Test Notifications

Configure the callback URL(s) that you would like us to send proactive querying, network alert, referral alert, & ADT notifications to.

➡️

Note: Unlike in the production environment, we do not need to pre-register the callback URL for our customers in order for them to start receiving notifications. You are free to use any callback URL you would like.

Trigger Signal Alerts & Retrieve Data in Sandbox

Trigger Signal Alerts

1. Once you have created a patient (and subscribed patients, if only testing out Signal for a subset of patients), you can trigger Signal Alerts in Sandbox. See API Reference here.

POST /api/v1/patients/{particle_patient_id}/subscriptions/trigger-sandbox-workflow\

Request Body:

{
    "workflow": "REFERRAL_ALERT", // valid: "REFERRAL_ALERT", "DISCHARGE_SUMMARY_ALERT", "NEW_ENCOUNTER_ALERT", "NETWORK_ALERT"
    "callback_url": "http://test-webhook-url",// callback url to receive the test notif
    "display_name": "Test Referral Alert 1" // display name for the webhook
}

NOTE if you are attempting to trigger and test Referral Alertworkflows, you will need to first register your ReferralOrganization (step 3.a above).

2. You will receive a notification at the callback URL you specified.

Sample - Referral Alert Notification

{
  "specversion": "1.0",
  "type": "com.particlehealth.api.v2.referralalert",
  "subject": "Referral Complete",
  "source": "api/notifications",
  "id": "ea77d12d-bb97-438e-82eb-1b0d10a7e3ee",
  "time": "2024-07-22T10:10:10Z",
  "datacontenttype": "application/json",
	"data": {
    "network_organization": {
      "name": "Rochester Hospital",
      "oid": "2.16.840.1.113883.3.8391.5.710576"
    },
    "particle_patient_id": "d939196d-0c80-4e82-b0e1-19f9ee271085",
    "network_alert_ids": [
	    "1cac1ea7-f3a9-43b3-bca3-04d3ec4362c5",
    ],
    "adt_message_ids": [
	    "6e7303bd-2c1a-49f2-add0-820babbdb95a",
    ],
    "referral_id": "a17846c4-4270-427b-b191-bd5e76cf8f30",
    "referral_status": "COMPLETE",
    "resources": [
      {
	      "file_id": "d6a96f73-eb18-4faa-b021-143e7777fe8b",
        "resource_ids": [
          "Encounter/b10fe2ef-47f9-4507-97c8-1a8c2215478e"
        ]
      }
    ]
  }
}

3. Retrieve the sample data delta for Elvira Valadez using the Deltas API:

• FHIR: GET /deltas/R4/patient/{particle_patient_id}/$everything
• FLAT: GET /deltas/flat/{particle_patient_id}

In addition to retrieving the full patient history or data delta in FHIR or FLAT, you can also retrieve the individual encounter or the file where the new encounter was found. See examples here for reference.

See Discharge Summary document for Elvira Valadez below for an example of the documents available in Sandbox for testing these workflows. Note the visual below is a representation of the Discharge Summary document in our Sandbox UI. If you are interested in the Particle UI, you can learn more here.

📘

We currently support triggering 5 Signal Alerts, and retrieving 5 associated deltas/files/encounters for the patient Elvira Valadez in Sandbox. After you have triggered 5 Signal Alerts, the data will automatically reset, if you want to run further testing with the same patient data.

ADTs

1. After you have subscribed to test notifications and configured the appropriate call back URLs, request an ADT notification using the Register HL7v2 API.

POST /api/v1/patients/{particle_patient_id}/subscriptions/trigger-sandbox-workflow

Request Body:

{
    "workflow": "ADT", // valid: ADT
    "event_type": "A01", // valid: A01, A02, A03, A04, A08
    "callback_url": "http://test-webhook-url",// callback url to receive the test notif
    "display_name": "Test ADT Notification 1" // display name for the webhook
}

2. You will receive a notification at the callback URL you specified. This notification will contain the Patient ID and a message ID.
3. Retrieve the sample ADT message using the HL7v2 API.
   GET /hl7v2/{message_id}

Sample ADT messages are customized based on the patient and ADT event type specified.