Integrations and Onboarding – Turnstile Partner

Date: 10-11-2023

Overview

The primary objective of this feature is to provide an integration implementation pattern so that customers who already have a technology partner managing contractor staff onboarding and site access (DSOS) privileges ( e.g., Datascope ) have the ability to digitally induct these operatives onto a site before enabling site access. 

Digital inductions will reduce time to site and improve compliance.

Note: In this integration pattern, Visita is the unreal system of record for staff or contractors, the other technology partner is (DSOS). 

Current User Story (before Visita)

1. The site EHS lead (EHSL) adds a contractor admin profile to DSOS for a specific site. 
2. DSOS sends a link to the contractor admin (CA) to upload the contractor operative personal information via a form and upload required compliance documents (i.e., SafePass and Manual Handling).
3. The CA uploads the operative information into the portal system, including certificates.
4. The EHS lead is notified of the uploads and checks that each operative record and certificate is valid. The EHS then “accepts” or “rejects” the operatives. 
5. The EHS lead then schedules the operatives for classroom-based site onboarding on the next available morning.
6. On completing the onboarding class, the EHS marks the operative profile as inducted, and their site access becomes active.

Proposed Future State User Story

Steps 1-4 continue as per above.

1. DSOS pushes the contractor information, including approved profiles, down into the Visita system (VST). 
2. VST sends the relevant site induction out to the contract operatives represented by each profile created by relevant language.
3. Each contract operative gets assigned the learn course, gets an email and a text message, and logs in to complete the course.
4. On completion of a course, VST pushes the completion data back into the DSOS system
5. DSOS updates the operative profile with the induction status( ? & cert).
6. DSOS notifies EHS that the operative records have been updated.
7. EHS reviews & approves / schedules for work, and their site access becomes active.
8. Operative turns up inducted and does short orientation and badge allocation.

Integration Solution Overview

Data mappings/sync
DSOS.Contractor -> VST.Contractor?
DSOS.Site -> VST.Team?
DSOS.Profile -> VST.Profile
DSOS.Profile.Biometric_id -> VST.Profile.ext_id ?
DSOS.Profile.email -> VST.Profile.email ?
DSOS.Profile.mobile -> VST.Profile.mobile ?
DSOS.Profile.site/team -> VST.Profile.team_id ?

VST.Profile_id -> DSOS.Profile.visita _id

Happy Path Sequence Diagram

User Stories

New employee joins a company, and HR System ( master ) syncs down

When a new profile is created in the HRS system, it contacts the VST OnboardingBusinessSv API. The VST system then performs the following actions: It creates a new profile or updates an existing one. Optionally, it can activate the profile by creating a user authentication, a UATA, and setting it to “active”. The profile can also be added to a team if data is provided. However, an exception is thrown if the team name or ID is supplied but not found.

An employee leaves a company, and HR System ( master ) syncs down

When an HR admin suspends a profile in the HRS system, the VST OnboardingBusinessSv API is called. The VST system then updates the profile/UATA by marking it as inactive.

HR System ( master ) syncs down a Profile with email clash

The HRS system uses the VST OnboardingBusinessSv API. The VST system checks profile details with an external ID (Profile A). If Profile A has a different email from the supplied email, the system checks if the supplied email already exists. If it does, the system updates a different profile (Profile B) and moves the external ID from Profile A to Profile B. If the email does not exist, the system updates Profile A.

When Inactive user tries to log in to Visita

If a user who is not active tries to log in to access Visita, the system will check if they are only part of one account. If the user is part of only one account, Visitawill displays an error message that says, “Account verification has failed. Your account may not be activated or currently suspended. Please contact your administrator or the Visita Support team for help”.

When a user is in multiple accounts, one account is active, and another is inactive

A user enters login details and VST authorizes them. User views their profile modal, sees their accounts, and can switch between them. Disabled accounts display help text and are not clickable.

User is given a termination date

A profile can be assigned a termination date in the HR Administration system. When this happens, the HRS system calls the VST OnboardingBusinessSv API. This API assigns a termination date to the profile and marks it as inactive once the termination date has passed in the last 24 hours. This process is done by the Visita nightly Daemon each night.

