Help Center

Menu

Staff directory and org chart

This procedure is correct for at least Workplace v3.8.

Overview

Workplace’s staff directory and organisation (org) chart features allow you to view information about staff members within your organisation, as well as to whom these staff members report.

The staff directory and org chart features in Workplace are populated from the following data sources:

  • Staff directory - CSV or database *

  • Org chart - CSV or JSON

* Limited staff directory content is also created/populated for a Workplace user whenever this person logs in to Workplace for the first time.

This page describes the processes for populating both of these features in Workplace from three sample CSV and JSON data sources, obtained through Workplace’s admin mode. These sample source files are:

  • sample-staff-data.csv - contains information about staff data, such as the user’s name, job title, among other details.

  • sample-org-chart-data.csv - contains information about the structure of the org chart.

  • sample-json-org-chart-data.json - also contains information about the structure of the org chart, but in JSON format.

The staff directory and org chart features are not configured by default in Workplace and must be configured separately. These features are deliberately separated from username logins and any user data content that forms part of a user’s login profile. This separation allows for:

  • a more consistent approach to how user data is represented in Workplace, and

  • additional people not configured to log in to Workplace to be represented through the staff directory and org chart features.

Therefore, use the instructions provided on this page to implement the staff directory and org chart features within your Workplace instance.

Integrating org chart data from third-party systems using REST APIs

You can use third-party employee management systems to manage your org chart and staff directory information. These tools may provide access to org chart and staff directory data through a REST API endpoint.

If this option is available to you, you can use Matrix REST Resource assets in the Workplace Admin to integrate with the third-party system.

Third-party systems each implement org chart data schemas differently. Therefore, you will need to map the parameter values in the org chart and staff directory data sources to suit the third-party system’s API schema.

Setting up an integration with a third-party system may require extra configuration over what is described in the subsequent procedures on this page. However, the advantages of setting up the integration are that staff data changes can be automated between your primary employee management system and Workplace.

For more information about integrating with a third-party system, contact the Workplace support team for assistance.

Prerequisites

You need a Workplace system administrator account to set up staff directory, and org chart features for your Workplace instance.

A Squiz staff member with server-level access to your Workplace instance itself. These people are known as Workplace server administrators.

Last, ensure the general prerequisites have been met before continuing.

Configure case-sensitive support for usernames in the staff directory and org chart

By default, Workplace’s staff directory and org chart features handle usernames in a case-sensitive manner.

Usernames are typically defined in a user directory and configured in Workplace through LDAP. Usernames can be spelled the same way but feature unique combinations of differing letter cases (e.g. jdoe and JDoe) depending on the LDAP configuration settings. In these cases, usernames are treated as separate user accounts when logging in to Workplace. In the case of jdoe, two staff directory entries are created by default.

You can configure the staff directory, and org chart features in Workplace to disable support for case-sensitive usernames. With the settings disabled, users with usernames like jdoe and JDoe are merged into a 'jdoe' staff directory or org chart entry.

To configure the staff directory and org chart features to disable support for case-sensitive usernames:

  1. Ensure you are logged in to Workplace as a Workplace system administrator and have accessed admin mode.

  2. In the asset map, locate the Squiz Workplace Mk III  Squiz Workplace - Site  Services  Staff Data  Staff Data REST asset, right-click it, choose Details from the drop-down menu (and then Acquire locks on the right if necessary).

  3. Scroll down to the Staff Root Nodes Settings section, and in the Case Sensitive Username field, change its value in the drop-down to Disabled.

  4. Click Commit button to save your changes.

Obtain, update and upload the sample org chart CSV data source in Workplace

As a Workplace system administrator, obtain the sample CSV data from Workplace by downloading it from admin mode. You can then modify this data with your organisation’s actual organisational data and then upload it through Workplace admin mode.

Obtain and download the sample org chart CSV file from Workplace

  1. Ensure you are logged in to Workplace as a Workplace system administrator and have accessed admin mode.

  2. In the asset map, locate the Squiz Workplace Mk III > Squiz Workplace - Site > Site Configuration > Data > Sample data asset and expand its tree.

  3. Right-click the sample-org-chart-data.csv asset and choose Details.

  4. On the right, under the Details section, click the file’s name (Title) in the File field to download the
    sample-org-chart-data.csv file.

Update the org chart CSV file

  1. Open the sample-org-chart-data.csv file in a text or CSV file editor and familiarise yourself with its values, described in Table 1 below. Each row depicts a position within your organisation and the people/staff members who occupy that position.

  2. Remove the sample data and begin updating the following fields for each person within your organisation:

    Table 1. sample-org-chart-data.csv fields
    Field name Data type Description Required?

    positionId

    integer

    A unique ID number for the person’s (i.e. staff member’s) position.

    Yes

    parentPosition

    integer

    The positionId value of the person’s manager (i.e. the person to whom this staff member reports).

    Yes *

    positionTitle

    string

    The title of the person’s position.
    This value relates to the positionId.

    Yes

    positionOffset

    integer

    A value used to sort the person visually within the same level (i.e. team) of the organisation’s hierarchy, where the people within this team report to the same manager.
    For example, within a team, a person with a positionOffset value of 10 appears higher in the org chart than people with positionOffset values from 0 to 9 and any negative positionOffset values.

    No

    orgUnitID

    integer

    A unique ID number for the team that the person belongs to.

    Yes

    orgUnit

    string

    The name of the team that the person belongs to.
    This value relates to the orgUnitID.

    Yes

    parentUnitID

    integer

    The orgUnitID value of the parent team of the person’s team. In other words, the parent orgUnitID value of the person’s own orgUnit and orgUnitID values.

    Yes **

    usernames

    string

    The case-sensitive username/s of the person or people occupying this position.


    Multiple people may occupy a given position. For example, one staff member acts in a position on behalf of another, or two people may job-share or hold the same position.


    To specify a single user for a given position, simply specify that user’s username.


    To specify multiple usernames, separate each username with a 'pipe' (|), for example, username|username or username|username|username.


    Specifying multiple usernames results in these users appearing within the same position box in the org chart.


    To indicate such people in the org chart with their position boxes, create a new row for each person with the same data values above. However, alter the positionId and usernames values accordingly and any other appropriate field values.


    NOTE: Ensure that the usernames specified here match a username in the sample-staff-data.csv file described in the Update the staff directory CSV file section. If usernames do not match between files, clicking the position box will result in an error for the staff profile.

    No ***

    * This value is not required for the top person in the organisation’s hierarchy - for example, a CEO.

    ** This value is not required for the top-level/team in the organisation’s hierarchy - for example, the "Executive team".

    *** To indicate an unfilled position, leave this field empty.

  3. Ensure you have saved the completed CSV file with a new name to indicate the version number (and remove sample- from the name) - e.g. org-chart-data-v1.csv.

Upload the org chart CSV file to Workplace

  1. Ensure you are logged in to Workplace as a Workplace system administrator and have accessed admin mode.

  2. In the asset map side nav on the left, locate the Squiz Workplace Mk III > Squiz Workplace - Site > Site Configuration > Data > Org Chart Data asset and expand its tree.

  3. Right-click the Org Chart Import asset and choose Details (and Acquire Locks on the right if necessary).

  4. On the right, under the Upload Org Chart (from file - JSON/CSV) section, click Choose file and choose the org-chart-data-v1.csv you modified above.

  5. Click Commit to save your org chart changes.

Obtain, update and upload the org chart from a JSON data source in Workplace

As a Workplace system administrator, obtain the sample JSON data from Workplace by downloading it from admin mode. You can then modify this data with your organisation’s actual organisational data and then upload it through Workplace admin mode.

Obtain and download the sample org chart JSON file from Workplace

  1. Ensure you are logged in to Workplace as a Workplace system administrator and have accessed admin mode.

  2. In the asset map, locate the Squiz Workplace Mk III > Squiz Workplace - Site > Site Configuration > Data > Sample data asset and expand its tree.

  3. Right-click the sample-json-org-chart-data.json asset and choose Details.

  4. On the right, under the Details section, click the file’s name (Title) in the File field to download the
    sample-json-org-chart-data.json file.

Update the org chart JSON file

  1. Open the sample-json-org-chart-data.json file in a text or JSON file editor and familiarise yourself with its values, described in Table 1 above. Each row depicts a position within your organisation and the people/staff members who occupy that position.

  2. Remove the sample data and begin updating the field data described in table 1 for CSV files (above) for each person within your organisation, along the lines of the following example:

    [
 {
   "positionid": 1,
   "parentposition": null,
   "positiontitle": "Chief Executive Officer and Manging Director",
   "positionoffset": 0,
   "orgunitid": 1,
   "orgunit": "CEO Office",
   "parentunitid": null,
   "usernames": "jdoe"
 },
 {
   "positionid": 2,
   "parentposition": 1,
   "positiontitle": "Chief Operating Officer",
   "positionoffset": 0,
   "orgunitid": 1,
   "orgunit": "COO Office",
   "parentunitid": 1,
   "usernames": "pnovac"
 }
]
    Use the JSONLint or JSON Editor Online tools to ensure that your JSON file is still valid.

  3. Ensure you have saved the completed JSON file with a new name to indicate the version number (and remove sample-json- from the name) - e.g. org-chart-data-v1.json.

Upload the org chart JSON file to Workplace

  1. Ensure you are logged in to Workplace as a Workplace system administrator and have accessed admin mode.

  2. In the asset map side nav on the left, locate the Squiz Workplace Mk III > Squiz Workplace - Site > Site Configuration > Data > Org Chart Data asset and expand its tree.

  3. Right-click the Org Chart Import asset and choose Details (and Acquire Locks on the right if necessary).

  4. On the right, under the Upload Org Chart (from file - JSON/CSV) section, click Choose file and choose the org-chart-data-v1.json you modified above.

    If you have your org chart data in JSON format accessible through a Workplace asset, you can configure your org chart for Workplace based on this data source by choosing this asset from within the Upload Org Chart (from source - JSON) section.

  5. Click Commit to save your org chart changes.

Obtain, update and upload the staff directory CSV data source in Workplace

As a Workplace system administrator, obtain the sample CSV data from Workplace by downloading it from admin mode. You can then modify this data with your organisation’s actual organisational data and then upload it through Workplace admin mode.

Obtain and download the sample staff directory CSV file from Workplace

  1. Ensure you are logged in to Workplace as a Workplace system administrator and have accessed admin mode.

  2. In the asset map, locate the Squiz Workplace Mk III > Squiz Workplace - Site > Site Configuration > Data > Sample data asset and expand its tree.

  3. Right-click the sample-staff-data.csv asset and choose Details.

  4. On the right, under the Details section, click the file’s name (Title) in the File field to download the
    sample-staff-data.csv file.

