The Teams Bulk Update feature allows an Admin to download an xls of all Team scoped records in their environment’s databases so that missing parent or team IDs can be added, then the xls uploaded and changes applied.

It could also be used to apply a new Associated Teams configuration for an Account to all existing Projects and related records associated with that Account.

This feature is accessible via the Configuration Portal, found in your menu.

Common Use Cases

  • Unity Teams is deployed to an environment that has been running Crunchwork for some time and has many existing records.

  • One or more Associated Internal or External Teams have been added to an Account via the Accounts app, and you wish to apply the same Team scoping to all Projects (and their related records) associated with this account.

  • One or more records associated with a Project or other ‘parent’ record seem to be missing or are not visible in CW. An error may have occurred when applying Team scoping to these records, and to help identify if this is the case we can download a Teams Bulk Update XLS for the specified record types in Configuration Portal, identify whether the records do exist and have incorrect Teams, and repair them.

Downloading the XLS

  1. Ensure that you have the correct permission.

  2. Navigate to the Configuration App.

  3. Select ‘Teams Bulk Update’ from the ‘Select Record Type’ dropdown list.

  4. Click the ‘Download Xls’ button, and select the record types that you want included in the spreadsheet (there’ll be one sheet per record type, and a ‘Teams’ sheet for reference).

  5. Click ‘Confirm’, and an xlsx file will be downloaded.

Viewing/Modifying the XLS

  • In each sheet of the xls (except for the ‘Teams’ reference sheet), there is an ‘Updated …’ column to the right of each column whose value can be changed. These columns' cells are coloured grey, to indicate that this is the only place that changes can be made. Changes to any cells that are not grey will be ignored by the Bulk Update process.

  • Sheets that contain more complicated options than just ‘Updated .. Teams’ have instruction text at the top.

  • When specifying ‘Updated .. Teams’ for a record, copy the Team Names from the ‘Teams’ sheet and separate them with commas. Team names must be written exactly as they are in the ‘Teams’ sheet.

  • When specifying a new parent for a record, paste in the ID of the parent record. Copy the ID of the desired parent record from its sheet. (e.g. after identifying which Pulse Project you wish to assign to an Invoice, copy the ID from the ‘Pulse Projects’ sheet into the ‘Updated Pulse Project’ column in the ‘Invoices’ sheet)

  • The ‘Pulse Projects’ sheet also has a ‘Repair’ column. Putting ‘Y' in this column results in the specified Project’s current Teams being propagated down to all of its descendants.

Example of repair column.

Executing Bulk Updates (In the Correct Order)

Because of the way changes to parents or Teams propagates down to a record’s descendants, it’s important to perform Bulk Updates in the following order. If executed out of order, later changes may overwrite or have no effect on earlier changes (when an effect is expected).

Execute a Bulk Update

  1. In Configuration Portal, select ‘Teams Bulk Update’, then click the ‘Upload XLS’ button in the table header.

  2. Drag in or navigate to the xls file that you previously downloaded and modified.

  3. Upon uploading the xls, a new entry should appear in the ‘Teams Bulk Update’ table to represent your Bulk Update. (You may need to click the refresh button in the table header to make it appear.)

  • Bulk Updates will be executed from oldest to newest, so if there was Bulk Updates already queued, yours will be added to the back of the queue.

  • Keep an eye on the ‘Status’ of your Bulk Update. If an error occurs, it will change to ‘Failed’, and a list of errors will be displayed in the ‘Errors’ column.

Note that Bulk Updates could take a long time to execute, as they’re calling many ‘set<record type>Teams’ gql mutations which in turn potentially execute many reads and writes to database tables.

Correct Order

1. Accounts

The Associated Internal and External Teams defined for an Account are combined and applied to all Pulse Projects related to that Account at creation time. However Bulk Updating or just changing Account teams via the Accounts app does not trigger propagation to Projects.

If you wish to change the Teams associated with an Account and have them propagated to Projects, execute a Bulk Update with Account changes first, then Pulse Projects - with ‘Re-inherit from Account’ selected.

2. Pulse Projects

Pulse Projects are at the core of Team assigning and inheritance. Changes made to a Project’s Teams apply to all descendants of the Project (Jobs, Quotes, Invoices, Attachments, Emails, etc.). The ‘Pulse Projects’ sheet contains more options than any other record types' sheets in the downloaded xls.

  1. If you made changes to Account teams, or you just want to re-inherit teams from each Project’s Account (e.g. if this is the first time you’ve deployed Teams to an environment with existing records which may have ‘Default’ team assigned to everything), place a ‘Y' in the 'Re-inherit from Accounts’ column for each record you wish to update, and execute the Bulk Update.

  2. If you are happy with the Teams assigned to each Project and you just wish to re-propagate those Teams down to all of the Project’s descendants, place a ‘Y' in the 'Repair’ column for each record you wish to repair and execute a Bulk Update.

  3. If you wish to change the Teams assigned to some Pulse Projects so that they are different to those inherited from the Project’s Account, list comma separated Team names in the ‘Updated Teams’ column and execute a Bulk Update.

3. Everything Else

Now that your Account and Pulse Project Teams are exactly what you need them to be, the only remaining work is to ensure that records that are not owned by a Pulse Project or Account are correctly Team scoped.

  1. Specify comma separated Team names in the ‘Updated Teams’ column for all records that you wish to update, then execute a Bulk Update.

Troubleshooting

  • If you’re encountering issues like ‘Account not found’ when executing a Bulk Update and the uuid of the specified account definitely matches an Account in the database, check that the Account has at least one Team uuid in its associated_internal_teams or associated_external_teams columns. Early Teams code didn't ensure that at least one Team was applied to a new Account at creation time, so it is possible that some accounts have null in their team_ids column, making that record inaccessible by the Bulk Update process.

    • To fix: Either manually paste some valid team_ids into the accounts table, or run one the unity:db:setAssociatedInternalTeams helper from operations / operations-dev to apply the ‘Default’ Team to all accounts that have null in their associated_internal_teams column, then run the Bulk Update again.

Did this answer your question?