Integrate participants' project flow

Engage Help Center

www.longenesis.com/engage

ENGAGE HELP CENTER

How to integrate participants' project flow

This section will provide details on how to easily integrate whole Engage project flows for the authorised participants to navigate in your portal.

Integrating Engage project workflows into your web portal is designed to optimize user interaction by simplifying the interface, focusing solely on the project content and eliminating general navigation elements like the left-side navigation bar and login buttons.

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.

Integration process overview

The integration follows a detailed sequence of operations to ensure secure and efficient user management and interaction:

1. Participant Authentication: Initially, the participant logs into the Partner Portal.
2. Activity Initiation: The participant starts the first activity presented in the Partner Portal.
3. Authorization and Token Management:
- Authentication with Longenesis Auth Service.
- Acquisition of access_token for the portal.
4. Participant Verification:
- Posting of participant ID to Engage API.
- Receipt of a unique authorization_code for the participant.
5. iFrame Loading: The portal dynamically constructs an iFrame embedding one of the initial view URLs with the authorization code. Example URLs include:
- https://engage.longenesis.com/en/{ORG_SLUG}/project?authCode={code}
- https://engage.longenesis.com/en/{ORG_SLUG}/project/{PROJECT_SLUG}?authCode={code}
- https://engage.longenesis.com/en/{ORG_SLUG}/project/{PROJECT_SLUG}/{ENGAGE_ACTIVITY_SLUG}?authCode={code}
6. User Engagement: Participants navigate and interact within the project flow.

Authentication code retrieval example

Here is a Python code example of how to retrieve 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>"
PROJECT_SLUG = "<your project slug>"
ENGAGE_ACTIVITY_SLUG = "<activity SLUG>"
REDIRECT_URL = (
    "https://engage.longenesis.com/en/{ORG_SLUG}/project/{PROJECT_SLUG}/{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 resulting URL should resemble this format:

https://engage.longenesis.com/en/{ORG_SLUG}/project/{PROJECT_SLUG}/{ENGAGE_ACTIVITY_SLUG}?authCode=A2DA055ED45F4FBE806EAD5B3B937F00

The documentation on the EngageAPI endpoints is available here.

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

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.

Example iFrame implementation

For embedding the Engage UI within your Partner Portal, use this HTML iFrame snippet:

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

Dynamic iFrame height
It is possible to control the iFrame height in the Partner Portal. Use this HTML iFrame snippet:

<iframe 
id="iframe-id"
src="https://engage.longenesis.com/en/sunshinehospital/project/aabbcc/ddeeff?authCode=AABBCCDDEEFF001122" 
width="100%" 
style="border: none;" 
scrolling="no"></iframe>

Here is a JavaScript code example of how to dynamically adjust the iFrame height based on messages from its content, ensuring the iFrame fits its content without unnecessary scrollbars.

function handleIframeMessage(event) {
  const iframe = document.getElementById('iframe-id');
  if (event.data.type === 'setHeight') {
    iframe.style.height = event.data.height + 'px';
    if (event.data.scrollToTop) {
      window.scrollTo(0, 0);
    }
  }
}

window.addEventListener('message', handleIframeMessage);

Participant data requirements

Minimal data necessary is the participant_id. For enhanced interaction, include the participant_full_name. If acting on behalf of a minor, include both the guardian's ID and name.

Admin and User permission management

Permissions for administrative users can be managed through a PERSON_DATA object, detailing access levels organization-wide and per project:

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

Assigning "role": "A" provides all permissions at the organization level without specifying per project.

Session management

To effectively manage sessions, send a POST request to /invalidate/<session_id> on the Engage API. It is advisable to store session IDs in an in-memory database and invalidate them once participants disengage.

Styling and customization

Integration style settings are adaptable and should be utilized to maintain design consistency between the Partner Portal and integrated project flows. Further details on these settings can be found here.

Find the elements ORG_SLUG , PROJECT_SLUG and ENGAGE_ACTIVITY_SLUG necessary for the iFrame link in Engage .

Read about locating the ORG_SLUG here.
Read about locating the PROJECT_SLUG here.
Read about locating the ENGAGE_ACTIVITY_SLUG 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 previous: Activity submissions