01 INTRODUCTION Welcome to the first edition of Manual Migration Training. In this video we ll take a high-level look at the steps necessary to perform a successful migration of SteelBrick content. In later videos we ll investigate each step in detail so that you will be prepared to perform migrations as part of your implementation process. These videos are designed for learners who are familiar with SteelBrick functionality and the relationships between SteelBrick custom objects. Also, manual migration requires the use of Salesforce Change Sets, as well as a data loading tool such as dataloader.io. These tools and concepts have their own dedicated training resources should you need them. With that disclaimer, lets move on. For our training example we imagine that SteelBrick was installed into Production and the Sandbox was then immediately refreshed. The project was implemented in the Sandbox, data and metadata was cleaned up, and the customer has signed off on user acceptance testing. We are now ready to migrate our work into Production. Migration is the process of moving Sandbox data into a Production environment. This includes moving both data and metadata related to the SteelBrick Implementation. Example metadata would be custom fields, page layouts, and field sets. Example data would be records for every Quote Template. The migration process can be represented by three, high-level stages. First, we will prepare the Sandbox data so it contains information that facilitates the migration process, and then export Sandbox data. Second, we will move metadata from Sandbox into the Production environment. Third, we will import Sandbox data into Production and verify that Production functions as expected. Each stage involves many nuances specific to SteelBrick implementations, which we will investigate in the following videos. Occasionally we ll reference a migration cheat sheet that includes a summary of the concepts seen during this training, as well as granular details that will be helpful in future migrations. You can find this cheat sheet in the class materials. We re now ready to move to our next video, where we ll learn how to prepare Sandbox data for deployment. 02 PREPARING SANDBOX DATA The first stage in the migration process is to prepare Sandbox data so it can be successfully imported into Production, maintaining all relationships between related records. For example, imagine we need to migrate Features and Product Option records. As we know, Product Options have a lookup field which references a Feature record. The
Salesforce ID of the Feature record is stored in the Product Option record to maintain the relationship. As the data loader tool inserts Feature records into Production, the records will be given new Salesforce IDs. This presents a problem when inserting Product Option records. These records still contain the Salesforce IDs for the Sandbox versions of Features, IDs that do not exist in Production! This results in an orphaned record, which will cause any number of issues. To successfully migrate we must ensure that as Product Option records are created, they reference the new Feature Salesforce IDs. This is done with the help of External IDs that we create prior to migrating data. External IDs are text fields created on every object we intend to migrate; each record will have a unique value. For example Feature records will be assigned FE0001, FE0002, and so on. When we export Product Option data, we ll include a column that contains the External ID value for the related Feature record. As the data loader tool creates Product Option records, it will query the Production database to find the Salesforce ID of the Feature record based on the known External ID. It will then populate the lookup field on the Product Option record using the found Salesforce ID, effectively recreating the original relationship. As admins, we must create and populate an External ID field for nearly every object we intend to migrate. This is done in four steps. First, create the External ID field for an object. Second, export the object s records. Third, use Excel to generate values for the External ID. Fourth, upsert the modified data. For our example we ll create an External ID field for the Feature object. External ID will be a text field with a length long enough to support unique values for every record. We will check External ID before clicking next, but we will not check the option to make unique since this could present problems with the Clone with Related action on the Product object. When a Product is cloned the related Features are cloned too. Cloned Features will have the same External ID as the original records, causing the subsequent Save to fail. Now that the Feature object contains the External ID field, we will export all Feature records in CSV format. It is best practice to only export the id and External ID fields so as to avoid inadvertent changes to the data when we later upsert the modified data. Open the CSV file in Excel and type a value for the first External ID. Our recommendation is to abbreviate the object name, followed by a four-digit number starting at 0001. This convention can help identify what object the External ID is referencing, even without context. Dragging the cell corner will cause Excel to increment the numeric portion of the cell, giving each record a unique value.
Finally, after saving our changes we can upsert the data back into Sandbox. The Features object is now prepared for migration. We must now repeat the process for all other objects that we intend to migrate, with the possible exception of Products. In the next section we ll investigate options for preparing Product data to ensure a successful migration. 03 PREPARING PRODUCTS Products are prepared for migration in various ways depending on the specifics of the implementation. For example, products may not yet exist in Production, but oftentimes they do. In this section we ll discuss approaches for preparing Product data for migration under differing business scenarios. If products exist in Production, the ideal scenario is to refresh Sandbox before starting a project so all products are present and accounted for. This results in identical Salesforce IDs, which greatly simplifies migration if no additional products are created as part of the implementation. When SteelBrick records are moved into Production, any relationships to Products automatically remain intact. In this scenario there is no need for an External ID on the Product object. Some implementations require new products to be created in the Sandbox after a refresh. This may occur if products are created to act as bundle containers, or when Production has no products to start with. Either way, we must have some method of uniquely identifying each record to reestablish relationships between related records. Sometimes the customer will have a pre-existing External ID field, in which case we can simply use that. If they do not already have and External ID field, we can create one just as we did for the SteelBrick objects. The most challenging scenario is when there is nothing similar between the products in Production and the products in Sandbox. This might occur when Sandbox is not refreshed before beginning the project, and products have been created separately in both Sandbox and Production. If the Product Names are not unique, you may have to work with the customer to establish an External ID that is carefully populated in both Production and Sandbox environments. This scenario requires more effort; thankfully it is the exception. Whatever the scenario, we can only proceed if we are certain that products can be uniquely identified through either Salesforce IDs or External IDs, at which point all Sandbox data will be ready to migrate. The next step is to export the Sandbox data, which is the topic of the following section. 04 EXPORTING SANDBOX DATA
After Sandbox data has been prepared with External IDs, we can export that data for later importing into Production. We will eventually export all SteelBrick records created as part of the implementation, as well as Product records and Price Book entries if necessary. This process is fairly straightforward, with just a few nuances to account for our External IDs. We ll demonstrate the steps for exporting Product Options because this object references multiple other objects with which we need to maintain relationships. As we learned in an earlier video, the External ID field is used to reestablish relationships between related objects. For example, imagine Features have already been imported. They will have new Salesforce IDs and our known External IDs. As the data loader creates Product Option records, it will lookup the new Salesforce ID of the related Feature by using the External ID field. Our exported Product Option records must include the External IDs of the related Features. We must also include External ID columns for the other related objects of Configured SKU, Optional SKU, and Discount Schedule. The dataloader.io tool makes this process easy since related objects automatically appear in the export interface. After clicking the Select All checkbox, we ll expand the first related object so we can check the External ID field. We ll select the External ID fields for the remaining related objects as well. After downloading, a quick look at the CSV file will show that the External ID fields appear to the far right. We must repeat the export process for many other objects, some which have their own related objects. See the migration cheat sheet for a full list of objects commonly included in the migration process, along with their related objects needing External ID fields. Note that some implementations may not utilize all SteelBrick functionality. Those unused components may be skipped. Once we ve exported all records from the required objects we can move to the next stage of the migration process, which is to prepare Production so it is ready to receive Sandbox data. This is the topic of our next video. 05 PREPARING PRODUCTION Before any records can be migrated there are a few updates we must make to Production. For one, Production must be updated to account for the new External ID fields we created to prepare the Sandbox data. We must also move the custom fields we created during the implementation. At the same time we ll move other metadata such as workflow rules and page layouts. Lastly, we ll make a few manual changes in Production to account for new picklist values and Price Books.
To move metadata we ll create a Change Set in Sandbox. Creating a Change Set for SteelBrick metadata is accomplished in the same manner as any other Change Set. The most challenging aspect is in selecting every last piece of metadata created during the implementation. This is made easier by maintaining good documentation as the project progresses. Use this documentation as a checklist while assembling the Change Set. Commonly selected metadata includes custom fields, custom labels, workflow rules, field updates, approval processes, field sets, and page layouts. Once all metadata is selected, make profile selections as needed then upload the Change Set to Production. Once in Production it s best practice to validate the Change Set before deployment. After the Change Set successfully deploys, there are still a few manual changes we must eventually make to the Production environment. One change is to update the picklist values to match any that were modified in the Sandbox environment. Again, use documentation as a checklist during this process. Otherwise, carefully compare Production with Sandbox side-by-side, accounting for the commonly effected picklists such as the Tested Field on Rule Conditions. Lastly, we ll manually create Price Books to match those in Sandbox. Thankfully this is a relatively quick task. Once done, we will have a Production environment ready to import Sandbox data. This import step is the topic of our next section. 06 IMPORTING RECORDS INTO PRODUCTION At this point in the migration process our Production environment is ready to receive the Sandbox data we ve already exported. Importing the data must be done very carefully, as we must take steps to ensure that relationships between related objects are maintained. There is a specific sequence in which we will import Sandbox data to account for dependencies. For example, we absolutely must import Feature records before Product Option records, since each Product Option record references a Feature record. Reversing the order results in a reference to something that doesn t yet exist, which leads to potential issues. The migration cheat sheet defines the recommended order in which we should import Sandbox data. Use it as a checklist to track migration progress. Note that we will use the upsert operation when importing Products, and the insert operation for everything else. As we learned earlier, as the data loader tool creates Product Option records in Production, it will not use any Salesforce IDs found in the import file, as those IDs reference the Sandbox versions of related records, which are totally useless in the Production environment. Instead, the data loader tool will use our prepared External IDs as a means to lookup the new Salesforce IDs of the previously imported records.
This process requires a tool that can perform lookups while inserting new records. For our example we will use dataloader.io to demonstrate the exact steps necessary to successfully insert Product Option records. At this point we ve used dataloader.io to log into our Production environment. We ll start a new Import task, leaving the operation as Insert. We ll choose the Product Option object, and then click Next. Click Upload CSV to locate the previously exported Product Option file. Once found, we are brought to the most critical step in the import process. Here we determine how columns from our source data are mapped to fields in Production. For the most part, dataloader.io matches fields well. However there are very important changes we must make before continuing. For example, if we scroll down a bit we see that the data in the Feature column will be placed into the Feature field. This is a problem because the data contains a Salesforce ID that is only relevant to Sandbox. It must not be placed into the Production field, therefore we will click the trash icon to remove the mapping. This leads us to a second issue. The Feature field still needs data from somewhere so that the Product Option knows which Feature it s related to. Thankfully we know which Feature it s related to because of our External IDs. If we scroll to the bottom of the field mapping list we ll see the External ID columns we included as part of our Sandbox export. Here we find that this sample Product Option is related to the Feature with an External ID of FE0006. We ll tell the tool to lookup the Production Salesforce ID of Feature FE0006, and place that found Salesforce ID into the Feature field of this new Product Option record, effectively reestablishing the relationship. We set this up by clicking Select in the External ID row for the Feature object. Choose the unassigned Feature field from the popup, then check the Lookup via checkbox. Finally, we ll choose the ExternalID option from the drop-down menu to finish mapping the Feature field. If we forget to check the Lookup checkbox, dataloader.io will attempt to use the literal value of FE0006 in the Feature field, which of course is not a valid Salesforce ID, and will cause the insert to fail. We now must correctly map the remaining related fields using the same method of trashing the default mapping, then creating a new mapping based on a lookup. Once all related fields have been remapped, we can click Next, and then Save and Run to begin
importing records. After a few minutes, our Product Option records will have been moved, and we can continue importing records for the next object in the recommended sequence. As a side note, the process of moving Product data is very similar, except we re more likely to use the upsert operation since often Products already exist in Production. This requires us to identify which field will act as the external ID, so existing records can be matched with incoming data. The chosen field will depend on various factors, as discussed in the Preparing Products section of this class. In a real migration, we would follow the recommended sequence of import objects until all data is moved. Once completed we will spot-check our work by generating a quote in a test Opportunity. Verify rules fire as expected and that an output document can be generated successfully. Assuming no issues are discovered, we can consider our job complete. With that, we ve seen the entire process of manual migration between a Sandbox and Production environment. We at the training team hope you now feel prepared to perform your first migration. Please let us know if you have any questions or comments related to the material by sending us an email at training@steelbrick.com. Thank you for watching.