Skip to content
  • There are no suggestions because the search field is empty.

Directory management

Use Calven's directory management tools to automate directory properties, create hierarchy, and synthesize dynamic groups

Background

Calven is a workplace tool that is designed to support enterprise customers who need to operate at scale. One of the ways that Calven supports this scale is by connecting to your directory systems to configure Calven behaviors. We provide workplace administrators with the tools to stage, audit and track directory changes so they can view changes in those behaviors. 

The primary goals of using the directory management at scale are:

  1. Create groups in Calven that match your directory structure
  2. To assign a user’s primary office when you have multiple offices
  3. To assign a user’s primary group - which is the group of users they will sit with by default

Note: this is a technical article and is meant to be read by people familiar with their directory tools and SCIM.

Directory Connections via SCIM

Calven connects to your directory via SCIM. SCIM is a protocol utilized to share directory information from tools like Okta and Microsoft Entra ID. Some information is shared by default, including user attributes such as: name, email address & department. 

More user properties can also be shared from those tools, and that information can be configured in the directory tools through a process called expression mapping. Mapping is not required for straightforward implementations - but it allows you to do more powerful configuration of Calven at scale.

Mapping allows some customization of the attributes that are shared with Calven. For example, if you wanted to create a new attribute that is a user’s full name you could build it from their firstName and lastName fields by utilizing this mapping:

String.append(source.firstName, “ “, source.lastName)

There are very powerful mapping capabilities available to customize the way you share your directory data with Calven. You can find the full details on SCIM mapping capabilities in Okta and Microsoft at those links. 

Utilizing SCIM in Calven

Calven can create groups based on user properties pushed from your directory via SCIM. This allows directory changes to be communicated to Calven at scale. 

Calven allows administrators to see the changes in their directory. This document will outline how administrators in Calven can operate controls to set up the directory configuration and review changes over time.

Setting up groups

For the most straightforward implementation, you can use the department property to create groups and assign those groups to users as their primary group. The department property is always shared with Calven via SCIM so it does not require any configuration in your directory. 

For more sophisticated setups, where you want to share multiple levels of an organization and create your org hierarchy in Calven, or where you want to share additional properties to create groups like Fire Wardens and First Aiders, we can do more. You should decide which properties you want to be used to create groups. 

Calven allows you to set both a group ID and a group friendly name. This allows you to maintain the same group through name changes that happen over time. For example, if “Engineering” changes to “Engineering and Development” but you have an ID property for that group in your directory, that name change will maintain the same group rather than deleting and creating a new one. Cost codes are one common way of maintaining a consistent group ID through name changes. We recommend using a group ID if you have one available.

The second decision you need to make is whether you want employees to be able to configure their primary groups to sit with other teams that may not reflect their directory location. You have 3 options:

  • Do not allow employees to configure their primary group, restrict it to the directory setting.
  • Set the default for employees but then let them change their primary group
  • Do not provision a primary group from the directory, let employees set it (not recommended).

Once you have made the decision on which groups you want to create in Calven, if you have group IDs, and whether users should be able to change their primary group - you are ready to set up groups..

Setting up primary offices

If you have multiple offices, you can configure users so that they are automatically assigned into their office by default. To do so, you need to configure their primaryOffice attribute. To be assigned to an office, the property for a user must mach the name of the office in Calven.

Often there may not be a 1:1 correlation between location attributes in Calven and your office names. For example you may have 2 location attributes for users (‘US-CA-Bay-Remote’ and ‘US-CA-SFO’) that should both be assigned to the ‘San Francisco’ office. In order to convert those properties into the right format for primaryOffice, you can use a mapping like the one shown below (Okta example). 

String.stringSwitch(

  user.locationName, "Remote",

  "US-CA-Bay-Remote", "San Francisco",

  "US-CA-SFO", "San Francisco"

)

Once you have decided on which property you want to use to determine a user’s primary office, you are ready to set that up.

Implementing Directory Management Configuration

Directory management is available to users with the role of Global Administrator and Integrations Admin. To setup directory management, navigate to https://backoffice.calven.com/directory-management  and you should see a screen like below. It shows the user properties that are being synchronized from SCIM.

The view in here is ready-only. To set up your SCIM integration, contact your Calven representative. You will need to share the decisions you have made above about what configuration you want to use.

Process

Once the Calven team has configured directory management, you can synchronize the data. Only global admins and integration administrator roles have access to the steps below.

Moving the information from your directory into Calven is done in 2 ways: 

  1. copying User Properties from your directory to Calven
  2. creating Dynamic Groups based on those properties. 

In both of these methods, properties are shared with Calven via SCIM immediately, but Calven will not utilize those properties until an administrator approves those changes. That process of approving the changes goes as follows:

  1. The administrator creates a mapping report that shows the changes that have happened in the directory and highlights any issues from applying those changes in Calven.
  2. The administrator can download and audit those changes in a mapping report. While this step is optional, we always recommend reviewing the changes.
  3. The administrator applies the changes.

This is done so you can always review changes. Now lets go through those steps for each of the 2 report types.

Dynamic groups

Dynamic groups will be created from user properties in a way that all user properties that have the same name (e.g. Bill and Sarah both have a department property of “Marketing” will become members of a group called “Marketing”). Go to the directory management dynamic groups page here to view the configuration.

A report that shows the groups that will be generated based on user properties is used to audit the groups that will be generated. The report can be manually generated by clicking “Generate group mapping report”. If you have thousands of users, the report can take a minute or two to generate. Once it is generated you can download the report to review it.

Things to look for In the group mapping report:

  • errors can be found by searching for or creating a filter for the term “error”. These errors will show what groups cannot be created because of conflicting directory information. See the error’s details for more information. 

  • Deleted groups because no users have the property set to that value anymore. 

User Properties

As a reminder, user properties can be shared with Calven for the following purposes:

  • To assign a user’s primary office - via the primaryOffice property. The user’s primary office determines what office they are assigned to - which affects their default “change my plan to come into the office” behavior, as well as counts them as members of that office for analytics purposes. The primaryOffice property value must match the name of the office for the user to be assigned.
  • To assign a user’s primary group - via the primaryGroup property. The user’s primary group determines which team they will sit with by default when using the dynamic stack booking algorithm. Calven will begin using the primaryGroup property in other areas of the product so we always recommend setting this value. The primaryGroup property value must match the name of the group for the user to be assigned.
  • To assign a user’s timezone - via the timezone property. The timezone is used to show what the time is for other users when viewing their profile, and that user is remote. 
  • To share properties about a user that are visible to global administrators when viewing the user’s profile. Any property can be used for this purpose, it just needs to be configured.

Note that when a user onboard/offboards, user provisioning/deprovisioning occurs immediately and is divorced from this process. 

To begin, go to the directory management user properties page here. by first generating a property mapping report, then downloading it to review. 

In the user property mapping report, errors can be found by searching for or creating a filter for “error”. Most errors occur from setting a user’s primary office or primary group to an invalid value or having 2 offices/groups with the same value, and they need to be made unique. 

The primary group must be set to a name or group ID of an existing group in Calven. If that primary office name or group ID does not exist, then an error will be shown. Because 

The mapping report can be applied even if errors exist, but those values with errors will not be updated. Pending changes will be made when the report is applied, and no-op values are already correct and will not be changed.