Help Center

Menu

Staff directory and org chart

Overview

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

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

  • Staff directory - CSV or database

  • Org chart - CSV only

This page describes the processes for populating both of these features in Workplace from two sample CSV data sources, which can be obtained through Workplace’s admin mode. These CSV files are:

  • example-staff-data.csv - contains information about staff data, such as the user’s name, job title, etc.

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

The staff directory and org chart features are not configured by default in Workplace.

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

Prerequisites

To set up staff directory and org chart features for your Workplace instance, you require a Workplace user whose account type is system administrator in Workplace. These people are known as Workplace system administrators.

Read more about morphing an existing Workplace user into a Workplace system administrator in Changing Account Types of the Squiz Matrix documentation. An existing Workplace system administrator can morph an existing Workplace user to a Workplace system administrator account type.

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.

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 section on the left, 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 this staff member reports to).

    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, as well as 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 own team - i.e. the parent orgUnitID value of the person’s own orgUnit and orgUnitID values.

    Yes **

    usernames

    string

    The username/s of the person/people occupying this position.


    Multiple people may occupy a given position when, for example, one member of staff acts in a position on behalf of another, or two people may job-share and/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 own position boxes, create a new row for each person with the same data values above. However, alter the positionId and usernames values accordingly, along with any other appropriate field values.


    NOTE: Ensure that the usernames specified here match a username in the example-staff-data.csv file below. If not, then a username defined in this sample-org-chart-data.csv file which is not defined in the example-staff-data.csv file will lead to "An error occurred while loading this staff profile!" appearing when that user’s position box is clicked in Workplace’s org chart view.

    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 section on the left, locate the Squiz Workplace Mk III > Squiz Workplace - Site > Site Configuration > Data > Staff CSV asset and expand its tree.

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

  4. On the right, under the Upload new CSV file 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 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 section on the left, 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-directory-CSV.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
    example-staff-data.csv file.

Update the staff directory CSV file

  1. Open the example-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. example-staff-data.csv fields
    Field name Data type Description Required?

    username

    string

    A unique name for the person (i.e. staff member).


    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/or 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 this staff member reports to).

    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 and/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 above. If not, then the same person will have differing position titles displayed in the staff directory and org chart features of Workplace.
    That is, the position_title defined in this
    example-staff-data.csv file is displayed for the person in the staff directory and 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. However, bear in mind that omitting this value has no impact on the functionality of the staff directory and/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, then 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
    example-staff-data.csv file is displayed for the person in the staff directory and 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 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 the location value for each person 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 example- 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 section on the left, locate the Squiz Workplace Mk III > Squiz Workplace - Site > Site Configuration > Data > Staff CSV 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 CSV file

As a Workplace server administrator, configure the Workplace server’s crontab file to ensure that 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.