Back to Blog Tour Status

Smart Upload Manager: Smart Reference Keys


The Smart Upload Manager is an additional feature for Mavenlink. For access, please contact your Client Success Manager.


To assist you in learning more about the Smart Upload Manager, visit the Smart Upload Manager Training Courses.


The Smart Upload Manager (SUM) is designed for additional flexibility when importing data into Mavenlink. This enables certain Mavenlink fields to have multiple mutually exclusive columns in a data set template that can satisfy that specific field. These additional attributes are called Smart Reference Keys. Data set management becomes easier and more efficient with Smart Reference Keys.

Smart Reference Key Definition: An optional column in a data set that can be used in place of a Mavenlink system ID. Also known as an Alternate Reference Key.

Smart Reference Keys will always resolve to the system-generated Mavenlink ID when uploading. However, when using an Archival Reference Key (ARK) Column, the Smart Upload Manager automatically does this for you on the back end. This flexibility keeps your data sets and files easier to understand and manage from the front end.

Smart Reference Keys: External References

The simplest way Smart Reference Keys can be used in SUM is through External References within Mavenlink. An external reference is essentially a background “tag” with an ID that you can attach to many objects in Mavenlink. You can arbitrarily set this ID and then use said ID to refer to the object it’s “tagged” to.

You can learn more about external references in the article: Smart Upload Manager (SUM) FAQ.

The SUM can create an external reference only when creating a new object in Mavenlink. This means it cannot create an external reference when updating existing objects.

When creating an object in SUM, setting a value in the external_id column automatically creates an external reference with that value when the object is imported.

In other data sets and future blueprint imports, you can use this external ID as a Smart Reference Key to refer to this object in place of the Mavenlink generated ID.

Example: Use Case

You can upload projects with values in the external_id column of your CSV file. These projects are from an external system or from deals won in your CSM tool.

You can set the external_id of the projects in your data sets to match the ID from your deal or external system. This external_id can now be used as a Smart Reference Key for any other data set where you would need a Mavenlink project ID.

You can import tasks to this project by inputting the external_id for the desired project into the external_workspace_id column as a Smart Reference Key for the normal workspace_id field.

Additionally, you can import project custom fields to this project by inputting the external_id for the desired project into the external_subject_id column as an Alternate Reference Key for the normal subject_id field.

Smart Reference Keys: Flexible & Friendly

With the Smart Upload Manager, Smart Reference Keys can extend beyond external references. Data sets are enhanced with extra alternate reference keys to make importing data more flexible and easier to manage. In addition to an external reference, you can use unique and easier-to-find data points to import values into Mavenlink fields.

Example: Use Case (A)

When importing the project data set you can set the project lead in a multitude of ways, with several different column headers only one of which you need to fill out.

In the API the project lead is called the primary_maven. The smart reference key fields for primary_maven are listed below.

  • Primary_maven_id: A Mavenlink system-generated ID for the user.
  • External_primary_maven_id: An external reference ID that is arbitrarily set by the user.
  • Primary_maven_email: An email address of the desired user. This user must be a member of the Mavenlink account.

When you are creating or updating a project in Mavenlink with the SUM, you can fill in any of the above fields to set the project lead. Only one is needed to set the project lead, and it’s recommended to only fill out one smart reference key for a single data point or field in Mavenlink

Example: Use Case (B)

Another user-friendly implementation of smart reference keys is within custom field data sets. Instead of using the custom field ID, which isn’t actually available in the Mavenlink UI, you can simply use the name of the custom field as it appears in the UI.

Custom field data sets are available for the following objects: In the API the project lead is called the primary_maven. The smart reference key fields for primary_maven are:

  • Projects
  • Tasks
  • Users
  • Project Groups
  • Resources


Certain fields are required for each scenario in order to import the data into Mavenlink correctly. Please refer to the Smart Upload Manager Data Set Templates to see which fields are required.

Related Articles

Created on