Migrating content

Migrating content to Prepr

From this guide, you’ll learn how to prepare and migrate your content from another CMS or legacy content system to Prepr using the REST API.

Introduction

Content migration is the process of moving content from one content management system to another.

Follow the steps below to migrate content from a CMS or any other external database to a headless setup in Prepr.

  • Step 1 Analyze existing content - In the first step, the data analyst identifies data cleanup activities, content structure discrepancies or gaps and defines a content migration audit checklist.
  • Step 2 Design mapping rules - Based on the analysis results and the content structure in Prepr, design mapping rules to transform the content to Prepr content.
  • Step 3 Create the migration script - Use the mapping rules from the previous step to extract data from the legacy system and transform this data to a Prepr content structure. Use the Prepr REST API to load the transformed content into Prepr.
  • Step 4 Verify and migrate content - Use a combination of automated auditing, manual checks and system testing to confirm that the content was migrated successfully.

Step 1: Analyze existing content

It's essential for a data analyst to analyze the existing content before moving it to a new system. The results of this analysis will provide insights into necessary data cleanup activities, content structure and an audit checklist. Here is a list of key points answered during this step:

  • Identify any other related external systems - For example, where data lookups are referenced.
  • Identify the set of data to be migrated - The scope of all content that needs to be migrated can be defined with the following criteria:
    • Type of content, for example, pages, articles, authors, etc.
    • Age of the content to be migrated, for example, it might not be necessary to migrate very old or archived articles.
    • The number of content items
    • Structure of content items, i.e., what fields are included in a content item like title, slug, description, media, etc. and the corresponding validation rules, for example, whether they are mandatory or other limits.
    • Technical analysis of the content items, such as API documentation.
  • Identify any necessary data rules
  • Identify the requirements for data cleansing - Identify outdated and low-performing pages, broken links and redirects, and missing page elements such as tags, categories, meta descriptions, etc. This way, you can identify how to clean up the content and simplify the migration process.

The content modeler can use the results from this analysis when modeling the new content structure for the front-end implementation. Check out the Design schema guide and UX patterns for practical suggestions on designing a scalable content structure for your web app. To continue the next step for content migration, you'll need a completed Prepr schema, at least modeled if not yet in Prepr.

Step 2: Design the mapping rules

Now that you have the results of the analysis of the existing content, you can design mapping rules according to the new content structure for your web app.

At a high level, look at the table below for suggestions on how to map data types from your old structure to field types in Prepr.

General field types

Data typePrepr field type
Text entryText
Media filesAssets
URL pathSlug (For a URL path to a specific content item.)
Boolean valueBoolean
Predefined listList
Integer or floatNumber
Date and timeDate and time
Tags, keywordsTags
CoordinatesLocation
Social media post embedSocial
HEX color codeColor

Special field types

Prepr supports special field types that let you create feature-rich web pages and deliver personalized content to your end users. For more details, see the table below.

Prepr field typeCapability
StackAllows you to create a stack of components and models for feature-rich web pages. And the in-built Personalization feature lets you deliver the right content to your audiences.
Dynamic contentAllows you to combine various elements. Those elements can include text, headings, lists and even components. This field is often used for (blog) articles that contain all kinds of elements.
Remote contentAllows you to reference content in a remote source.
Content referenceAllows you to create a link to another content entry. Please note each referenced content must be set up as a separate content item in Prepr.
ComponentAllows adding a custom set of fields to your model.

See an example below of mapping rules of an article and the article author from a legacy CMS to Prepr. This mapping is based on the Article and Person models from the Blog pattern. You can also see the schema in a Prepr environment with Demo data or create a model and choose the Blog template.

Person mapping

Legacy fieldLegacy field typePrepr fieldPrepr field typeAdditional rules
AUTHOR.display_namenamefull_nameTextRequired

Article mapping

Legacy fieldLegacy field typePrepr fieldPrepr field typeAdditional rules
headlinetitletitleTextRequired.
descriptionsummaryexcerptTextMap as HTML to include styling.
IMAGEImageObjectcoverAssetUpload this asset in Prepr first and link with Prepr generated id.
datePublisheddatetimepublish_onDate and timeParse value to UTC timestamp.
AUTHORPersonauthorsContent referenceCreate the Person content item first and link with Prepr generated id.
bodylong-textcontentDynamic contentMap as HTML to include styling.

