Importing org structures into Charts

NOTES 

You can jump to Reports-to template if you're only looking to download the pre-formatted template.

The Edit Teams allows you to build Chart structures manually in the Teams user interface. Smaller organizations may find this preferable to importing, as each user is placed manually into the tree.

Certain types of team imports can also be done via SFTP.

Table of contents

1. Importing a hierarchy into a Chart (CSV)
2. Importing a self-managed team into a Chart (CSV)
3. Importing via TXT

About importing

In Administration Settings > Views and Functions > Import Chart into Teams there are two methods of importing available:

• CSV (.csv file): used for importing new structures or overwriting existing structures
• TXT (.txt file): used for importing a previously-exported backup of an existing structure

CAUTION: If you import a CSV/TXT to an existing Chart it will replace (overwrite) the existing Chart.

If the Team Names remain the same we will preserve Org Units as much as possible when you do overwrite a Chart via a CSV import.

More information about creating a CSV for Team importing (via SFTP) can be found here.

Importing a hierarchy into a Chart (CSV)

For many organizations, the main reports-to hierarchy exists in another enterprise system. By exporting that data and formatting it into a suitable CSV you can import into a Chart. You can use this same method to upload the structure of a project team into another Chart.

1. Populate your CSV

In its most basic form, it simply needs to be a CSV with two columns:

• Username - for each employee (usually their work email address)*
• Supervisor Username - each employee's supervisor's username.

*Verify Usernames via Administration Settings > User Accounts and Data > Edit, Invite, Disable Users. Assigning a user’s work email as their Username is the recommended setting, and is the method shown in the template and examples below.

There are two additional fields you can use when importing a reports-to structure into a Chart:

• Role Name - This will define the Role of each user (employee) in the hierarchy.  Often this maps to a person's job title, but doesn't always have to (learn more here).  If this is left blank you will have to add these Role Names manually later.
• Team Name - If you leave this field blank during your import, they will be automatically named based on your existing structure (as shown in the examples below where two teams were created - CEO's Team and Emp 1's Team) 

Reports-to template: Importing your structure using the .csv file is only for solid-line (primary) reports-to structures. You can use our pre-formatted template to get started.

• *Golden rule*  It is important to ensure the chain of command is continuous from top to bottom. Your CSV must form a single, continuous tree, so make sure to leave a blank for your top manager's (CEO, City Administrator, etc.) Supervisor Username (see example in Section 2, below)

NOTES

Sub-Teams: You can include a Sub-Team within your structure by entering "Sub team" in the Role Name field and the name of the Sub-Team in the Team Name field (and the Username does not need to be an email address).

Open Roles: If you want to import a structure that includes a Role that has not been filled, you can do so by entering a dummy name in the Username field (something that is not an email address, for example, "emptyusername"). This will create an Open Role card that can be assigned to someone later via the Edit Chart mode.

2. Import your CSV

Once the CSV is ready to be imported:

1. Go to Administration Settings > Views and Functions > Import Chart into Teams

2. In the Import Options section, select CSV and any other optional settings.

3. Click the Choose File button to locate and select your CSV. 

4. In the Destination section, make the appropriate Category and Chart Selections (if you're importing your organization's main reports-to hierarchy, select the Main Organization category)

5. Click Upload. If needed, follow the onscreen mapping prompt

NOTE—the mapping prompt will only appear if your column headers are anything other than our defaults (Username, Supervisor Username, Role Name, and Team Name). If our column header defaults do exist in the .csv file being uploaded, the mapping step will be skipped.

If your CSV upload is successful, the process looks like this:

If your CSV upload is unsuccessful, it may be due to the following errors:

Error 1: Supervisor field left blank for anyone other than the top of the tree: 

Error 2: People are reporting to themselves (i.e., a Username and its corresponding Supervisor Username are identical):

Error 3: "Specified user was not found" error. This can occur when the incorrect Username for a Contributor is entered, which most commonly happens when a Contributor's work email has not been set as their Username in their Profile, but was entered in the CSV as if it were. Verify Usernames via Administration Settings > User Accounts and Data > Edit, Invite, Disable Users.

