Excerpt | ||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||
Excerpt | ||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||
OverviewThere are a number of upgrade checks and pre-upgrade checks REST API endpoints that can be used to retrieve information or run/cancel the pre-upgrade/upgrade checks process for the document activity upgrade. These REST API endpoints are provided for customers and partners to manage and run
It is recommended that partners have an appropriate level of scripting expertise and knowledge. Global administrator permissions are required to use these endpoints.
|
Upgrade and pre-upgrade checks REST API endpoints
Table of Contents | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
|
...
Request a list of spaces with Comala Document Management workflow activity and the current upgrade check status for each space with workflow activity
Endpoint:
http://<confluencehostname>/rest/cw/2/documentactivity/upgrade/report
Method:
GET
Endpoint response is a list of spaces with workflow activity. This JSON object includes
spacesPreChecks - a list of spaces with data for each space including
space name; space key; space home URL; number of pages containing workflow history; total space pages; check details
Info |
---|
The check details includes details of the check process including space key; check progress; check status; duration of check process; start date of check; number of errors; support package url (if errors); check phase |
metadata - values related to check statistics for the check across the spaces selected
GET Space upgrade check progress status
Request the upgrade process status of a space with page activity.
Endpoint:
http://<confluencehostname>/rest/cw/2/documentactivity/upgrade/status/{spaceKey}
Tip |
---|
Leave |
Method:
GET
Info |
---|
If the progress status returned for a space is CHECK_FAIL, the action supplies a URL to download the space check support package |
Endpoint response is a list of space with workflow activity progress check status. This JSON object includes
spacekey; check status; duration of process time; start date; number of errors; support package URL (if check status is CHECK_FAIL or UPGRADE_FAIL); current phase of check progress
RUN Spaces upgrade check process
Run the upgrade/pre-upgrade check process for one or more spaces.
http://<confluencehostname>/rest/cw/2/documentactivity/upgrade/run
Method:
POST
The endpoint request is an array of space keys
["TESTSPACE_1", "TESTSPACE_2",]
Endpoint response is a list of spaces with checks in progress. The JSON object includes
spacesPreChecks - check status; start time for check process; progress percentage; space key
RUN Page / Blog post upgrade check process
Run the upgrade/pre-upgrade check process for one page or blog post.
http://<confluencehostname>/rest/cw/2/documentactivity/upgrade/content/run
Method:
POST
The endpoint request is a contentID
being the page or blog post id of the content to be upgraded
Endpoint response includes the id of the content, the status and a link to the support package
GET Failing space upgrade check support package
A way to download the support package zip file for a failing upgrade check of a named space.
Endpoint:
http://<confluencehostname>/rest/cw/2/documentactivity/upgrade/support/{spaceKey}
Method:
GET
Endpoint response downloads the support package zip file (located in the Confluence local temp directory) for the added space.
Note |
---|
The space must have an upgrade check process CHECK_FAIL status to get the support package. |
CANCEL Space upgrade check process
Cancel an upgrade/pre-upgrade check task that is in progress for a named space.
Endpoint:
http://<confluencehostname>/rest/cw/2/documentactivity/upgrade/cancel/{spaceKey}
Method:
POST
Endpoint response is
http 200 (OK) status code - if process has been cancelled
http 404 (NOT FOUND) status code - if the check process selected was not in the IN_PROGRESS status
Excerpt
Get a list of the spaces that have workflows and their upgrade status
Get the specific upgrade status of a space
Run the upgrade or pre-checks of a space
Cancel a running upgrade or pre-checks execution of a space
Get the support package zip file of a failing upgrade or pre-checks execution of a space
Upgrade and pre-upgrade checks REST API documentation
Excerpt | ||
---|---|---|
| ||
The upgrade and pre-upgrade checks REST API is available as Open API (Swagger) Documentation. This includes details of the JSON objects and response examples.
|
Open api | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
{
"swagger" : "2.0",
"info" : {
"version" : "latest",
"title" : "Document Activity Upgrade API"
},
"basePath" : "/rest/cw/2/",
"tags" : [ {
"name" : "documentactivity"
} ],
"schemes" : [ "https" ],
"paths" : {
"/documentactivity/upgrade/cancel" : {
"post" : {
"tags" : [ "documentactivity" ],
"summary" : "Cancels the running space upgrade/pre-check task for the space provided",
"description" : "",
"operationId" : "cancelSpaceUpgrade",
"consumes" : [ "application/json" ],
"produces" : [ "application/json" ],
"parameters" : [ {
"in" : "body",
"name" : "Space Upgrade/Pre-check task cancel request",
"required" : false,
"schema" : {
"$ref" : "#/definitions/RestSpaceUpgradeCancelRequest"
}
} ],
"responses" : {
"200" : {
"description" : "Upgrade task successfully cancelled"
},
"401" : {
"description" : "The application has no permission over this method"
},
"403" : {
"description" : "The given user does not have access."
},
"404" : {
"description" : "There is no upgrade process for the given space"
},
"500" : {
"description" : "Something went wrong, unable to cancel the space upgrade task."
}
}
}
},
"/documentactivity/upgrade/content/run" : {
"post" : {
"tags" : [ "documentactivity" ],
"summary" : "Run the content upgrade/pre-check task given a content id",
"description" : "",
"operationId" : "runContentUpgrade",
"consumes" : [ "application/json" ],
"produces" : [ "application/json" ],
"parameters" : [ {
"in" : "body",
"name" : "Page Upgrade request",
"required" : false,
"schema" : {
"$ref" : "#/definitions/RestContentUpgradeRunRequest"
}
} ],
"responses" : {
"200" : {
"description" : "The content upgrade/pre-check task has been executed successfully.",
"schema" : {
"$ref" : "#/definitions/RestContentUpgradeRunResponse"
}
},
"400" : {
"description" : "The content id parameter is not provided or the space to which the page belongs to is not upgraded."
},
"401" : {
"description" : "The application has no permission over this method."
},
"403" : {
"description" : "The given user does not have access or read only mode is not enabled."
},
"404" : {
"description" : "The given content id does not exist."
},
"500" : {
"description" : "Something went wrong, unable to run the content upgrade/pre-check task."
}
}
}
},
"/documentactivity/upgrade/report" : {
"get" : {
"tags" : [ "documentactivity" ],
"summary" : "Retrieves the upgrade report, giving the information about the spaces with workflows and their respective statistics.",
"description" : "",
"operationId" : "getUpgradesReport",
"produces" : [ "application/json" ],
"responses" : {
"200" : {
"description" : "The upgrade report is generated and returned.",
"schema" : {
"$ref" : "#/definitions/RestUpgradeResponse"
}
},
"401" : {
"description" : "The application has no permission over this method"
},
"403" : {
"description" : "The given user does not have access."
},
"500" : {
"description" : "Something went wrong, unable to retrieve space upgrade report."
}
}
}
},
"/documentactivity/upgrade/run" : {
"post" : {
"tags" : [ "documentactivity" ],
"summary" : "Run the space upgrade/pre-check task given a list of space keys to upgrade ",
"description" : "",
"operationId" : "runSpaceUpgrade",
"consumes" : [ "application/json" ],
"produces" : [ "application/json" ],
"parameters" : [ {
"in" : "body",
"name" : "Space Upgrade request",
"required" : false,
"schema" : {
"$ref" : "#/definitions/RestSpaceUpgradeRunRequest"
}
} ],
"responses" : {
"200" : {
"description" : "The upgrade task is running for the list of given spaces.",
"schema" : {
"$ref" : "#/definitions/RestSpaceUpgradeRunResponse"
}
},
"400" : {
"description" : "The given space key does not exist."
},
"401" : {
"description" : "The application has no permission over this method"
},
"403" : {
"description" : "The given user does not have access."
},
"500" : {
"description" : "Something went wrong, unable to run the space upgrade task."
}
}
}
},
"/documentactivity/upgrade/status/{spaceKey}" : {
"get" : {
"tags" : [ "documentactivity" ],
"summary" : "Retrieves the space upgrade/pre-check status of the space provided.",
"description" : "",
"operationId" : "getSpaceUpgradeStatus",
"produces" : [ "application/json" ],
"parameters" : [ {
"name" : "spaceKey",
"in" : "path",
"description" : "Space key to get upgrade/pre-check data",
"required" : true,
"type" : "string",
"x-example" : "spacekey"
} ],
"responses" : {
"200" : {
"description" : "The space upgrade/pre-check status is returned.",
"schema" : {
"$ref" : "#/definitions/RestSpaceUpgradeTask"
}
},
"401" : {
"description" : "The application has no permission over this method"
},
"403" : {
"description" : "The given user does not have access."
},
"500" : {
"description" : "Something went wrong, Unable to retrieve the space pre-check status."
}
}
}
},
"/documentactivity/upgrade/support/{spaceKey}" : {
"get" : {
"tags" : [ "documentactivity" ],
"summary" : "Get support file for the document activity upgrade",
"description" : "",
"operationId" : "getSupportFile",
"produces" : [ "application/octet-stream" ],
"parameters" : [ {
"name" : "spaceKey",
"in" : "path",
"description" : "Space key to get upgrade/pre-check support package file",
"required" : true,
"type" : "string",
"x-example" : "spacekey"
} ],
"responses" : {
"200" : {
"description" : "Support file is generated and returned"
},
"400" : {
"description" : "Space key is null or does not exist"
},
"401" : {
"description" : "The application has no permission over this method"
},
"403" : {
"description" : "User is not administrator"
},
"404" : {
"description" : "No support package content"
},
"500" : {
"description" : "Cannot generate support data"
}
}
}
}
},
"definitions" : {
"RestContentUpgradeRunRequest" : {
"type" : "object",
"required" : [ "contentId", "upgrade" ],
"properties" : {
"contentId" : {
"type" : "integer",
"format" : "int64",
"example" : 7667751,
"description" : "Content(Page/BlogPost) id to perform the upgrade or pre-check process"
},
"upgrade" : {
"type" : "boolean",
"description" : "True or false if we want to perform the upgrade or pre-check process respectively."
}
},
"description" : "This is the specification of content upgrade/pre-check run request."
},
"RestContentUpgradeRunResponse" : {
"type" : "object",
"properties" : {
"contentId" : {
"type" : "integer",
"format" : "int64",
"description" : "Content id to perform the upgrade or pre-check process"
},
"status" : {
"type" : "string",
"example" : "CHECK_SUCCESS",
"description" : "Status of the actual state, possible outcomes: CHECK_NOT_RUN, CHECK_IN_PROGRESS, CHECK_SUCCESS, CHECK_FAIL, CHECK_CANCEL, UPGRADE_IN_PROGRESS, UPGRADE_SUCCESS, UPGRADE_FAIL, UPGRADE_CANCEL"
},
"support" : {
"type" : "string",
"example" : "/rest/cw/2/documentactivity/upgrade/support/TEST",
"description" : "The support file link, to complete the partial link concat the root url"
}
},
"description" : "This is the specification of content upgrade/pre-check run response."
},
"RestSpaceUpgrade" : {
"type" : "object",
"properties" : {
"name" : {
"type" : "string",
"example" : "demo space name",
"description" : "space name"
},
"key" : {
"type" : "string",
"example" : "DEMO",
"description" : "space key"
},
"home" : {
"type" : "string",
"example" : "/display/DEMO/demo",
"description" : "space home url"
},
"numPagesWithHistory" : {
"type" : "integer",
"format" : "int64",
"example" : 4,
"description" : "number of pages with a workflow history in the space"
},
"totalPages" : {
"type" : "integer",
"format" : "int64",
"example" : 5,
"description" : "the total number of pages in the space"
},
"preCheck" : {
"description" : "the space upgrade task status",
"$ref" : "#/definitions/RestSpaceUpgradeTask"
}
},
"description" : "This is the specification of the space with the data about the workflows and the pages."
},
"RestSpaceUpgradeCancelRequest" : {
"type" : "object",
"required" : [ "spaceKey", "upgrade" ],
"properties" : {
"spaceKey" : {
"type" : "string",
"example" : "DEMO",
"description" : "space key"
},
"upgrade" : {
"type" : "boolean",
"description" : "True or false if we want to perform the cancel of the upgrade or pre-check process respectively."
}
},
"description" : "This is the specification of space upgrade/pre-check cancel request."
},
"RestSpaceUpgradeRunRequest" : {
"type" : "object",
"required" : [ "spaceKeys", "upgrade" ],
"properties" : {
"spaceKeys" : {
"type" : "array",
"description" : "List of space keys to perform the upgrade or pre-check process",
"items" : {
"type" : "string"
}
},
"upgrade" : {
"type" : "boolean",
"description" : "True or false if we want to perform the upgrade or pre-check process respectively."
}
},
"description" : "This is the specification of space upgrade/pre-check run request."
},
"RestSpaceUpgradeRunResponse" : {
"type" : "object",
"properties" : {
"upgradeTasks" : {
"type" : "array",
"description" : "List of space upgrade tasks started",
"items" : {
"$ref" : "#/definitions/RestSpaceUpgradeTask"
}
}
},
"description" : "This is the specification of space upgrade/pre-check run response."
},
"RestSpaceUpgradeTask" : {
"type" : "object",
"properties" : {
"spaceKey" : {
"type" : "string",
"example" : "DEMO",
"description" : "space key"
},
"status" : {
"type" : "string",
"example" : "UPGRADE_IN_PROGRESS",
"description" : "Status of the actual state, possible outcomes: CHECK_NOT_RUN, CHECK_IN_PROGRESS, CHECK_SUCCESS, CHECK_FAIL, CHECK_CANCEL, UPGRADE_IN_PROGRESS, UPGRADE_SUCCESS, UPGRADE_FAIL, UPGRADE_CANCEL"
},
"startedAt" : {
"type" : "integer",
"format" : "int64",
"example" : 1672752415,
"description" : "started date of the update task, the format is the current instant with the system UTC clock."
},
"duration" : {
"type" : "string",
"example" : "2m ",
"description" : "The time in seconds, minutes, hours that the task has taken to be executed"
},
"progress" : {
"type" : "integer",
"format" : "int32",
"example" : 75,
"description" : "The percentage of the upgrade process that has been completed"
},
"numErrors" : {
"type" : "integer",
"format" : "int32",
"example" : 0,
"description" : "The number of errors found in the pages "
},
"support" : {
"type" : "string",
"example" : "/rest/cw/2/documentactivity/upgrade/support/DEMO",
"description" : "The support file link, to complete the partial link concat the root url"
},
"phase" : {
"type" : "string",
"example" : "Phase 2/4 DB storage (AO Tables): page 1/5",
"description" : "Phase the upgrade process is currently in"
}
},
"description" : "It is the current state of the upgrade in a space in which the upgrade task has been executed."
},
"RestUpgradeMetadata" : {
"type" : "object",
"properties" : {
"totalPagesWithHistory" : {
"type" : "integer",
"format" : "int64",
"example" : 3,
"description" : "the total number of pages with workflows history"
},
"totalSpacesWithHistory" : {
"type" : "integer",
"format" : "int64",
"example" : 2,
"description" : "the total number of spaces with workflow history"
},
"totalSpaces" : {
"type" : "integer",
"format" : "int64",
"example" : 2,
"description" : "total spaces"
},
"medianPagesWithWorkflowPerSpace" : {
"type" : "number",
"format" : "double",
"example" : 1.5,
"description" : "the median number of pages with workflow per space"
},
"highestNumPagesWithWorkflowPerSpace" : {
"type" : "integer",
"format" : "int64",
"example" : 2,
"description" : "the largest amount of pages with workflow per space"
},
"totalSpacesChecked" : {
"type" : "integer",
"format" : "int64",
"example" : 2,
"description" : "total spaces checked for the upgrade"
},
"totalSpacesUpgraded" : {
"type" : "integer",
"format" : "int64",
"example" : 2,
"description" : "total spaces upgraded for the upgrade"
},
"latestSpaceUpgraded" : {
"type" : "integer",
"format" : "int64",
"example" : 2,
"description" : "latest timestamp of a space upgraded"
},
"totalDocActivityEntries" : {
"type" : "integer",
"format" : "int64",
"example" : 3,
"description" : "total document activity entries"
}
},
"description" : "These are the workflow related statistics of the spaces that have or have had workflows."
},
"RestUpgradeResponse" : {
"type" : "object",
"properties" : {
"restSpaceUpgradeList" : {
"type" : "array",
"description" : "list of space upgrades statuses",
"items" : {
"$ref" : "#/definitions/RestSpaceUpgrade"
}
},
"restUpgradeMetadata" : {
"description" : "upgrade metadata",
"$ref" : "#/definitions/RestUpgradeMetadata"
},
"readOnlyMode" : {
"type" : "boolean"
}
},
"description" : "This is the specification of all the space upgrades statuses with some workflow metadata of the Confluence instance."
}
}
} |
Appanvil karma designer | ||||
---|---|---|---|---|
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|