Project Duplication

Project duplication enables administrators to duplicate projects within the same environment for the same MD type (PostgreSQL to PostgreSQL) directly using REST APIs, replacing the need for legacy tools like Object Manager, Developer.

APIs

Privileges and authorization

You need the following privileges to use the project duplication functionality:

DssXmlPrivilegesDuplicateProject and DssXmlPrivilegesBypassAccessChecks privilege on the duplicated project

To execute the API, you must get the authorization token by executing the POST /api/auth/login request, and get a token as X-MSTR-AuthToken in the response header. Keep the token value. It is required to execute the REST API. See Authentication for more information.

General workflow

The general workflow for using the project duplication APIs involves:

Initiate project duplication
Check duplication status
List all project duplications
Cancel project duplication

Initiate project duplication

Use POST /api/projectDuplications to start a project duplication operation. This initiates an asynchronous process that creates a duplicate of the source project with the settings you specify.

Step 1: Create the duplication request

Sample Request Header:

Content-Type: application/json
X-MSTR-AuthToken: <authToken>
Prefer: respond-async
X-MSTR-ProjectID: <projectID>

The Prefer: respond-async header instructs the server to process the duplication asynchronously without waiting for completion.

Sample Request Body:

The source.environment.id must be equal to target.environment.id as project duplication only works within the same environment.

{
  "source": {
    "environment": {
      "id": "http://example.com/MicroStrategyLibrary",
      "name": "Source Environment"
    },
    "project": {
      "id": "B7CA92F04B9FAE8D941C3E9B7E0CD754",
      "name": "Tutorial"
    }
  },
  "target": {
    "environment": {
      "id": "http://example.com/MicroStrategyLibrary",
      "name": "Target Environment"
    },
    "project": {
      "name": "Target Project"
    }
  },
  "settings": {
    "import": {
      "description": "this is a test description",
      "defaultLocale": 2052,
      "locales": [1033, 2052]
    }
  }
}

Sample Curl:

curl -X POST "https://demo.microstrategy.com/MicroStrategyLibrary/api/projectDuplications" \
  -H "Content-Type: application/json" \
  -H "X-MSTR-AuthToken: o0ak9privdo27nfo798j40m8aa" \
  -H "Prefer: respond-async" \
  -H "X-MSTR-ProjectID: B7CA92F04B9FAE8D941C3E9B7E0CD754" \
  -d '{
    "source": {
        "environment": {
            "id": "http://example.com/MicroStrategyLibrary",
            "name": "Source Environment"
        },
        "project": {
            "id": "B7CA92F04B9FAE8D941C3E9B7E0CD754",
            "name": "Tutorial"
        }
    },
    "target": {
        "environment": {
            "id": "http://example.com/MicroStrategyLibrary",
            "name": "Target Environment"
        },
        "project": {
            "name": "Target Project"
        }
    },
    "settings": {
      "import": {
            "description": "this is a test description",
            "defaultLocale": 2052,
            "locales": [1033, 2052]
      }
    }
}'

Sample Response Code: 202 (Accepted)

Sample Response Body:

{
  "id": "F8F1280022A444C5A10B3445B552E33A",
  "source": {
    "environment": {
      "id": "http://example.com/MicroStrategyLibrary",
      "name": "Source Environment"
    },
    "project": {
      "id": "B7CA92F04B9FAE8D941C3E9B7E0CD754",
      "name": "Tutorial"
    },
    "creator": {
      "id": "86A002474C1A18F1F92F2B8150A43741",
      "name": "mstr1"
    }
  },
  "target": {
    "environment": {
      "id": "http://example.com/MicroStrategyLibrary",
      "name": "Target Environment"
    },
    "project": {
      "id": "B0D8B3CC70854505A1576DBBE26C4B8B",
      "name": "Target Project"
    },
    "creator": {
      "id": "86A002474C1A18F1F92F2B8150A43741",
      "name": "mstr1"
    }
  },
  "createdDate": "2025-05-20T02:30:24.632+0000",
  "lastUpdatedDate": "2025-05-20T02:34:57.748+0000",
  "status": "EXPORTING",
  "progress": 0,
  "message": "",
  "settings": {
    "export": {
      "projectObjectsPreference": {
        "schemaObjectsOnly": false,
        "skipEmptyProfileFolders": false
      },
      "subscriptionPreferences": {
        "includeUserSubscriptions": false,
        "includeContactSubscriptions": false
      }
    },
    "import": {
      "description": "this is a test description",
      "defaultLocale": 2052,
      "locales": [1033, 2052]
    }
  }
}

The duplication process is executed asynchronously. The response includes a unique id that you can use to check the status of the operation using the GET /api/projectDuplications/{id} endpoint.

Check duplication status

Use GET /api/projectDuplications/{id} to check the status of a specific project duplication operation. Since duplication is an asynchronous process, you should poll this endpoint to monitor the progress.

Step 2: Monitor the duplication progress

Sample Request Header:

X-MSTR-AuthToken: <authToken>

Sample Curl:

curl -X GET "https://demo.microstrategy.com/MicroStrategyLibrary/api/projectDuplications/F8F1280022A444C5A10B3445B552E33A" \
  -H "X-MSTR-AuthToken: o0ak9privdo27nfo798j40m8aa"

Sample Response Body:

{
  "id": "F8F1280022A444C5A10B3445B552E33A",
  "source": {
    "environment": {
      "id": "http://example.com/MicroStrategyLibrary",
      "name": "Source Environment"
    },
    "project": {
      "id": "B7CA92F04B9FAE8D941C3E9B7E0CD754",
      "name": "Tutorial"
    },
    "creator": {
      "id": "86A002474C1A18F1F92F2B8150A43741",
      "name": "mstr1"
    }
  },
  "target": {
    "environment": {
      "id": "http://example.com/MicroStrategyLibrary",
      "name": "Target Environment"
    },
    "project": {
      "id": "B0D8B3CC70854505A1576DBBE26C4B8B",
      "name": "Target Project"
    },
    "creator": {
      "id": "86A002474C1A18F1F92F2B8150A43741",
      "name": "mstr1"
    }
  },
  "createdDate": "2025-05-20T02:30:24.632+0000",
  "lastUpdatedDate": "2025-05-20T02:34:57.748+0000",
  "status": "COMPLETED",
  "progress": 100,
  "message": "",
  "settings": {
    "export": {
      "projectObjectsPreference": {
        "schemaObjectsOnly": false,
        "skipEmptyProfileFolders": false
      },
      "subscriptionPreferences": {
        "includeUserSubscriptions": false,
        "includeContactSubscriptions": false
      }
    },
    "import": {
      "description": "this is a test description",
      "defaultLocale": 2052,
      "locales": [1033, 2052]
    }
  }
}

Sample Response Code: 200 (OK)

Duplication Status Values

EXPORTING: The duplication is currently in export progress
EXPORTED: The duplication has been successfully exported
EXPORT_FAILED: The duplication has failed (check the message field for details)
IMPORTING: The duplication is currently in import progress
IMPORT_FAILED: The duplication has failed (check the message field for details)
COMPLETED: The duplication has been successfully completed
CANCELLED: The duplication was cancelled by a user

You should poll the status endpoint at reasonable intervals (e.g., every 10-30 seconds) until the status changes to COMPLETED, IMPORT_FAILED, EXPORT_FAILED, or CANCELLED.

List all project duplications

Use GET /api/projectDuplications to retrieve a list of all project duplication operations. This is useful for monitoring and managing multiple duplication tasks.

Retrieving the duplication history

Sample Request Header:

X-MSTR-AuthToken: <authToken>

Sample Curl:

curl -X GET "https://demo.microstrategy.com/MicroStrategyLibrary/api/projectDuplications?offset=0&limit=1" \
  -H "X-MSTR-AuthToken: o0ak9privdo27nfo798j40m8aa"

Sample Response Body:

{
  "projectDuplications": [
    {
      "id": "F8F1280022A444C5A10B3445B552E33A",
      "source": {
        "environment": {
          "id": "http://example.com/MicroStrategyLibrary",
          "name": "Source Environment"
        },
        "project": {
          "id": "B7CA92F04B9FAE8D941C3E9B7E0CD754",
          "name": "Tutorial"
        },
        "creator": {
          "id": "86A002474C1A18F1F92F2B8150A43741",
          "name": "mstr1"
        }
      },
      "target": {
        "environment": {
          "id": "http://example.com/MicroStrategyLibrary",
          "name": "Target Environment"
        },
        "project": {
          "id": "B0D8B3CC70854505A1576DBBE26C4B8B",
          "name": "Target Project"
        },
        "creator": {
          "id": "86A002474C1A18F1F92F2B8150A43741",
          "name": "mstr1"
        }
      },
      "createdDate": "2025-05-20T02:30:24.632+0000",
      "lastUpdatedDate": "2025-05-20T02:34:57.748+0000",
      "status": "COMPLETED",
      "progress": 100,
      "message": "",
      "settings": {
        "export": {
          "projectObjectsPreference": {
            "schemaObjectsOnly": false,
            "skipEmptyProfileFolders": false
          },
          "subscriptionPreferences": {
            "includeUserSubscriptions": false,
            "includeContactSubscriptions": false
          }
        },
        "import": {
          "description": "this is a test description",
          "defaultLocale": 2052,
          "locales": [1033, 2052]
        }
      }
    }
  ]
}

Sample Response Code: 200 (OK)

You can use this endpoint to check all your past and current duplication operations. It provides a comprehensive view of all duplication tasks and their statuses.

Cancel project duplication

Use PUT /api/projectDuplications/{id} to cancel an ongoing project duplication operation. This is useful if you made a mistake or need to stop a long-running duplication task.

Step 3: Cancel a duplication (if needed)

Sample Request Header:

Content-Type: application/json
X-MSTR-AuthToken: <authToken>

Sample Request Body:

{
  "status": "cancelled"
}

Sample Curl:

curl -X PUT "https://demo.microstrategy.com/MicroStrategyLibrary/api/projectDuplications/F8F1280022A444C5A10B3445B552E33A" \
  -H "Content-Type: application/json" \
  -H "X-MSTR-AuthToken: o0ak9privdo27nfo798j40m8aa" \
  -d '{
    "status": "cancelled"
}'

Sample Response Code: 204 (No Content)

Important limitations:

You can only cancel duplications that are in EXPORTING, EXPORTED, or IMPORTING status
Attempting to cancel a duplication that has already completed (COMPLETED), failed (EXPORT_FAILED, IMPORT_FAILED), or been cancelled (CANCELLED) will result in an error
Once cancelled, a duplication cannot be resumed and must be initiated again if needed