1. TaskRay
  2. TaskRay Guide
  3. Advanced

Migrate TaskRay Templates Across Environments

There could be instances where you might need to transfer TaskRay templates across environments. One common application of this is transferring templates from sandbox environments into production. TaskRay Templates consist of various object records, which means that they can be transferred across environments using data import/export tools.

This article will provide information for different scenarios on how to approach this process as it is important to import the records in a particular order to ensure that all the dependencies across records are linked correctly.

 

Template Versioning

Before we go into the specifics of the importing process, it is important to note that the instructions in this article apply to templates where Template Versioning has been enabled. It is recommended to enable Template Versioning. With that said, when Template Versioning is enabled, there are some additional object records that are involved in the exporting/importing process.

More specifically, with Template Versioning enabled, the following objects become included with the templates: Principal Template and Principal Template Version. These objects are used to manage and track the Addressable IDs assigned to the templates. By importing all the necessary records related to templates, the Addressable IDs remain intact across environments.

Important! Inserting all records with the Addressable IDs from each object is key to this operation maintaining the correct context of Principal Templates and Versions. Otherwise, new Addressable IDs will be created on all records and the tree of versions will be corrupted.

 

Importing / Exporting Data

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. 

When working on transferring templates, refer to both documents for details.

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. 

 

Migrating Templates: Scenarios

The following section will summarize two scenarios that pertain to template versioning and provide information in how to approach the process.

 

Scenario 1

Summary of scenario: A new Principal Template and version has been made in a Salesforce environment, and needs to be moved into a different environment.

Reminder: Inserting all records with the Addressable IDs from each object is key to this operation maintaining the correct context of Principal Templates and Versions. Otherwise, new Addressable IDs will be created on all records and the tree of versions will be corrupted.

 

  1. Use the Template Hub to build the new Principal Template, Principal Version, Project Template and all of its related objects (Task Groups, Tasks, Checklist Groups, Checklist Items, Dependencies, etc.).
  2. Use the dataloader (or any data extraction tool) to extract the full hierarchy of objects (1 file per object). Make sure to get the Addressable ID fields for each record in the exported files, as well as any other fields you’d like to move the data from. For reference, see the TaskRay Entity Resource Diagram.
  3. Start by importing the Principal Template into the target org.
  4. 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.
  5. 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.
  6. 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__trVersionNumber__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.
  7. Import the Project (template) record into the target org.
  8. 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 Project (template) record’s TASKRAY__trVersionNumber__c field. This links the Version and the Project (template) record
  9. 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.

 

Scenario 2

Summary of scenario: An existing Principal Template has had a new version created in a Salesforce environment, and the new version needs to be moved into a different environment.

Reminder: Inserting all records with the Addressable IDs from each object is key to this operation maintaining the correct context of Principal Templates and Versions. Otherwise, new Addressable IDs will be created on all records and the tree of versions will be corrupted.

 

  1. Use the Template Hub to build the new Principal Version (under the existing Principal Template), Project Template and all of its related object (Task Groups, Tasks, Checklist Groups, Checklist Items, Dependencies, etc.).
  2. Use the dataloader (or any data extraction tool) to extract the hierarchy of objects starting with the Principal Version, downward (Project, Task Groups, Tasks, Checklist Groups, Checklist Items, Dependencies, etc.). Make sure to get the Addressable ID fields for each record in the exported files, as well as any other fields you’d like to move the data from. For reference, see the TaskRay Entity Resource Diagram.
  3. Get the Salesforce Record ID of the related Principal Template record in the target org. Add that as a column to the file for the Principal Version.
  4. Import the Principal 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.
  5. 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__trVersionNumber__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 6 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 6 below.
  6. Import the Project (template) record into the target org.
  7. 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.