In some cases, it may be necessary to make numerous changes to data in Gtmhub very quickly. A few potential scenarios:
As a new customer, you want to quickly create a large number of Objectives and Key results from another source
You have added a new custom field and want to populate it on all existing objects
Your company went through a reorganization and you need to update your users, teams, and OKRs accordingly
Gtmhub provides a utility that allows you to make these kinds of bulk changes in an Excel environment, then import them into Gtmhub. The utility allows you to bulk create, modify, and delete:
Objectives and Key Results
Access the tool for US accounts - .us appears in the account URL:
Access the tool for EU accounts - .us does not appear in the account URL:
To see a video walk-through of using this utility, click here.
Logging in to the Import/Export Utility
The import/export utility is separate from the main Gtmhub application, so you will log into it separately. When you access the main screen, you will be given the option to "Login to Account" or "Use API Token". "Login to Account" will log in through your normal authentication provider, "Use API Token" will prompt you for an Account ID and API Token.
If you have previously used the utility and the token you used is still valid, you will be given the option to re-connect to that account. This can be helpful if you're using the utility multiple times in a day.
Once you are logged in, if you have access to multiple Gtmhub accounts you will be asked which account you want to connect to. If not, or after you've selected the account you want, you will select the type of data you want to import or export.
When you select the data type, you will be directed to that data type's importer page. Note that on larger accounts, the page may take a while to load.
Before importing data, you will likely want to export either a template or the existing data from Gtmhub. If you are primarily interested in creating new objects, you will likely use the template. If you are planning to bulk-modify or delete existing data, you will want to use the Export from Gtmhub option.
Both buttons will download an Excel file with the format expected for import of the data type you selected. The only difference is that the template will not have any pre-populated data, the full export will include all data already in the system.
Working with the Data in Excel
Each Excel file contains an "Instructions" sheet that explains how the importer works, the unique identifier, and limitations for the importer for that particular data type. You will also see a listing of all columns in the main import sheets and how they are expected to be filled out.
A few general guidelines for working in the Excel files:
Each row represents one object (I.E. in the sessions import, each row is one session).
When creating, the System ID should be blank.
When bulk-editing data, delete rows that you do not intend to edit. Deleting a row means "leave it alone" in the system. Data is not deleted from the account unless you explicitly specify to delete in the delete column.
You can use formulas to fill out the cells if it helps.
You can add additional worksheets or columns on the right side of the existing worksheets.
For import types that support parent/child relationships (sessions, teams, OKRs), the parents should be listed first in the Excel file
Importing the Data
Once your modifications are complete, you are ready to import the data. On the main importer screen, click "Upload Import File" and select the modified file. Make sure Excel has saved prior to selecting the file!
You will see a list of all the data to be imported and whether it is being treated as a create, update, or delete. Any rows with invalid data will show a status of "Validation Error", all other rows will show as "Ready to Process".
Note: When importing, rows with a status of "Validation Error" will be skipped.
Once you have verified that the data looks good, click "Start Import" to being the import process. The status will change to "Complete" if everything went as expected. If there's a problem, you'll see a status of "Processing Error" and the error message.
If you need to abort the import for some reason, you can use the Abort button, but note that rows already completed will not be reverted - this only stops future rows from processing.
In some cases, particularly if someone else sent you the Excel file to import, you may want to copy the errors to your clipboard to send to someone. Use the "Copy Errors to Clipboard" button to copy a text-friendly version of the error message and what row it applies to.
If to fix validation or processing errors you make changes in Gtmhub, you will need to use the "Refresh" button to make sure the importer is checking against the latest Gtmhub data.
Unique Identification of Items on Import
The import utility determines whether to create a new object or update an existing object based on the object's unique identifier. With the exception of Users, the true unique identifier for each object is its system ID. For Users, the non-case-sensitive e-mail address is the unique identifier.
To support importing a file with new objects and then immediately importing changes to those objects (I.E. you filled out a field wrong on the initial import and want to update it), the importer can also uniquely identify objects by name combinations. The unique name for each object is as follows (always not case sensitive):
Sessions: Session Name
Objectives: Session Name + Objective Name + Owners
Key Results: Objective + Key Result Name + Owners
Tasks: Task Name + Owners + Task Parent (if present)
Users: E-mail Address
Teams: Team Name
If the system ID is not populated, the importer will attempt to find the object using the unique name specified above. If a matching object is found, that object will be updated.
In some import data types, you will reference other objects. For example, users can be added to Teams in the user import. In these cases, if there is a duplicate for the unique name (I.E. two teams with the same name), then you will not be allowed to reference that object and a validation error will be shown.
Matching Objectives to Key Results
In the OKRs importer, you will see additional columns for the Import ID on the "Objective" and "Key Results" sheets. This import ID is intended to uniquely identify the Objective or Key Result within that import file only. When creating new objectives or key results, you can use whatever ID you would like (it can be as simple as 1, 2, 3) as long as it is unique within that file.
The objective Import ID is required, the key result Import ID is only required if you intend to have objectives as children of that key result. To link a key result to an objective, reference that objective's import ID in the "Parent Objective ID" column. To make an objective the child of a key result, put the key result's Import ID in the "Parent ID" column of the objective. If an objective's parent is not present in the import file, it must be referenced by its system ID.
Example: Populating a new Custom Field on Objectives
The Problem: You have added a new custom field to objectives and want to populate that custom field on all objectives in current sessions, but leave objectives in older sessions untouched.
Download the full excel file for OKRs
On the "Key Results" sheet, delete all rows except the header. Because our custom field is on objectives, we don't intend to touch key results.
On the "Objectives" sheet, delete all rows for objectives in older sessions (use the filter on the session column to help you do this)
Find the column for your custom field (custom fields are on the right side)
Populate the appropriate value for each row
Import the file
Important Note: The steps to delete the rows are technically optional, as you can complete the import with the full data set. However, deleting the unmodified rows will (1) prevent unintended changes to data (accidentally entering something in Excel or someone changing data online between the export and import) and (2) make the import process faster.