Primary Location for Occupancy Analytics

Populate data in your Occupancy Analytics by setting an employee's

Updated over a week ago

Primary Location For Occupancy Analytics

You will see "primary" and "default" location used interchangeably. Please note that these refer to the same employee data field.

Envoy now offers the ability to set a default location for employees, manually or via SCIM. Setting default location provides data to our Workplace Occupancy analytics. It allows for data to be populated in our Workplace Utilization graph and the Attendance + People in dept columns in the Daily average attendance by department graph.

Note: Setting default/primary Location does not change what location the employee sees when they first log into Envoy. The defaultLocation attribute allows Envoy to populate valuable data in our Workplace Occupancy Analytics.

How it works

When viewing an employee's record within the employee directory, you'll be able to see their primary location. Learn more about the employee directory.

To view, simply navigate to Employee directory > and select an employee.

Setting up primary location


If you have a smaller employee count, managing primary location can be done manually. This allows you to use the occupancy dashboard without needing a SCIM integration.

  1. Select an employee you wish to edit. Scroll down until you see the Edit button, then click Edit.

  2. Use the dropdown under Primary location to designate an employee's primary location.

    1. You can only select between locations the employee has been added to. You can view which locations an employee has been added to by looking at the Employee's Locations list at the bottom of their record. You can add/remove locations by using the Edit button.

  3. Click Save to save your changes.

Via SCIM integration

SCIM Requirements

  • The default location values in this custom attribute must be an exact match with the Envoy location name you want

  • For example, if John Doe works in the New York City office of Acme Industries and the location name set in Envoy is “NYC”, this custom attribute must set John’s default location name as “NYC”.

    • Please note that in Envoy, your company’s name is automatically prepended to the location name. For example, you might see “Acme Industries NYC” in the dashboard while the location name is just “NYC”.

  • To find the names of locations, go to the location picker. The Envoy location names are the text after your company name (e.g. “Envoy New York” means the name is “New York”)

Okta Instructions

  1. Once you have logged into the Okta admin dashboard, go to Applications section in the sidebar and click on “Applications”

  2. On this page you should have an Envoy app with status “Active”. Click on it.

  3. Within the Envoy app configuration there is a tab titled “Provisioning”, navigate here.

  4. About halfway down the page you will see “Envoy Attribute Mappings”, click on the “Go to Profile Editor” button.

  5. In the Profile Editor you will see a button that says “Add Attribute” click here and a modal will open.

  6. Within the Add Attribute menu set:

    1. Data type: String

    2. Display name: Default Location Name (or any preferred title)

    3. Variable name: This can be whatever you choose, but we recommend something along the lines of "defaultLocation".

    4. External name: defaultLocationName

    5. External namespace: urn:scim:schemas:extension:envoy:core:1.0:User

    6. Description: Add any text here to help other admins know what this is for

  7. When done click Save

  8. Now back on the Profile Editor click “Mappings”

  9. On the menu titled Envoy User Profile Mappings click “Okta User to Envoy”

  10. At the bottom of the attribute list on the page you should see the newly created defaultLocationName attribute.

  11. You will need to map this to the Envoy attribute defaultLocationName.

  12. Click “Save Mappings” and you are done! Upon the next data sync the data will be set in Envoy.

Bulk update this custom attribute

You can bulk update this custom attribute with the necessary values through a CSV upload. For example, if your HRIS system does not store office locations in a format that matches Envoy location names, you can create a separate employee mapping spreadsheet with matching values to upload.

For instructions on this process, please reference the official Okta documentation on this topic (link).

Azure Instructions

  1. After logging into Azure, use this link to access the page with all the menu options available to add new extension parameters

  2. Go to EnterpriseApplications → Your SCIM Application → Provisioning

  3. Click on “Edit Attribute Mappings”

  4. Under the Mappings section select the mappings for Users

  5. At the bottom of the page click “Show Advanced Options”

  6. Click “Edit attribute list for Envoy” and this will show you a section where you can add the new “defaultLocationName”. There is no dropdown menu since Azure does not populate these fields from the schema. Instead you simply type this into the box.

  7. After this you can return to your User mappings and you will be able to add a new mapping referencing this extension in the “Target attribute” field

    1. “Mapping type” should be “Direct”

  8. And that’s it! Once your provisioning runs a sync the attribute will be applied to your Employees in Envoy.

Note: You can set an employee's default location with a Visitors-only account, but the occupancy analytics are only available with Workplace Premium subscription.

Did this answer your question?