Importing a self-managed team into a Chart (CSV)

Similar to importing a reports-to structure into a Chart, you need to create your CSV and follow the golden rule. In this example, we’re creating a Basketball Team as a new Chart under the category “Committees and Clubs”.

Since this is a self-managed team, it does not have a supervisor. So the card everyone 'reports to' on this team is a Team Card.

In the first row of the CSV:

1. Enter a placeholder Username for this Team Card (eg. "basketballteamcard")
2. Leave the Supervisor username field empty (golden rule)
3. Enter “Team Card” in the  Role name column.
4. Enter your Team's name in the Team name column.

Then add a row for each of your Team members. Enter their Usernames and Role names and then for each of their Supervisor username fields, enter the placeholder Username from the first row (i.e. "basketballteamcard").

NOTE—you can use this same method of setting the Role Name to be "Team Card" to create a self-managed team anywhere in a Chart, including within an extended reports-to structure.

To import your completed CSV

Go to the Administration Settings > Views and Functions > Import Chart into Teams, and fill out the Import Options  as detailed in the "Importing a hierarchy" section above.

In the Destination section, select your Category (in this example, "Committees and Clubs") and then select “Create new Chart” for you Chart. Then click Upload.

 After the import your new Chart will look like this 

NOTE: If you do not add the Team Name (leave this field blank) the Team will be called "Unnamed Team".

Importing via TXT (using previously exported structures)

The following process explains TXT importing, which is only recommended for importing existing structures (that were previously exported to either to use as a backup or to make edits to existing Charts and then re-import back into Teams).

Editing structures

If you have exported a structure via .txt file, it will contain over 20 columns of Chart data. However, for editing purposes there are only 8 columns to be concerned with: 

• Id - This is essentially the row (with each row indicated by a sequential numeric value) and allows for a hierarchy to be constructed.
• ReportsToId - (NOTE – this should be read as “Reports To Id” not “Reports Told”) This is the Id of the supervisor (i.e. this role reports to the card identified by Id)
• Username - The Jostle username of the employee assigned to the related role. If this field is empty then the created role will be vacant.
• RoleName - Contains the role name
• RoleType - One of DIRECTED_TEAM, CONTRIBUTOR (which indicates a leaf node), COLLABORATIVE_TEAM (which indicates this is a Team card), or SUB_TEAM (which indicates this is a Sub-Team)
• RelationshipType - One of PRIMARY_SUPERVISOR, SECONDARY_SUPERVISOR, or COLLABORATOR which specify solid line, dotted line or collaborator as the relationship to the role specified by ReportsToId. This will be empty for the top node in the chart
• TeamName - This is populated with the name of the team if this person is the team lead. 
• OrgUnit - This is populated with the name of the Org unit if there is one for that team. This is a Read-Only field, so deleting a row from an exported file that contains an Org unit will cause that Org unit to be deleted for the whole org when the file is re-imported.

TIPS 

When round-tripping from a Chart txt export you can:

1. Export .txt file as described above.
2. Manually edit the file name to change the termination from .txt to .csv.
3. Open the .csv in Excel of Google Sheets, so that it is easy to understand. Edit it as required.
4. Import the edited .csv file while selecting the .txt import option (see below).

Also note:

• If you want to change the ordering of your structure, it's better to use the Organize option on the Edit Teams screen post-import.
• If any of the above column names (except "Username") are missing from the file header when you re-import your file, the import will fail.
• The Id, RoleType and RelationshipType fields cannot be left empty when you re-import.
• ReportsToId must be left empty for your org's top supervisor (i.e. your CEO)
• If RoleName or TeamName are left empty, the roles will be created with default names, like 'New Role' or 'New Team'.
• Username can be left empty,  but if it's filled in with a user that doesn't exist, importing that row will fail.
• If an import fails, any information about the errors will be reported in the Results file that can be downloaded from the Status page.

Importing

1. Go to Administration Settings > Views and Functions > Import Chart into Teams

2. In the Import Options section, select TXT and any other optional settings.

3. Click the Choose File button to locate and select your .txt file. 

4. In the Destination section select the desired Category and Chart and then click Upload.

Attachment: