Integrate activities with authorisation

Engage Help Center

www.longenesis.com/engage

ENGAGE HELP CENTER

How to integrate activities with authorisation

This section will provide details on how to easily integrate Engage activities that do require authorisation.

Activities with authorisation

If you would rather have the participants of your project identified and have them submit activity responses with registration, we offer a secure way to seamlessly log your participants into Engage. To use this method, your website must have a server-side component which will be used to authenticate at Longenesis and acquire an access token for your participants. The overall process flow is as follows:

(1) Participant logs into the Partner Portal.
(2) Participant clicks the button to take the activity in the Partner Portal.
(3) Portal authorizes at Longenesis Auth Service and (4) receives access_token for the Portal itself.
(5) Portal posts participant ID to EngageAPI and (6) receives authorization_code for the participant.
(7) Portal instructs its front-end to load https://engage.longenesis.com/en/{ORG_SLUG}/partner_view?&activitySlug={ENGAGE_ACTIVITY_SLUG} in an iFrame.
(8) Participant submits the activity.

More details on the difference between activities with and without authorisation can be found here.

How to authenticate your participant into Engage

Here is a python code example of how to get the authorization_code for the participant.

import requests

AUTH_ENDPOINT = (
    "https://auth.longenesis.com/realms/curator-engage/protocol/openid-connect/token"
)
USERNAME = "<your username>"
PASSWORD = "<your password>"
CLIENT_ID = "<Longenesis issued client id>"
CLIENT_SECRET = "<Longenesis issued client id>"
ORG_SLUG = "<your organisation slug>"
ENGAGE_ACTIVITY_SLUG = "<activity SLUG>"
REDIRECT_URL = (
    "https://engage.longenesis.com/en/{ORG_SLUG}/partner_view?activitySlug={ENGAGE_ACTIVITY_SLUG}&authCode={code}"
)

access_token = requests.post(
    AUTH_ENDPOINT,
    data={
        "username": USERNAME,
        "password": PASSWORD,
        "grant_type": "password",
        "client_id": CLIENT_ID,
        "client_secret": CLIENT_SECRET,
    },
).json()["access_token"]

PERSON_DATA = {
    "participant_id": "0000099",
    "participant_full_name": "John Doe",
    "guardian_id": "0007",
    "guardian_full_name": "Jane Doe",
    "free_text": ["Hello John!"],
}

response = requests.post(
    f"https://engage-openapi.longenesis.com/get_auth_code",
    json=PERSON_DATA,
    headers={"Authorization": f"Bearer {access_token}"},
)

print(
    REDIRECT_URL.format(
        slug=ENGAGE_ACTIVITY_SLUG, code=response.json()["authorization_code"]
    )
)

The documentation on the EngageAPI endpoints is available here.

In the example, the ORG_SLUG element must be set to the slug of your Engage organisation and the ENGAGE_ACTIVITY_SLUG element must be set to the slug of the specific activity.

The ORG_SLUG element necessary for the iFrame link can be found in the Engage section My organisation.

To find the ORG_SLUG element follow the below steps.
1. Log into the Engage platform,
2. Go to the section My organisation,
3. Navigate to the section Slug for your organisation invitation link,
4. Obtain the ORG_SLUG from the organisation link displayed. It is the last element of the link.

The ENGAGE_ACTIVITY_SLUG element can be found when accessing the Public sharing section of the Engage activity.

To find the ENGAGE_ACTIVITY_SLUG element follow the below steps.
1. Log into the Engage platform,
2. Opt to View activities of the Engage project where the specific activity is located,
3. Click on the three vertical dots on the card of the specific activity and select Public sharing,
4. Obtain the activity slug from the very end of the Public link of the activity.

Permission management

There is no need to worry about permissions for ordinary users (e.g. participants and patients). Users always have access to published content and their own data.

Admin users
Permissions are set using PERSON_DATA object (in the example above). The recommended way is to provide permissions with the following structure:

    "person_id":"same_as_participant_id",
    "org_level": ["perm1", "perm2", ...],
    "projects": {
        "project_slug1": ["perm1", "perm2", ...],
        "project_slug2": ["perm1", ...],
    }
}

List of permissions:
CRP - Create project MA - Manage admins MC - Manage content MP - Manage participants SR - Submissions read SW - Submissions write SD - Submissions deleteThere is also another way to grant permissions.
Setting "role": "A" will grant the user all permissions in Organisation level and is equivalent to:

    "person_id":"same_as_participant_id",
    "org_level": ["MA", "CRP", "MC", "MP", "SR", "SW", "SD"],
    "projects": {}
}

Properties role and permissions are mutually exclusive.

Step-by-step review of the python sample

Let's break down the python example of how to get the authorization_code for the participant into sections.
First, we load the popular requests library.

import requests

Then we sort out the credentials and configuration.

AUTH_ENDPOINT = (
    "https://auth.longenesis.com/realms/curator-engage/protocol/openid-connect/token"
)
USERNAME = "<your username>"
PASSWORD = "<your password>"
CLIENT_ID = "<Longenesis issued client id>"
CLIENT_SECRET = "<Longenesis issued client id>"
ORG_SLUG = "<your organisation slug>"
ENGAGE_ACTIVITY_SLUG = "<activity SLUG>"
REDIRECT_URL = (
    "https://engage.longenesis.com/en/{ORG_SLUG}/partner_view?activitySlug={ENGAGE_ACTIVITY_SLUG}&authCode={code}"
)

Next we acquire the access_token for this script.

access_token = requests.post(
    AUTH_ENDPOINT,
    data={
        "username": USERNAME,
        "password": PASSWORD,
        "grant_type": "password",
        "client_id": CLIENT_ID,
        "client_secret": CLIENT_SECRET,
    },
).json()["access_token"]

The access_token expires after 30 minutes, while the refresh_token remains valid for 60 minutes.

Then we compile the participant data.

PERSON_DATA = {
    "participant_id": "0000099",
    "participant_full_name": "John Doe"
    "guardian_full_name": "Jane Doe",
    "free_text": ["Hello John!"],
    "org_slug": "sunshinehospital",
}

The required minimal amount of data is just the participant_id i.e. {"participant_id": "aabbcc0011",}.
It is recommended to provide the participant's full name as well: {"participant_id": "aabbcc0011", "participant_full_name": "Janice Doe"}.
In case a parent or guardian is acting on behalf of a minor, the person data information should include the parent's id and name as well.

Please note that the participant_id must be a string with length not greater than 250 characters. The participant_id also must be unique within the Partner's organization.

Next we submit the participant data to EngageAPI.

response = requests.post(
    f"https://engage-openapi.longenesis.com/get_auth_code",
    json=PERSON_DATA,
    headers={"Authorization": f"Bearer {access_token}"},
)

And finally we print the redirect_url on screen.

print(
    REDIRECT_URL.format(
        slug=ENGAGE_ACTIVITY_SLUG, code=response.json()["authorization_code"]
    )
)

A link very similar to this should be next printed on screen: https://engage.longenesis.com/en/sunshinehospital/partner_view?activitySlug=abcde&authCode=A2DA055ED45F4FBE806EAD5B3B937F00

Please note that the print statement in this example is for demo purposes only to have the sample create some output.

The Partner Portal Frontend must implement iFrame similar to what is displayed below where the sunshinehospital has to be replaced with the slug of your Engage organisation, the activitySlug must be set to the slug of the specific activity that requires authorisation and the actual authCode must come from the Partner Portal Backend - acquired just before constructing an iFrame.

Below is an example of the iFrame implemented by the Partner Portal Frontend.

<iframe 
  src="https://engage.longenesis.com/en/sunshinehospital/partner_view?activitySlug=aabbcc&authCode=AABBCCDDEEFF001122&menu=false" 
  width="100%" 
  height="1200" 
  style="border:none;"></iframe>

How to invalidate Engage sessions

To invalidate a participant session, Partner Portal must send a POST request to /invalidate/<session_id> endpoint in EngageAPI.
The session_id is included in /get_auth_code response together with the authorization_code. It is up to the Partner how to handle session IDs while the participant is engaged into Engage activities. We recommend for the Partner Portal to store the session ID of the participant in an in-memory database and invalidate the session as soon as the participant navigates away from the page with the EngageUI iFrame.

import requests

AUTH_ENDPOINT = (
    "https://auth.longenesis.com/realms/curator-engage/protocol/openid-connect/token"
)
USERNAME = "<your username>"
PASSWORD = "<your password>"
CLIENT_ID = "<Longenesis issued client id>"
CLIENT_SECRET = "<Longenesis issued client id>"

SESSION_ID = "...load the session_id from the place you stored it..."

access_token = requests.post(
    AUTH_ENDPOINT,
    data={
        "username": USERNAME,
        "password": PASSWORD,
        "grant_type": "password",
        "client_id": CLIENT_ID,
        "client_secret": CLIENT_SECRET,
    },
).json()["access_token"]


response = requests.post(
    f"https://engage-openapi.longenesis.com/invalidate/{SESSION_ID}",
    headers={"Authorization": f"Bearer {access_token}"},
)

print(response.json())

Activity report

After having submitted the activity response, the participants will be able to complete the below-listed actions via the Engage integration:
- Review the answers they have given in detail,
- View the participant report section,
- Download their response submission in PDF format.

Our team is ready to provide you assistance in any of the steps and would gladly guide you through the process.

Do not hesitate to contact us via support@longenesis.com if you have any questions or any help is required.

← Read previous: Activities without authorisation