Kristi Webb is a Senior Consultant at ThreeWill. She has over 18 years of software development experience working on software solutions and integrations for enterprise and product solutions. Her passion is applying technology solutions to solve business problems and improve efficiency.
In the previous blog post, we discussed the extraction of data from the Unily platform so the content can be transformed and eventually uploaded into the latest version of Unily. This blog post highlights several of the steps in the data transformation process that must be completed to prepare for uploading the content into the new Unily platform. Of course, the target system could be a different platform which would require additional transformations. However, it is important to understand that even moving older Unily content to the latest Unily platform still involves many required content item transformations.
Unily Content Transformation
Authors
Content Items are extracted in a JSON format and stored in our document database as JSON objects, but some properties on the JSON must be modified or transformed to work properly in the new Unily Target system. For example, ‘Author A’ in the old system has a specific Unily UserID in that older Unily system but their UserID in the new Unily platform has a completely different UserID number. The Author property value for a content item must be updated to the new UserID value in the newer Unily platform to ensure the correct author name is displayed in the UI when users view the content item. The database used by our migration utilities houses a UserID mapping table to make this transformation more efficient.
Topics
Another example of a JSON property value transformation is the replacement of the ‘Topics’. Each content item may have been tagged with one or more Topic values to help search and sort the content items. When the master list of Topics in the older system is loaded into the new Unily platform, each Topic receives a new ID value in the new Unily system. The migration database also houses a Topic ID mapping table, so the list of Topic IDs could be quickly replaced with the new, equivalent value in the new Unily platform. This ensures that after the next step (Upload), the content item will display the correct list of Topic values in the new Unily instance.
Legacy Date Fields
In this migration, the older Unily platform stored the created date and last modified date for Content objects. These dates had to be mapped to respective custom “legacy date fields” in the new system since the customer wanted to retain these date values. The time provided from the legacy Unily platform API was expected to be in Zulu (UTC) time; however, we were told by Unily that the actual time provided was the time zone of the server that the older Unily instance was hosted on. So, we had to transform these date-times carefully, adjusting for the timezone, to bring over the correct values into these new “legacy date fields”.
Media Item Transformation
Media Item transformation is the most complex aspect of the migration. Any content item that references or includes a media item requires several steps to transform and prepare both the media item and its parent content item for successful upload into the new target Unily platform.
If a Content Item references a media item, you must first make an API call to get the actual Media Item. Then another API call must be made to retrieve the actual media binary file. Then the binary file has to be uploaded first into the new Unily platform. Next, the new binary URL must be updated in the Media JSON. Then the Media JSON is updated to the new Media location and the Media item gets uploaded into the new target system. Of course, the Content JSON object also must be updated or transformed with the correct Media item details after the media item is uploaded into the new Unily platform. Then finally, the transformed content item can be uploaded into the new Unily platform.
Post Images
As a specific example, some content items contained Post Images which display an actual image file as part of the viewed content in Unily. These Post Images must have the binary file migrated over into the Media section and then the reference to the media item also must be updated before upload, so the image will be properly displayed in the new Unily instance just like the other referenced media binary files.
Link Transformation
Within a content item, any link references to other content items in Unily also need to be updated to the new equivalent URL in the new Unily system. We suggest pre-mapping all the content that will be migrating to known locations in the target system so the transformation process can go ahead and map any migrating content links to the new URL equivalents. This programmatic mapping saves countless hours of manual updates for content authors.
Link transformations can get complex for some migration projects, but in this case, we were mapping the sites to the same site equivalent in the new system which kept the mapping process simpler. If needed, we have a lot of experience doing complex link mapping for several other projects.
Unexpected Transformation Requirements
HTML Tags Cleanup
Additional cleanup of some of <body> and </body> HTML tags in the actual displayed content was needed for some older content items since the upload would not accept “pageContent” with these additional HTML tags via the Upload API endpoint. The HTML tags were present in older content items from a previous content management system.
Removing NULL Properties
Another Unily specific Upload API requirement was that any content item property with a null or empty value had to be removed from the JSON object before upload. If these null or blank properties remained in the content JSON object, the upload would fail. We simply stripped the null or empty JSON nodes as the last transformation step. The Unily APIs required this extra step when we worked with them in early 2021.
Below is an example of a property in the JSON that has a null value:
Summary
Some transformations are required for every piece of content, like the Author User ID replacement. However, some transformations may only be required in certain circumstances. Also, some types of content may even require a specific transformation just for that content/data type. Fortunately, our utilities can be quickly adjusted to handle any of these transformation cases.
What’s Next
This blog post has covered the key challenges and steps when transforming the Unily data in preparation for its upload into the new destination system. In the next blog post, Unily Migration Step 3: Data Upload we will dive into the details required for the successful Upload of this data into the new Unily platform via the Unily APIs.
CONTACT THREEWILL TO LEARN MORE ABOUT UNILY MIGRATIONS TODAY!