-
Notifications
You must be signed in to change notification settings - Fork 198
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat(import): document export/import entities API
related to OPT-5823
- Loading branch information
Showing
4 changed files
with
352 additions
and
0 deletions.
There are no files selected for viewing
136 changes: 136 additions & 0 deletions
136
...-managed/optimize-deployment/rest-api/dashboard/export-dashboard-definitions.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 | ||
| } | ||
| ] | ||
| ``` |
119 changes: 119 additions & 0 deletions
119
docs/self-managed/optimize-deployment/rest-api/import-entities.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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" | ||
| } | ||
| ] | ||
| ``` |
94 changes: 94 additions & 0 deletions
94
docs/self-managed/optimize-deployment/rest-api/report/export-report-definitions.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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": {...} | ||
| } | ||
| ] | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters