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

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.

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

Article mapping

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.

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.

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).