Staff directory and org chart

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

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

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.

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

Ensure you are logged in to Workplace as a Workplace system administrator and have accessed admin mode.
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.
Right-click the sample-org-chart-data.csv asset and choose Details.
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

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.

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.

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

Ensure you are logged in to Workplace as a Workplace system administrator and have accessed admin mode.
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.
Right-click the Org Chart Import asset and choose Details (and Acquire Locks on the right if necessary).
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.
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

Ensure you are logged in to Workplace as a Workplace system administrator and have accessed admin mode.
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.
Right-click the sample-json-org-chart-data.json asset and choose Details.
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

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.

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.

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

Ensure you are logged in to Workplace as a Workplace system administrator and have accessed admin mode.
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.
Right-click the Org Chart Import asset and choose Details (and Acquire Locks on the right if necessary).

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.

Click Commit to save your org chart changes.

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

Obtain and download the sample staff directory CSV file from Workplace

Ensure you are logged in to Workplace as a Workplace system administrator and have accessed admin mode.
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.
Right-click the sample-staff-data.csv asset and choose Details.
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

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.

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

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

Ensure you are logged in to Workplace as a Workplace system administrator and have accessed admin mode.
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.
Right-click the Staff Data CSV asset and choose Details (and Acquire Locks on the right if necessary).
On the right, under the Upload Staff CSV file section, click Choose file and choose the staff-data-v1.csv you modified above.
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.

Help Center

Menu

Staff directory and org chart

Overview

Prerequisites

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

Obtain and download the sample org chart CSV file from Workplace

Update the org chart CSV file

Upload the org chart CSV file to Workplace

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

Obtain and download the sample org chart JSON file from Workplace

Update the org chart JSON file

Upload the org chart JSON file to Workplace

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

Obtain and download the sample staff directory CSV file from Workplace

Update the staff directory CSV file

Upload the staff directory CSV file to Workplace

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