This article is best for system administrators, engineers, and developers. Too small? Click here.

We know that our customers have their own way of dealing with data. That’s why we on PlusPlus already expect the data not to be retrieved from a specific provider and in a specific format.

We can integrate with your software even though we still don’t have explicit support for it. We just need the information to be provided respecting a small set of constraints.

How People integration works

We use data from an external data source to provision and deprovision users on our system. The data source provided by the customer is used to fetch data and we map the fields to PlusPlus’ Users fields.

The fetch happens once a day by a scheduled background job. This background job is responsible for:

  • Provisioning users;
  • Updating existing users;
  • Deprovisioning terminated users;
  • Adding users to Groups they must be assigned to;
  • Using our Automated Rules API to automatically enroll users to events and assign them to tracks.

Integration Levels

Our People Integrations are released in phases. Each phase has one objective which is a requirement to start implementing the next one.

Level 1: Provisioning & Data Enrichment

In this phase, we are going to set everything up in order to start fetching the data on the customer’s data source and use this data to provision users correctly. As soon as we have all users created successfully on PlusPlus, we can move on to creating automation.

In this phase, it can be defined for each user, based on the integration data, rules to set information like roles, location, badges, etc. These rules need to be negotiated with the Customer Success Rep of your account.

Level 2: Groups Creation/Association

In this phase, we are going to define the rules for groups’ creation based on the users’ data we’re fetching. The rules are 100% customizable by the customer as long as they only require information in the external data source and in PlusPlus. The groups created through the integration are public and, initially, have no owner.

These groups aren’t editable through the PlusPlus Dashboards, the only way to edit members is through the external data source.

Level 3: Automated Rules

In this phase we define automated rules to automatically enroll users to events and assign them to tracks as well. This is done based on the groups the users are members of and the data that we fetch from the external data source for that user.

Security Concerns

Some of the security techniques we use to protect the data that customers send us are:

  • All communication is encrypted in transit. (End 2 End, including behind the App Gateway, Load Balancers, etc)
  • All data is encrypted at rest

What PlusPlus Needs for Integration

This is what we have out of the box that we can use for the integration.

Supported Authentication Mechanisms

Usually, integration endpoints are behind an authentication layer. These are the authentication methods we support out the box:

  • Basic
  • Token
  • OAuth

Data we expect to receive

We expect a minimum set of fields that should be provided to us when implementing integrations. Here is the the list of expected fields:

  • Full name (string) *: Full name of the employee
  • Email (string, format: email) *: Primary email of the employee
  • Photo (string, format: URL) : URL pointing to the employee’s profile picture
  • Employee ID (string): Employee identifier string in the original People Management System
  • Hire Date (string, format: YYYY-MM-DD): Date in which the user joined the company
  • Termination Date (string, format: YYYY-MM-DD): Date in which the person left the company, in case they did
  • Department (string): Department which the employee works on
  • Job Title (string): Job title of the employee
  • Location (string): Name of the employee’s location. It must match a location name previously created on PlusPlus otherwise users’ locations will be left blank.
  • Manager’s Email (string, format: email): Primary email of the employee’s manager.

* Fields marked with an asterisk are mandatory

Other fields can be included but we won’t have any special treatment to them unless we implement custom rules that are specific to the customer of the integration.

Data Fetch Methods

We have a couple of methods that we currently support for fetching your data. They’re broad and not tied to any specific software or tool, but they have some constraints that may require some configuration.

CSV over SFTP

We provide a repository for sending updates on customers’ People data through the SFTP protocol. To have access to this feature you have to contact your Customer Success Manager and request the access credentials. We support both Basic Auth and Private Key.

The integration using this method must be implemented respecting the following requirements:

  • Only 1(one) file can be sent file per day
  • The file to be sent should be named in the following format “people_report_YYYY-MM-DD.csv”, eg.: “people_report_2020-02-09.csv”, “people_report_2020-11-30.csv”.
  • The files should be uploaded to this folder "uploads/hr_reports".

