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/partner_view 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>"
ENGAGE_ACTIVITY_SLUG = "<activity SLUG>"
REDIRECT_URL = (
    "https://engage.longenesis.com/partner_view?activitySlug={slug}&code={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 ENGAGE_ACTIVITY_SLUG element must be set to the slug of the specific activity.
The activitySlug element of the Engage activity can be found when accessing the Public sharing section of the activity.

To find the activitySlug 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>"
REDIRECT_URL = (
    "https://engage.longenesis.com/partner_view?activitySlug={slug}&code={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"]
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/partner_view?activitySlug=abcde&code=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 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.