Update the staff directory CSV file

  1. Open the sample-staff-data.csv file in a text or CSV file editor and familiarise yourself with its values, described in Table 2 below. Each row depicts a person/staff member within your organisation, along with relevant details.

  2. Remove the example data and begin updating the following fields for each person within your organisation:

    Table 2. sample-staff-data.csv fields
    Field name Data type Description Required?

    username

    string

    A unique name for the person (i.e. staff member). Be aware that usernames are case-sensitive.


    This value should typically match the username of the person’s login credentials.

    Yes

    first_name

    string

    The person’s first name, which appears in search results and their staff directory entry.

    Yes

    last_name

    string

    The person’s last name, which appears in search results and their staff directory entry.

    Yes

    display_name

    string

    The person’s preferred display name in Workplace. Any value specified in this field overrides any value defined in the first_name and last_name fields. However, the person can still be found when searching with the first_name and last_name field values.

    Yes

    email

    string

    The person’s email address.

    Yes

    work_phone

    string

    The person’s phone number or extension.


    You can use any format to specify the phone number or extension value. However, for the benefit of your Workplace users and to minimise confusion, use the same format consistently when specifying the work_phone value for each person in this CSV file.

    No

    supervisor

    string

    The username of the person’s manager (i.e. the person to whom this staff member reports). Be aware that usernames are case-sensitive.

    No

    position_id

    string

    A unique ID number for the person’s (i.e. staff member’s) position.


    NOTE: The position_id value specified here should match a positionId value in the
    sample-org-chart-data.csv file above. However, bear in mind that omitting this value has no impact on the functionality of the staff directory or org chart.

    No

    position_title

    string

    The title of the person’s position.
    This value relates to the position_id.


    NOTE: Ensure that the position_title value specified here matches a positionTitle value in the
    sample-org-chart-data.csv file described in the Update the org chart CSV file section. The same person will have differing position titles displayed in the staff directory and org chart features of Workplace if the values do not match.
    That is, the position_title defined in this
    sample-staff-data.csv file is displayed for the person in the staff directory. The different positionTitle value (associated with the same person’s username value) defined in the sample-org-chart-data.csv file is displayed in the org chart.

    Yes

    org_unit_team_id

    integer

    A unique ID number for the team that the person belongs to.


    NOTE: The org_unit_team_id value specified here should match an orgUnitID value in the
    sample-org-chart-data.csv file above. Omitting this value has no impact on the functionality of the staff directory or org chart.

    No

    org_unit_team_name

    string

    The name of the team that the person belongs to.
    This value relates to the org_unit_team_id.


    NOTE: Ensure that the org_unit_team_name value specified here matches a orgUnit value in the
    sample-org-chart-data.csv file above. If not, the same person will have differing team names displayed in the staff directory and org chart features of Workplace.
    That is, the org_unit_team_name defined in this
    sample-staff-data.csv file is displayed for the person in the staff directory. The different orgUnit value (associated with the same person’s username value) defined in the sample-org-chart-data.csv file is displayed in the org chart.

    Yes

    avatar

    string

    The web path to a person’s profile image. Images should be no less than 200px x 200px (72 dpi).


    If no URL is available, leave this field blank.

    No

    location_desk_number

    string

    The person’s desk number.


    You can use any string format to specify this value. However, for the benefit of your Workplace users and to minimise confusion, use the same format consistently when specifying the location_desk_number value for each person in this CSV file.

    No

    location

    string

    The name of the location of the person’s physical Workplace.


    Again, you can use any string format to specify this value. However, for the benefit of your Workplace users and to minimise confusion, use the same format consistently when specifying each person’s location value in this CSV file.

    No

    expiry

    ISO date

    The date when this user’s account should be archived.

    No

  3. Ensure you have saved the completed CSV file with a new name to indicate the version number (and remove sample- from the name) - e.g. staff-data-v1.csv.

Upload the staff directory CSV file to Workplace

  1. Ensure you are logged in to Workplace as a Workplace system administrator and have accessed admin mode.

  2. In the asset map, locate the Squiz Workplace Mk III > Squiz Workplace - Site > Site Configuration > Data > Staff Data asset and expand its tree.

  3. Right-click the Staff Data CSV asset and choose Details (and Acquire Locks on the right if necessary).

  4. On the right, under the Upload Staff CSV file section, click Choose file and choose the staff-data-v1.csv you modified above.

  5. Click Commit to save your staff directory changes.

Configure scheduled updates to the staff directory and org chart CSV files

As a Workplace server administrator, configure the Workplace server’s crontab file to ensure that any data updates to the staff directory CSV file are reflected in Workplace.

Contact your Squiz Workplace server administrator to configure these scheduled updates for you.