The file format should follow these requirements:

  • The header of the file should be: "Full Name", "Email", "Employee ID", "Department", "Title", "Hire Date", "Manager’s email", "Picture URL", "Department", "Job Title", "Location", "Termination Date";
  • The "Employee ID", "Hire Date", "Termination Date", "Department", "Job Title", "Location", "Manager’s email" fields are optional, can be left empty
  • New columns can be added to the right of the default ones. They aren’t going to be stored in the user profile, but they can be used to define automated rules for enrollments, groups’ membership and track assignments;
  • All values should be quoted with double quotes (");
  • The separator character should be ",";
  • The escaping character (in case escaping is needed) is "\\";
  • The new line characters are "\r\n".

JSON/CSV Endpoints

We can also retrieve the data directly from your People Software or database. We need access to two endpoints in order to have the data correctly for all situations:

  • List all users: We need an endpoint the returns the list of all users that will need to be provisioned and updated on PlusPlus
  • Retrieve a user by email (optional): When users log in, we need to retrieve their information on the People Management System to update them in PlusPlus.

People Systems we Support

Groups Creation/Assignment

PlusPlus is able to automatically create groups based on fields available through the integration. This process is not automatic and it must be aligned with the success/support rep beforehand. As this is a custom work it may take a few sprints to be fully implemented.

Automated Rules (event enrollments and track assignments)

PlusPlus has an internal API for creating automated rules for event enrollments, track assignments and assignment to groups. This API is not open to customers, but allows the PlusPlus Engineering Team to quickly implement the rules needed.

PlusPlus Success Rep will provide a spreadsheet that will allow customers to fill all the information needed by the Engineering Team to implement the rules. The information includes the conditions for each rule and the expected effects on each user that fits the conditions.

We’ll explain in detail what each information on the spreadsheet means.

Conditions

They define whether users are going to be selected to have effects run on them based on the fields fetched through the integration and the information available on PlusPlus (like event enrollments, track assignments, groups membership, etc).

We need to have full descriptions of all the conditions considering field names, so they can be implemented by the PlusPlus Engineering Team. This is the only part of the automated rules that is fully customizable.

Effects

Effects are operations that will be applied to a set of users when the integration runs. There are options for enrolling users on events of a track or of an event-type, assigning users to tracks and adding/removing users from groups.

Enrollment Effects

These effects are for enrolling users into events from a Track or an Event Type.

Common Parameters

All effects related to enrollments in events have the following options:

  • force_enrollment: Forces the user to be enrolled in the event increasing the capacity in case the list is already full.
  • enroll_in_next_event_if_over_cap: Tries to enroll the user. If the event is over capacity, it tries to enroll the user in the next events until it finds one with enough capacity. If there's none, it doesn’t do anything. It can be combined with enroll_or_enter_waitlist to also consider waitlist capacity before trying the next event.
  • enroll_or_enter_waitlist: Tries to enroll the user. If the event is over capacity, it tries to enroll the user in the waitlist. If the waitlist is full, it doesn’t do anything. It can be combined with enroll_in_next_event_if_over_cap parameter to enroll in the next event if the waitlist is full.

Common Parameters precedence order

  • force_enrollment takes precedence over all the other parameters.
  • If enroll_in_next_event_if_over_cap and enroll_or_enter_waitlist are used together, waitlist capacity is also considered before trying to enroll in the next event.

Available Effects

Enrolls users to all events of an Event Type (enroll_user_on_next_event_of_event_type)

Parameters:

  • event_type_id (int): The id of the event type you whose events you want to enroll users to.
  • after_timedelta (datetime.timedelta): This will only enroll users on events after current_date_time + timedelta
  • force_enrollment (bool)
  • enroll_in_next_event_if_over_cap (bool)
  • enroll_or_enter_waitlist (bool)

Enrolls users to the next event of an Event Type (enroll_user_on_nth_event_of_event_type)

Parameters:

  • event_type_id (int): The id of the event type you whose events you want to enroll users to.
  • event_number (int): The number of the event you want to enroll users to (1 for first, 2 for second, 3 for third and so on).
  • after_timedelta (datetime.timedelta): This will only enroll users on events after current_date_time + timedelta
  • force_enrollment (bool)
  • enroll_in_next_event_if_over_cap (bool)
  • enroll_or_enter_waitlist (bool)

Enrolls users to the nth event of an Event Type (enroll_user_on_all_events_of_event_type)

Parameters:

  • event_type_id (int): The id of the event type you whose events you want to enroll users to.
  • after_timedelta (datetime.timedelta): This will only enroll users on events after current_date_time + timedelta
  • force_enrollment (bool)
  • enroll_or_enter_waitlist (bool)
  • PS.: enroll_in_next_event_if_over_cap isn't available in this effect because if you're enrolling in all the events of an event type it makes no sense as the user will already be enrolled in the next event.

Enrolling users to the next event of each Event Types of a Track (enroll_user_on_next_events_of_all_event_types_in_track)

Parameters:

  • track_id (int): The id of the track you want to use for enrolling users. The users will be enrolled to the next event of each event type on it.
  • after_timedelta (datetime.timedelta): This will only enroll users on events after current_date_time + timedelta
  • force_enrollment (bool)
  • enroll_in_next_event_if_over_cap (bool)
  • enroll_or_enter_waitlist (bool)

Track Assignment Effects

Available Effects

Assigning the selected Track to a user (assign_track_to_user)

Parameters:

  • track_id (int): The id of the track you want to use for enrolling users. The users will be enrolled in the next event of each event type on it.
  • inviter_user_id (int): The id of the user that is going to appear as inviter in the invitation email.

Group Membership Effects

Available Effects

Adding the user to a group with the selected name. If the group doesn't exist it is created. Be careful to write the group name correctly to avoid duplicate groups. (add_user_to_group)

Parameters:

  • group_name (str): The name of the group you want to add the user to.

Removing the user from the group with the selected name. If the group doesn't exist we'll skip this operation. (remove_user_from_group)

Parameters:

  • group_name (str): The name of the group you want to remove the user from.

Did this answer your question?