Advanced features

Include or exclude pre-migration checks

You can customize your pre-migration checks by including or excluding checks using the create migration task api.

Include checks

1
2
{
    "task": "Check",
    "options": {
        "checkTypes": {
            "includeKeys": ["AnonPermission","MissingAttachments"]
        }
    }
}

Exclude checks

1
2
{
    "task": "Check",
    "options": {
        "checkTypes": {
            "excludeKeys": ["AnonPermission","MissingAttachments"]
        }
    }
}

Override checks

You can ignore certain failed pre-migration checks by excluding them from migrate task. Adding checks to the exclude list will override the check status from ERROR to WARNING.

You need to check the response of failed checks using the get task status endpoint. It returns a boolean field excludable which says whether you can override that check or not.

Example of pre-migration check task status response

1
2
{
  "data": {
    "status": "FINISHED",
    "outcome": "FAILED",
    "message": "At least one Preflight check has failed.",
    "children": {
      "AnonPermission": {
        "status": "FINISHED",
        "outcome": "FAILED",
        "message": "Project settings will allow public access",
        "details": {
          "excludable": true,
          "description": "Some items like projects, boards or filters have settings that allow anonymous access. In case you exclude this check, such items will have public access on cloud, This means they will be available to anyone on the internet after you migrate."
        }
      }
    }
  }
}

You can then override only those checks that are marked as excludable = true by adding check types in the excludeKeys list of create migration task request.

Example of Create Migration task request body for override checks

1
2
{
    "task": "Migrate",
    "options": {
        "checkTypes": {
            "excludeKeys": ["AnonPermission","MissingAttachments"]
        }
    }
}

Migration error logs and reports [BETA]

Migration APIs support error logs and reports called artifacts. Artifacts are generated as a result of executing the task. Some of the artifacts supported by MAPI are:

1. Pre-migration reports - generated when pre-migration checks are completed. (available since JCMA version - 1.12.5 & not supported in CCMA)
2. Post-migration reports - generated when migration gets completed. (available since JCMA version - 1.12.5 & not supported in CCMA)
3. Migration error logs - generated when migrate task fails or partially complete. (available since JCMA version - 1.12.2 & CCMA version - 3.10.5)

You can use the get task details endpoint to check all artifacts generated. It returns artifactId in the location path which can be used to download artifact.

Example of Get task details API with Artifacts

1
2
{
  "taskId": "00000132-0319-a3cb-a391-52d37934632d",
  "taskType": "check",
  "createdAt": "2024-09-20T01:02:19.000+00:00",
  "results": {
    "artifacts": [
      {
        "name": "pre-migration-reports.zip",
        "location": "https://api.stg.atlassian.com/migrations/public/v1/artifacts/ae74a7f-asab-42sa-9s82-03s2f3a3b330",
        "expireAt": 1223769308339
      }
    ]
  }
}

You can then use the get artifact endpoint to download the artifact file by providing the artifactId obtained from the response of the get task details endpoint.