Integrate views with activity submissions

Engage Help Center

www.longenesis.com/engage

ENGAGE HELP CENTER

This section will provide information on how to integrate views with the activity submissions on your web application.

Review completed submissions

Let you registered participants review their completed activities and administrators or doctors review all activity submissions. To apply this functionality, your web application must have a server-side component which will be used to authenticate at Longenesis and acquire an access token for your participants.

All domains where you plan to integrate iFrames must be whitelisted.

Contact support@longenesis.com to provide a list of your development and production domains that need to be whitelisted.

The overall process flow is as follows:

(1) Participant logs into the Partner Portal.
(2) Participant clicks the button to view activity submissions 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 authorisation code (authCode) for the participant.
(7) Portal instructs its front-end to load activity submissions for participant or admin in an iFrame.

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>"
ENGAGE_ACTIVITY_SLUG = "<activity SLUG>"
ORG_SLUG = "<organisation 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 replaced with the slug of your Engage organisation and the ENGAGE_ACTIVITY_SLUG element must be set to the slug of the specific Engage 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. 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.

Step-by-step review of the python sample

Let's break this example 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>"
ENGAGE_ACTIVITY_SLUG = "<activity SLUG>"
ORG_SLUG = "<organisation 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 registering and the actual authCode must come from the Partner Portal Backend - acquired just before constructing an iFrame.

Participant view of the completed submissions

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&page=participant" 
  width="100%" 
  height="1200" 
  style="border:none;"></iframe>

Administrator view of the completed submissions

The integration enables the administrators/doctors to process and analyze the submitted participant responses right from the Partner Portal.

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

To view the participants' submissions, the Partner Portal user must have minimal administrator rights in the Engage organization.

The administrator must have organization- or project-level permissions to View Submissions to review integrated views containing participant submissions. Read more about Permission management.

Engage supports a number of useful response processing and analytics features also via the integration.

Participants tab - view all responses
The section Participants enables the administrators to view the list of all participant responses submitted, as well as Download them in Excel format for further analysis.

Participants tab - view individual responses
Administrators can also review individual participant submissions from the Participants tab. When selecting each individual submission with the button Completed, the specific participant's answers are listed. Similarly, the administrator can view the participant Report that has been displayed to the selected respondent. Furthermore, it is possible to Download the selected individual response in PDF format.

Analytics
For the convenience purposes, the integration allows the administrators to enjoy the Analytics functionality without having to leave the Partner Portal.

Read more about the functionality here.

Answers
The section Answers shows all of the submitted responses in a table view and allows the administrators to further filter and process the gathered data, as well as download only the filtered data selection.

Read more about the functionality here.

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 next: Participants' project flow →

← Read previous: Activities with authorisation