Migrate TaskRay Templates Across Environments (Starter and Standard Editions)

Important Note About Template Migration & This Article

Important! The following article applies to Starter and Standard editions of TaskRay. If you are on the Premium edition of TaskRay, you can migrate TaskRay templates across environments using the Template Migration feature.

About Data Migration and Salesforce Environments

The purpose of this article is to summarize the process of manually migrating TaskRay template data across environments, such as from sandbox to production. Sandbox environments are often used for TaskRay configurations and testing, including setting up templates before making them live in production. When it comes to configurations, Salesforce offers the functionality of Change Sets to transfer configurations between sandbox and production environments. With that said, Change Sets only allow transferring metadata (e.g. configurations done through the Setup menu), but they cannot be used for transferring record data, such as TaskRay Templates. When it comes to migrating data, it is necessary to utilize data migration tools, such as Data Loader.

About TaskRay Template Management (Starter and Standard Editions)

If you are on the Starter or Standard edition of TaskRay, there are a couple of options for managing templates. The first and recommended option is to utilize the Template Versioning feature and manage templates in draft mode directly in production. Alternatively, you can choose the option to build templates in sandbox and then manually migrate data to production.

Option 1: Template Versioning

Template Versioning is available on all editions of TaskRay and it allows managing templates in draft mode in production environments before making them active. Starter and Standard edition customers have the option to utilize Template Versioning for building out and making updates to templates in production.

With this approach, you can work on template updates in draft mode without impacting live project workflows. This is the recommended approach for Starter and Standard edition customers to ensure that all Template functionality is working as designed. This is also the recommended approach for ongoing management of templates.

Option 2: Manual Data Migration

If your organization has the requirement of building templates in sandbox environments before making them live in production, it is possible to manually migrate data. For those use cases, you can leverage tools like Data Loader, but it is only recommended for net-new templates. In other words, any imported templates will be created as new templates and it is not possible to import new versions for existing templates.

For some additional context, TaskRay Templates are created with a unique identifier called Addressable ID, which is used for actions like cloning or stitching. When a template is created, TaskRay assigns a permanent Addressable ID to it, which is then automatically traversed to all subsequent versions that are created on the template.

Whenever the manual data migration approach is used to migrate template data across environments, the templates are imported with an entirely new Addressable ID. As such, it is not possible to manually migrate template data to create new versions for existing templates. However, you can manually migrate template data to create new templates.

Manual Template Migration for New Templates

Important! The following applies to Starter and Standard editions of TaskRay. If you are on the Premium edition of TaskRay, you can migrate TaskRay templates across environments using the Template Migration feature.

If you are working in a sandbox environment and building out a brand new template in sandbox, you can use the following steps to migrate the template into your production environment. Remember: any imported templates will be created as new templates and it is not possible to import new versions for existing templates.

TaskRay Template Data Structure

TaskRay Templates incorporate several different objects. When migrating TaskRay template data, it is important that the object data is imported in a very specific order to ensure that all the necessary connections and references are established. Ultimately, the approach is to start from the top-level objects and then work down to the child objects.

Below is a list of objects that must be included in the export/import process and the order in which they should be migrated.

Required Objects (each will have 1 record to export/import)

Principal Template
Principal Template Version
TaskRay Project

Other Objects (number of records will depend on how the template is structured)

TaskRay Task Group
TaskRay Task
TaskRay Checklist
TaskRay Checklist Item
TaskRay Dependency

Manual Template Migration

TaskRay Templates can be transferred across environments using various data importing tools. Refer to the following article for information on the specific approach for exporting and importing TaskRay data: Migrate External Data Into TaskRay. You can also use the following template to prepare the data files: Project Data Migration Template.

Note: There are many ways to export/import data in Salesforce. This document is agnostic of the particular tool/application being used. The concept explained below assumes that the tool being used will export the data into a series of CSV files, and then those files will be manipulated manually and used to import and update the data in another org in a series of operations.

In the source environment (e.g. sandbox) use the Template Hub to build the new template.
Once the template is created, use the Data Loader (or any data extraction tool) to extract the full hierarchy of objects (1 file per object). You should have files for the following object records: Principal Template, Principal Version, Project Template and all of the template’s related objects (Task Groups, Tasks, Checklist Groups, Checklist Items, Dependencies, etc.). Make sure to get any fields you’d like to move the data from. For reference, see the TaskRay Entity Resource Diagram.
Start by importing the Principal Template into the target org.
Get the Salesforce Record ID of the Principal Template record created in the target org, and add it as a column in the Template Version file before importing. This will parent the Principal Template to the Template Version being inserted.
Import the Template Version record into the target org.
Note: the TASKRAY__trVersionNumber__c cannot be modified and will be set appropriately in the background. In other words, do not include that as a column in your file.
Get the Salesforce Record ID of the Principal Version record created in the target org, and add the Principal Version Salesforce Record ID to a TASKRAY__trPrincipalVersion__c column in the Project (template) file before importing.
- If you want the version to act as a draft to activate through the Template Hub manually at a later time, continue with step 7 below.
- If you want the version to be activated through the data importing process:
  1. Create another file of the Principal Template, with a column for TASKRAY__trActivePrincipalVersion__c field that holds the Salesforce ID of the Principal Version record.
  2. Use that file to run an update operation of the Principal Template record.
  3. Continue with step 7 below.
Import the Project (template) record into the target org.
Get the Salesforce Record ID of the Principal Version record created in the target org, and the Salesforce Record ID of the Project (template) that was just inserted. Use this to create a file to update the Principal Version record’s TASKRAY__trTaskRayProject__c field. This links the Version and the Project (template) record.
Continue the process of getting the Salesforce Record ID of the newly inserted record, and using it to parent the next set of child records. Refer to Migrate External Data Into TaskRay for information on the remaining objects.