User is archived

When a user is marked as archived by the VST Administrator, the VST system saves their profile as JSON on S3, removes all collections from the profile in the database, and marks the profile as archived.

User is unarchived

The VST Admin can browse a list of archived users in VST, which is now driven by a database. The VST Admin can then choose a profile to unarchive. The VST system will then load a JSON object from S3 and merge the profile collections, such as certificates, into the archived profile. The system will update the profile to no longer be archived and delete the JSON file from S3.

Use Cases – User Logging in and Activating/Archiving

We need a quick review of the login process and how a user/admin “activates” an account.

UserAuth “Enabled” flag – This flag previously indicated that the user had activated their account, but now we have multiple accounts per user, but we also have enabled it on each UATA object as per each account the user may be a member of. 

UATA “Enabled” flag – This flag indicates when the user has enabled an account. It gets set to true when a user clicks on the verification link when they first activate their account, or if they are already active in one account, they may be logged in and switch to a new account they have been added to. They will be prompted to click ‘Activate Account’ in order to access the new account.

Core User Stories RE User to multi-account management

For company 1

The account admin for Company 1 can add a new user to their account by creating a new profile. Once the profile is created, the new user will receive an activation email. The VST system checks if the username already exists in the userauth table. If it does, a new profile is created and the tenant, userauth ID, and profile ID are added to UATA. 

If the username does not exist, a new profile, userauth, and UATA are created for the new user in Company 1. The profile will be inactive until the account admin clicks on the ‘Send Activation Invite’ link located on the user list page. Once the activation email is received and the account is activated, the user’s enabled flag will be set to true in both the userauth table and UATA. If the user is inactive, the enabled flag will be set to false in both tables.

For company 2 

An Account Admin in Company 2 can activate an existing User’s Profile by adding it to their account. The User will receive an activation email and can activate their account via the link provided. The Account Admin can use the VST system to create a new profile. If the username already exists in the userauth table, a new profile will be created and added to UATA. 

If not, a new profile and userauth will be created and added to UATA. The profile will be inactive. The Account Admin can activate the profile by clicking on the “Send Activation Invite” link on the user list page. The User will receive an activation email and can activate their account. The system will update the userauth and UATA flags to reflect the User’s status.

Account Admin in Company 2 shares a Profile Client Company 3

Company Admin shares a contracting profile with Company 3. This creates a profile in Company 3’s account and a new UATA. The UATA is enabled/disabled based on the same setting as the original profile UATA for Company 2. If enabled, the profile user can see and switch to Company 3’s account option when logging in. If disabled, the user can only see and access Company 2’s account.

Technical Solution

Create a new business API that takes a POST of actions list and a form of parameters, which will then validate the supplied data versus the requested actions, and make the required internal REST API service calls to kick-off onboarding of Profile / Staff.

API Functionality

Profile Update: 

This feature searches for a profile with a specific ID number. If a profile is found, it updates the profile with the new data. If a profile is not found, it creates a new profile using the same data. This feature also adds a UATA and UA to the profile if it is the user’s first time using the account.

Profile Activate:

This feature does everything that the Profile Update feature does, but it also sets the profile to active and sends an email activation notification to the user asking them to verify their account or set their password.

Team Onboard:

This feature does everything that the Profile Update and Activate features do, but it also searches for a specific team by ID number and name. If the team is found, it adds the team ID to the user’s profile. This feature kicks off onboarding, which includes new functions and code.

Profile Archive:

This feature does everything that the Profile Update feature does, but it also sets the profile to archive and creates an S3 file of the user profile object. It deletes the profile object collections (certificates and logged hours) from the database.

Profile Unarchive:

This feature does everything that the Profile Update feature does, but it also sets the profile to unarchive. It deletes the S3 file of the user profile object and restores the profile object collections (certificates and logged hours) from S3.

[ Read Also: Benefits of Using Static Code Analysis Tools for Software Testing ]