Staff directory and org chart

Overview

Workplace’s staff directory and organisation (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 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, which can be 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, etc.

  • 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. While username logins may be configured in Workplace (typically defined in a user directory, e.g. via LDAP), and some content for these people may be visible through the staff directory, user data for the staff directory and org chart features must still be configured separately. 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.

Prerequisites

To set up staff directory and org chart features for your Workplace instance, you require a Workplace system administrator account.

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.

This is designed to support case-sensitive usernames in Workplace (typically defined in a user directory, and configured in Workplace via LDAP), such that usernames spelled the same way but with unique combinations of differing letter cases (e.g. jdoe and JDoe), are treated as separate user accounts when logging in to Workplace.

If, however, you require Workplace’s usernames to be unique for a given spelling only, then Workplace’s default username settings for the staff directory and org chart features may cause issues, since upon importing data for these features, usernames like jdoe and JDoe would be treated as different user accounts/people. Therefore, upon import, you would end up with two entries for 'jdoe' in your staff directory and/or org chart.

Hence, you can configure the staff directory and org chart features in Workplace to disable support for case-sensitive usernames, so that upon importing user data for these features, entries for users with usernames like jdoe and JDoe would be merged into a 'jdoe' staff directory and/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 side nav on the left, 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 side nav 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. Be aware that usernames are case-sensitive.


    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 sample-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 sample-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 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 side nav 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-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 alternatively configure your org chart for Workplace to be 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 side nav 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-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/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). 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 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
    sample-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
    sample-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 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 side nav on the left, 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 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.

© 2015- Squiz Pty Ltd