# Syncing PageBuilder data across environments

Source: https://dev.arcxp.com/pagebuilder-editor/developer-docs/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 ](https://youtube.com/watch?v=Rtzpumn4Uag) 

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](https://arcpublishing.atlassian.net/servicedesk/customer/portal/2).

- 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.
- The Data Sync API works only within a single organization and its default experience. It does not support:

  - Secondary Micro Experiences (MX)
  - Copies across different organizations (secondary orgs)
  - Copies across different Arc XP installations  
For these scenarios, use the [Export-Import](https://dev.arcxp.com/pagebuilder-editor/developer-docs/pagebuilder-editor-export-import-technical-documentation/) feature to move pages and templates manually via `.pbexport` files.

## 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 [Accessing Arc XP APIs](https://dev.arcxp.com/api/accessing-arcxp-apis/)
- You must have basic knowledge of REST APIs. You can use tools like Postman, Insomnia, or Curl to execute the requests to the API.

> **Audience Targeting users:**
> 
> If your target environment has active Audience Targeting segments mapped to page variants, deactivate those segments before running a data sync. Page variant IDs from the source environment replace the existing ones in the target after the copy. Active segments that reference the old variant IDs end up in a locked state, and you can’t deactivate them from the UI. To recover from this state, contact [Arc XP Customer Support](https://arcpublishing.atlassian.net/servicedesk/customer/portal/2).

## 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`.

![PageBuilder Data Copy and Sync Workflow](https://dev.arcxp.com/_astro/KB0011296.C88UPAwo_ZQ9fB1.webp)

## 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](https://dev.arcxp.com/api/pagebuilder/pagebuilder-editor-data-sync-api).

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

Terminal window

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

> **Important:**
> 
> You must include a bearer access token in the request header. For more information, see [Accessing Arc XP APIs](https://dev.arcxp.com/api/accessing-arcxp-apis/).

## 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

Terminal window

```bash
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

```json
{
    "source": "production"
}
```

### Response

```json
{
    "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

Terminal window

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

#### Response

```json
{
    "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

Terminal window

```bash
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

```json
{
    "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

Terminal window

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

#### Response

```json
[
    {
        "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`.

Terminal window

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

#### Response

```json
{
    "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

Terminal window

```bash
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

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