Syncing PageBuilder data across environments

PageBuilder data sync is an API solution that lets you copy and sync your PageBuilder data from Production and lower environments to non-Production environments. This data includes PageBuilder pages, templates, and resolvers.

Syncing your data lets you maintain parity between your PageBuilder environments, ensuring functionality behaves the same in each instance. Retaining parity helps with testing and quality assurance of new features, like new feature bundles, in lower environments before they’re introduced to your Production environment. For example, you can test PageBuilder Engine upgrades in your Sandbox environment that may impact current blocks, chains, and layouts with greater confidence knowing that you’re using the same data that exists in your Production environment. Additionally, you can reproduce and examine Production-environment errors in non-Production environments to effectively troubleshoot issues without disrupting your Production data.

With PageBuilder data sync, you can:

• Initiate a PageBuilder data copy task from any environment to a non-Production environment.
• Cancel a PageBuilder copy request.
• Revert to a previous version of PageBuilder data.
• Track progress of your PageBuilder data copy (status and logs).

Introduction and Demo

Play

PageBuilder Data Sync API Introduction and Demo

Limitations

The PageBuilder data sync has the following limitations:

• PageBuilder data syncs can occur only from Production and lower environments to a non-Production environment. The API is disabled in Production environments to avoid inconsistencies or problems. While you can’t sync PageBuilder data to Production, you can import pages and templates through the UI.

Note

If your production environment is not live yet and you want to request a PageBuilder data copy from a lower environment to a production environment, please contact Arc XP Customer Support.

• An environment can have only one copy queued at a time. If a copy-state is either PENDING or IN PROGRESS, you must wait for the copy to finish or cancel it before starting a new one. If you request a data copy while another job is in status, you receive the error, “PageBuilder data sync limit exceeded.”
• You can revert a data copy only for the version backed up during the copy. You can’t revert an environment to any given previous state.
• When you initiate a PageBuilder data copy, the system may take up to 30 minutes to begin the actual copy task, and the copy itself can take up to two hours to complete, depending on the size of the PageBuilder data. Additionally, after you complete or revert a PageBuilder data copy, the system requires you wait 30 minutes before attempting another data copy. 
• The PageBuilder Data Sync API supports only the basic environments provided by Arc XP, which are included in the following list. Special cases for environments aren’t currently available through the API.
  • Production (Only as source)
  • Sandbox
  • Staging
  • Development
  • Outbound Feeds (Only as source)
  • Outbound Feeds-Sandbox
• The source and target environments are fully usable while a sync is in progress; however, changes you make may be overwritten or not copied, depending on the timing of the sync. For this reason, we recommend notifying your team that a sync is in progress.
• If you are using Micro Experiences and have multiple experiences, Data Sync API only works on your default experience. You can’t use this API on secondary experiences yet.

Prerequisites

Before using PageBuilder data sync, ensure the following items are in place: 

• You must have a restricted-access token for the PageBuilder Data Sync API with Full Access option. This is managed and granted under Developer Center. To learn more, see Restricted-access tokens.
• You must have basic knowledge of REST APIs. You can use tools like Postman, Insomnia, or Curl to execute the requests to the API.

Key Concepts

• Source - the environment that the PageBuilder Data Copy is made from.
• Target - the environment that the PageBuilder Data Copy is made to. The API requests are made from this environment.

PageBuilder Data Sync Workflow

The following steps describe the general process of syncing PageBuilder data between environments.

Note

All API requests must be in accordance with the prerequisites and limitations outlined previously.

1. Data copy: You must copy the PageBuilder data from a source environment by creating a data sync task for the target environment. Note that this step can take up to 30 minutes and the returned state is PENDING.
2. Data backup: When the copy task begins, the job status changes to IN PROGRESS. The system automatically creates a backup of the target environment to mitigate potential issues and enable a rollback to the previous environment version.
   • Any changes you make to the target environment from the moment that the data sync task is created until it starts, which can take up to 30 minutes, are included in the backup.
3. Data transfer: After the backup is complete, the process of copying source PageBuilder data into the target environment begins. 
4. Data sync: When the data copy process completes, the target environment is synced with the source. The status changes to COMPLETED.

Managing a PageBuilder data sync

Use these instructions to schedule, cancel, revert, and monitor your PageBuilder data copies. For additional details on the API, see PageBuilder Editor Data Sync API.

The base URL to use the PageBuilder Data Sync API must include the target environment and the organization name.

https://api.<target_environment>.<organization>.arcpublishing.com/

Important

You must include a bearer access token in the request header. For more information, see Restricted-access tokens.

Initiating a PageBuilder data copy

The first step in establishing a data sync is initiating a data copy, which involves identifying a source and target environment.

1. Identify which environments are the source and target environments for the copy. Remember that the target must be a non-Production environment.
2. Using the URL of the target environment, make a POST request to initiate a data copy from the source environment. After the request is initiated, the API returns the taskId for you to monitor the process.

The following example uses source = production and target = sandbox.

API request

curl --location --request POST 'https://api.sandbox.myorg.arcpublishing.com/pagebuilder/datasync/sync' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{BEARER_TOKEN}}' \
--data '{"source": "production"}'

Body

{
    "source": "production"
}

Response

{
    "taskId": "5025c384-88ce-43f5-b46c-fa55b700bd18"
}

Canceling or reverting a PageBuilder data copy

You can cancel or revert a PageBuilder data copy, as applicable. 

While a data copy job’s status is IN PROGRESS, you cannot cancel or revert. To cancel, the job must be PENDING, and to revert, the job must be COMPLETED.

Canceling a PageBuilder data copy

You can cancel a PageBuilder data copy only when the job status is PENDING. Because the job takes as long as 30 minutes to begin, the job can be in the PENDING status for that long.

Using the URL of the target environment and the taskId, make a request to cancel the PageBuilder data copy.

• The example below uses taskId = 5025c384-88ce-43f5-b46c-fa55b700bd18.

API request

curl --location --request POST 'https://api.sandbox.myorg.arcpublishing.com/pagebuilder/datasync/cancel/5025c384-88ce-43f5-b46c-fa55b700bd18' \
--header 'Authorization: Bearer {{BEARER_TOKEN}}'

Response

{
    "taskId": "5025c384-88ce-43f5-b46c-fa55b700bd18",
    "status": "CANCELLED"
}

Reverting a PageBuilder data copy

You can revert a PageBuilder data copy only when the status is COMPLETED. The revert process is similar to the copy request, but the revert process uses the backup to restore data to the target environment.

Using the URL of the target environment and the taskId, make a request to revert the PageBuilder data copy.

The following example uses taskId = 5025c384-88ce-43f5-b46c-fa55b700bd18.

API request

curl --location --request POST 'https://api.sandbox.myorg.arcpublishing.com/pagebuilder/datasync/revert/5025c384-88ce-43f5-b46c-fa55b700bd18' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{BEARER_TOKEN}}'

Response

{
    "taskId": "5025c384-88ce-43f5-b46c-fa55b700bd18",
    "status": "REVERTING"
}

Monitoring a PageBuilder data copy request

Finding the taskID of a PageBuilder data copy

To find the taskId of a current or past PageBuilder data copy task, use the GET /pagebuilder/datasync/list endpoint to retrieve a list of past data copy tasks and their statuses. If a PageBuilder data copy was initiated in the last 30 minutes, the job status is PENDING or IN PROGRESS.

API request

curl --location --request GET 'https://api.sandbox.myorg.arcpublishing.com/pagebuilder/datasync/list' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{BEARER_TOKEN}}'

Response

[
    {
        "logs": [
            {
                "log": "Data copy process initiated. Source environment: production",
                "timestamp": 1709240990785
            }
        ],
        "taskId": "90a12af5-d995-4090-9497-e71f47c2b7d4",
        "updatedAt": 1709241000326,
        "status": "PENDING",
        "createdAt": 1709240990785,
        "source": "production",
        "env": "myorg-sandbox"
    },
    {
        "logs": [
            {
                "log": "Data copy process initiated. Source environment: production",
                "timestamp": 1709634333686
            },
            {
                "log": "Data copy status updated to COMPLETED",
                "timestamp": 1709652222755
            }
        ],
        "taskId": "a04547f4-58d7-427a-91e0-211036dc5145",
        "updatedAt": 1709652222755,
        "status": "COMPLETED",
        "createdAt": 1709634333686,
        "source": "production",
        "env": "myorg-sandbox"
    }
]

Finding the status of a PageBuilder data copy

Using the taskId, you can know the status of the PageBuilder data copy request. The available statuses are:

• CANCELLED - When the PageBuilder data copy was cancelled before starting.
• COMPLETED - When the PageBuilder data copy completed and the environments were synced. In this state, you can revert the copy.
• FAILED - When PageBuilder data copy process experienced an error. You can create a request to the logs-endpoint to get details on why the copy failed.
• IN PROGRESS - When the PageBuilder data copy process has started.
• PENDING - When the PageBuilder data copy request is initiated but it hasn’t started yet. During this state, you can cancel the copy.
• REVERTING - When the PageBuilder data copy Revert process has started.
• REVERTED - When the PageBuilder data copy has been reverted to the previous state of the target.
• NOTFOUND - When a resource for a PageBuilder data copy doesn’t exist.

API request

Using the URL of the target environment and the taskId, make a request to get the status of the PageBuilder data copy.

The following example uses taskId = 5025c384-88ce-43f5-b46c-fa55b700bd18.

curl --location 'https://api.sandbox.myorg.arcpublishing.com/pagebuilder/datasync/status/5025c384-88ce-43f5-b46c-fa55b700bd18' \
--header 'Authorization: Bearer {{BEARER_TOKEN}}'

Response

{
    "taskId": "5025c384-88ce-43f5-b46c-fa55b700bd18",
    "status": "PENDING"
}

Retrieving the log history of a PageBuilder data copy

You can get the log history of a PageBuilder data copy to learn the process status or to troubleshoot issues that may occur.

API request

curl --location --request GET 'https://api.sandbox.myorg.arcpublishing.com/pagebuilder/datasync/logs/5025c384-88ce-43f5-b46c-fa55b700bd18' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{BEARER_TOKEN}}'

Response

{
    "taskId": "5025c384-88ce-43f5-b46c-fa55b700bd18",
    "status": [
        {
            "log": "Data copy process initiated. Source environment: production",
            "timestamp": 1709664172994
        }
    ]
}