Use the JSON examples below to clarify the mapping for the content migration developer to transform and load data in Prepr with the correct hard-coded values and the matching Prepr REST API request structure.

Person JSON mapping example

{
  "model": {
    "id": {{Prepr Person model Id in the target environment}} 
  },
  "publish_on": {
    "en-US": {{Current date time in UTC timestamp}}
  },
  "locales": [
    "en-US" // List of available languages for this content item.
  ],
  "workflow_stage": {
    "en-US": "Done"// The status for this content item locale entry
  },
  "items": {
    "en-US": { // The locale of a specific content item entry.
      "full_name": { 
        "label": "Text", // API label for a Text field
        "body": {{AUTHOR.display_name}}
      }
    }    
  }
}

Article JSON mapping example

{
  "model": {
    "id": {{Prepr Article model Id in the target environment}} 
  },
  "publish_on": {
    "en-US": {{datePublished}}
  },
  "locales": [
    "en-US"
  ],
  "workflow_stage": {
    "en-US": {{"Done" if datePublished is not empty, else "In progress"}}
  },
  "items": {
    "en-US": { 
      "authors": { 
        "label": "Publication", 
          // API label for a Content reference field
        "items": [
          {
            "id": {{The auto-generated Id of the created Person}}
          }
        ]
      },
      "content": { 
        "label": "ElementBox",
          // API label for a dynamic content field
        "items": [
          {
            "label": "Text",
            "body": {{body}}
          }      
        ]
      },
      "cover": { 
          "label": "Asset", // API label for an Asset field
          "items": [
            {
              "id": {{The auto-generated Id of the uploaded asset}}
            }
          ]    
      },
      "excerpt": { 
        "label": "Text",
        "body": {{description}}
      },
      "title": { 
        "label": "Text",
        "body": {{headline}}
      }
    }
  }
}

Step 3: Create the migration script

Depending on your content migration strategy, the available legacy tools and technical solution, this process could be one or more scripts or programs to do the following:

  1. Extract the content from the legacy system that matches the scope criteria defined in Step 1.
  2. Transform the content using the mapping rules from Step 2 and prepare it for the load process.
  3. Load the transformed content using the Prepr REST API.

It's typical to include reporting of totals during each of these stages to keep track of the number of items extracted, transformed and loaded.

Once you’ve transformed the content, it’s time to load it in Prepr using the Prepr REST API. Load the content in the following order:

1. Upload assets - This is necessary if the Prepr Media Library will be the source repository for all the images, videos and files linked to your content. When an asset is uploaded successfully, you can then use the id generated by Prepr to link to it when you create the corresponding content item. Alternatively, you can include a reference_id on the asset for an external Id value. Check out the REST API Manage assets doc for more details.

2. Create referenced content items - If you have content that references other content items, for example, an Article that references an Author, then it's important to create the child content item first, the Author in this case. When the child content item is created successfully, you can then use the id generated by Prepr to link it to the parent content item that you will migrate afterwards. Check out the REST API Create content items doc for more details.

3. Migrate remaining content items - Once all the content dependencies have been created in Prepr, create the remaining content items using the same REST API endpoint that you used in the previous instruction.

If you have circular references, for example, two articles reference each other, consider creating empty content items first. In this case, add a migration-specific field to the model to store the legacy Id so that you can link the content items by using this Id.

Once all the content items are correctly linked, you can then call the update endpoint to update the empty content items. Check out the REST API Update content item doc for more details.

⚠️

Include an Authorization HTTP header with the corresponding access token of the Prepr environment that you are migrating to. Check out the Mutation API Authorization doc for more details.

Once it's ready, run the script in a Test or Development environment to prevent affecting production-ready content. Learn more on how to set up a DTAP configuration in Prepr.

Move on to the next step to verify and migrate the content to production.

Step 4: Verify and migrate content

That’s it. The hardest part is over. After the test migration is completed, ensure all the data is moved to Prepr correctly by checking the reported totals and error logs. If you’ve already connected your front end, you can also verify the content in your web app.

In case there are any inconsistencies, check and update the existing data according to the audit requirements or adjust your migration script. Once you're satisfied with the testing results, run the script in the Production environment.

If you still have questions or need assistance, please contact our Support team (opens in a new tab).

Was this article helpful?

We’d love to learn from your feedback