diff --git a/docs/self-managed/optimize-deployment/rest-api/dashboard/export-dashboard-definitions.md b/docs/self-managed/optimize-deployment/rest-api/dashboard/export-dashboard-definitions.md new file mode 100644 index 00000000000..2c96c9b809a --- /dev/null +++ b/docs/self-managed/optimize-deployment/rest-api/dashboard/export-dashboard-definitions.md @@ -0,0 +1,136 @@ +--- +id: export-dashboard-definitions +title: "Export Dashboard Definitions" +description: "The REST API to export Dashboard definitions." +--- + +## Purpose + +This API allows users to export Dashboard definitions which can later be imported into another Optimize system. Note that exporting a Dashboard also exports all Reports contained within the Dashboard. The Dashboards to be exported may be within a Collection or private entities, the API has access to both. +The obtained list of entity exports can be imported into other Optimize systems either using the dedicated [import API](../../import-entities) or [via UI](../../../../../components/optimize/userguide/additional-features/export-import#importing-entities). + +## Method & HTTP Target Resource + +POST `/api/public/export/dashboard/definition/json` + +## Request Headers + +The following request headers have to be provided with every request: + +|Header|Constraints|Value| +|--- |--- |--- | +|Authorization|REQUIRED*|[Authorization](../../authorization)| + +* Only required if not set as a query parameter + +## Query Parameters + +The following query parameters have to be provided with every request: + +|Parameter|Constraints|Value| +|--- |--- |--- | +|access_token|REQUIRED*|See [Authorization](../../authorization)| + +* Only required if not set as a request header + +## Request Body + +The request body should contain a JSON array of Dashboard IDs to be exported. + +## Result + +The response contains a list of exported Dashboard definitions as well as all Report Definitions contained within the Dashboards. + +## Response Codes + +Possible HTTP Response Status codes: + +|Code|Description| +|--- |--- | +|204|Request successful.| +|401|Secret incorrect or missing in HTTP Header. See [Authorization](../../authorization) on how to authenticate.| +|404|At least one of the given Dashboard IDs does not exist.| +|500|Some error occurred while processing the request, best check the Optimize log.| + +## Example + +### Export two Dashboards + +Assuming you want to export the two Dashboards with IDs `123` and `456` and have configured the accessToken `mySecret`, this is what it would look like: + +POST `/api/public/export/dashboard/definition/json?access_token=mySecret` + +with request body: + +``` +[ "123", "456" ] +``` + +##### Response + +Status 200. + +##### Response Content + +The response contains the two exported Dashboard definitions as well as all three process Reports contained within the two Dashboards. + +``` +[ + { + "id": "61ae2232-51e1-4c35-b72c-c7152ba264f9", + "exportEntityType": "single_process_report", + "name": "Number: Process instance duration", + "sourceIndexVersion": 8, + "collectionId": null, + "data": {...} + }, + { + "id": "625c2411-b95f-4442-936b-1976b9511d4a", + "exportEntityType": "single_process_report", + "name": "Heatmap: Flownode count", + "sourceIndexVersion": 8, + "collectionId": null, + "data": {...} + }, + { + "id": "94a7252e-d5c3-45ea-9906-75271cc0cac2", + "exportEntityType": "single_process_report", + "name": "Data Table: User task count", + "sourceIndexVersion": 8, + "collectionId": null, + "data": {...} + }, + { + "id": "123", + "exportEntityType": "dashboard", + "name": "Dashboard 1", + "sourceIndexVersion": 5, + "reports": [ + { + "id": "61ae2232-51e1-4c35-b72c-c7152ba264f9", + ... + }, + { + "id": "625c2411-b95f-4442-936b-1976b9511d4a", + ... + } + ], + "availableFilters": [...], + "collectionId": null + }, + { + "id": "456", + "exportEntityType": "dashboard", + "name": "Dashboard 2", + "sourceIndexVersion": 5, + "reports": [ + { + "id": "94a7252e-d5c3-45ea-9906-75271cc0cac2", + ... + } + ], + "availableFilters": [...], + "collectionId": null + } +] +``` \ No newline at end of file diff --git a/docs/self-managed/optimize-deployment/rest-api/import-entities.md b/docs/self-managed/optimize-deployment/rest-api/import-entities.md new file mode 100644 index 00000000000..d78a597a5a7 --- /dev/null +++ b/docs/self-managed/optimize-deployment/rest-api/import-entities.md @@ -0,0 +1,119 @@ +--- +id: import-entities +title: "Import Entities" +description: "The REST API to import Entity definitions." +--- + +## Purpose + +This API allows users to import entity definitions such as Reports and Dashboards into existing Collections. These entity definitions may be obtained either using the [Report](../report/export-report-definitions/) or [Dashboard](../dashboard/export-dashboard-definitions) export API or [via the UI](../../../../components/optimize/userguide/additional-features/export-import#exporting-entities). + +### Prerequisites + +Please note that for importing via API, the following prerequisites must be met: + +- All definitions the entities require exist in the target Optimize. +- The target Collection, identified using the `collectionId` query parameter, must exist in the target system +- The Collection Data Sources must include all relevant definitions for the entities. +- The entity data structures match. To ensure matching data structures, please confirm that the Optimize version of the source is the same as the version of the target Optimize. + +If any of the above conditions are not met, the import will fail with an error response, please refer to the error message in the response for more information. + +## Method & HTTP Target Resource + +POST `/api/public/import` + +## Request Headers + +The following request headers have to be provided with every request: + +|Header|Constraints|Value| +|--- |--- |--- | +|Authorization|REQUIRED*|[Authorization](../authorization)| + +* Only required if not set as a query parameter + +## Query Parameters + +The following query parameters have to be provided with every request: + +|Parameter|Constraints|Value| +|--- |--- |--- | +|access_token|REQUIRED*|[Authorization](../authorization)| +|collectionId|REQUIRED|The ID of the Collection for which to retrieve the Report IDs.| + +* Only required if not set as a request header + +## Request Body + +The request body should contain a JSON array of entity definitions to be imported. These entity definitions may be obtained by using the [Report](../report/export-report-definitions) or [Dashboard](../dashboard/export-dashboard-definitions) export APIs or by [manually exporting entities](../../../../components/optimize/userguide/additional-features/export-import#exporting-entities) via the Optimize UI. + +## Result + +The response contains a list of IDs of the newly created entities in the target system. + +## Response Codes + +Possible HTTP Response Status codes: + +|Code|Description| +|--- |--- | +|200|Request successful.| +|400|The provided list of entities is invalid. This can occur if any of the above listed [prerequisites](#prerequisites) are not met. Please check the `detailedMessage` of the error response for more information.| +|401|Secret incorrect or missing in HTTP Header. See [Authorization](../authorization) on how to authenticate.| +|404|The given target Collection ID does not exist.| +|500|Some error occurred while processing the request, best check the Optimize log.| + +## Example + +### Import two Entities + +Assuming you want to import a Report and a Dashboard into the Collection with ID `123`, this is what it would look like: + +POST `/api/public/import?collectionId=123&access_token=mySecret` + +with request body: + +``` +[ + { + "id": "61ae2232-51e1-4c35-b72c-c7152ba264f9", + "exportEntityType": "single_process_report", + "name": "Number: Process instance duration", + "sourceIndexVersion": 8, + "collectionId": null, + "data": {...} + }, + { + "id": "b0eb845-e8ed-4824-bd85-8cd69038f2f5", + "exportEntityType": "dashboard", + "name": "Dashboard 1", + "sourceIndexVersion": 5, + "reports": [ + { + "id": "61ae2232-51e1-4c35-b72c-c7152ba264f9", + ... + } + ], + "availableFilters": [...], + "collectionId": null + } +] +``` + +##### Response + +Status 200. + +##### Response Content + +``` +[ + { + "id": "e8ca18b9-e637-45c8-87da-0a2b08b34d6e" + }, + { + "id": "290b3425-ba33-4fbb-b20b-a4f236036847" + } +] +``` \ No newline at end of file diff --git a/docs/self-managed/optimize-deployment/rest-api/report/export-report-definitions.md b/docs/self-managed/optimize-deployment/rest-api/report/export-report-definitions.md new file mode 100644 index 00000000000..0335e017051 --- /dev/null +++ b/docs/self-managed/optimize-deployment/rest-api/report/export-report-definitions.md @@ -0,0 +1,94 @@ +--- +id: export-report-definitions +title: "Export Report Definitions" +description: "The REST API to export Report definitions." +--- + +## Purpose + +This API allows users to export Report definitions which can later be imported into another Optimize system. The Reports to be exported may be within a Collection or private entities, the API has access to both. +The obtained list of entity exports can be imported into other Optimize systems either using the dedicated [import API](../../import-entities) or [via UI](../../../../../components/optimize/userguide/additional-features/export-import#importing-entities). + +## Method & HTTP Target Resource + +POST `/api/public/export/report/definition/json` + +## Request Headers + +The following request headers have to be provided with every request: + +|Header|Constraints|Value| +|--- |--- |--- | +|Authorization|REQUIRED*|[Authorization](../../authorization)| + +* Only required if not set as a query parameter + +## Query Parameters + +The following query parameters have to be provided with every request: + +|Parameter|Constraints|Value| +|--- |--- |--- | +|access_token|REQUIRED*|See [Authorization](../../authorization)| + +* Only required if not set as a request header + +## Request Body + +The request body should contain a JSON array of Report IDs to be exported. + +## Result + +The response contains a list of exported Report definitions. + +## Response Codes + +Possible HTTP Response Status codes: + +|Code|Description| +|--- |--- | +|204|Request successful.| +|401|Secret incorrect or missing in HTTP Header. See [Authorization](../../authorization) on how to authenticate.| +|404|At least one of the given Report IDs does not exist.| +|500|Some error occurred while processing the request, best check the Optimize log.| + +## Example + +### Export two Reports + +Assuming you want to export the two Reports with IDs `123` and `456` and have configured the accessToken `mySecret`, this is what it would look like: + +POST `/api/public/export/report/definition/json?access_token=mySecret` + +with request body: + +``` +[ "123", "456" ] +``` + +##### Response + +Status 200. + +##### Response Content + +``` +[ + { + "id": "123", + "exportEntityType": "single_process_report", + "name": "Number: Process instance duration", + "sourceIndexVersion": 8, + "collectionId": "40cb3657-bdcb-459d-93ce-06877ac7244a", + "data": {...} + }, + { + "id": "456", + "exportEntityType": "single_process_report", + "name": "Heatmap: Flownode count", + "sourceIndexVersion": 8, + "collectionId": "40cb3657-bdcb-459d-93ce-06877ac7244a", + "data": {...} + } +] +``` \ No newline at end of file diff --git a/sidebars.js b/sidebars.js index a2aa6af01b7..4247ead1f39 100644 --- a/sidebars.js +++ b/sidebars.js @@ -428,18 +428,21 @@ module.exports = { "Dashboard": [ "self-managed/optimize-deployment/rest-api/dashboard/get-dashboard-ids", "self-managed/optimize-deployment/rest-api/dashboard/delete-dashboard", + "self-managed/optimize-deployment/rest-api/dashboard/export-dashboard-definitions", ], }, { "Report": [ "self-managed/optimize-deployment/rest-api/report/get-report-ids", "self-managed/optimize-deployment/rest-api/report/delete-report", + "self-managed/optimize-deployment/rest-api/report/export-report-definitions", "self-managed/optimize-deployment/rest-api/report/get-data-export", ], }, "self-managed/optimize-deployment/rest-api/event-ingestion", "self-managed/optimize-deployment/rest-api/external-variable-ingestion", "self-managed/optimize-deployment/rest-api/health-readiness", + "self-managed/optimize-deployment/rest-api/import-entities", ], }, "self-managed/optimize-deployment/reimport",