Awell Health Developer Hub
Developer Hub
Front-end:
Back-end:

This page will allow users to complete a pathway or flow and is a low-code integration.

Pathway lifecycle

The basic lifecycle for a hosted pathway experience looks like this:

  1. When a pathway needs to be started for a client, your application creates a new Pathway Session.
  2. The Pathway Session provides a URL that redirects your client to an Awell-hosted pathway page.
  3. Your client can interact with the pathway or care flow and complete activities.
  4. When the pathway is completed, a webhook (pathway.completed) is triggered to let you know the pathway is completed.
Hosted pathway sequence diagram
Hosted pathway lifecycle © Awell Health

Low-code integration

The hosted pathway integration requires minimal coding. Compare the hosted pathway integration to other options to determine which option meets your requirements .

Prerequisites

To get started, there are a couple of things you need:

  1. An API key to authorize requests to the Awell API. Click here to get your API key.
  2. A published pathway that meets the requirements to be used with the Awell hosted pathway integration. To get started quickly, you can use a template pathway that is available for you in Awell Studio by default (see table below). You can also use a pathway you created yourself.

Published pathway

To get started quickly with this guide, use a template pathway to test this integration. Choose the pathway definition id in the environment you are integrating against.

EnvironmentPathway definition id
SandboxJ0oNK2V91RL2
ProductionNot available yet

Webhooks (optional)

You can configure Webhooks to get notified when a pathway is started and/or completed. Webhooks are configured on a per pathway basis via the pathway settings so if you want to receive webhooks for these events, you will have to configure them via the pathway settings.

Configure webhooks

Click here for more information on how to configure Webhooks on pathways. The payload of the pathway.started and pathway.completed webhook can be found on the respective links.

Get started

1
Set up the front-end

Add a start pathway button

Add a button to your page. When a client clicks this button, they are redirected to the Awell-hosted pathway page.

Show a message when client is redirected back

We want to show something to the client when they get redirected back to the application. In this case, we show a simple message.

Check if there is a redirect back from Hosted Pathway

We want to show something to the client when they get redirected back to the application. In this case, we show a simple message.

  • App.js
01import React, { useState, useEffect } from "react";
02

03const StartPathwaySessionButton = () => (
04  <form action="/start-pathway-session" method="POST">
05    <button type="submit">
06      Start pathway session
07    </button>
08  </form>
09);
10

11const Message = ({ message }) => (
12  <p>{message}</p>
13);
14

15export default function App() {
16  const [message, setMessage] = useState("");
17

18  useEffect(() => {
19    const query = new URLSearchParams(window.location.search);
20

21    if (query.get("success")) {
22      setMessage("Pathway completed.");
23    }
24

25    if (query.get("canceled")) {
26      setMessage(
27        "Pathway canceled."
28      );
29    }
30  }, []);
31

32  return message ? (
33    <Message message={message} />
34  ) : (
35    <StartPathwaySessionButton />
36  );
37}
2
Set up the server

Install node-fetch library

Your server will need to call the Awell (GraphQL) API. In this example we use node-fetch, but feel free to use any library of your liking.

  • terminal
01npm install node-fetch

Configure variables

You will need an API key to authorize requests to the Awell API and a pathway definition id to indicate what pathway you would like to start.

Resources:

Create a pathway session

Add an endpoint on your server that creates a Pathway Session. A session is created by calling the Awell API (graphql).

Resources:

Define a patient resource to start the pathway for Optional

Every pathway is linked to a patient resource in our system. We automatically create an anonymous patient resource if

patient_id
is not set as an input variable. You can also create a patient first and pass the id of that patient via the input variables.

If you want to create a patient first, you will have to do an a priori API call to create the patient.

Resources:

Pass baseline info or baseline data points Optional

Care flows/pathways can be configured to accept sending baseline data point values (i.e. baseline information) when starting the pathway.

Add a

data_points
variable if you want to pass baseline data point values to your care flow.

Resources:

Define pathway to start, success and cancel URLs

Specify what pathway needs to be started as well as the start and cancel URLs. Make sure these URLs are publicly accessible so Awell can redirect clients to them.

Redirect to Hosted Pathway page

After creating the session, redirect your client to the URL for the hosted pathway page returned in the response.

  • server.js
01const express = require('express');
02const fetch = require('node-fetch');
03const app = express();
04

05app.use(express.static('public'));
06

07const AWELL_SANDBOX_API_ENDPOINT = 'https://api.sandbox.awellhealth.com/orchestration/m2m/graphql'
08const AWELL_SANDBOX_API_KEY = 'YOUR_API_KEY'
09const YOUR_DOMAIN = 'https://your-domain.com'
10const PATHWAY_DEFINITION_ID = "J0oNK2V91RL2"
11

12app.post('/start-pathway-session', async (req, res) => {
13  const body = JSON.stringify({
14    query: `
15    mutation StartHostedPathwaySession(
16      $input: StartHostedPathwaySessionInput!,
17    ) {
18      startHostedPathwaySession(input: $input) {
19        session_id
20        session_url
21        pathway_id
22      }
23    }`,
24    variables: {
25      input: {
26        pathway_definition_id: PATHWAY_DEFINITION_ID,
27        success_url: `${YOUR_DOMAIN}?success=true`,
28        cancel_url: `${YOUR_DOMAIN}?canceled=true`
29      }
30    }
31  });
32

33  const session = await fetch(AWELL_SANDBOX_API_ENDPOINT, {
34    method: 'POST',
35    headers: {
36      apiKey: AWELL_SANDBOX_API_KEY,
37      Accept: 'application/json',
38      'Content-Type': 'application/json'
39    },
40    body,
41    cache: 'default'
42  })
43    .then(response => response.json())
44    .then(response => response.data.startHostedPathwaySession)
45

46  res.redirect(303, session.session_url);
47});
48

49app.listen(4242, () => console.log('Running on port 4242'));

Awell Node library

We are working on an Awell Node library that you can install to make it even more easy to access the Awell API functionalities.

3
Test your page

Run the application

Start your applications (front-end and server) and navigate to http://localhost:3000. Press the "Start pathway session" button to go to the Awell hosted pathway page and complete the pathway.

Try it out

Click the button below to see a working example of the hosted pathway page.

Try it out

Frequently asked questions

If you can't find what you're looking for, you can always send us a message over Intercom with your enquiry.