|
1 | | -# DataSync |
2 | | -Starter kit for building data integrations. |
| 1 | +# DataSync |
| 2 | +Starter kit for building data integrations or content migrations. |
| 3 | + |
| 4 | +## Step 1 - Get Data |
| 5 | + |
| 6 | + |
| 7 | + |
| 8 | +##### Generate Request Headers (Web Service Only) |
| 9 | +In the event that you need to authenticate to a site prior to being able to call for data, you can leverage this method. The recommendation is to use ```$PSDefaultParameterValues``` to automatically append any necessary headers or other data onto your outbound calls. |
| 10 | + |
| 11 | +##### Source Path (required) |
| 12 | +* Web Service - URL to call to retrieve data |
| 13 | +* Flat File - Path to the file |
| 14 | +* Sql Query - Connection String to source database |
| 15 | + |
| 16 | +Information is retrieved and stored in the ```$sourceItems``` object, to be used in later methods |
| 17 | + |
| 18 | +##### Paging (Web Service Only) |
| 19 | +If the data you are retrieving is paged, such as in a REST API, you can tell the import how to get to the next page. The expression should evaluate to another url for the import process to call. |
| 20 | + |
| 21 | +Example: ``` if ($sourceItems.links.next) { $sourceItems.links.next } ``` |
| 22 | + |
| 23 | +##### Before Import |
| 24 | +```$sourceItems``` is expected to be an array of objects. If you have anything different, you can use an expression here to massage it into the appropriate format. |
| 25 | + |
| 26 | +## Step 2 - Map Data |
| 27 | + |
| 28 | + |
| 29 | + |
| 30 | +##### Template (required) |
| 31 | +Select the template to use for creating the new item |
| 32 | + |
| 33 | +##### Force Item ID |
| 34 | +Provide an expression to use for assigning an Item ID to the new item. This can be useful if you are imported relational data from another system, such as in content migration scenarios. |
| 35 | + |
| 36 | +##### Item Name (required) |
| 37 | +Provide an expression to use for assigning the Item Name. |
| 38 | +```New-ItemName``` is included as a module method; this method will take the passed in value, and sanitize it for Sitecore naming requirements. |
| 39 | + |
| 40 | +##### Display Name |
| 41 | +Provide an expession to use for the Display Name of the item. This is useful for multi-lingual imports |
| 42 | + |
| 43 | +##### Field-to-Expression mapping (required) |
| 44 | +Map template fields to values in the source data. Each field mapping can be its own expression, or can reference a method for more complex mappings. |
| 45 | + |
| 46 | +Spaces in the field names are supported via underscores (Example: Navigation Title --> Navigation_Title) |
| 47 | + |
| 48 | +##### Skip Existing Items |
| 49 | +Used in conjunction with ```Item Sync Field``` to determine if existing items should be overwritten or skipped |
| 50 | + |
| 51 | +##### Item Sync Field |
| 52 | +Used to determine if the item being imported already exists within Sitecore |
| 53 | + |
| 54 | +##### Item Processing Script |
| 55 | +For any additional processing that may be required during the item import, you can provide an expression here. It is recommended that the extra processors be written as methods, and added to the Custom Functions folder. |
| 56 | + |
| 57 | +##### Multi-lingual Imports |
| 58 | +You can provided an expression to use for determining the language of the imported item. The process will use the Item Sync Field to determine if the item already exists in the ```en``` language. If the item does not exist, it is created and then a separate version of the item is created in the given language. |
| 59 | + |
| 60 | +## Step 3 - Store Data |
| 61 | + |
| 62 | +##### Destination Path |
| 63 | +Based path for the imported items |
| 64 | + |
| 65 | +##### Parent Path Expression |
| 66 | +Used on conjunction with the ```Destination Path``` to determine where the imported item should live in the content tree. The resulting expression should return a path, which is then appended to the base path to build the final path for the imported item. |
| 67 | + |
| 68 | +##### Post Processing |
| 69 | +Any extra work that needs to be done post process for the script. |
| 70 | + |
| 71 | +## Technical Stuff |
| 72 | + |
| 73 | + |
| 74 | + |
| 75 | +The scripting section is delivered with the necessary expressions for executing the imports. If you are leveraging any custom or |
| 76 | +included methods in any of the above fields, the you will need to add those methods to list of imported methods (see screenshot). |
| 77 | + |
| 78 | +## How To Execute |
| 79 | + |
| 80 | +The Data Sync execution links can be found in the PowerShell Toolbox. |
| 81 | + |
| 82 | + |
| 83 | + |
| 84 | +If you choose to run the "Data Sync - All" command, then it will process all import scripts defined in the module. |
| 85 | + |
| 86 | +If you choose to run the "Data Sync - Single" command, then you will be prompted to choose your import?: |
| 87 | + |
| 88 | + |
| 89 | + |
| 90 | +In either case, when the import is complete, you are presenting with information on the content that was imported. This information will also include some helpful metrics detailing counts for new and updated items, as well as total run time. |
| 91 | + |
| 92 | + |
| 93 | + |
| 94 | +## Resources |
| 95 | + |
| 96 | +- Check out [the article](https://xcentium.com/blog/2019/06/15/sitecore-spe---data-sync-extension) written by Aaron Bickle. |
0 commit comments