From 395318cee73716b5a8a1afebe0777262bffdb175 Mon Sep 17 00:00:00 2001 From: zhe Date: Thu, 19 Jun 2025 11:24:15 +0800 Subject: [PATCH 1/4] Update --- .../project-duplication.md | 522 ++++++++++++++++++ .../analytics/auto-bot-api/auto-bot-api.md | 28 + .../auto-bot-api/get-image-of-answer.md | 41 ++ .../auto-bot-api/get-question-by-id.md | 83 +++ .../auto-bot-api/get-questions-by-bot.md | 102 ++++ .../analytics/auto-bot-api/post-question.md | 129 +++++ .../analytics/auto-bot-api/post-suggestion.md | 130 +++++ ...ask-question-to-bots-in-the-application.md | 2 +- .../get-image-of-answer.md | 2 +- ...t-question-from-bots-in-the-application.md | 2 +- .../use-bot-api/ask-bot-instance-question.md | 2 +- .../ask-bot-instance-suggested-question.md | 2 +- .../use-bot-api/create-a-bot-instance.md | 2 +- .../use-bot-api/delete-a-bot-instance.md | 2 +- .../use-bot-api/get-a-bot-question.md | 2 +- .../use-bot-api/get-bot-configuration.md | 2 +- .../use-bot-api/get-bot-question-list.md | 2 +- docs/getting-started/getting-started.md | 11 +- docs/getting-started/oauth2.md | 80 +++ docs/whats-new.md | 9 + sidebars.js | 29 +- 21 files changed, 1170 insertions(+), 14 deletions(-) create mode 100644 docs/common-workflows/administration/project-duplication/project-duplication.md create mode 100644 docs/common-workflows/analytics/auto-bot-api/auto-bot-api.md create mode 100644 docs/common-workflows/analytics/auto-bot-api/get-image-of-answer.md create mode 100644 docs/common-workflows/analytics/auto-bot-api/get-question-by-id.md create mode 100644 docs/common-workflows/analytics/auto-bot-api/get-questions-by-bot.md create mode 100644 docs/common-workflows/analytics/auto-bot-api/post-question.md create mode 100644 docs/common-workflows/analytics/auto-bot-api/post-suggestion.md create mode 100644 docs/getting-started/oauth2.md diff --git a/docs/common-workflows/administration/project-duplication/project-duplication.md b/docs/common-workflows/administration/project-duplication/project-duplication.md new file mode 100644 index 00000000..36f922ed --- /dev/null +++ b/docs/common-workflows/administration/project-duplication/project-duplication.md @@ -0,0 +1,522 @@ +--- +sidebar_label: Project Duplication +title: Project Duplication +description: The REST API provides endpoints to duplicate projects within same environment, enabling + administrators to create copies of projects with customizable settings. +--- + +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 + +- [POST /api/projectDuplications](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Project%20Duplication/createProjectDuplication) +- [GET /api/projectDuplications/\{id}](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Project%20Duplication/getProjectDuplication) +- [GET /api/projectDuplications](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Project%20Duplication/getProjectDuplications) +- [PUT /api/projectDuplications/\{id}](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Project%20Duplication/updateProjectDuplication) + +## Privileges and authorization + +You need the following privileges to use the project duplication functionality: + +- [DssXmlPrivilegesDuplicateProject](https://www2.microstrategy.com/producthelp/Current/WebAPIReference/com/microstrategy/webapi/EnumDSSXMLPrivilegeTypes.html#DssXmlPrivilegesDuplicateProject) and [DssXmlPrivilegesBypassAccessChecks](https://www2.microstrategy.com/producthelp/Current/WebAPIReference/com/microstrategy/webapi/EnumDSSXMLPrivilegeTypes.html#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](/docs/getting-started/authentication.md) for +more information. + +## General workflow + +The general workflow for using the project duplication APIs involves: + +1. [Initiate project duplication](#initiate-project-duplication) +1. [Check duplication status](#check-duplication-status) +1. [List all project duplications](#list-all-project-duplications) +1. [Cancel project duplication](#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: + +```http +Content-Type: application/json +X-MSTR-AuthToken: +Prefer: respond-async +X-MSTR-ProjectID: +``` + +:::tip The `Prefer: respond-async` header instructs the server to process the duplication asynchronously without waiting for completion. +::: + +Sample Request Body: + +:::important The `source.environment.id` must be equal to `target.environment.id` as project duplication only works within the same environment. +::: + +```json +{ + "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: + +```bash +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: + +```json +{ + "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] + } + } +} +``` + +:::note 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: + +```http +X-MSTR-AuthToken: +``` + +Sample Curl: + +```bash +curl -X GET "https://demo.microstrategy.com/MicroStrategyLibrary/api/projectDuplications/F8F1280022A444C5A10B3445B552E33A" \ + -H "X-MSTR-AuthToken: o0ak9privdo27nfo798j40m8aa" +``` + +Sample Response Body: + +```json +{ + "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) + +:::info 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: + +```http +X-MSTR-AuthToken: +``` + +Sample Curl: + +```bash +curl -X GET "https://demo.microstrategy.com/MicroStrategyLibrary/api/projectDuplications?offset=0&limit=1" \ + -H "X-MSTR-AuthToken: o0ak9privdo27nfo798j40m8aa" +``` + +Sample Response Body: + +```json +{ + "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) + +:::tip 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: + +```http +Content-Type: application/json +X-MSTR-AuthToken: +``` + +Sample Request Body: + +```json +{ + "status": "cancelled" +} +``` + +Sample Curl: + +```bash +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) + +:::note 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 + ::: + +## Project duplication settings + +You can customize various aspects of the project duplication process using the settings in the +request. The following sections describe the available options. + +### Export settings + +The `settings.export` object controls how the source project is exported: + +```json +"settings": { + "export": { + "projectObjectsPreference": { + "schemaObjectsOnly": false, + "skipEmptyProfileFolders": false + }, + "subscriptionPreferences": { + "includeUserSubscriptions": false, + "includeContactSubscriptions": false + } + } +} +``` + +### Import settings + +The `settings.import` object controls how the project is imported to the target environment: + +```json +"settings": { + "import": { + "description": "Development copy of production project", + "defaultLocale": 2052, + "locales": [1033, 2052] + } +} +``` + +## Request fields reference + +The following table describes the fields available in the project duplication request: + +| Field | Type | Description | Required | +| --------------------------------------------------------------------- | ------- | -------------------------------------------------------------------------- | -------- | +| `source.environment.id` | String | URL of the source environment (must be identical to target.environment.id) | Yes | +| `source.environment.name` | String | Name of the source environment | Yes | +| `source.project.id` | String | ID of the source project | Yes | +| `source.project.name` | String | Name of the source project | Yes | +| `target.environment.id` | String | URL of the target environment (must be identical to source.environment.id) | Yes | +| `target.environment.name` | String | Name of the target environment | Yes | +| `target.project.name` | String | Name to assign to the duplicated project | Yes | +| `settings.import.description` | String | Description for the duplicated project | No | +| `settings.import.defaultLocale` | Number | Default locale ID for the duplicated project | No | +| `settings.import.locales` | Array | List of locale IDs to include in the duplicated project | No | +| `settings.export.projectObjectsPreference.schemaObjectsOnly` | Boolean | Whether to include only schema objects | No | +| `settings.export.projectObjectsPreference.skipEmptyProfileFolders` | Boolean | Whether to skip empty profile folders | No | +| `settings.export.subscriptionPreferences.includeUserSubscriptions` | Boolean | Whether to include user subscriptions | No | +| `settings.export.subscriptionPreferences.includeContactSubscriptions` | Boolean | Whether to include contact subscriptions | No | + +## Response fields reference + +The following table describes the fields available in the project duplication response: + +| Field | Type | Description | +| -------------------- | ------ | ---------------------------------------------------------- | +| `id` | String | Unique identifier for the duplication operation | +| `source` | Object | Information about the source project and environment | +| `source.environment` | Object | Details about the source environment | +| `source.project` | Object | Details about the source project | +| `source.creator` | Object | Details about the user who created the source project | +| `target` | Object | Information about the target project and environment | +| `target.environment` | Object | Details about the target environment | +| `target.project` | Object | Details about the target project | +| `target.creator` | Object | Details about the user who created the target project | +| `createdDate` | String | ISO datetime when the duplication was initiated | +| `lastUpdatedDate` | String | ISO datetime when the duplication was last updated | +| `status` | String | Current status of the duplication operation | +| `progress` | Number | Completion percentage of the duplication operation (0-100) | +| `message` | String | Additional information or error message | +| `settings` | Object | Configuration settings used for the duplication operation | + +## Common errors and troubleshooting + +| HTTP Status | Error Code | Description | Resolution | +| ----------- | ---------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------- | +| 400 | DIFFERENT_ENVIRONMENTS | Source and target environments are not the same | Ensure source.environment.id and target.environment.id are identical | +| 400 | INVALID_REQUEST | Request body is not valid | Check the request JSON format and required fields | +| 403 | FORBIDDEN | User lacks sufficient privileges | Ensure the user has administrator privileges on both source and target projects | +| 404 | PROJECT_NOT_FOUND | Source project not found | Verify the source project ID is correct | +| 409 | PROJECT_NAME_EXISTS | Target project name already exists | Choose a different name for the target project | +| 500 | INTERNAL_SERVER_ERROR | Internal server error occurred | Check server logs for details and retry the operation | + +## Best practices + +1. **Plan for downtime**: Project duplication operations can be resource-intensive. Schedule them + during off-peak hours if possible. + +1. **Use descriptive names**: Give your duplicated projects clear, descriptive names that indicate + their purpose (e.g., "Sales_Dev", "Marketing_Test"). + +1. **Monitor progress**: Large projects may take considerable time to duplicate. Use the status + field to monitor progress. + +1. **Testing**: Test the duplication process with a small project before attempting to duplicate + large, complex projects. diff --git a/docs/common-workflows/analytics/auto-bot-api/auto-bot-api.md b/docs/common-workflows/analytics/auto-bot-api/auto-bot-api.md new file mode 100644 index 00000000..712de78b --- /dev/null +++ b/docs/common-workflows/analytics/auto-bot-api/auto-bot-api.md @@ -0,0 +1,28 @@ +--- +title: Next-Gen AI +description: This page contains a summary of REST APIs for the "auto bots" endpoint. You can use REST API requests to interact with Auto Bots. +--- + + + +With the release of Strategy ONE (March 2025), we have introduced an enhanced set of APIs designed to leverage the capabilities of Next-Gen AI. These APIs are built on top of the existing question APIs and are compatible with both the Next-Gen AI and the legacy Auto Bots. + +The Next-Gen AI APIs provide a seamless way to interact with Next-Gen AI, allowing you to ask questions, retrieve answers, and get historical chat messages from specific bots. Additionally, the APIs offer the ability to get suggested questions, enhancing the user experience by providing relevant queries and answers efficiently. + +Starting from Strategy ONE (June 2025), we've added support for retrieving images within answers, allowing for richer, more visual responses from the Next-Gen AI system. This feature includes customizable resolution settings to optimize image quality based on your specific needs. + +### Key Features + +- **Ask a question to a specific bot**: Submit a question to the specific Auto Bot. This API has been enhanced from the existing question API. +- **Get answer by the question ID**: Retrieve the answer to a specific question using its ID. This API has been enhanced from the existing question API. +- **Get chat history from a specific bot**: Obtain all historical chat messages from a specific bot. +- **Get suggested questions from a specific bot**: Get recommended questions based on the context from a specific bot. +- **Image support in answers**: Request and retrieve images as part of answers from Next-Gen AI, with customizable resolution settings. (Available from Strategy ONE (June 2025)) + +For further details on how to use these APIs, please refer to the following sections of this manual: + +- [Ask a question to a specific bot](./post-question.md) +- [Get answer by the question ID](./get-question-by-id.md) +- [Get chat history from a specific bot](./get-questions-by-bot.md) +- [Get suggested questions from a specific bot](./post-suggestion.md) +- [Get image from an answer](./get-image-of-answer.md) diff --git a/docs/common-workflows/analytics/auto-bot-api/get-image-of-answer.md b/docs/common-workflows/analytics/auto-bot-api/get-image-of-answer.md new file mode 100644 index 00000000..97af8bae --- /dev/null +++ b/docs/common-workflows/analytics/auto-bot-api/get-image-of-answer.md @@ -0,0 +1,41 @@ +--- +sidebar_label: Get an image in the answer of a specific question +title: Get an image in the answer of a specific question +description: This workflow sample demonstrates how to get an image in the answer of a specific question. +--- + + + +This workflow sample demonstrates how to get an image in the answer of a specific question. + +:::info + +Obtain the authorization token needed to execute the request using [POST /api/auth/login](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Authentication/postLogin). + +::: + +## Get an image of an answer related to a question with bot routing + +Endpoint: [GET /api/questions/\{questionsId}/answers/images/\{imageId}](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Next-Gen%20AI/getMessageImage) + +:::note +Replace `{questionsId}` in `GET /api/questions/{questionsId}/answers/images/{imageId}` with the question ID from `POST /api/questions` and `{imageId}` with your image ID from `GET /api/questions/{questionId}`. +::: + +Sample Curl: + +```bash +curl 'https://demo.microstrategy.com/MicroStrategyLibrary/api/questions/862D61DE2EDD4937B31139B7F574E8EE/answers/images/32A0F79BB4374D4792253B38C1177A6D' \ +-H 'accept: image/png' \ +-H 'X-MSTR-AuthToken: t40ltbk411923ipk85r8r0tace' \ +``` + +Sample Response: + +| Response Code | Status | +| ------------- | ------------------------------- | +| 200 | Successfully returned the image | +| 400 | Error in getting the image | +| 401 | Authorization failed | +| 403 | Forbidden | +| 404 | Image not found | diff --git a/docs/common-workflows/analytics/auto-bot-api/get-question-by-id.md b/docs/common-workflows/analytics/auto-bot-api/get-question-by-id.md new file mode 100644 index 00000000..911e0d70 --- /dev/null +++ b/docs/common-workflows/analytics/auto-bot-api/get-question-by-id.md @@ -0,0 +1,83 @@ +--- +sidebar_label: Get answer by the question ID +title: Get answer by the question ID +description: This workflow sample demonstrates how to get a question's answer by the question ID. +--- + + + +This workflow sample demonstrates how to get a question's answer by the question ID. + +:::info + +Obtain the authorization token needed to execute the request using [POST /api/auth/login](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Authentication/postLogin). + +::: + +## Get a question with question ID + +Endpoint: [GET /api/questions/\{questionId}](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Next-Gen%20AI/queryMessage_1) + +:::note +Replace `{questionId}` in `GET /api/questions/{questionId}` with your question ID from `POST /api/questions`. +::: + +Sample Request Body: +No request body. + +Sample Curl: + +```bash +curl 'https://demo.microstrategy.com/MicroStrategyLibrary/api/questions/9161386651E84054A6230796C84E12C5:68696ADB633946B4B430ABD959433B3B:FCC1C28296014AB19ABD877E60590890' \ +-H 'accept: */*' \ +-H 'X-MSTR-AuthToken: evvk84kcucn8abon6c1qfbud7' \ +``` + +Sample Response Code: + +| Response Code | Status | +| ------------- | ------------------------------------------------------------------------------ | +| 200 | Successfully returned the question from the bot that has been answered | +| 202 | Successfully returned the question from the bot which is still being processed | +| 400 | Error in getting the question from the bot | +| 401 | Authorization failed | +| 404 | Question does not exist | + +## Response Body on Success + +The response is the question and answer with the specific ID. + +### Response when the question is still being processed + +If the response code is 202, indicating that the question is still being processed, continue calling this API to check the status of the question. + +If the question is being processed, the response is: + +```json +{ + "id": "9161386651E84054A6230796C84E12C5:68696ADB633946B4B430ABD959433B3B:FCC1C28296014AB19ABD877E60590890", + "text": "Analyze the distribution of cooking times for recipes", + "answers": [], + "creationDate": "2024-03-08T09:01:43.154+0000" +} +``` + +### Response when all data is ready + +If the status code is 200, indicating that the question has been answered. + +```json +{ + "id": "9161386651E84054A6230796C84E12C5:68696ADB633946B4B430ABD959433B3B:FCC1C28296014AB19ABD877E60590890", + "text": "Analyze the distribution of cooking times for recipes", + "answers": [ + { + "bot": { "id": "68696ADB633946B4B430ABD959433B3B" }, + "text": "#Title 1\nThe distribution of cooking times for recipes is as follows:\n- The shortest cooking time is -1 minute.\n- The majority of recipes have cooking times ranging from 2 to 60 minutes.\n- There are a few recipes with longer cooking times, such as 75, 90, 120, and 720 minutes.\n- The exact distribution of cooking times can be seen in the visualization result.", + "images": [{ "id": "79FD176AEAD9446395B083B5931E9EC7", "width": 800, "height": 600 }], + "route": "sql" + } + ], + "creationDate": "2024-03-08T09:01:43.154+0000" +} +``` diff --git a/docs/common-workflows/analytics/auto-bot-api/get-questions-by-bot.md b/docs/common-workflows/analytics/auto-bot-api/get-questions-by-bot.md new file mode 100644 index 00000000..f5cde644 --- /dev/null +++ b/docs/common-workflows/analytics/auto-bot-api/get-questions-by-bot.md @@ -0,0 +1,102 @@ +--- +sidebar_label: Get chat history from a specific bot +title: Get chat history from a specific bot +description: This workflow sample demonstrates how to get the historical chat messages from a specific bot. +--- + + + +This API is used to get the historical questions from a specific bot for the current user, which can be used as the `history` parameter in the `Ask a question to a specific bot` API. + +:::info + +Obtain the authorization token needed to execute the request using [POST /api/auth/login](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Authentication/postLogin). + +::: + +## Get Questions by Bot + +Endpoint: [GET /api/questions/](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Next-Gen%20AI/getChats_1) + +Sample Request Headers: + +| Header | Required | Description | Sample Value | +| ---------------- | -------- | -------------------------- | -------------------------------- | +| X-MSTR-AuthToken | Yes | Authorization Token | t40ltbk411923ipk85r8r0tace | +| X-MSTR-ProjectID | Yes | Project ID | B7CA92F04B9FAE8D941C3E9B7E0CD754 | +| Content-Type | Yes | Type of content being sent | application/json | + +Sample Request Query Strings: + +| Query String | Required | Description | Sample Value | +| ------------ | -------- | ---------------------------------------------------------- | -------------------------------- | +| botId | Yes | The ID of the bot whose chat history you want to retrieve. | 065B007500614D158B41B0D020C96966 | + +Sample Curl: + +```bash +curl 'https://demo.microstrategy.com/MicroStrategyLibrary/api/questions?botId=065B007500614D158B41B0D020C96966' \ +-H 'accept: */*' \ +-H 'X-MSTR-AuthToken: evvk84kcucn8abon6c1qfbud7' \ +-H 'X-MSTR-ProjectID: B7CA92F04B9FAE8D941C3E9B7E0CD754' \ +``` + +Sample Response Code: + +| Response Code | Status | +| ------------- | ------------------------------------------------ | +| 200 | Successfully returned the questions from the bot | +| 400 | Error in getting the questions from the bot | +| 401 | Authorization failed | +| 404 | Bot does not exist | + +## Response Body on Success + +The response is a list of questions and answers from the specific bot. + +### Sample Response + +```json +{ + "questions": [ + { + "id": "B7CA92F04B9FAE8D941C3E9B7E0CD754:065B007500614D158B41B0D020C96966:1BA14D43628D40ABA5DF6616843C611F", + "text": "Show the revenue in euros per month of the highest-grossing branch in Germany in 2024 in a gid.", + "answers": [ + { + "bot": { + "id": "065B007500614D158B41B0D020C96966", + "projectId": "B7CA92F04B9FAE8D941C3E9B7E0CD754" + }, + "text": "The highest-grossing branch in Germany in 2024 generated the following revenue in euros per month:\n- August: €11,327,719\n- September: €10,847,290\n- October: €12,609,864\n- November: €13,793,524\n- December: €12,002,767", + "route": "sql" + } + ], + "creationDate": "2025-03-06T06:07:47.272+0000", + "snapshot": false, + "type": "snapshots" + }, + { + "id": "B7CA92F04B9FAE8D941C3E9B7E0CD754:065B007500614D158B41B0D020C96966:75262B7346CC469EA7B874E49888040E", + "text": "What was the Umsatz in Euro in Kristallhöhle during 2024/10 Okt?", + "answers": [ + { + "bot": { + "id": "065B007500614D158B41B0D020C96966", + "projectId": "B7CA92F04B9FAE8D941C3E9B7E0CD754" + }, + "text": "Der Gesamtumsatz in Euro (Umsatz in Euro) für die Region 'kristallhöhle' im Oktober 2024 betrug €92.541.045.", + "route": "sql" + } + ], + "creationDate": "2025-03-07T02:56:53.708+0000", + "snapshot": false, + "type": "history" + } + ] +} +``` + +:::note +Questions with `type` as `snapshots` should not be used as history in the `Ask a Specific Bot a Question` API. +::: diff --git a/docs/common-workflows/analytics/auto-bot-api/post-question.md b/docs/common-workflows/analytics/auto-bot-api/post-question.md new file mode 100644 index 00000000..d2d1cf9d --- /dev/null +++ b/docs/common-workflows/analytics/auto-bot-api/post-question.md @@ -0,0 +1,129 @@ +--- +sidebar_label: Ask a question to a specific bot +title: Ask a question to a specific bot +description: Submit a question to the Auto Bot and receive an question ID. +--- + + + +Use this API to submit a question to a specific Auto Bot and receive an question ID. + +:::info + +Obtain the authorization token needed to execute the request using [POST /api/auth/login](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Authentication/postLogin). + +::: + +## Ask a Specific Bot a Question + +Endpoint: [POST /api/questions](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Next-Gen%20AI/createQuestion) + +Sample Request Headers: + +| Header | Required | Description | Sample Value | +| ---------------- | -------- | ----------------------------------------------- | -------------------------- | +| X-MSTR-AuthToken | Yes | Authorization Token | t40ltbk411923ipk85r8r0tace | +| Prefer | Yes | The response mode, which must be respond-async. | respond-async | +| Content-Type | Yes | Type of content being sent | application/json | + +Sample Request Body: + +| Field | Required | Description | Sample Value | +| -------------- | -------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| question | Yes | The question text | Which customer has the highest revenue? | +| bots | Yes | The bot to which the question is directed. Only one bot is supported. | [\{"id": "065B007500614D158B41B0D020C96966", "projectId": "B7CA92F04B9FAE8D941C3E9B7E0CD754"\}] | +| answers.images | No | Optional. If not specified, the image is not generated. Supports one image. | [\{"width": 800, "height": 600\}] | +| history | No | Optional. Previous questions and answers. Supports up to 5 entries. | [\{"id": "B7CA92F04B9FAE8D941C3E9B7E0CD754:065B007500614D158B41B0D020C96966:E41CC2178F6042BCAAD72E322E802A90", "question": "show the monthly percentage development of the revenue in euros compared to the previous month for branch a013.. today's date is 04-march-2025. make sure to do correct datetime based calculation.", "text": "The monthly percentage development of revenue in euros for branch A013 shows fluctuations over the observed period. Starting in September 2024, there was an 8% decrease in revenue compared to the previous month. This was followed by a smaller decline of 3% in October 2024. November 2024 saw a slight increase of 1%, while December 2024 experienced a significant rise of 42%. However, in January 2025, there was a notable decrease of 19% in revenue compared to December 2024." \}, \{"id": "B7CA92F04B9FAE8D941C3E9B7E0CD754:065B007500614D158B41B0D020C96966:5720DC60EBB648FFAFCDE05A7363395B", "question": "what was the revenue in euros for branch a013 in december 2024?", "text": "The revenue in euros for branch A013 in December 2024 was €4,519,521." \}] | + +:::note +Get the history questions by `GET /api/questions?botId={botId}`. +::: + +```json +{ + "question": "What was the Umsatz in Euro in Kristallhöhle during 2024/10 Okt?", + "bots": [ + { + "id": "065B007500614D158B41B0D020C96966", + "projectId": "B7CA92F04B9FAE8D941C3E9B7E0CD754" + } + ], + "answers": { + "images": [ + { + "width": 800, + "height": 600 + } + ] + }, + "history": [ + { + "id": "B7CA92F04B9FAE8D941C3E9B7E0CD754:065B007500614D158B41B0D020C96966:E41CC2178F6042BCAAD72E322E802A90", + "question": "show the monthly percentage development of the revenue in euros compared to the previous month for branch a013.. today's date is 04-march-2025. make sure to do correct datetime based calculation.", + "text": "The monthly percentage development of revenue in euros for branch A013 shows fluctuations over the observed period. Starting in September 2024, there was an 8% decrease in revenue compared to the previous month. This was followed by a smaller decline of 3% in October 2024. November 2024 saw a slight increase of 1%, while December 2024 experienced a significant rise of 42%. However, in January 2025, there was a notable decrease of 19% in revenue compared to December 2024." + }, + { + "id": "B7CA92F04B9FAE8D941C3E9B7E0CD754:065B007500614D158B41B0D020C96966:5720DC60EBB648FFAFCDE05A7363395B", + "question": "what was the revenue in euros for branch a013 in december 2024?", + "text": "The revenue in euros for branch A013 in December 2024 was €4,519,521." + } + ] +} +``` + +Sample Curl: + +```bash +curl 'https://demo.microstrategy.com/MicroStrategyLibrary/api/questions' \ +-X 'POST' \ +--header 'X-MSTR-AuthToken: t40ltbk411923ipk85r8r0tace' \ +--header 'X-MSTR-ProjectID: FCC1924411EAABC39C6C0080EFA54501' \ +--header 'Prefer: respond-async' \ +--header 'Content-Type: application/json' \ +--data '{ + "question": "What was the Umsatz in Euro in Kristallhöhle during 2024/10 Okt?", + "bots": [ + { + "id": "065B007500614D158B41B0D020C96966", + "projectId": "B7CA92F04B9FAE8D941C3E9B7E0CD754" + } + ], + "answers": { + "images": [ + { + "width": 800, + "height": 600 + } + ] + }, + "history": [ + { + "id": "B7CA92F04B9FAE8D941C3E9B7E0CD754:065B007500614D158B41B0D020C96966:E41CC2178F6042BCAAD72E322E802A90", + "question": "show the monthly percentage development of the revenue in euros compared to the previous month for branch a013.. today's date is 04-march-2025. make sure to do correct datetime based calculation.", + "text": "The monthly percentage development of revenue in euros for branch A013 shows fluctuations over the observed period. Starting in September 2024, there was an 8% decrease in revenue compared to the previous month. This was followed by a smaller decline of 3% in October 2024. November 2024 saw a slight increase of 1%, while December 2024 experienced a significant rise of 42%. However, in January 2025, there was a notable decrease of 19% in revenue compared to December 2024." + }, + { + "id": "B7CA92F04B9FAE8D941C3E9B7E0CD754:065B007500614D158B41B0D020C96966:5720DC60EBB648FFAFCDE05A7363395B", + "question": "what was the revenue in euros for branch a013 in december 2024?", + "text": "The revenue in euros for branch A013 in December 2024 was €4,519,521." + } + ] +}' +``` + +Sample Response: + +| Response Code | Status | +| ------------- | ---------------------------------- | +| 202 | Successfully accepted the question | +| 400 | Error in accepting the question | +| 401 | Authorization failed | +| 404 | No bot found | + +Sample Response Body on success: + +```json +{ + "id": "9161386651E84054A6230796C84E12C5:68696ADB633946B4B430ABD959433B3B:FCC1C28296014AB19ABD877E60590890" +} +``` diff --git a/docs/common-workflows/analytics/auto-bot-api/post-suggestion.md b/docs/common-workflows/analytics/auto-bot-api/post-suggestion.md new file mode 100644 index 00000000..c43fc2df --- /dev/null +++ b/docs/common-workflows/analytics/auto-bot-api/post-suggestion.md @@ -0,0 +1,130 @@ +--- +sidebar_label: Get suggested questions from a specific bot +title: Get suggested questions from a specific bot +description: This workflow sample demonstrates how to get suggested questions from a specific bot. +--- + + + +This workflow sample demonstrates how to get suggested questions from a specific bot. + +:::info + +Obtain the authorization token needed to execute the request using [POST /api/auth/login](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Authentication/postLogin). + +::: + +## Ask suggested questions with bot routing + +Endpoint: [POST /api/questions/suggestions](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Next-Gen%20AI/createSuggestions_1) + +Sample Request Header: + +| Header Name | Required | Description | +| ---------------- | -------- | -------------------------------------------------------- | +| X-MSTR-AuthToken | Yes | Authorization token obtained from `POST /api/auth/login` | +| Content-Type | Yes | The body request type, which must be `application/json` | + +Sample Request Body: + +| Field | Required | Description | Sample Value | +| ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| count | Yes | The count of suggestions you want to get, Supports up to 5. | 5 | +| bots | Yes | The bot to which the question is directed. Only one bot is supported. | [\{"id": "065B007500614D158B41B0D020C96966", "projectId": "B7CA92F04B9FAE8D941C3E9B7E0CD754"\}] | +| history | No | Optional. Previous questions and answers. Supports up to 5 entries. | [\{"id": "B7CA92F04B9FAE8D941C3E9B7E0CD754:065B007500614D158B41B0D020C96966:E41CC2178F6042BCAAD72E322E802A90", "question": "show the monthly percentage development of the revenue in euros compared to the previous month for branch a013.. today's date is 04-march-2025. make sure to do correct datetime based calculation.", "text": "The monthly percentage development of revenue in euros for branch A013 shows fluctuations over the observed period. Starting in September 2024, there was an 8% decrease in revenue compared to the previous month. This was followed by a smaller decline of 3% in October 2024. November 2024 saw a slight increase of 1%, while December 2024 experienced a significant rise of 42%. However, in January 2025, there was a notable decrease of 19% in revenue compared to December 2024." \}, \{"id": "B7CA92F04B9FAE8D941C3E9B7E0CD754:065B007500614D158B41B0D020C96966:5720DC60EBB648FFAFCDE05A7363395B", "question": "what was the revenue in euros for branch a013 in december 2024?", "text": "The revenue in euros for branch A013 in December 2024 was €4,519,521." \}] | +| route | No | Route information for the answer to the last question. Retrieve it from the `route` field in the response of GET /api/questions/\{questionId\}. | sql | + +:::note +Get the history questions by `GET /api/questions?botId={botId}`. +::: + +```json +{ + "count": 3, + "bots": [ + { + "id": "065B007500614D158B41B0D020C96966", + "projectId": "B7CA92F04B9FAE8D941C3E9B7E0CD754" + } + ], + "history": [ + { + "id": "B7CA92F04B9FAE8D941C3E9B7E0CD754:065B007500614D158B41B0D020C96966:75262B7346CC469EA7B874E49888040E", + "question": "what was the umsatz in euro in kristallhöhle during october 2024?", + "text": "Der Gesamtumsatz in Euro (Umsatz in Euro) für die Region 'kristallhöhle' im Oktober 2024 betrug €92.541.045." + } + ], + "route": "sql" +} +``` + +Sample Curl: + +```bash +curl 'https://demo.microstrategy.com/MicroStrategyLibrary/api/questions/suggestions' \ +-X 'POST' \ +--header 'X-MSTR-AuthToken: t40ltbk411923ipk85r8r0tace' \ +--header 'Content-Type: application/json' \ +--data '{ + "count": 3, + "bots": [ + { + "id": "065B007500614D158B41B0D020C96966", + "projectId": "B7CA92F04B9FAE8D941C3E9B7E0CD754" + } + ], + "history": [ + { + "id": "B7CA92F04B9FAE8D941C3E9B7E0CD754:065B007500614D158B41B0D020C96966:75262B7346CC469EA7B874E49888040E", + "question": "what was the umsatz in euro in kristallhöhle during october 2024?", + "text": "Der Gesamtumsatz in Euro (Umsatz in Euro) für die Region 'kristallhöhle' im Oktober 2024 betrug €92.541.045." + } + ], + "route": "sql" +}' +``` + +Sample Response: + +| Response Code | Status | +| ------------- | --------------------------------------------- | +| 200 | Successfully returned the suggested questions | +| 400 | Error in generating the suggested questions | +| 401 | Authorization failed | +| 404 | No bot or bot instance found | + +Sample Response Body on Success: + +```json +{ + "suggestions": [ + { + "bot": { + "id": "065B007500614D158B41B0D020C96966" + }, + "project": { + "id": "B7CA92F04B9FAE8D941C3E9B7E0CD754" + }, + "text": "What is the Umsatz in Euro for the Duft Warensortiment in the Kristallhöhle region during November 2024?" + }, + { + "bot": { + "id": "065B007500614D158B41B0D020C96966" + }, + "project": { + "id": "B7CA92F04B9FAE8D941C3E9B7E0CD754" + }, + "text": "How much Menge was sold for the Ernährung Warensortiment in the Zauberwald region in September 2024?" + }, + { + "bot": { + "id": "065B007500614D158B41B0D020C96966" + }, + "project": { + "id": "B7CA92F04B9FAE8D941C3E9B7E0CD754" + }, + "text": "What was the Umsatz in Euro for Haar Warensortiment in Zauberwald during December 2024?" + } + ] +} +``` diff --git a/docs/common-workflows/analytics/question-with-bot-routing-api/ask-question-to-bots-in-the-application.md b/docs/common-workflows/analytics/question-with-bot-routing-api/ask-question-to-bots-in-the-application.md index 2c3be7ff..7d4fe4f6 100644 --- a/docs/common-workflows/analytics/question-with-bot-routing-api/ask-question-to-bots-in-the-application.md +++ b/docs/common-workflows/analytics/question-with-bot-routing-api/ask-question-to-bots-in-the-application.md @@ -16,7 +16,7 @@ Obtain the authorization token needed to execute the request using [POST /api/au ## Ask a question with bot routing -Endpoint: [POST /api/questions](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/AI%20Chatbot/createQuestion) +Endpoint: [POST /api/questions](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Next-Gen%20AI/createQuestion) Sample Request Headers: diff --git a/docs/common-workflows/analytics/question-with-bot-routing-api/get-image-of-answer.md b/docs/common-workflows/analytics/question-with-bot-routing-api/get-image-of-answer.md index 4eef3efd..3b5b3997 100644 --- a/docs/common-workflows/analytics/question-with-bot-routing-api/get-image-of-answer.md +++ b/docs/common-workflows/analytics/question-with-bot-routing-api/get-image-of-answer.md @@ -16,7 +16,7 @@ Obtain the authorization token needed to execute the request using [POST /api/au ## Get an image of an answer related to a question with bot routing -Endpoint: [GET /api/questions/\{questionsId}/answers/images/\{imageId}](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/AI%20Chatbot/getMessageImage) +Endpoint: [GET /api/questions/\{questionsId}/answers/images/\{imageId}](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Auto%20Bots%20/getMessageImage) :::note Replace `{questionsId}` in `GET /api/questions/{questionsId}/answers/images/{imageId}` with the question ID from `POST /api/questions` and `{imageId}` with your image ID from `GET /api/questions/{questionId}`. diff --git a/docs/common-workflows/analytics/question-with-bot-routing-api/get-question-from-bots-in-the-application.md b/docs/common-workflows/analytics/question-with-bot-routing-api/get-question-from-bots-in-the-application.md index fd7a25d9..56fda8e7 100644 --- a/docs/common-workflows/analytics/question-with-bot-routing-api/get-question-from-bots-in-the-application.md +++ b/docs/common-workflows/analytics/question-with-bot-routing-api/get-question-from-bots-in-the-application.md @@ -16,7 +16,7 @@ Obtain the authorization token needed to execute the request using [POST /api/au ## Get a question with bot routing -Endpoint: [GET /api/questions/\{questionId}](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/AI%20Chatbot/queryMessage_1) +Endpoint: [GET /api/questions/\{questionId}](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Next-Gen%20AI/queryMessage_1) :::note Replace `{questionId}` in `GET /api/questions/{questionId}` with your question ID from `POST /api/questions`. diff --git a/docs/common-workflows/analytics/use-bot-api/ask-bot-instance-question.md b/docs/common-workflows/analytics/use-bot-api/ask-bot-instance-question.md index 66fe137c..b8520f97 100644 --- a/docs/common-workflows/analytics/use-bot-api/ask-bot-instance-question.md +++ b/docs/common-workflows/analytics/use-bot-api/ask-bot-instance-question.md @@ -28,7 +28,7 @@ Obtain the authorization token needed to execute the request using [POST /api/au ## Ask the bot instance a question -Endpoint: [POST /api/bots/\{botId}/instances/\{instanceId}/questions](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/AI%20Chatbot/postQuestion) +Endpoint: [POST /api/bots/\{botId}/instances/\{instanceId}/questions](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Auto%20Bots%20/postQuestion) :::note Replace `{botId}` in `POST /api/bots/{botId}/instances/{instanceId}/questions` with the chatbot ID and `{instanceId}` with your bot instance ID created with `POST /api/bots/{botId}/instances` in your environment. diff --git a/docs/common-workflows/analytics/use-bot-api/ask-bot-instance-suggested-question.md b/docs/common-workflows/analytics/use-bot-api/ask-bot-instance-suggested-question.md index 904cf555..0f5118f2 100644 --- a/docs/common-workflows/analytics/use-bot-api/ask-bot-instance-suggested-question.md +++ b/docs/common-workflows/analytics/use-bot-api/ask-bot-instance-suggested-question.md @@ -28,7 +28,7 @@ Obtain the authorization token needed to execute the request using [POST /api/au ## Ask a bot instance for suggested questions -Endpoint: [POST /api/bots/\{botId}/instances/\{instanceId}/suggestions](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/AI%20Chatbot/createSuggestions) +Endpoint: [POST /api/bots/\{botId}/instances/\{instanceId}/suggestions](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Auto%20Bots%20/createSuggestions) :::note Replace `{botId}` in `POST /api/bots/{botId}/instances/{instanceId}/suggestions` with the chatbot ID and `{instanceId}` with your bot instance ID created with `POST /api/bots/{botId}/instances` in your environment. diff --git a/docs/common-workflows/analytics/use-bot-api/create-a-bot-instance.md b/docs/common-workflows/analytics/use-bot-api/create-a-bot-instance.md index aa69f6fb..952ca77e 100644 --- a/docs/common-workflows/analytics/use-bot-api/create-a-bot-instance.md +++ b/docs/common-workflows/analytics/use-bot-api/create-a-bot-instance.md @@ -28,7 +28,7 @@ Obtain the authorization token needed to execute the request using [POST /api/au ## Create a bot instance -Endpoint: [POST /api/bots/\{botId}/instances](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/AI%20Chatbot/createInstance) +Endpoint: [POST /api/bots/\{botId}/instances](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Auto%20Bots%20/createInstance) :::note Replace `{botId}` in `POST /api/bots/{botId}/instances` with the chatbot ID in your environment. diff --git a/docs/common-workflows/analytics/use-bot-api/delete-a-bot-instance.md b/docs/common-workflows/analytics/use-bot-api/delete-a-bot-instance.md index fc771a59..0b754ebd 100644 --- a/docs/common-workflows/analytics/use-bot-api/delete-a-bot-instance.md +++ b/docs/common-workflows/analytics/use-bot-api/delete-a-bot-instance.md @@ -32,7 +32,7 @@ Obtain the authorization token needed to execute the request using [POST /api/au ## Delete a bot instance -Endpoint: [DELETE /api/bots/\{botId}/instances/\{instanceId}](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/AI%20Chatbot/deleteInstance) +Endpoint: [DELETE /api/bots/\{botId}/instances/\{instanceId}](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Auto%20Bots%20/deleteInstance) :::note Replace `{botId}` in `DELETE /api/bots/{botId}/instances/{instanceId}` with the chatbot ID and `{instanceId}` with your bot instance ID created with `POST /api/bots/{botId}/instances` in your environment. diff --git a/docs/common-workflows/analytics/use-bot-api/get-a-bot-question.md b/docs/common-workflows/analytics/use-bot-api/get-a-bot-question.md index e9e45a7a..52d3a1d2 100644 --- a/docs/common-workflows/analytics/use-bot-api/get-a-bot-question.md +++ b/docs/common-workflows/analytics/use-bot-api/get-a-bot-question.md @@ -24,7 +24,7 @@ Obtain the authorization token needed to execute the request using [POST /api/au ## Get a chat bot's question -Endpoint: [GET /api/bots/\{botId}/questions/\{questionId}](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/AI%20Chatbot/queryMessage) +Endpoint: [GET /api/bots/\{botId}/questions/\{questionId}](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Auto%20Bots%20/queryMessage) :::note Replace `{botId}` in `GET /api/bots/{botId}/questions/{questionId}` with the chatbot ID and `{questionId}` with your question ID in your environment. diff --git a/docs/common-workflows/analytics/use-bot-api/get-bot-configuration.md b/docs/common-workflows/analytics/use-bot-api/get-bot-configuration.md index fd33b984..1d94d703 100644 --- a/docs/common-workflows/analytics/use-bot-api/get-bot-configuration.md +++ b/docs/common-workflows/analytics/use-bot-api/get-bot-configuration.md @@ -16,7 +16,7 @@ Obtain the authorization token needed to execute the request using [POST /api/au ## Get a chat bot's configuration -Endpoint: [GET /api/bots/\{botId}/configuration](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/AI%20Chatbot/getConfiguration) +Endpoint: [GET /api/bots/\{botId}/configuration](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Auto%20Bots%20/getConfiguration) :::note Replace `{botId}` in `GET /api/bots/{botId}/configuration` with the chatbot ID and `{questionId}` with your question ID in your environment. diff --git a/docs/common-workflows/analytics/use-bot-api/get-bot-question-list.md b/docs/common-workflows/analytics/use-bot-api/get-bot-question-list.md index 1582e043..b955e9b1 100644 --- a/docs/common-workflows/analytics/use-bot-api/get-bot-question-list.md +++ b/docs/common-workflows/analytics/use-bot-api/get-bot-question-list.md @@ -16,7 +16,7 @@ Obtain the authorization token needed to execute the request using [POST /api/au ## Get a chat bot's question list -Endpoint: [GET /api/bots/\{botId}/questions](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/AI%20Chatbot/queryMessages) +Endpoint: [GET /api/bots/\{botId}/questions](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Auto%20Bots%20/queryMessages) :::note Replace `{botId}` in `GET /api/bots/{botId}/questions` with the chatbot ID in your environment. diff --git a/docs/getting-started/getting-started.md b/docs/getting-started/getting-started.md index e9605c6e..75c92985 100644 --- a/docs/getting-started/getting-started.md +++ b/docs/getting-started/getting-started.md @@ -8,7 +8,8 @@ To get started, view the following topics to know the basics of the Strategy RES - [REST API architecture](rest-api-architecture.md) - [REST API families](rest-api-families.md) -After learning the basics, view the following topics to understand some general topics that apply to the REST API: +After learning the basics, view the following topics to understand some general topics that apply to +the REST API: - [Authentication](authentication.md) - [Configure clustered environments](configure-clustered-environments.md) @@ -21,4 +22,10 @@ You can use the REST API Explorer and Playground as tools to learn more and run - [Strategy REST API Explorer](microstrategy-rest-api-explorer.md) - [Strategy REST API Playground](playground.md) -For more specific REST API topics, view the [common workflows](../common-workflows/common-workflows.md). +For more specific REST API topics, view the +[common workflows](../common-workflows/common-workflows.md). + +As newly introduced, Strategy Library now supports OAuth2 authorization for accessing the Strategy +Library API, which can simplify API usage: + +- [Using REST API with OAuth2](oauth2.md) diff --git a/docs/getting-started/oauth2.md b/docs/getting-started/oauth2.md new file mode 100644 index 00000000..ae460c60 --- /dev/null +++ b/docs/getting-started/oauth2.md @@ -0,0 +1,80 @@ +--- +title: Using REST API with OAuth2 +description: + Learn how to implement OAuth2 authentication with Strategy REST API for secure and scalable + client-server communication. +--- + +## Overview + +Strategy's OAuth2 authentication provides a modern, secure, and standardized way for clients to +authenticate with the Library server. This implementation follows industry best practices and +simplifies the authentication process across different client applications. + +## Why OAuth2? + +### What is OAuth2? + +OAuth2 (Open Authorization 2.0) is an industry-standard protocol for authorization. It enables +secure delegation of access to resources on behalf of a user without sharing their credentials. +OAuth2 is widely adopted for its flexibility, scalability, and ability to support various use cases, +such as single sign-on (SSO), third-party integrations, and API access. + +At its core, OAuth2 operates through the exchange of tokens, which represent a user's authorization +to access specific resources. These tokens are issued by an authorization server and can be used by +client applications to interact with resource servers securely. + +### Why Using OAuth2? + +The traditional authentication methods required clients to implement multiple authentication modes +separately (standard mode, SAML, OIDC), each with its own API calls and cookie management. This +approach became increasingly complex as the number of clients grew, especially with integrations +like Tableau, PowerBI, and Google plugins. + +One of the most significant limitations of the previous authentication system was its heavy reliance +on cookies. Every API request required maintaining and managing cookie headers, which introduced +several challenges: + +- Session stickiness requirements +- Cross-Site Request Forgery (CSRF) vulnerabilities +- Complex cookie management across different domains +- Limited scalability in distributed systems + +The new OAuth2-based authentication mechanism offers several key advantages: + +1. **Unified Authentication Flow**: All clients and third-party integrations can use a single, + standardized method to authenticate with the Library server, regardless of the authentication + mode configured on the server. +1. **Improved Security**: Replaces cookie-based authentication with secure token-based + authentication, eliminating CSRF risks and session stickiness requirements. +1. **Better Scalability**: Follows modern security best practices for distributed systems by using + stateless token-based authentication instead of stateful cookie-based sessions. + +## How to Use OAuth2 + +### Configure OAuth2 + +Please refer to [Configure OAuth 2.0 to log in to Library](https://www2.microstrategy.com/producthelp/Current/Workstation/en-us/Content/config_oauth2.htm) + +### API Access + +1. Firstly, we should implement the OAuth2 Authorization Workflow against the Authorization Endpoint + (`oauth2/authorize`) and Token Endpoint (`oauth2/token`) to get a valid Access Token + +1. Then the following Rest API calls will only require puting this Access Token in the Authorization + Header (`X-MSTR-AuthToken`) + +1. If the client doesn't want require User Login for a certain time, it can also persist a Refresh + Token locally which can be used to refresh the Access Token later. + +### Sample Projects + +We provide a comprehensive +[OAuth2 Extension Sample](https://github.com/MicroStrategy/rest-api-samples) that demonstrates how +to implement OAuth2 authentication with Strategy REST API. This sample includes: + +- Complete authentication flow implementation +- Token management examples +- Test API with Access Token +- Best practices for secure token storage +- Error handling and session management diff --git a/docs/whats-new.md b/docs/whats-new.md index 4e7b854e..f31bb7b8 100644 --- a/docs/whats-new.md +++ b/docs/whats-new.md @@ -4,6 +4,15 @@ sidebar_label: What's new Description: What's New in the REST API. --- +## Strategy ONE (June 2025) + +- [Next-Gen AI Image Support](common-workflows/analytics/auto-bot-api/auto-bot-api.md). Request and retrieve images in answer from Next-Gen AI. +- [Project Duplication](common-workflows/administration/project-duplication/project-duplication.md). Duplicate a project within the same environment. + +## Strategy ONE (March 2025) + +- [Next-Gen AI](common-workflows/analytics/auto-bot-api/auto-bot-api.md). Ask questions, retrieve answers, get historical chat messages and suggested questions from Next-Gen AI. + ## MicroStrategy ONE (September 2024) - [Managing bookmarks](common-workflows/administration/manage-bookmarks/manage-bookmarks.md). Retrieve, create, update, and delete bookmarks. diff --git a/sidebars.js b/sidebars.js index 3fc93108..98b1eef7 100644 --- a/sidebars.js +++ b/sidebars.js @@ -47,6 +47,7 @@ const sidebars = { "getting-started/microstrategy-rest-api-explorer", "getting-started/playground", "getting-started/embedding-sdk", + "getting-started/oauth2", ], }, { @@ -409,13 +410,28 @@ const sidebars = { "common-workflows/analytics/manage-insights/update-insight-status", ], }, + { + type: "category", + link: { + type: "doc", + id: "common-workflows/analytics/auto-bot-api/auto-bot-api", + }, + label: "Next-Gen AI", + items: [ + "common-workflows/analytics/auto-bot-api/post-question", + "common-workflows/analytics/auto-bot-api/get-question-by-id", + "common-workflows/analytics/auto-bot-api/get-questions-by-bot", + "common-workflows/analytics/auto-bot-api/post-suggestion", + "common-workflows/analytics/auto-bot-api/get-image-of-answer", + ], + }, { type: "category", link: { type: "doc", id: "common-workflows/analytics/use-bot-api/use-bot-api", }, - label: "Bot APIs", + label: "Bot APIs ", items: [ "common-workflows/analytics/use-bot-api/get-bot-configuration", "common-workflows/analytics/use-bot-api/get-bot-question-list", @@ -432,7 +448,7 @@ const sidebars = { type: "doc", id: "common-workflows/analytics/question-with-bot-routing-api/question-api", }, - label: "Question with Bot Routing APIs", + label: "Question with Bot Routing APIs ", items: [ "common-workflows/analytics/question-with-bot-routing-api/ask-question-to-bots-in-the-application", "common-workflows/analytics/question-with-bot-routing-api/get-question-from-bots-in-the-application", @@ -1056,6 +1072,15 @@ const sidebars = { "common-workflows/administration/manage-bookmarks/get-bookmarks/get-bookmarks", ], }, + { + type: "category", + link: { + type: "doc", + id: "common-workflows/administration/project-duplication/project-duplication", + }, + label: "Project Duplication", + items: ["common-workflows/administration/project-duplication/project-duplication"], + }, ], }, ], From e1c88c0708ec622b6ee3fb9b88621ad4a074ffdb Mon Sep 17 00:00:00 2001 From: zhe Date: Tue, 1 Jul 2025 10:07:43 +0800 Subject: [PATCH 2/4] Update --- .../project-duplication/project-duplication.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/common-workflows/administration/project-duplication/project-duplication.md b/docs/common-workflows/administration/project-duplication/project-duplication.md index 36f922ed..8a7c2354 100644 --- a/docs/common-workflows/administration/project-duplication/project-duplication.md +++ b/docs/common-workflows/administration/project-duplication/project-duplication.md @@ -9,10 +9,10 @@ Project duplication enables administrators to duplicate projects within the same ## APIs -- [POST /api/projectDuplications](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Project%20Duplication/createProjectDuplication) -- [GET /api/projectDuplications/\{id}](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Project%20Duplication/getProjectDuplication) -- [GET /api/projectDuplications](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Project%20Duplication/getProjectDuplications) -- [PUT /api/projectDuplications/\{id}](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Project%20Duplication/updateProjectDuplication) +- [POST /api/projectDuplications](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Project%20Duplications/createDuplication) +- [GET /api/projectDuplications/\{id}](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Project%20Duplications/getProjectDuplication) +- [GET /api/projectDuplications](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Project%20Duplications/getProjectDuplications) +- [PUT /api/projectDuplications/\{id}/status](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Project%20Duplications/cancelDuplication) ## Privileges and authorization @@ -374,7 +374,7 @@ Sample Response Code: 200 (OK) ### Cancel project duplication -Use `PUT /api/projectDuplications/{id}` to cancel an ongoing project duplication operation. This is +Use `PUT /api/projectDuplications/{id}/status` 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) @@ -397,7 +397,7 @@ Sample Request Body: Sample Curl: ```bash -curl -X PUT "https://demo.microstrategy.com/MicroStrategyLibrary/api/projectDuplications/F8F1280022A444C5A10B3445B552E33A" \ +curl -X PUT "https://demo.microstrategy.com/MicroStrategyLibrary/api/projectDuplications/F8F1280022A444C5A10B3445B552E33A/status" \ -H "Content-Type: application/json" \ -H "X-MSTR-AuthToken: o0ak9privdo27nfo798j40m8aa" \ -d '{ From 7e9a7934c1c8728881c1323083ad554a973f4e53 Mon Sep 17 00:00:00 2001 From: zhe Date: Tue, 22 Jul 2025 17:58:51 +0800 Subject: [PATCH 3/4] Update --- .../manage-content-group-packages.md | 2 + .../monitors/project-administration.md | 92 +- .../cross-env-project-duplication.md | 1175 +++++++++++++++++ .../project-duplication.md | 26 +- .../analytics/auto-bot-api/auto-bot-api.md | 2 + .../analytics/auto-bot-api/get-columns.md | 66 + .../auto-bot-api/get-question-by-id.md | 7 +- docs/whats-new.md | 5 + sidebars.js | 6 +- 9 files changed, 1366 insertions(+), 15 deletions(-) create mode 100644 docs/common-workflows/administration/project-duplication/cross-env-project-duplication.md create mode 100644 docs/common-workflows/analytics/auto-bot-api/get-columns.md diff --git a/docs/common-workflows/administration/migrations/create-and-import-migration-packages/manage-content-group-packages.md b/docs/common-workflows/administration/migrations/create-and-import-migration-packages/manage-content-group-packages.md index 8adbc708..57a3c208 100644 --- a/docs/common-workflows/administration/migrations/create-and-import-migration-packages/manage-content-group-packages.md +++ b/docs/common-workflows/administration/migrations/create-and-import-migration-packages/manage-content-group-packages.md @@ -89,6 +89,7 @@ Sample request of the project package: { "id": "54F3D26011D2896560009A8E67019608", "name": "admin_group", + "level": "configuration_object", "type": 77, "action": "replace", "includeDependents": true @@ -139,6 +140,7 @@ Sample request of the project package: { "id": "54F3D26011D2896560009A8E67019608", "name": "admin_group", + "level": "configuration_object", "type": 77, "action": "replace", "includeDependents": true diff --git a/docs/common-workflows/administration/monitors/project-administration.md b/docs/common-workflows/administration/monitors/project-administration.md index deb4bb88..fa6bcc66 100644 --- a/docs/common-workflows/administration/monitors/project-administration.md +++ b/docs/common-workflows/administration/monitors/project-administration.md @@ -309,6 +309,86 @@ In the example above, the project status of `"MicroStrategy Tutorial"` was chang } ``` +## Update status for a specific project on all cluster nodes + + + +Endpoint: [PATCH /api/monitors/projects/status](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Monitors/updateProjectStatusOnAllNodes) + +There are several use cases in which it is required to load or unload a project on an environment. A dedicated endpoint `PATCH /api/monitors/projects/status` is implemented to address these use cases. The endpoint call requires to provide the identifier or the name of the project in the query parameters and `X-MSTR-AuthToken` in the header. + +If a project ID is passed in the query parameter, we will use the project by ID. Otherwise, a project name must be passed and the project with specific name ignoring cases will be used. + +This API will accept the request and start processing to execute based on the request submitted. By default, the API will wait for server session to expire before unloading a project. You can provide a `deleteSessions` query parameter in the case of unloading project to close all active sessions immediately. + +- Request parameters: + + - `X-MSTR- AuthToken`: Authorization Token + - `projectId`: Project Id + - `projectName`: Project name + - `deleteSessions`: Whether to close all active sessions when unloading project + +- Request body: + + ```json + { + "status": "loaded" // Valid values are: loaded, unloaded, request_idle, exec_idle, partial_idle, wh_exec_idle, full_idle + } + ``` + +- Curl: + + ```bash + curl -X PATCH " https:// demo.microstrategy.com/MicroStrategyLibrary/api/monitors/projects/status?projectId=B7CA92F04B9FAE8D941C3E9B7E0CD754" -H "accept: application/json" -H "X-MSTR-AuthToken: jal5uua4uo6gfag1vivmadag17" -H "Content-Type: application/json" -d "{\\"status\\":\\"unloaded\\"}" + ``` + +- Response code: 202 (Accepted) + +## Get status for a specific project on all cluster nodes + + + +Endpoint: [GET /api/monitors/projects/status](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Monitors/getProjectStatusOnAllNodes) + +This endpoint queries the status of a project on each node, especially after you load or unload a project with the `PATCH /api/monitors/projects/status` API. The endpoint call requires to provide the identifier or the name of the project in the query parameters and `X-MSTR-AuthToken` in the header. + +If a project ID is passed in the query parameter, we will use the project by ID. Otherwise, a project name must be passed and the project with specific name ignoring cases will be used. + +You can expect the following statuses of the project to be returned with respect to the nodes: unloaded, loaded, exec_idle, request_idle, full_idle, wh_exec_idle, partial_idle, unloaded_pending, loaded_pending. + +- Request parameters: + + - `X-MSTR- AuthToken`: Authorization Token + - `projectId`: Project Id + - `projectName`: Project name + +- Curl: + + ```bash + curl -X GET "https://demo.microstrategy.com/MicroStrategyLibrary/api/monitors/projects/status?projectId=B7CA92F04B9FAE8D941C3E9B7E0CD754" -H "accept: application/json" -H "X-MSTR-AuthToken: s664q0cqjergslaj4vfpnneb3m" + ``` + +- Response body: + + ```json + { + "nodes": [ + { + "serverName": "env-160560laio1use1", + "serverPort": 34952, + "status": "running" + }, + { + "serverName": "env-160560laio2use1", + "serverPort": 34952, + "status": "unloaded" + } + ] + } + ``` + +- Response code: 200 (Success: OK) + ## Delete project @@ -319,7 +399,9 @@ There are several use cases in which it is required to delete a project from an curl -X 'DELETE' 'https://demo.microstrategy.com/MicroStrategyLibrary/api/projects/A435ED1A4CF916B9A0A0729F9C93C9B9' -H 'accept: */*' -H 'X-MSTR-AuthToken: tp43crmdrkf54avoo9jbgj4a3q' ``` -The response code is either `202 Accepted` or `204 No Content`. The code depends on the deletion execution status. If the endpoint manages to delete the project in a given timeout, it sends `204` code. If the deletion takes longer than the timeout, the endpoint sends `202` code. The status of the operation can be checked using `GET /api/monitors/iServer/nodes` endpoint. If the deletion is successful, the endpoint stops reporting the project. The endpoint will delete a project only if the project has unloaded status on every node. If the project is not unloaded a following error will be provided to a client. +The response code is either `202 Accepted` or `204 No Content`. The code depends on the deletion execution status. If the endpoint manages to delete the project in a given timeout, it sends `204` code. If the deletion takes longer than the timeout, the endpoint sends `202` code. The status of the operation can be checked using `GET /api/monitors/iServer/nodes` endpoint. If the deletion is successful, the endpoint stops reporting the project. + +By default, the endpoint will delete a project only if the project has unloaded status on every node. If the project is not unloaded a following error will be provided to a client. ```json { @@ -331,6 +413,14 @@ The response code is either `202 Accepted` or `204 No Content`. The code depends The project status can be changed using the `PATCH /api/monitors/iServer/nodes/{nodeName}/projects/{projectId}` endpoint. The client can delete the project if it is administrator or owner of the project. + + +You can provide a `deleteSessions` query parameter which will help to automatically close all active sessions across all the clustered nodes and then delete the project. The exemplary call is listed below: + +```bash +curl -X 'DELETE' \ 'https://demo.microstrategy.com/MicroStrategyLibrary/api/projects/B7CA92F04B9FAE8D941C3E9B7E0CD754?deleteSessions=true' \ -H 'accept: */*' \ -H 'X-MSTR-AuthToken: tp43crmdrkf54avoo9jbgj4a3q' +``` + ## Log out Endpoint: [POST /api/auth/logout](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Authentication/postLogout) diff --git a/docs/common-workflows/administration/project-duplication/cross-env-project-duplication.md b/docs/common-workflows/administration/project-duplication/cross-env-project-duplication.md new file mode 100644 index 00000000..4f755472 --- /dev/null +++ b/docs/common-workflows/administration/project-duplication/cross-env-project-duplication.md @@ -0,0 +1,1175 @@ +--- +sidebar_label: Project Duplication (Cross Environment) +title: Project Duplication (Cross Environment) +description: The REST API provides endpoints to duplicate projects across two environments, enabling + administrators to create copies of projects with customizable settings. +--- + +Project duplication enables administrators to duplicate projects across two environments for the same MD type (PostgreSQL to PostgreSQL) directly using REST APIs, replacing the need for legacy tools like Object Manager, Developer. + +:::warning + +These project duplication APIs do not work when [User Fencing](https://www2.microstrategy.com/producthelp/current/SystemAdmin/WebHelp/Lang_1033/content/Work_Fences.htm) is enabled. Please ensure that User Fencing is disabled in the Library. + +::: + +## APIs + +- [POST /api/projectDuplications](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Project%20Duplications/createDuplication) +- [PUT /api/projectDuplications/\{id}](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Project%20Duplications/createDuplicationOnTarget) +- [GET /api/projectDuplications/\{id}](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Project%20Duplications/getProjectDuplication) +- [GET /api/projectDuplications](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Project%20Duplications/getProjectDuplications) +- [PUT /api/projectDuplications/\{id}/status](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Project%20Duplications/cancelDuplication) +- [GET /api/projectDuplications/\{id}/backup](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Project%20Duplications/getProjectDuplicationFiles) +- [POST /api/projectDuplications/restoration](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Project%20Duplications/triggerDuplicationByPackage) +- [DELETE /api/projectDuplications/\{id}](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Project%20Duplications/deleteDuplication) + +## Privileges and authorization + +You need the following privileges to use the project duplication functionality: + +- [DssXmlPrivilegesDuplicateProject](https://www2.microstrategy.com/producthelp/Current/WebAPIReference/com/microstrategy/webapi/EnumDSSXMLPrivilegeTypes.html#DssXmlPrivilegesDuplicateProject) and [DssXmlPrivilegesBypassAccessChecks](https://www2.microstrategy.com/producthelp/Current/WebAPIReference/com/microstrategy/webapi/EnumDSSXMLPrivilegeTypes.html#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](/docs/getting-started/authentication.md) for +more information. + +## General workflow + +The general workflow for using the project duplication APIs involves: + +1. [Initiate project duplication on source environment](#initiate-project-duplication-on-source-environment) +1. [Initiate project duplication on target environment](#initiate-project-duplication-on-target-environment) +1. [Check duplication status](#check-duplication-status) +1. [List all project duplications](#list-all-project-duplications) +1. [Cancel project duplication](#cancel-project-duplication) +1. [Download project duplication package file](#download-project-duplication-package-file) +1. [Restore project duplication with package file](#restore-project-duplication-with-package-file) + +### Initiate project duplication on source environment + +Use `POST /api/projectDuplications` to start a project duplication operation on source environment. This initiates an asynchronous process +that creates a duplicate of the source project with the settings you specify. The duplicated project will be synced with the target environment. + +For cross environment project duplication, `source.environment.id` and `target.environment.id` in the request body should be different. + +#### Step 1: Create the duplication request on source environment + +Sample Request Header: + +```http +Content-Type: application/json +X-MSTR-AuthToken: +Prefer: respond-async +X-MSTR-ProjectID: +``` + +:::tip The `Prefer: respond-async` header instructs the server to process the duplication asynchronously without waiting for completion. +::: + +Sample Request Body: + +:::important For cross environment project duplication, `source.environment.id` and `target.environment.id` in the request body should be different. +::: + +```json +{ + "source": { + "environment": { + "id": "http://example1.com/MicroStrategyLibrary", + "name": "Source Environment" + }, + "project": { + "id": "B7CA92F04B9FAE8D941C3E9B7E0CD754", + "name": "Tutorial" + } + }, + "target": { + "environment": { + "id": "http://example2.com/MicroStrategyLibrary", + "name": "Target Environment" + }, + "project": { + "name": "Target Project" + } + }, + "settings": { + "import": { + "description": "this is a test description", + "defaultLocale": 2052, + "locales": [1033, 2052], + "configurationObjects": { + "conflictRules": [ + { + "type": 5, + "rule": 1 + }, + { + "type": 34, + "rule": 6 + }, + { + "type": 29, + "rule": 2 + }, + { + "type": 44, + "rule": 2 + } + ], + "matchUsersByLogin": false + } + }, + "export": { + "configurationObjects": { + "rules": [ + { + "type": 5, + "rule": 1 + }, + { + "type": 34, + "rule": 2 + } + ], + "objects": ["95A868464F2F105205B2848BBCB81C50", "4E70890241DBB18E6CA1D8B850952A68"], + "includeAllUserGroups": false + } + } + } +} +``` + +Sample Curl: + +```bash +curl -X POST "https://example1.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://example1.com/MicroStrategyLibrary", + "name": "Source Environment" + }, + "project": { + "id": "B7CA92F04B9FAE8D941C3E9B7E0CD754", + "name": "Tutorial" + } + }, + "target": { + "environment": { + "id": "http://example2.com/MicroStrategyLibrary", + "name": "Target Environment" + }, + "project": { + "name": "Target Project" + } + }, +"settings": { + "import": { + "description": "this is a test description", + "defaultLocale": 2052, + "locales": [1033, 2052], + "configurationObjects": { + "conflictRules":[ + { + "type": 5, + "rule": 1 + }, + { + "type": 34, + "rule": 6 + }, + { + "type": 29, + "rule": 2 + }, + { + "type": 44, + "rule": 2 + } + ], + "matchUsersByLogin": false + } + }, + "export": { + "configurationObjects": { + "rules": [ + { + "type": 5, + "rule": 1 + }, + { + "type": 34, + "rule": 2 + } + ], + "objects": [ + "95A868464F2F105205B2848BBCB81C50", + "4E70890241DBB18E6CA1D8B850952A68" + ], + "includeAllUserGroups": false + } + } + } +}' +``` + +Sample Response Code: 201 (Created) + +Sample Response Body: + +```json +{ + "id": "F8F1280022A444C5A10B3445B552E33A", + "source": { + "environment": { + "id": "http://example1.com/MicroStrategyLibrary", + "name": "Source Environment" + }, + "project": { + "id": "B7CA92F04B9FAE8D941C3E9B7E0CD754", + "name": "Tutorial" + }, + "creator": { + "id": "86A002474C1A18F1F92F2B8150A43741", + "name": "mstr1" + } + }, + "target": { + "environment": { + "id": "http://example2.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 + }, + "configurationObjects": { + "rules": [ + { + "type": 34, + "rule": 2 + }, + { + "type": 5, + "rule": 1 + } + ], + "objects": ["95A868464F2F105205B2848BBCB81C50", "4E70890241DBB18E6CA1D8B850952A68"], + "includeAllUserGroups": false + } + }, + "import": { + "description": "this is a test description", + "defaultLocale": 2052, + "locales": [1033, 2052], + "configurationObjects": { + "conflictRules": [ + { + "type": 44, + "rule": 2 + }, + { + "type": 34, + "rule": 6 + }, + { + "type": 5, + "rule": 1 + }, + { + "type": 29, + "rule": 2 + } + ], + "matchUsersByLogin": false + } + } + } +} +``` + +:::note 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. +::: + +### Initiate project duplication on target environment + +Before initiating project duplication on target environment, call `POST /api/projectDuplications` to start a project duplication operation on source environment and get the project duplication ID in the response body. + +On target environment, use `PUT /projectDuplications/{id}` with the project duplication ID to initiate an asynchronous process that creates a duplicate of the project with the settings you specify. The duplicated project will be synced from the source environment. + +#### Step 2: Create the duplication request on target environment + +Sample Request Header: + +```http +Content-Type: application/json +X-MSTR-AuthToken: +Prefer: respond-async +X-MSTR-ProjectID: +``` + +:::tip The `Prefer: respond-async` header instructs the server to process the duplication asynchronously without waiting for completion. +::: + +Sample Request Body: + +:::important For cross environment project duplication, `source.environment.id` and `target.environment.id` in the request body should be different. Use the same request body as in the `POST /projectDuplications` request. +::: + +```json +{ + "source": { + "environment": { + "id": "http://example1.com/MicroStrategyLibrary", + "name": "Source Environment" + }, + "project": { + "id": "B7CA92F04B9FAE8D941C3E9B7E0CD754", + "name": "Tutorial" + } + }, + "target": { + "environment": { + "id": "http://example2.com/MicroStrategyLibrary", + "name": "Target Environment" + }, + "project": { + "name": "Target Project" + } + }, + "settings": { + "export": { + "projectObjectsPreference": { + "schemaObjectsOnly": false, + "skipEmptyProfileFolders": false + }, + "subscriptionPreferences": { + "includeUserSubscriptions": false, + "includeContactSubscriptions": false + }, + "configurationObjects": { + "rules": [ + { + "type": 34, + "rule": 2 + }, + { + "type": 5, + "rule": 1 + } + ], + "objects": ["95A868464F2F105205B2848BBCB81C50", "4E70890241DBB18E6CA1D8B850952A68"], + "includeAllUserGroups": false + } + }, + "import": { + "description": "this is a test description", + "defaultLocale": 2052, + "locales": [1033, 2052], + "configurationObjects": { + "conflictRules": [ + { + "type": 44, + "rule": 2 + }, + { + "type": 34, + "rule": 6 + }, + { + "type": 5, + "rule": 1 + }, + { + "type": 29, + "rule": 2 + } + ], + "matchUsersByLogin": false + } + } + } +} +``` + +Sample Curl: + +```bash +curl -X PUT "https://example2.com/MicroStrategyLibrary/api/projectDuplications/C17A7B510F8A4B74B6B19F168106921E" \ + -H "Content-Type: application/json" \ + -H "X-MSTR-AuthToken: o0ak9privdo27nfo798j40m8aa" \ + -H "Prefer: respond-async" \ + -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 + ], + "configurationObjects": { + "conflictRules": [ + { + "type": 44, + "rule": 2 + }, + { + "type": 34, + "rule": 6 + }, + { + "type": 5, + "rule": 1 + }, + { + "type": 29, + "rule": 2 + } + ], + "matchUsersByLogin": false + } + } + } +}' +``` + +Sample Response Code: 201 (Created) + +Sample Response Body: + +```json +{ + "id": "F8F1280022A444C5A10B3445B552E33A", + "source": { + "environment": { + "id": "http://example1.com/MicroStrategyLibrary", + "name": "Source Environment" + }, + "project": { + "id": "B7CA92F04B9FAE8D941C3E9B7E0CD754", + "name": "Tutorial" + }, + "creator": { + "id": "86A002474C1A18F1F92F2B8150A43741", + "name": "mstr1" + } + }, + "target": { + "environment": { + "id": "http://example2.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 + }, + "configurationObjects": { + "rules": [ + { + "type": 34, + "rule": 2 + }, + { + "type": 5, + "rule": 1 + } + ], + "objects": ["95A868464F2F105205B2848BBCB81C50", "4E70890241DBB18E6CA1D8B850952A68"], + "includeAllUserGroups": false + } + }, + "import": { + "description": "this is a test description", + "defaultLocale": 2052, + "locales": [1033, 2052], + "configurationObjects": { + "conflictRules": [ + { + "type": 44, + "rule": 2 + }, + { + "type": 34, + "rule": 6 + }, + { + "type": 5, + "rule": 1 + }, + { + "type": 29, + "rule": 2 + } + ], + "matchUsersByLogin": false + } + } + } +} +``` + +:::note 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 on either source environment or target environment. Since duplication is an asynchronous process, you should poll this endpoint to monitor the progress. + +#### Step 3: Monitor the duplication progress + +Sample Request Header: + +```http +X-MSTR-AuthToken: +``` + +Sample Curl: + +```bash +curl -X GET "https://demo.microstrategy.com/MicroStrategyLibrary/api/projectDuplications/F8F1280022A444C5A10B3445B552E33A" \ + -H "X-MSTR-AuthToken: o0ak9privdo27nfo798j40m8aa" +``` + +Sample Response Body: + +```json +{ + "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 + }, + "configurationObjects": { + "rules": [ + { + "type": 34, + "rule": 2 + }, + { + "type": 5, + "rule": 1 + } + ], + "objects": ["95A868464F2F105205B2848BBCB81C50", "4E70890241DBB18E6CA1D8B850952A68"], + "includeAllUserGroups": false + } + }, + "import": { + "description": "this is a test description", + "defaultLocale": 2052, + "locales": [1033, 2052], + "configurationObjects": { + "conflictRules": [ + { + "type": 44, + "rule": 2 + }, + { + "type": 34, + "rule": 6 + }, + { + "type": 5, + "rule": 1 + }, + { + "type": 29, + "rule": 2 + } + ], + "matchUsersByLogin": false + } + } + } +} +``` + +Sample Response Code: 200 (OK) + +:::info Duplication Status Values + +The status of project duplication on source environment may be `exporting`, `export_syncing`, `exported`, `export_failed`, `cancelled`. + +- exporting: Target environment is exporting the duplicated project. +- export_syncing: Source environment is syncing the project to target environment. +- exported: Project duplication finishes successfully on source environment. +- export_failed: Failure occurs during project duplication on source environment. +- cancelled: Project duplication is cancelled. + +The status of project duplication on target environment may be `import_syncing`, `importing`, `completed`, `import_failed`, `cancelling`, `cancelled`. + +- import_syncing: Target environment is syncing the project from source environment. +- importing: Target environment is importing the duplicated project. +- completed: Project duplication finishes successfully on target environment. +- import_failed: Failure occurs during project duplication on target environment. +- cancelling: Project duplication is being cancelled. +- cancelled: Project duplication is cancelled. + +You should poll the status endpoint at reasonable intervals (e.g., every 10-30 seconds) until the +status changes to `exported`, `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: + +```http +X-MSTR-AuthToken: +``` + +Sample Curl: + +```bash +curl -X GET "https://demo.microstrategy.com/MicroStrategyLibrary/api/projectDuplications?offset=0&limit=1" \ + -H "X-MSTR-AuthToken: o0ak9privdo27nfo798j40m8aa" +``` + +Sample Response Body: + +```json +{ + "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 + }, + "configurationObjects": { + "rules": [ + { + "type": 34, + "rule": 2 + }, + { + "type": 5, + "rule": 1 + } + ], + "objects": [ + "95A868464F2F105205B2848BBCB81C50", + "4E70890241DBB18E6CA1D8B850952A68" + ], + "includeAllUserGroups": false + } + }, + "import": { + "description": "this is a test description", + "defaultLocale": 2052, + "locales": [ + 1033, + 2052 + ], + "configurationObjects": { + "conflictRules": [ + { + "type": 44, + "rule": 2 + }, + { + "type": 34, + "rule": 6 + }, + { + "type": 5, + "rule": 1 + }, + { + "type": 29, + "rule": 2 + } + ], + "matchUsersByLogin": false + } + } + } + } +} +``` + +Sample Response Code: 200 (OK) + +:::tip 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 on either source environment or target environment. +This is useful if you made a mistake or need to stop a long-running duplication task. + +For source environment, if the project duplication status has not been `exported`, cancelling the project duplication on source environment will also cancel any pending project duplication with the same ID on target environment. +However, cancelling the project duplication on target environment will not cancel the same project duplication on source environment. + +#### Step 4: Cancel a duplication (if needed) + +Sample Request Header: + +```http +Content-Type: application/json +X-MSTR-AuthToken: +``` + +Sample Request Body: + +```json +{ + "status": "cancelled" +} +``` + +Sample Curl: + +```bash +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) + +:::note Important limitations: + +- You can only cancel duplications that are in `exporting`, `exporting_syncing`, `import_syncing` or `importing` status +- Attempting to cancel a duplication that has already completed (`exported` on source environment, `completed` on target environment), 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 + ::: + +### Download project duplication package file + +You may use `GET /api/projectDuplications/{id}/backup` to download the project duplication file. The package file can be used to restore the duplicated project on other environments with `POST /projectDuplications` API. + +This API can only be called on source environment and the project duplication status must already be `exported`. + +#### Step 5: Download project duplication package file (if needed) + +Sample Request Header: + +```http +X-MSTR-AuthToken: +``` + +Sample Curl: + +```bash +curl -X GET "https://demo.microstrategy.com/MicroStrategyLibrary/api/projectDuplications/F8F1280022A444C5A10B3445B552E33A/backup" \ + -H "X-MSTR-AuthToken: o0ak9privdo27nfo798j40m8aa" \ + -o F8F1280022A444C5A10B3445B552E33A.projdup +``` + +Sample Response Body: File binary + +Sample Response Code: 200 (OK) + +### Restore project duplication with package file + +Use `POST /api/projectDuplications/restoration` to restore a duplicated project with a project duplication package file on any environment. + +With this API, upload a package file you download with `GET /projectDuplications/{id}/backup` API and a new project duplication will be triggered as in target environment. + +#### Step 6: Restore project duplication with package file (if needed) + +Sample Request Header: + +```http +Content-Type: multipart/form-data +X-MSTR-AuthToken: +``` + +Sample Request Body: + +The request body must contain the form data with the following fields: + +| Field Name | Type | Required | Description | +| ---------- | ------ | -------- | ------------------------------------------------------------ | +| `file` | File | Yes | The sample file to be uploaded. | +| `metadata` | String | Yes | A JSON string that contains the metadata of the restoration. | + +Sample Curl: + +```bash +curl -X PUT "https://demo.microstrategy.com/MicroStrategyLibrary/api/projectDuplications/F8F1280022A444C5A10B3445B552E33A" \ + -H "Content-Type: application/json" \ + -H "X-MSTR-AuthToken: o0ak9privdo27nfo798j40m8aa" \ + --form 'file=@"/your/path/to/package.projdup' \ + --form 'metadata="{ + \"target\": { + \"environment\": { + \"id\": \"https://demo.microstrategy.com/MicroStrategyLibrary\", + \"name\": \"Target environment\" + }, + \"project\": { + \"name\": \"New project name\" + } + }, + \"settings\": { + \"import\": { + \"description\": \"string\", + \"defaultLocale\": 2052, + \"locales\": [ + 1033, 2052 + ], + \"configurationObjects\": { + \"conflictRules\": [ + { + \"type\": 0, + \"rule\": 0 + } + ], + \"matchUsersByLogin\": true + } + } + } + }"' +``` + +Sample Response Code: 201 (Created) + +## Project duplication settings + +You can customize various aspects of the project duplication process using the settings in the +request. The following sections describe the available options. + +### Export settings + +The `settings.export` object controls how the source project is exported: + +```json +"settings": { + "export": { + "projectObjectsPreference": { + "schemaObjectsOnly": false, + "skipEmptyProfileFolders": false + }, + "subscriptionPreferences": { + "includeUserSubscriptions": false, + "includeContactSubscriptions": false + }, + "configurationObjects": { + "rules": [ + { + "type": 34, + "rule": 2 + }, + { + "type": 5, + "rule": 1 + } + ], + "objects": [ + "95A868464F2F105205B2848BBCB81C50", + "4E70890241DBB18E6CA1D8B850952A68" + ], + "includeAllUserGroups": false + } + } +} +``` + +`settings.export.configurationObjects` is set for the export configuration objects (only used for cross environment project duplication). +`settings.export.configurationObjects.rules` is set for the rules to select which configuration objects to duplicate. Rules are used in combination with type, indicating which rule applies to a specific object type. + +`settings.export.configurationObjects.rules.rule` There are four types of rules: + +- 0 (none): Do not duplicate configuration objects of this type. + +- 1 (project-related): Duplicate only the configuration objects of this type that are related to the source project. + +- 2 (selected): Duplicate only the configuration objects of this type that are listed in the array `settings.export.configurationObjects.objects`. + +- 3 (all): Duplicate all configuration objects of this type. + +`settings.export.configurationObjects.rules.type` Currently, the object types for which rules can be applied are limited to two: 5 and 34. + +- 5 represents the default, which applies to all configuration objects. + +- 34 represents users. + +Rules set on type 34 have a higher priority than those set on the type 5 default. + +For example, if a user sets `settings.export.configurationObjects.rules.rule` to 3 (all) on `settings.export.configurationObjects.rules.type` to 34 and `settings.export.configurationObjects.rules.rule` to 1 (related) on `settings.export.configurationObjects.rules.type` to 5, the I-Server will duplicate all user objects and all other configuration objects related to the source project. + +To prevent broken objects after duplication, the `settings.export.configurationObjects.rules.type` 5 (default) only supports `settings.export.configurationObjects.rules.rule` 1 (project-related) and 3 (all). + +For example, if we set `settings.export.configurationObjects.rules.rule` to 0 (none) on `settings.export.configurationObjects.rules.type` to 34, and `settings.export.configurationObjects.includeAllUserGroups` to true, the I-Server will duplicate the complete user group structure but will not include any user objects. + +### Import settings + +The `settings.import` object controls how the project is imported to the target environment: + +```json +"settings": { + "import": { + "description": "Development copy of production project", + "defaultLocale": 2052, + "locales": [1033, 2052], + "configurationObjects": { + "conflictRules": [ + { + "type": 44, + "rule": 2 + }, + { + "type": 34, + "rule": 6 + }, + { + "type": 5, + "rule": 1 + }, + { + "type": 29, + "rule": 2 + } + ], + "matchUsersByLogin": false + } + } +} +``` + +`settings.import.configurationObjects` is set for the import configuration objects (only used for cross environment project duplication). +`settings.import.configurationObjects.matchUsersByLogin` matchUsersByLogin: This field determines how to handle cases where there are two user objects with the same login but different IDs in the source MD and target MD. + +If matchUsersByLogin is false: Both user objects are retained, and the login of the user object from the source MD is modified to avoid duplication. + +If matchUsersByLogin is true: The ID of the user object from the source MD is changed to match the user object in the target MD. Then, further processing is performed based on the configured conflict rule. + +`settings.import.configurationObjects.conflictRules` This field specifies which rule to apply when a conflict occurs during duplication for a specific type of configuration object. A conflict means there are configuration objects with the same ID and type in both the source MD (metadata) and the target MD. + +`settings.import.configurationObjects.conflictRules.rule` Currently, we support three conflict rules: + +- 1 (Use-existing): Ignore the object in the source MD and retain the object with the same ID in the target MD. + +- 2 (Replace): Overwrite the object in the target MD with the object from the source MD. + +- 6 (Merge): Applicable only to user and securityRole objects. If the merge rule is set for other types of objects, it will fall back to use-existing. + +`settings.import.configurationObjects.conflictRules.type` Currently, we support all [object types](https://www2.microstrategy.com/producthelp/Current/ReferenceFiles/reference/com/microstrategy/webapi/EnumDSSXMLObjectTypes.html). + +## Request fields reference + +The following table describes the fields available in the project duplication request: + +| Field | Type | Description | Required | +| --------------------------------------------------------------------- | ------- | -------------------------------------------------------------------------- | -------- | +| `source.environment.id` | String | URL of the source environment (must be identical to target.environment.id) | Yes | +| `source.environment.name` | String | Name of the source environment | Yes | +| `source.project.id` | String | ID of the source project | Yes | +| `source.project.name` | String | Name of the source project | Yes | +| `target.environment.id` | String | URL of the target environment (must be identical to source.environment.id) | Yes | +| `target.environment.name` | String | Name of the target environment | Yes | +| `target.project.name` | String | Name to assign to the duplicated project | Yes | +| `settings.import.description` | String | Description for the duplicated project | No | +| `settings.import.defaultLocale` | Number | Default locale ID for the duplicated project | No | +| `settings.import.locales` | Array | List of locale IDs to include in the duplicated project | No | +| `settings.import.configurationObjects` | Object | Configuration objects for the duplicated project | No | +| `settings.import.configurationObjects.matchUsersByLogin` | Boolean | Whether to match users by login | No | +| `settings.import.configurationObjects.conflictRules` | Array | Rules to resolve conflicts when importing configuration objects | No | +| `settings.import.configurationObjects.objects` | Array | List of configuration objects to import | No | +| `settings.import.configurationObjects.includeAllUserGroups` | Boolean | Whether to include all user groups | No | +| `settings.export.projectObjectsPreference.schemaObjectsOnly` | Boolean | Whether to include only schema objects | No | +| `settings.export.projectObjectsPreference.skipEmptyProfileFolders` | Boolean | Whether to skip empty profile folders | No | +| `settings.export.subscriptionPreferences.includeUserSubscriptions` | Boolean | Whether to include user subscriptions | No | +| `settings.export.subscriptionPreferences.includeContactSubscriptions` | Boolean | Whether to include contact subscriptions | No | +| `settings.export.configurationObjects` | Object | Configuration objects for the duplicated project | No | +| `settings.export.configurationObjects.rules` | Array | Rules to select which configuration objects to duplicate | No | +| `settings.export.configurationObjects.objects` | Array | List of configuration objects to duplicate | No | +| `settings.export.configurationObjects.includeAllUserGroups` | Boolean | Whether to include all user groups | No | + +## Response fields reference + +The following table describes the fields available in the project duplication response: + +| Field | Type | Description | +| -------------------- | ------ | ---------------------------------------------------------- | +| `id` | String | Unique identifier for the duplication operation | +| `source` | Object | Information about the source project and environment | +| `source.environment` | Object | Details about the source environment | +| `source.project` | Object | Details about the source project | +| `source.creator` | Object | Details about the user who created the source project | +| `target` | Object | Information about the target project and environment | +| `target.environment` | Object | Details about the target environment | +| `target.project` | Object | Details about the target project | +| `target.creator` | Object | Details about the user who created the target project | +| `createdDate` | String | ISO datetime when the duplication was initiated | +| `lastUpdatedDate` | String | ISO datetime when the duplication was last updated | +| `status` | String | Current status of the duplication operation | +| `progress` | Number | Completion percentage of the duplication operation (0-100) | +| `message` | String | Additional information or error message | +| `settings` | Object | Configuration settings used for the duplication operation | + +## Common errors and troubleshooting + +| HTTP Status | Error Code | Description | Resolution | +| ----------- | --------------------- | ---------------------------------- | ------------------------------------------------------------------------------- | +| 400 | INVALID_REQUEST | Request body is not valid | Check the request JSON format and required fields | +| 403 | FORBIDDEN | User lacks sufficient privileges | Ensure the user has administrator privileges on both source and target projects | +| 404 | PROJECT_NOT_FOUND | Source project not found | Verify the source project ID is correct | +| 409 | PROJECT_NAME_EXISTS | Target project name already exists | Choose a different name for the target project | +| 500 | INTERNAL_SERVER_ERROR | Internal server error occurred | Check server logs for details and retry the operation | + +## Best practices + +1. **Plan for downtime**: Project duplication operations can be resource-intensive. Schedule them + during off-peak hours if possible. + +1. **Use descriptive names**: Give your duplicated projects clear, descriptive names that indicate + their purpose (e.g., "Sales_Dev", "Marketing_Test"). + +1. **Monitor progress**: Large projects may take considerable time to duplicate. Use the status + field to monitor progress. + +1. **Testing**: Test the duplication process with a small project before attempting to duplicate + large, complex projects. diff --git a/docs/common-workflows/administration/project-duplication/project-duplication.md b/docs/common-workflows/administration/project-duplication/project-duplication.md index 8a7c2354..6fac87cd 100644 --- a/docs/common-workflows/administration/project-duplication/project-duplication.md +++ b/docs/common-workflows/administration/project-duplication/project-duplication.md @@ -1,18 +1,25 @@ --- -sidebar_label: Project Duplication -title: Project Duplication +sidebar_label: Project Duplication (Same Environment) +title: Project Duplication (Same Environment) description: The REST API provides endpoints to duplicate projects within same environment, enabling administrators to create copies of projects with customizable settings. --- 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. +:::warning + +These project duplication APIs do not work when [User Fencing](https://www2.microstrategy.com/producthelp/current/SystemAdmin/WebHelp/Lang_1033/content/Work_Fences.htm) is enabled. Please ensure that User Fencing is disabled in the Library. + +::: + ## APIs - [POST /api/projectDuplications](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Project%20Duplications/createDuplication) - [GET /api/projectDuplications/\{id}](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Project%20Duplications/getProjectDuplication) - [GET /api/projectDuplications](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Project%20Duplications/getProjectDuplications) - [PUT /api/projectDuplications/\{id}/status](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Project%20Duplications/cancelDuplication) +- [DELETE /api/projectDuplications/\{id}](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Project%20Duplications/deleteDuplication) ## Privileges and authorization @@ -498,14 +505,13 @@ The following table describes the fields available in the project duplication re ## Common errors and troubleshooting -| HTTP Status | Error Code | Description | Resolution | -| ----------- | ---------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------- | -| 400 | DIFFERENT_ENVIRONMENTS | Source and target environments are not the same | Ensure source.environment.id and target.environment.id are identical | -| 400 | INVALID_REQUEST | Request body is not valid | Check the request JSON format and required fields | -| 403 | FORBIDDEN | User lacks sufficient privileges | Ensure the user has administrator privileges on both source and target projects | -| 404 | PROJECT_NOT_FOUND | Source project not found | Verify the source project ID is correct | -| 409 | PROJECT_NAME_EXISTS | Target project name already exists | Choose a different name for the target project | -| 500 | INTERNAL_SERVER_ERROR | Internal server error occurred | Check server logs for details and retry the operation | +| HTTP Status | Error Code | Description | Resolution | +| ----------- | --------------------- | ---------------------------------- | ------------------------------------------------------------------------------- | +| 400 | INVALID_REQUEST | Request body is not valid | Check the request JSON format and required fields | +| 403 | FORBIDDEN | User lacks sufficient privileges | Ensure the user has administrator privileges on both source and target projects | +| 404 | PROJECT_NOT_FOUND | Source project not found | Verify the source project ID is correct | +| 409 | PROJECT_NAME_EXISTS | Target project name already exists | Choose a different name for the target project | +| 500 | INTERNAL_SERVER_ERROR | Internal server error occurred | Check server logs for details and retry the operation | ## Best practices diff --git a/docs/common-workflows/analytics/auto-bot-api/auto-bot-api.md b/docs/common-workflows/analytics/auto-bot-api/auto-bot-api.md index 712de78b..8ca1777d 100644 --- a/docs/common-workflows/analytics/auto-bot-api/auto-bot-api.md +++ b/docs/common-workflows/analytics/auto-bot-api/auto-bot-api.md @@ -18,6 +18,7 @@ Starting from Strategy ONE (June 2025), we've added support for retrieving image - **Get chat history from a specific bot**: Obtain all historical chat messages from a specific bot. - **Get suggested questions from a specific bot**: Get recommended questions based on the context from a specific bot. - **Image support in answers**: Request and retrieve images as part of answers from Next-Gen AI, with customizable resolution settings. (Available from Strategy ONE (June 2025)) +- **Get attributes and metrics from a specific bot**: Fetch the column information (attributes and metrics) from a specific bot, which can be used for auto-complete functionality in user inputs. (Available from Strategy ONE (July 2025)) For further details on how to use these APIs, please refer to the following sections of this manual: @@ -26,3 +27,4 @@ For further details on how to use these APIs, please refer to the following sect - [Get chat history from a specific bot](./get-questions-by-bot.md) - [Get suggested questions from a specific bot](./post-suggestion.md) - [Get image from an answer](./get-image-of-answer.md) +- [Get attributes and metrics from a specific bot](./get-columns.md) diff --git a/docs/common-workflows/analytics/auto-bot-api/get-columns.md b/docs/common-workflows/analytics/auto-bot-api/get-columns.md new file mode 100644 index 00000000..ca496811 --- /dev/null +++ b/docs/common-workflows/analytics/auto-bot-api/get-columns.md @@ -0,0 +1,66 @@ +--- +title: Get attributes forms and metrics from a specific bot +description: This page describes how to fetch the column information (attributes and metrics) from a specific bot. +--- + + + +This API is used to get the column information (attributes forms and metrics) from a specific bot. This information is essential for understanding what data elements the bot can access and use in its answers. The column information can be used to provide auto-complete functionality for user inputs, helping users formulate more accurate questions by suggesting relevant data elements as they type. + +:::info + +Obtain the authorization token needed to execute the request using [POST /api/auth/login](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Authentication/postLogin). + +::: + +## Get attributes forms and metrics from a specific bot + +Endpoint: [GET /api/v2/bots/\{botId}/columns](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Next-Gen%20AI/getBotColumns) + +Request Parameters: + +| Name | Located in | Description | Required | Type | +| ---------------- | ---------- | -------------------- | -------- | ------ | +| botId | path | ID of the bot | Yes | string | +| X-MSTR-AuthToken | header | Authentication token | Yes | string | +| X-MSTR-ProjectID | header | Project ID | Yes | string | + +Sample Curl: + +```bash +# Replace with your actual values +curl 'GET https://demo.microstrategy.com/MicroStrategyLibrary/api/v2/bots/4B7EF8B549D2D32E941C3E9B7E0CD754/columns' \ +-H 'X-MSTR-AuthToken: pqu5mkrcbv4461hh5qprr9j5ve' \ +-H 'X-MSTR-ProjectID: B7CA92F04B9FAE8D941C3E9B7E0CD754' \ +-H 'Content-Type: application/json' +``` + +Sample Response: + +```json +{ + "id": "8D679D4B11D3E4981000E787EC6DE8A4", + "columns": ["Customer(ID)", "Customer(Name)", "Revenue"] +} +``` + +Notes: + +- This API is useful for understanding the data elements that a bot has access to. +- Column information is essential for developers who want to build integrations that utilize specific data from bots. + +## Use Cases + +Auto-Complete Functionality: + +One of the main purposes of this API is to enable auto-complete functionality for user input: + +1. When a user starts typing a question to the bot, your application can retrieve column information to suggest relevant attributes and metrics. +1. As the user types, match their input against column names and descriptions to provide real-time suggestions. +1. This improves user experience by helping users formulate better questions and increases the accuracy of bot responses by ensuring users reference valid data elements. + +Example implementation: + +- Cache the column information at application startup or when a bot is selected +- Implement a suggestion engine that matches partial user input against attribute and metric names +- Display matching columns as suggestions, possibly with their descriptions for additional context diff --git a/docs/common-workflows/analytics/auto-bot-api/get-question-by-id.md b/docs/common-workflows/analytics/auto-bot-api/get-question-by-id.md index 911e0d70..1789c891 100644 --- a/docs/common-workflows/analytics/auto-bot-api/get-question-by-id.md +++ b/docs/common-workflows/analytics/auto-bot-api/get-question-by-id.md @@ -56,7 +56,7 @@ If the question is being processed, the response is: ```json { "id": "9161386651E84054A6230796C84E12C5:68696ADB633946B4B430ABD959433B3B:FCC1C28296014AB19ABD877E60590890", - "text": "Analyze the distribution of cooking times for recipes", + "text": "What was the Number of Flights for AirTran Airways Corporation in July 2010?", "answers": [], "creationDate": "2024-03-08T09:01:43.154+0000" } @@ -69,11 +69,12 @@ If the status code is 200, indicating that the question has been answered. ```json { "id": "9161386651E84054A6230796C84E12C5:68696ADB633946B4B430ABD959433B3B:FCC1C28296014AB19ABD877E60590890", - "text": "Analyze the distribution of cooking times for recipes", + "text": "What was the Number of Flights for AirTran Airways Corporation in July 2010?", "answers": [ { "bot": { "id": "68696ADB633946B4B430ABD959433B3B" }, - "text": "#Title 1\nThe distribution of cooking times for recipes is as follows:\n- The shortest cooking time is -1 minute.\n- The majority of recipes have cooking times ranging from 2 to 60 minutes.\n- There are a few recipes with longer cooking times, such as 75, 90, 120, and 720 minutes.\n- The exact distribution of cooking times can be seen in the visualization result.", + "text": "**The Number of Flights for AirTran Airways Corporation in July 2010 was 2260.**", + "insights": "- \uD83D\uDE0A **July is often a peak travel month, so seeing a high number of flights is typical for airlines during this period.**\n- ✈️ **A total of 2260 flights in one month indicates strong operational capacity and demand for AirTran Airways Corporation at that time.**\n- \uD83D\uDCC8 **Tracking monthly flight numbers can help identify seasonal trends and inform future scheduling or marketing strategies.**", "images": [{ "id": "79FD176AEAD9446395B083B5931E9EC7", "width": 800, "height": 600 }], "route": "sql" } diff --git a/docs/whats-new.md b/docs/whats-new.md index f31bb7b8..d3e37eca 100644 --- a/docs/whats-new.md +++ b/docs/whats-new.md @@ -4,6 +4,11 @@ sidebar_label: What's new Description: What's New in the REST API. --- +## Strategy ONE (July 2025) + +- [Project duplication across environments](common-workflows/administration/project-duplication/cross-env-project-duplication.md). Duplicate a project across two environments. +- [Get attributes forms and metrics from a specific bot](common-workflows/analytics/auto-bot-api/get-columns.md). Fetch the column information (attributes and metrics) from a specific bot, which can be used for auto-complete functionality in user inputs. + ## Strategy ONE (June 2025) - [Next-Gen AI Image Support](common-workflows/analytics/auto-bot-api/auto-bot-api.md). Request and retrieve images in answer from Next-Gen AI. diff --git a/sidebars.js b/sidebars.js index 98b1eef7..a458ed74 100644 --- a/sidebars.js +++ b/sidebars.js @@ -423,6 +423,7 @@ const sidebars = { "common-workflows/analytics/auto-bot-api/get-questions-by-bot", "common-workflows/analytics/auto-bot-api/post-suggestion", "common-workflows/analytics/auto-bot-api/get-image-of-answer", + "common-workflows/analytics/auto-bot-api/get-columns", ], }, { @@ -1079,7 +1080,10 @@ const sidebars = { id: "common-workflows/administration/project-duplication/project-duplication", }, label: "Project Duplication", - items: ["common-workflows/administration/project-duplication/project-duplication"], + items: [ + "common-workflows/administration/project-duplication/project-duplication", + "common-workflows/administration/project-duplication/cross-env-project-duplication", + ], }, ], }, From df85eee90344edce13fe4851045cc34880e9389b Mon Sep 17 00:00:00 2001 From: zhe Date: Mon, 18 Aug 2025 16:45:58 +0800 Subject: [PATCH 4/4] Update --- .../manage-data-model-attribute-objects.md | 20 + ...ve-an-attributes-elements-in-data-model.md | 70 ++ .../manage-data-model-object-acl.md | 21 + .../retrieve-a-data-model-object-acl.md | 85 +++ .../update-a-data-model-object-acl.md | 113 +++ ...-a-security-filter-object-in-data-model.md | 151 ++++ ...-a-security-filter-object-in-data-model.md | 56 ++ ...nage-data-model-security-filter-objects.md | 26 + ...a-security-filters-member-in-data-model.md | 96 +++ ...ecurity-filter-definition-in-data-model.md | 288 ++++++++ ...a-security-filters-member-in-data-model.md | 77 ++ ...ieve-all-security-filters-in-data-model.md | 186 +++++ ...-a-security-filter-object-in-data-model.md | 139 ++++ docs/common-workflows/mosaic/mosaic.md | 8 + .../publish/manage-data-model-publish.md | 19 + .../mosaic/publish/refresh-a-data-model.md | 304 ++++++++ .../publish/schedule-refresh-a-data-model.md | 673 ++++++++++++++++++ docs/whats-new.md | 15 + sidebars.js | 62 ++ 19 files changed, 2409 insertions(+) create mode 100644 docs/common-workflows/mosaic/manage-data-model-attribute-objects/manage-data-model-attribute-objects.md create mode 100644 docs/common-workflows/mosaic/manage-data-model-attribute-objects/retrieve-an-attributes-elements-in-data-model.md create mode 100644 docs/common-workflows/mosaic/manage-data-model-object-acl/manage-data-model-object-acl.md create mode 100644 docs/common-workflows/mosaic/manage-data-model-object-acl/retrieve-a-data-model-object-acl.md create mode 100644 docs/common-workflows/mosaic/manage-data-model-object-acl/update-a-data-model-object-acl.md create mode 100644 docs/common-workflows/mosaic/manage-data-model-security-filter-objects/create-a-security-filter-object-in-data-model.md create mode 100644 docs/common-workflows/mosaic/manage-data-model-security-filter-objects/delete-a-security-filter-object-in-data-model.md create mode 100644 docs/common-workflows/mosaic/manage-data-model-security-filter-objects/manage-data-model-security-filter-objects.md create mode 100644 docs/common-workflows/mosaic/manage-data-model-security-filter-objects/modify-a-security-filters-member-in-data-model.md create mode 100644 docs/common-workflows/mosaic/manage-data-model-security-filter-objects/retrieve-a-security-filter-definition-in-data-model.md create mode 100644 docs/common-workflows/mosaic/manage-data-model-security-filter-objects/retrieve-a-security-filters-member-in-data-model.md create mode 100644 docs/common-workflows/mosaic/manage-data-model-security-filter-objects/retrieve-all-security-filters-in-data-model.md create mode 100644 docs/common-workflows/mosaic/manage-data-model-security-filter-objects/update-a-security-filter-object-in-data-model.md create mode 100644 docs/common-workflows/mosaic/mosaic.md create mode 100644 docs/common-workflows/mosaic/publish/manage-data-model-publish.md create mode 100644 docs/common-workflows/mosaic/publish/refresh-a-data-model.md create mode 100644 docs/common-workflows/mosaic/publish/schedule-refresh-a-data-model.md diff --git a/docs/common-workflows/mosaic/manage-data-model-attribute-objects/manage-data-model-attribute-objects.md b/docs/common-workflows/mosaic/manage-data-model-attribute-objects/manage-data-model-attribute-objects.md new file mode 100644 index 00000000..a61159fa --- /dev/null +++ b/docs/common-workflows/mosaic/manage-data-model-attribute-objects/manage-data-model-attribute-objects.md @@ -0,0 +1,20 @@ +--- +title: Manage data model attribute objects +description: You can use REST API requests to retrieve an attribute's elements in data model. +--- + + + +:::tip + +You can try these workflows with [REST API Playground](https://www.postman.com/microstrategysdk/microstrategy-rest-api/collection/5aq5sem/strategy-rest-api-workflows). + +Learn more about Strategy REST API Playground [here](/docs/getting-started/playground.md). + +::: + +You can use REST API requests to retrieve an attribute's elements in data model: + +- [Retrieve an Attribute's Elements in Data Model](retrieve-an-attributes-elements-in-data-model.md) + +For more information about the Modeling service, see [Configuring the Modeling Service](https://www2.microstrategy.com/producthelp/Current/InstallConfig/en-us/Content/modeling_service.htm). diff --git a/docs/common-workflows/mosaic/manage-data-model-attribute-objects/retrieve-an-attributes-elements-in-data-model.md b/docs/common-workflows/mosaic/manage-data-model-attribute-objects/retrieve-an-attributes-elements-in-data-model.md new file mode 100644 index 00000000..6eceaa65 --- /dev/null +++ b/docs/common-workflows/mosaic/manage-data-model-attribute-objects/retrieve-an-attributes-elements-in-data-model.md @@ -0,0 +1,70 @@ +--- +title: Retrieve an attribute's elements in data model +sidebar_label: Retrieve an attribute's elements in data model +description: This workflow sample demonstrates how to retrieve an attribute's elements in data model. +--- + + + +:::tip + +You can try these workflows with [REST API Playground](https://www.postman.com/microstrategysdk/microstrategy-rest-api/collection/5aq5sem/strategy-rest-api-workflows). + +Learn more about Strategy REST API Playground [here](/docs/getting-started/playground.md). + +::: + +This workflow sample demonstrates how to retrieve an attribute's elements in data model. + +:::info + +Get the authorization token needed to execute the request with [POST /api/auth/login](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Authentication/postLogin). + +Get the project ID from [GET /api/projects](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Projects/getProjects_1). + +::: + +Retrieve the attribute's elements using `GET /api/dataModels/{dataModelId}/attributes/{id}/elements`. + +Sample Request Header: + +```http +"accept": "application/json" +"X-MSTR-AuthToken": "4bb7n1dhjo860e7tlpchg57hl" +"X-MSTR-ProjectID": "B7CA92F04B9FAE8D941C3E9B7E0CD754" +``` + +Sample Request Body: Empty + +Sample Curl: + +```bash +curl -X GET "https://demo.microstrategy.com/MicroStrategyLibrary/api/dataModels/7F071F619BE244C7B6CDC2626EBB1C6C/attributes/8D679D5111D3E4981000E787EC6DE8A4/elements" -H "accept: application/json" -H "X-MSTR-AuthToken: 4bb7n1dhjo860e7tlpchg57hl" -H "X-MSTR-ProjectID: B7CA92F04B9FAE8D941C3E9B7E0CD754" +``` + +Sample Response Body: + +You can view the data model's attribute's elements in the response body. + +```json +[ + { + "name": "2015", + "id": "h2015;;2015" + }, + { + "name": "2016", + "id": "h2016;;2016" + }, + { + "name": "2017", + "id": "h2017;;2017" + }, + { + "name": "2018", + "id": "h2018;;2018" + } +] +``` + +Response Code 200: (The attribute's elements is returned successfully.) diff --git a/docs/common-workflows/mosaic/manage-data-model-object-acl/manage-data-model-object-acl.md b/docs/common-workflows/mosaic/manage-data-model-object-acl/manage-data-model-object-acl.md new file mode 100644 index 00000000..84c42a9e --- /dev/null +++ b/docs/common-workflows/mosaic/manage-data-model-object-acl/manage-data-model-object-acl.md @@ -0,0 +1,21 @@ +--- +title: Manage data model object acl +description: You can use REST API requests to retrieve and update acl of objects in data model through the Modeling service. +--- + + + +:::tip + +You can try these workflows with [REST API Playground](https://www.postman.com/microstrategysdk/microstrategy-rest-api/collection/5aq5sem/strategy-rest-api-workflows). + +Learn more about Strategy REST API Playground [here](/docs/getting-started/playground.md). + +::: + +You can use REST API requests to retrieve and update acl of objects in data model through the Modeling service. + +- [Get ACL of an object in a Data Model](retrieve-a-data-model-object-acl.md) +- [Update ACL of an object in a Data Model](update-a-data-model-object-acl.md) + +For more information about the Modeling service, see [Configuring the Modeling Service](https://www2.microstrategy.com/producthelp/Current/InstallConfig/en-us/Content/modeling_service.htm). diff --git a/docs/common-workflows/mosaic/manage-data-model-object-acl/retrieve-a-data-model-object-acl.md b/docs/common-workflows/mosaic/manage-data-model-object-acl/retrieve-a-data-model-object-acl.md new file mode 100644 index 00000000..908a3b91 --- /dev/null +++ b/docs/common-workflows/mosaic/manage-data-model-object-acl/retrieve-a-data-model-object-acl.md @@ -0,0 +1,85 @@ +--- +title: Retrieve acl of an object inside a data model +description: You can use REST API requests to retrieve acl of an object inside a data model. +--- + + + +:::tip + +You can try out this workflow at [REST API Playground](https://www.postman.com/microstrategysdk/microstrategy-rest-api/collection/5aq5sem/strategy-rest-api-workflows). + +Learn more about Strategy REST API Playground [here](/docs/getting-started/playground.md). + +::: + +You can use REST APIs to retrieve the acl of an object inside a data model through the Modeling service. + +## Retrieve acl of an attribute inside a data model + +There is a "Customer Statistics" data model with an "A44F79895E9247719292556AA14373F5" ID. This data model contains a "Customer" attribute with an "B9E7FD5911D3E936C000B3B2D86C964F" ID. +You want to get the acl of the "Customer" attribute. + +:::info + +To get the authorization token needed to execute the request, use `POST /api/auth/login`. + +Get the project ID from `GET /api/projects`. + +::: + +:::tip + +Changesets are used in this workflow. For information on how to create and use changesets, see [Changesets](/docs/common-workflows/modeling/changesets.md). + +::: + +To get the acl of the object in your data model, use [GET /api/model/dataModels/\{dataModelId}/objects/\{objectId}/acl](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Data%20Models/getDataModelObjectAcl). + +Sample Request Header + +```http +"accept": "application/json" +"X-MSTR-AuthToken": "pisu5dkkutqfblaamdomgr00ch" +"X-MSTR-MS-Changeset": "0E9F01172ECF4BA2BB510F7B9FB4F6E8" +``` + +Sample Request Body: Empty + +Sample Curl: + +```bash +curl -X GET "https://demo.microstrategy.com/MicroStrategyLibrary/api/dataModels/A44F79895E9247719292556AA14373F5/objects/B9E7FD5911D3E936C000B3B2D86C964F/acl?subType=attribute" -H "accept: application/json" -H "X-MSTR-AuthToken: pisu5dkkutqfblaamdomgr00ch" -H "X-MSTR-MS-Changeset: 0E9F01172ECF4BA2BB510F7B9FB4F6E8" +``` + +Sample Response Body: + +```json +{ + "acl": { + "294DEDC011D2F1D56000D98E67019608": { + "granted": 255, + "denied": 0, + "inheritable": false, + "name": "Public / Guest", + "subType": "user_group" + }, + "C82C6B1011D2894CC0009D9F29718E4F": { + "granted": 45, + "denied": 16, + "inheritable": false, + "name": "Everyone", + "subType": "user_group" + }, + "D5ABCBF54937420EC3377FA23857A4DC": { + "granted": 255, + "denied": 0, + "inheritable": false, + "name": "F40308_automodel", + "subType": "user" + } + } +} +``` + +Response Code: 200 diff --git a/docs/common-workflows/mosaic/manage-data-model-object-acl/update-a-data-model-object-acl.md b/docs/common-workflows/mosaic/manage-data-model-object-acl/update-a-data-model-object-acl.md new file mode 100644 index 00000000..16041283 --- /dev/null +++ b/docs/common-workflows/mosaic/manage-data-model-object-acl/update-a-data-model-object-acl.md @@ -0,0 +1,113 @@ +--- +title: Update acl of an object inside a data model +description: You can use REST API requests to update acl of an object inside a data model. +--- + + + +:::tip + +You can try out this workflow at [REST API Playground](https://www.postman.com/microstrategysdk/microstrategy-rest-api/collection/5aq5sem/strategy-rest-api-workflows). + +Learn more about Strategy REST API Playground [here](/docs/getting-started/playground.md). + +::: + +You can use REST APIs to update the acl of an object inside a data model through the Modeling service. + +## Update acl of a metric inside a data model + +There is a "Customer Statistics" data model with an "A44F79895E9247719292556AA14373F5" ID. This data model contains a "Sales" metric with an "B9E7FD5911D3E936C000B3B2D86C964F" ID. +You want to update the acl of the "Sales" metric. + +:::info + +To get the authorization token needed to execute the request, use `POST /api/auth/login`. + +Get the project ID from `GET /api/projects`. + +::: + +:::tip + +Changesets are used in this workflow. For information on how to create and use changesets, see [Changesets](/docs/common-workflows/modeling/changesets.md). + +::: + +To update the acl of the object in your data model, use [PATCH /api/model/dataModels/\{dataModelId}/objects/\{objectId}/acl](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Data%20Models/updateDataModelObjectAcl). + +Sample Request Header + +```http +"accept": "application/json" +"X-MSTR-AuthToken": "pisu5dkkutqfblaamdomgr00ch" +"X-MSTR-MS-Changeset": "0E9F01172ECF4BA2BB510F7B9FB4F6E8" +``` + +Sample Request Body: + +```json +{ + "acl": { + "294DEDC011D2F1D56000D98E67019608": { + "granted": 255, + "denied": 0, + "inheritable": false, + "name": "Public / Guest", + "subType": "user_group" + }, + "C82C6B1011D2894CC0009D9F29718E4F": { + "granted": 45, + "denied": 16, + "inheritable": false, + "name": "Everyone", + "subType": "user_group" + }, + "D5ABCBF54937420EC3377FA23857A4DC": { + "granted": 255, + "denied": 0, + "inheritable": false, + "name": "F40308_automodel", + "subType": "user" + } + } +} +``` + +Sample Curl: + +```bash +curl -X PATCH "https://demo.microstrategy.com/MicroStrategyLibrary/api/dataModels/A44F79895E9247719292556AA14373F5/objects/B9E7FD5911D3E936C000B3B2D86C964F/acl?subType=metric" -H "accept: application/json" -H "X-MSTR-AuthToken: pisu5dkkutqfblaamdomgr00ch" -H "X-MSTR-MS-Changeset: 0E9F01172ECF4BA2BB510F7B9FB4F6E8" -d '{"acl":{"294DEDC011D2F1D56000D98E67019608":{"granted":255,"denied":0,"inheritable":false,"name":"Public / Guest","subType":"user_group"},"C82C6B1011D2894CC0009D9F29718E4F":{"granted":45,"denied":16,"inheritable":false,"name":"Everyone","subType":"user_group"},"D5ABCBF54937420EC3377FA23857A4DC":{"granted":255,"denied":0,"inheritable":false,"name":"F40308_automodel","subType":"user"}}}' +``` + +Sample Response Body: + +```json +{ + "acl": { + "294DEDC011D2F1D56000D98E67019608": { + "granted": 255, + "denied": 0, + "inheritable": false, + "name": "Public / Guest", + "subType": "user_group" + }, + "C82C6B1011D2894CC0009D9F29718E4F": { + "granted": 45, + "denied": 16, + "inheritable": false, + "name": "Everyone", + "subType": "user_group" + }, + "D5ABCBF54937420EC3377FA23857A4DC": { + "granted": 255, + "denied": 0, + "inheritable": false, + "name": "F40308_automodel", + "subType": "user" + } + } +} +``` + +Response Code: 200 diff --git a/docs/common-workflows/mosaic/manage-data-model-security-filter-objects/create-a-security-filter-object-in-data-model.md b/docs/common-workflows/mosaic/manage-data-model-security-filter-objects/create-a-security-filter-object-in-data-model.md new file mode 100644 index 00000000..2a59334b --- /dev/null +++ b/docs/common-workflows/mosaic/manage-data-model-security-filter-objects/create-a-security-filter-object-in-data-model.md @@ -0,0 +1,151 @@ +--- +title: Create a security filter object in data model +sidebar_label: Create a security filter object in data model +description: This workflow sample demonstrates how to create a security filter object in data model through the Modeling service. +--- + + + +:::tip + +You can try these workflows with [REST API Playground](https://www.postman.com/microstrategysdk/microstrategy-rest-api/collection/5aq5sem/strategy-rest-api-workflows). + +Learn more about Strategy REST API Playground [here](/docs/getting-started/playground.md). + +::: + +This workflow sample demonstrates how to create a security filter object in data model through the Modeling service. + +1. Create a changeset. +1. [Create a security filter in data model.](#create-a-security-filter-in-data-model) +1. Commit a changeset. +1. Delete the changeset. + +In this workflow sample, you want to create a "Year > 2015" security filter object in data model in the MicroStrategy Tutorial project. The data model ID is `7F071F619BE244C7B6CDC2626EBB1C6C`. The MicroStrategy Tutorial project ID is `B7CA92F04B9FAE8D941C3E9B7E0CD754`. + +:::info + +Get the authorization token needed to execute the request with [POST /api/auth/login](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Authentication/postLogin). + +Get the project ID from [GET /api/projects](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Projects/getProjects_1). + +::: + +Changesets are used in this workflow. For information on how to create and use changesets, see [Changesets](/docs/common-workflows/modeling/changesets.md). + +## Create a security filter in data model + +Use [POST /api/model/dataModels/7F071F619BE244C7B6CDC2626EBB1C6C/securityFilters](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Data%20Model/ms-postDataModelSecurityFilter) with `"tree"` format for the `"qualifications"`. For more examples of creating a new security filter, see [Security Filters](/docs/common-workflows/modeling/manage-security-filter-objects/create-a-security-filter-object.md) section. + +To create a security filter, in the request body, the security filter’s "qualification" must be in either "tree" or "tokens" format. If you add both formats, only "tree" is used. + +If you create an attribute element list qualification, only the “tree“ format is supported. + +If you create a qualification with inline custom expressions, only the "tree" format is supported. + +Any embedded objects (`"isEmbedded":true"`) cannot be used to create a new security filter. Any attributes outside the data model cannot be used to create a new security filter. + +Sample Request Header: + +```http +"accept": "application/json" +"X-MSTR-AuthToken": "ns42kvi9lb36ae7g3scphn0ga9" +"X-MSTR-MS-Changeset": "8DF1659E9D74484D9D47B9478D4C7D00" +``` + +Sample Request Body: + +```json +{ + "information": { + "subType": "md_security_filter", + "name": "Year > 2015" + }, + "qualification": { + "tree": { + "type": "predicate_form_qualification", + "predicateTree": { + "function": "greater", + "parameters": [ + { + "parameterType": "constant", + "constant": { + "type": "double", + "value": "2015.0" + } + } + ], + "attribute": { + "objectId": "8D679D5111D3E4981000E787EC6DE8A4", + "subType": "attribute", + "name": "Year" + }, + "form": { + "objectId": "45C11FA478E745FEA08D781CEA190FE5", + "subType": "attribute_form_system", + "name": "ID" + } + } + } + }, + "topLevel": [], + "bottomLevel": [] +} +``` + +Sample Curl: + +```bash +curl -X POST "https://demo.microstrategy.com/MicroStrategyLibrary/api/model/dataModels/7F071F619BE244C7B6CDC2626EBB1C6C/securityFilters" -H "accept: application/json" -H "X-MSTR-AuthToken: ns42kvi9lb36ae7g3scphn0ga9" -H "X-MSTR-MS-Changeset: 8DF1659E9D74484D9D47B9478D4C7D00" -H "Content-Type: application/json" -d '{"information":{"subType":"filter","name":"Year > 2015","destinationFolderId":"98FE182C2A10427EACE0CD30B6768258"},"qualification":{"tree":{"type":"predicate_form_qualification","predicateTree":{"function":"greater","parameters":[{"parameterType":"constant","constant":{"type":"double","value":"2015.0"}}],"attribute":{"objectId":"8D679D5111D3E4981000E787EC6DE8A4","subType":"attribute","name":"Year"},"form":{"objectId":"45C11FA478E745FEA08D781CEA190FE5","subType":"attribute_form_system","name":"ID"}}}}}' +``` + +Sample Response Body: + +You can view the new filter's definition in the response body. + +```json +{ + "information": { + "versionId": "88DF4A68957941EBBBC69B975B2D011F", + "primaryLocale": "en-US", + "objectId": "8981A1EB828F4888959C0C0A435870CC", + "subType": "md_security_filter", + "name": "Year > 2015", + "destinationFolderId": "EE9BD70043F0F571B38E43BF19B9301A" + }, + "qualification": { + "text": "Year (ID) > 2015", + "tree": { + "type": "predicate_form_qualification", + "predicateId": "43F6594B23BF4510A090F5AB3C44358F", + "predicateText": "Year (ID) > 2015", + "predicateTree": { + "function": "greater", + "parameters": [ + { + "parameterType": "constant", + "constant": { + "type": "double", + "value": "2015.0" + } + } + ], + "attribute": { + "objectId": "8D679D5111D3E4981000E787EC6DE8A4", + "subType": "attribute", + "name": "Year" + }, + "form": { + "objectId": "45C11FA478E745FEA08D781CEA190FE5", + "subType": "attribute_form_system", + "name": "ID" + } + } + } + }, + "topLevel": [], + "bottomLevel": [] +} +``` + +Response Code: 201 (A new data model security filter is created successfully in the changeset.) diff --git a/docs/common-workflows/mosaic/manage-data-model-security-filter-objects/delete-a-security-filter-object-in-data-model.md b/docs/common-workflows/mosaic/manage-data-model-security-filter-objects/delete-a-security-filter-object-in-data-model.md new file mode 100644 index 00000000..c1713a91 --- /dev/null +++ b/docs/common-workflows/mosaic/manage-data-model-security-filter-objects/delete-a-security-filter-object-in-data-model.md @@ -0,0 +1,56 @@ +--- +title: Delete a security filter definition in data model +sidebar_label: Delete a security filter definition in data model +description: This workflow sample demonstrates how to delete a security filter object in data model through the Modeling service. +--- + + + +:::tip + +You can try these workflows with [REST API Playground](https://www.postman.com/microstrategysdk/microstrategy-rest-api/collection/5aq5sem/strategy-rest-api-workflows). + +Learn more about Strategy REST API Playground [here](/docs/getting-started/playground.md). + +::: + +This workflow sample demonstrates how to delete a security filter object in a data model using the Modeling service. + +1. Create a changeset using `POST /api/model/changesets` +1. [Delete the security filter in data model using `DELETE /api/model/dataModels/{dataModelId}/securityFilters/{securityFilterId}`](#delete-the-security-filter-in-data-model-using-delete-apimodeldatamodelsdatamodelidsecurityfilterssecurityfilterid) +1. Commit the changeset using `POST /api/model/changesets/{changesetId}/commit`](#3-commit-the-changeset-using-post-apimodelchangesetschangesetidcommit) +1. Delete the changeset using `DELETE /api/model/changesets/{changesetId}` + +In this workflow sample, you want to delete the `"Year > 2015"` security filter object in data model in the MicroStrategy Tutorial project. The data model ID is `7F071F619BE244C7B6CDC2626EBB1C6C`. The object ID of the security filter is `8981A1EB828F4888959C0C0A435870CC`. + +:::info + +To get the authorization token needed to execute the request, use [POST /api/auth/login](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Authentication/postLogin). + +Get the project ID from [GET /api/projects](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Projects/getProjects_1). + +::: + +Changesets are used in this workflow. For information on how to create and use changesets, see [Changesets](/docs/common-workflows/modeling/changesets.md). + +## Delete the security filter in data model using [DELETE /api/model/dataModels/\{dataModelId}/securityFilters/\{securityFilterId}](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Data%20Model/ms-deleteDataModelSecurityFilter) + +Sample Request Header: + +```http +"accept": "application/json" +"X-MSTR-AuthToken": "frbicqfk7btoggg5bnu450hrqt" +"X-MSTR-MS-Changeset": "C4F6B0E4C87F46EF9B6C5690DFFF87C1" +``` + +Sample Request Body: Empty + +Sample Curl: + +```bash +curl -X DELETE "https://demo.microstrategy.com/MicroStrategyLibrary/api/model/dataModels/7F071F619BE244C7B6CDC2626EBB1C6C/securityFilters/8981A1EB828F4888959C0C0A435870CC" -H "accept: application/json" -H "X-MSTR-AuthToken: pisu5dkkutqfblaamdomgr00ch" -H "X-MSTR-MS-Changeset: C4F6B0E4C87F46EF9B6C5690DFFF87C1" +``` + +Sample Response Body: Empty + +Sample Response Code: 204 (The security filter has been deleted successfully from the data model.) diff --git a/docs/common-workflows/mosaic/manage-data-model-security-filter-objects/manage-data-model-security-filter-objects.md b/docs/common-workflows/mosaic/manage-data-model-security-filter-objects/manage-data-model-security-filter-objects.md new file mode 100644 index 00000000..2dac4d3f --- /dev/null +++ b/docs/common-workflows/mosaic/manage-data-model-security-filter-objects/manage-data-model-security-filter-objects.md @@ -0,0 +1,26 @@ +--- +title: Manage data model security filter objects +description: You can use REST API requests to retrieve, create and update security filter objects in data model through the Modeling service. +--- + + + +:::tip + +You can try these workflows with [REST API Playground](https://www.postman.com/microstrategysdk/microstrategy-rest-api/collection/5aq5sem/strategy-rest-api-workflows). + +Learn more about Strategy REST API Playground [here](/docs/getting-started/playground.md). + +::: + +You can use REST API requests to retrieve, create, and update security filter objects through the Modeling service: + +- [Create a Security Filter Object in Data Model](create-a-security-filter-object-in-data-model.md) +- [Update a Security Filter Object in Data Model](update-a-security-filter-object-in-data-model.md) +- [Retrieve a Security Filter Definition in Data Model](retrieve-a-security-filter-definition-in-data-model.md) +- [Retrieve all Security Filters in Data Model](retrieve-all-security-filters-in-data-model.md) +- [Retrieve a Security Filter's Member in Data Model](retrieve-a-security-filters-member-in-data-model.md) +- [Modify a Security Filter's Member in Data Model](modify-a-security-filters-member-in-data-model.md) +- [Delete a Security Filter Object in Data Model](delete-a-security-filter-object-in-data-model.md) + +For more information about the Modeling service, see [Configuring the Modeling Service](https://www2.microstrategy.com/producthelp/Current/InstallConfig/en-us/Content/modeling_service.htm). diff --git a/docs/common-workflows/mosaic/manage-data-model-security-filter-objects/modify-a-security-filters-member-in-data-model.md b/docs/common-workflows/mosaic/manage-data-model-security-filter-objects/modify-a-security-filters-member-in-data-model.md new file mode 100644 index 00000000..33a31b45 --- /dev/null +++ b/docs/common-workflows/mosaic/manage-data-model-security-filter-objects/modify-a-security-filters-member-in-data-model.md @@ -0,0 +1,96 @@ +--- +title: Modify a security filter's member in data model +sidebar_label: Modify a security filter's member in data model +description: This workflow sample demonstrates how to modify the users and user groups that a specified security filter in data model is applied to. +--- + + + +:::tip + +You can try out this workflow at [REST API Playground](https://www.postman.com/microstrategysdk/microstrategy-rest-api/collection/5aq5sem/strategy-rest-api-workflows). + +Learn more about Strategy REST API Playground [here](/docs/getting-started/playground.md). + +::: + +This workflow sample demonstrates how to modify the users and user groups that a specified security filter in data model is applied to. The data model ID is `7F071F619BE244C7B6CDC2626EBB1C6C`. The object ID of the security filter is `8981A1EB828F4888959C0C0A435870CC`. + +1. [Remove the users and user groups using `PATCH /api/dataModels/{dataModelId}/securityFilters/{id}/members`](#1-remove-the-users-and-user-groups-using-patch-apidatamodelsdatamodelidsecurityfiltersidmembers) +1. [Add the users and user groups using `PATCH /api/dataModels/{dataModelId}/securityFilters/{id}/members`](#2-add-the-users-and-user-groups-using-patch-apidatamodelsdatamodelidsecurityfiltersidmembers) + +:::info + +To get the authorization token needed to execute the request, use [POST /api/auth/login](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Authentication/postLogin). + +Get the project ID from [GET /api/projects](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Projects/getProjects_1). + +::: + +## 1. Remove the users and user groups using [PATCH /api/dataModels/\{dataModelId}/securityFilters/\{id}/members](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Data%20Model/updatePartialSecurityFilter) + +Sample Request Header: + +```http +"accept": "application/json" +"X-MSTR-AuthToken": "pamr302kmu0q1l0c22jeb13s2q" +"X-MSTR-ProjectID": "B7CA92F04B9FAE8D941C3E9B7E0CD754" +``` + +Sample Request Body: + +```json +{ + "operationList": [ + { + "op": "removeElements", + "path": "/members", + "value": ["D09773F94699124B4D75B48F1B358327", "54F3D26011D2896560009A8E67019608"] + } + ] +} +``` + +Sample Curl: + +```bash +curl -X PATCH "http://demo.microstrategy.com/MicroStrategyLibrary/api/dataModels/7F071F619BE244C7B6CDC2626EBB1C6C/securityFilters/8981A1EB828F4888959C0C0A435870CC/members" -H "accept: */*" -H "X-MSTR-AuthToken: pamr302kmu0q1l0c22jeb13s2q" -H "X-MSTR-ProjectID: B7CA92F04B9FAE8D941C3E9B7E0CD754" -H "Content-Type: application/json" -d '{"operationList":[{"op":"removeElements","path":"/members","value":["D09773F94699124B4D75B48F1B358327","54F3D26011D2896560009A8E67019608"]}]}' +``` + +Sample Response Body: Empty + +Response Code: 204 (The security filter's member is modified successfully.) + +## 2. Add the users and user groups using [PATCH /api/dataModels/\{dataModelId}/securityFilters/\{id}/members](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Data%20Model/updatePartialSecurityFilter) + +Sample Request Header: + +```http +"accept": "application/json" +"X-MSTR-AuthToken": "pamr302kmu0q1l0c22jeb13s2q" +"X-MSTR-ProjectID": "B7CA92F04B9FAE8D941C3E9B7E0CD754" +``` + +Sample Request Body: + +```json +{ + "operationList": [ + { + "op": "addElements", + "path": "/members", + "value": ["D09773F94699124B4D75B48F1B358327", "54F3D26011D2896560009A8E67019608"] + } + ] +} +``` + +Sample Curl: + +```bash +curl -X PATCH "http://demo.microstrategy.com/MicroStrategyLibrary/api/dataModels/7F071F619BE244C7B6CDC2626EBB1C6C/securityFilters/8981A1EB828F4888959C0C0A435870CC/members" -H "accept: */*" -H "X-MSTR-AuthToken: pamr302kmu0q1l0c22jeb13s2q" -H "X-MSTR-ProjectID: B7CA92F04B9FAE8D941C3E9B7E0CD754" -H "Content-Type: application/json" -d '{"operationList":[{"op":"addElements","path":"/members","value":["D09773F94699124B4D75B48F1B358327","54F3D26011D2896560009A8E67019608"]}]}' +``` + +Sample Response Body: Empty + +Response Code: 200 (The security filter's member is modified successfully.) diff --git a/docs/common-workflows/mosaic/manage-data-model-security-filter-objects/retrieve-a-security-filter-definition-in-data-model.md b/docs/common-workflows/mosaic/manage-data-model-security-filter-objects/retrieve-a-security-filter-definition-in-data-model.md new file mode 100644 index 00000000..3a69b5c9 --- /dev/null +++ b/docs/common-workflows/mosaic/manage-data-model-security-filter-objects/retrieve-a-security-filter-definition-in-data-model.md @@ -0,0 +1,288 @@ +--- +title: Retrieve a security filter definition in data model +sidebar_label: Retrieve a security filter definition in data model +description: This workflow sample demonstrates how to retrieve a security filter's definition in data model through the Modeling service. +--- + + + +:::tip + +You can try these workflows with [REST API Playground](https://www.postman.com/microstrategysdk/microstrategy-rest-api/collection/5aq5sem/strategy-rest-api-workflows). + +Learn more about Strategy REST API Playground [here](/docs/getting-started/playground.md). + +::: + +This workflow sample demonstrates how to retrieve a security filter's definition in data model through the Modeling service. + +1. Create a changeset using `POST /api/model/changesets` +1. [Retrieve a data model's security filter's definition using `GET /api/model/dataModels/{dataModelId}/securityFilters/{securityFilterId}`](#retrieve-a-data-models-security-filters-definition) +1. [Retrieve a data model's security filter's definition in tokens format using `GET /api/model/dataModels/{dataModelId}/securityFilters/{securityFilterId}?showFilterTokens=true`](#retrieve-a-data-models-security-filters-definition-in-tokens-format) +1. Delete the changeset using `DELETE /api/model/changesets/{changesetId}` + +### Create a changeset + +Use [POST /api/model/changesets](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Changesets/ms-createChangeset). + +Sample Request Header: + +```http +"accept": "application/json" +"X-MSTR-AuthToken": "pisu5dkkutqfblaamdomgr00ch" +"X-MSTR-ProjectID": "B7CA92F04B9FAE8D941C3E9B7E0CD754" +``` + +Sample Request Body: Empty + +Sample Curl: + +```bash +curl -X POST "https://demo.microstrategy.com/MicroStrategyLibrary/api/model/changesets" -H "accept: application/json" -H "X-MSTR-AuthToken: pisu5dkkutqfblaamdomgr00ch" -H "X-MSTR-ProjectID: B7CA92F04B9FAE8D941C3E9B7E0CD754" +``` + +Sample Response Body: + +```json +{ + "id": "0E9F01172ECF4BA2BB510F7B9FB4F6E8", + "dateCreated": "2025-08-11T16:38:09.825650Z", + "dateModified": "2025-08-11T16:38:09.825665Z", + "status": "Ready", + "schemaEdit": false, + "userName": "MSTR User", + "mstrProjectId": "B7CA92F04B9FAE8D941C3E9B7E0CD754", + "mstrUserId": "7FC05A65473CE2FD845CE6A1D3F13233", + "userDateNumberLocale": "en-US", + "userMetadataLocale": "en-US", + "userWarehouseLocale": "en-US" +} +``` + +Sample Response Code: 200 (A new changeset is created successfully.) + +### Retrieve a data model's security filter's definition + +In this workflow sample, you want to get the definition of the "Year > 2015" security filter object. The data model ID is `7F071F619BE244C7B6CDC2626EBB1C6C`. The object ID of the security filter is `8981A1EB828F4888959C0C0A435870CC` in the MicroStrategy Tutorial project. The project ID is `B7CA92F04B9FAE8D941C3E9B7E0CD754`. + +Use [GET /api/model/dataModels/\{dataModelId}/securityFilters/\{securityFilterId}](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Data%20Model/ms-getDataModelSecurityFilter). + +Sample Request Header: + +```http +"accept": "application/json" +"X-MSTR-AuthToken": "pisu5dkkutqfblaamdomgr00ch" +"X-MSTR-MS-Changeset": "0E9F01172ECF4BA2BB510F7B9FB4F6E8" +``` + +Sample Request Body: Empty + +Sample Curl: + +```bash +curl -X GET "https://demo.microstrategy.com/MicroStrategyLibrary/api/model/dataModels/7F071F619BE244C7B6CDC2626EBB1C6C/securityFilters/8981A1EB828F4888959C0C0A435870CC" -H "accept: application/json" -H "X-MSTR-AuthToken: pisu5dkkutqfblaamdomgr00ch" -H "X-MSTR-MS-Changeset: 0E9F01172ECF4BA2BB510F7B9FB4F6E8" +``` + +Sample Response Body: + +You can view the security filter's definition in the response body. + +```json +{ + "information": { + "dateCreated": "2025-08-11T07:37:35.858Z", + "dateModified": "2025-08-11T07:37:35.858Z", + "versionId": "88DF4A68957941EBBBC69B975B2D011F", + "primaryLocale": "en-US", + "objectId": "8981A1EB828F4888959C0C0A435870CC", + "subType": "md_security_filter", + "name": "Year > 2015" + }, + "qualification": { + "text": "Year (ID) > 2015", + "tree": { + "type": "predicate_form_qualification", + "predicateId": "62EE53C755F64508BAEE99989E9EACCC", + "predicateText": "Year (ID) > 2015", + "predicateTree": { + "function": "greater", + "parameters": [ + { + "parameterType": "constant", + "constant": { + "type": "double", + "value": "2015.0" + } + } + ], + "attribute": { + "objectId": "8D679D5111D3E4981000E787EC6DE8A4", + "subType": "attribute", + "name": "Year" + }, + "form": { + "objectId": "45C11FA478E745FEA08D781CEA190FE5", + "subType": "attribute_form_system", + "name": "ID" + } + } + } + }, + "topLevel": [], + "bottomLevel": [] +} +``` + +Response Code: 200 (The data model's security filter's definition is returned successfully.) + +### Retrieve a data model's security filter's definition in tokens format + +In this workflow sample, you want to get the definition of the "Year > 2015" security filter object in data model. The data model ID is `7F071F619BE244C7B6CDC2626EBB1C6C`. The object ID of the security filter is `8981A1EB828F4888959C0C0A435870CC` in the MicroStrategy Tutorial project. This procedure is similar to [Retrieve a data model's security filter's definition](#retrieve-a-data-models-security-filters-definition), except you want to enable the `showFilterTokens` parameter to retrieve the security filter's definition in tokens format. + +:::tip + +Security filter tokens are used the same as filter tokens. Tokens are a semi-structured representation of expression text that includes object references. For example, let's say a security filter expression is "Revenue > Cost". When the security filter expression is represented as tokens, the text is broken down into pieces (tokens) with information about what these pieces represent in the metadata: ("Revenue", Revenue_ID), (">", GreaterThan_ID), ("Cost", Cost_ID).

A security filter's "qualification" is presented in the following formats: + +- "text": A human-readable, but non-parsable text, describing a filter's qualification. +- "tree": A tree data structure fully defining the filter's qualification. +- "tokens": A list of parsed tokens that define a filter's qualification. Be aware that generating tokens requires additional time. + +If `showFilterTokens` is omitted or `false`, only "text" and "tree" formats return.
If `showFilterTokens` is `true`, all "text", "tree" and "tokens" formats return. + +::: + +To get the security filter's definition in tokens format, use [GET /api/model/dataModels/\{dataModelId}/securityFilters/\{securityFilterId}](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Data%20Model/ms-getDataModelSecurityFilter) with `showFilterTokens=true`. + +Sample Curl: + +```bash +curl -X GET "https://demo.cloud.microstrategy.com/MicroStrategyLibrary/api/model/dataModels/7F071F619BE244C7B6CDC2626EBB1C6C/securityFilters/8981A1EB828F4888959C0C0A435870CC?showFilterTokens=true" -H "accept: application/json" -H "X-MSTR-AuthToken: mcgi1hfofet0f1nhs3u3kjurah" -H "X-MSTR-MS-Changeset: 0E9F01172ECF4BA2BB510F7B9FB4F6E8"" +``` + +Sample Response Body: + +You can view the security filter's definition in the body of the response. Note that compared to [Retrieve a data model's security filter's definition](#retrieve-a-data-models-security-filters-definition), "qualification"`has an extra`"tokens"` field. + +```json +{ + "information": { + "dateCreated": "2025-08-11T07:37:35.858Z", + "dateModified": "2025-08-11T07:37:35.858Z", + "versionId": "6602277211EB330B01430080EF051B59", + "primaryLocale": "en-US", + "objectId": "8981A1EB828F4888959C0C0A435870CC", + "subType": "md_security_filter", + "name": "Year > 2015" + }, + "qualification": { + "text": "Year (ID) > 2015", + "tree": { + "type": "predicate_form_qualification", + "predicateId": "A0D326D440304DC4B07F12DA6631447F", + "predicateText": "Year (ID) > 2015", + "predicateTree": { + "function": "greater", + "parameters": [ + { + "parameterType": "constant", + "constant": { + "type": "double", + "value": "2015.0" + } + } + ], + "attribute": { + "objectId": "8D679D5111D3E4981000E787EC6DE8A4", + "subType": "attribute", + "name": "Year" + }, + "form": { + "objectId": "45C11FA478E745FEA08D781CEA190FE5", + "subType": "attribute_form_system", + "name": "ID" + } + } + }, + "tokens": [ + { + "level": "resolved", + "state": "initial", + "value": "%", + "type": "character" + }, + { + "level": "resolved", + "state": "initial", + "value": "Year@ID", + "type": "object_at_form", + "target": { + "dateCreated": "2001-01-02T20:48:10.000Z", + "dateModified": "2012-01-27T12:00:32.000Z", + "versionId": "24CEEC7044C6C7008EE0DF96565E9459", + "primaryLocale": "en-US", + "objectId": "8D679D5111D3E4981000E787EC6DE8A4", + "subType": "attribute", + "name": "Year" + }, + "attributeForm": { + "objectId": "45C11FA478E745FEA08D781CEA190FE5" + } + }, + { + "level": "resolved", + "state": "initial", + "value": ">", + "type": "character", + "target": { + "dateCreated": "2001-01-02T20:47:41.000Z", + "dateModified": "2018-01-29T21:13:06.000Z", + "versionId": "332E00E411E8053925F00080EF7500C5", + "primaryLocale": "en-US", + "objectId": "8107C317DD9911D3B98100C04F2233EA", + "subType": "function", + "name": ">", + "description": "Returns TRUE if the first value is greater than the second value." + } + }, + { + "level": "resolved", + "state": "initial", + "value": "2015.0", + "type": "integer" + }, + { + "level": "resolved", + "state": "initial", + "value": "", + "type": "end_of_text" + } + ] + }, + "topLevel": [], + "bottomLevel": [] +} +``` + +### Delete a changeset + +Use [DELETE /api/model/changesets/\{changesetId}](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Changesets/ms-deleteChangeset). + +Sample Request Header: + +```http +"accept": "application/json" +"X-MSTR-AuthToken": "pisu5dkkutqfblaamdomgr00ch" +"X-MSTR-MS-Changeset": "0E9F01172ECF4BA2BB510F7B9FB4F6E8" +``` + +Sample Request Body: Empty + +Sample Curl: + +```bash +curl -X DELETE "https://demo.cloud.microstrategy.com/MicroStrategyLibrary/api/model/changesets/0E9F01172ECF4BA2BB510F7B9FB4F6E8" -H "accept: */*" -H "X-MSTR-AuthToken: pisu5dkkutqfblaamdomgr00ch" -H "X-MSTR-MS-Changeset: 0E9F01172ECF4BA2BB510F7B9FB4F6E8" +``` + +Sample Response Body: Empty + +Sample Response Code: 204 (The changeset has been deleted successfully) diff --git a/docs/common-workflows/mosaic/manage-data-model-security-filter-objects/retrieve-a-security-filters-member-in-data-model.md b/docs/common-workflows/mosaic/manage-data-model-security-filter-objects/retrieve-a-security-filters-member-in-data-model.md new file mode 100644 index 00000000..5b88d196 --- /dev/null +++ b/docs/common-workflows/mosaic/manage-data-model-security-filter-objects/retrieve-a-security-filters-member-in-data-model.md @@ -0,0 +1,77 @@ +--- +title: Retrieve a security filter's member in data model +sidebar_label: Retrieve a security filter's member in data model +description: This workflow sample demonstrates how to get the users and user groups that the specified security filter in data model is applied to. +--- + + + +:::tip + +You can try these workflows with [REST API Playground](https://www.postman.com/microstrategysdk/microstrategy-rest-api/collection/5aq5sem/strategy-rest-api-workflows). + +Learn more about Strategy REST API Playground [here](/docs/getting-started/playground.md). + +::: + +This workflow sample demonstrates how to get the users and user groups to which the specified security filter in the data model applies. The data model ID is `7F071F619BE244C7B6CDC2626EBB1C6C`. The object ID of the security filter is `8981A1EB828F4888959C0C0A435870CC`. + +:::info + +To get the authorization token needed to execute the request, use [POST /api/auth/login](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Authentication/postLogin). + +Get the project ID from [GET /api/projects](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Projects/getProjects_1). + +::: + +To retrieve the security filter's member, use [GET /api/dataModels/\{dataModelId}/securityFilters/\{id}/members](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Data%20Model/getSecurityFilterUsers). + +Sample Request Header: + +```http +"accept": "application/json" +"X-MSTR-AuthToken": "4bb7n1dhjo860e7tlpchg57hl" +"X-MSTR-ProjectID": "B7CA92F04B9FAE8D941C3E9B7E0CD754" +``` + +Sample Request Body: Empty + +Sample Curl: + +```bash +curl -X GET "https://demo.microstrategy.com/MicroStrategyLibrary/api/dataModels/7F071F619BE244C7B6CDC2626EBB1C6C/securityFilters/8981A1EB828F4888959C0C0A435870CC/members" -H "accept: application/json" -H "X-MSTR-AuthToken: 4bb7n1dhjo860e7tlpchg57hl" -H "X-MSTR-ProjectID: B7CA92F04B9FAE8D941C3E9B7E0CD754" +``` + +Sample Response Body: + +You can view the data model's security filter's members in the response body. + +```json +{ + "users": [ + { + "name": "Katharine Shearn", + "id": "E96A79E011D4BBCE10004694316DE8A4", + "type": 34, + "abbreviation": "kshearn", + "subtype": 8704, + "dateCreated": "2001-01-02T20:42:34.000+0000", + "dateModified": "2019-12-04T16:53:47.000+0000", + "version": "A3930CAE11EA16B600000080EF359083", + "acg": 255, + "owner": { + "name": "Administrator", + "id": "54F3D26011D2896560009A8E67019608" + }, + "extType": 0, + "username": "kshearn", + "fullName": "Katharine Shearn", + "initials": "KS" + } + ], + "totalUsers": 1, + "totalUserGroups": 0 +} +``` + +Response Code 200: (The security filter's member is returned successfully.) diff --git a/docs/common-workflows/mosaic/manage-data-model-security-filter-objects/retrieve-all-security-filters-in-data-model.md b/docs/common-workflows/mosaic/manage-data-model-security-filter-objects/retrieve-all-security-filters-in-data-model.md new file mode 100644 index 00000000..38f8aa59 --- /dev/null +++ b/docs/common-workflows/mosaic/manage-data-model-security-filter-objects/retrieve-all-security-filters-in-data-model.md @@ -0,0 +1,186 @@ +--- +title: Retrieve all security filters in data model +sidebar_label: Retrieve all security filters in data model +description: This topic covers several workflows for retrieving all security filters in data model. +--- + + + +This topic covers several workflows to retrieve all security filters in a data model. + +- [Retrieve all security filters in data model within a changeset](#retrieve-all-security-filters-in-data-model-within-a-changeset) +- [Retrieve all security filters with users info in data model](#retrieve-all-security-filters-with-users-info-in-data-model) + +:::tip + +You can try these workflows with [REST API Playground](https://www.postman.com/microstrategysdk/microstrategy-rest-api/collection/5aq5sem/strategy-rest-api-workflows). + +Learn more about Strategy REST API Playground [here](/docs/getting-started/playground.md). + +::: + +## Retrieve all security filters in data model within a changeset + +You can retrieve all security filters in a data model using a changeset. + +1. Create a changeset using `POST /api/model/changesets` +1. [Retrieve all security filters in data model using `GET /api/model/dataModels/{dataModelId}/securityFilters`](#retrieve-all-security-filters-in-data-model-using-get-apimodeldatamodelsdatamodelidsecurityfilters) +1. Delete the changeset using `DELETE /api/model/changesets/{changesetId}` + +In this workflow sample, you want to retrieve all security filters in a data model. The data model ID is `7F071F619BE244C7B6CDC2626EBB1C6C`. + +:::info + +Get the authorization token needed to execute the request with [POST /api/auth/login](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Authentication/postLogin). + +Get the project ID from [GET /api/projects](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Projects/getProjects_1). + +::: + +Changesets are used in this workflow. For information on how to create and use changesets, see [Changesets](/docs/common-workflows/modeling/changesets.md). + +### Retrieve all security filters in data model using [GET /api/model/dataModels/\{dataModelId}/securityFilters](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Data%20Model/ms-getDataModelSecurityFilters) + +Sample Request Header: + +```http +"accept": "application/json" +"X-MSTR-AuthToken": "frbicqfk7btoggg5bnu450hrqt" +"X-MSTR-MS-Changeset": "C4F6B0E4C87F46EF9B6C5690DFFF87C1" +``` + +Sample Request Body: Empty + +Sample Curl: + +```bash +curl -X GET "https://demo.microstrategy.com/MicroStrategyLibrary/api/model/dataModels/7F071F619BE244C7B6CDC2626EBB1C6C/securityFilters" -H "accept: application/json" -H "X-MSTR-AuthToken: pisu5dkkutqfblaamdomgr00ch" -H "X-MSTR-MS-Changeset: C4F6B0E4C87F46EF9B6C5690DFFF87C1" +``` + +Sample Response Body: + +```json +{ + "offset": 0, + "limit": -1, + "total": 1, + "securityFilters": [ + { + "information": { + "dateCreated": "2025-08-11T07:37:35.858Z", + "dateModified": "2025-08-11T07:37:35.858Z", + "versionId": "88DF4A68957941EBBBC69B975B2D011F", + "primaryLocale": "en-US", + "objectId": "8981A1EB828F4888959C0C0A435870CC", + "subType": "md_security_filter", + "name": "Year > 2015" + }, + "qualification": { + "text": "Year (ID) > 2015", + "tree": { + "type": "predicate_form_qualification", + "predicateId": "62EE53C755F64508BAEE99989E9EACCC", + "predicateText": "Year (ID) > 2015", + "predicateTree": { + "function": "greater", + "parameters": [ + { + "parameterType": "constant", + "constant": { + "type": "double", + "value": "2015.0" + } + } + ], + "attribute": { + "objectId": "8D679D5111D3E4981000E787EC6DE8A4", + "subType": "attribute", + "name": "Year" + }, + "form": { + "objectId": "45C11FA478E745FEA08D781CEA190FE5", + "subType": "attribute_form_system", + "name": "ID" + } + } + } + }, + "topLevel": [], + "bottomLevel": [] + } + ] +} +``` + +Response Code: 200 (All security filters in data model were returned successfully.) + +## Retrieve all security filters with users info in data model + +Use [GET /api/dataModels/7F071F619BE244C7B6CDC2626EBB1C6C/securityFilters](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Data%20Model/getDataModelSecurityFilters). + +:::info + +To get the authorization token needed to execute the request, use [POST /api/auth/login](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Authentication/postLogin). + +Get the project ID from [GET /api/projects](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Projects/getProjects_1). + +::: + +Sample Request Header: + +```http +"accept": "application/json" +"X-MSTR-AuthToken": "4bb7n1dhjo860e7tlpchg57hl" +"X-MSTR-ProjectID": "B7CA92F04B9FAE8D941C3E9B7E0CD754" +``` + +Sample Request Body: Empty + +Sample Curl: + +```bash +curl -X GET "https://demo.microstrategy.com/MicroStrategyLibrary/api/dataModels/7F071F619BE244C7B6CDC2626EBB1C6C/securityFilters" -H "accept: application/json" -H "X-MSTR-AuthToken: 4bb7n1dhjo860e7tlpchg57hl" -H "X-MSTR-ProjectID: B7CA92F04B9FAE8D941C3E9B7E0CD754" +``` + +Sample Response Body: + +You can view the security filter's definition in the response body. + +```json +{ + "securityFilters": [ + { + "id": "8981A1EB828F4888959C0C0A435870CC", + "name": "Year > 2015", + "description": "", + "dateCreated": "2025-08-11T07:37:35.858Z", + "dateModified": "2025-08-11T07:37:35.858Z", + "users": [ + { + "name": "Katharine Shearn", + "id": "E96A79E011D4BBCE10004694316DE8A4", + "type": 34, + "abbreviation": "kshearn", + "subtype": 8704, + "dateCreated": "2001-01-02T20:42:34.000+0000", + "dateModified": "2019-12-04T16:53:47.000+0000", + "version": "A3930CAE11EA16B600000080EF359083", + "acg": 255, + "owner": { + "name": "Administrator", + "id": "54F3D26011D2896560009A8E67019608" + }, + "extType": 0, + "username": "kshearn", + "fullName": "Katharine Shearn", + "initials": "KS" + } + ], + "totalUsers": 1, + "totalUserGroups": 0 + } + ] +} +``` + +Response Code: 200 (All security filters in data model were returned successfully, as well as the users info.) diff --git a/docs/common-workflows/mosaic/manage-data-model-security-filter-objects/update-a-security-filter-object-in-data-model.md b/docs/common-workflows/mosaic/manage-data-model-security-filter-objects/update-a-security-filter-object-in-data-model.md new file mode 100644 index 00000000..da745b02 --- /dev/null +++ b/docs/common-workflows/mosaic/manage-data-model-security-filter-objects/update-a-security-filter-object-in-data-model.md @@ -0,0 +1,139 @@ +--- +title: Update a security filter object in data model +sidebar_label: Update a security filter object in data model +description: This workflow sample demonstrates how to update a security filter object in data model through the Modeling service. +--- + + + +:::tip + +You can try these workflows with [REST API Playground](https://www.postman.com/microstrategysdk/microstrategy-rest-api/collection/5aq5sem/strategy-rest-api-workflows). + +Learn more about Strategy REST API Playground [here](/docs/getting-started/playground.md). + +::: + +This workflow sample demonstrates how to update a security filter definition in a data model using the Modeling service. + +1. Create a changeset using `POST /api/model/changesets` +1. [Update the security filter's definition in data model using `PUT /api/model/dataModels/{dataModelId}/securityFilters/{securityFilterId}`](#update-the-security-filters-definition-in-data-model-using-put-apimodeldatamodelsdatamodelidsecurityfilterssecurityfilterid) +1. Commit the changeset using `POST /api/model/changesets/{changesetId}/commit` +1. Delete the changeset using `DELETE /api/model/changesets/{changesetId}` + +In this workflow example, you want to update the definition of the `"Year > 2015"` security filter object with a new definition of `"Year@ID > 2020"` and a new object name of `"Year > 2020"`. The data model ID is `7F071F619BE244C7B6CDC2626EBB1C6C`. The object ID of the security filter is `8981A1EB828F4888959C0C0A435870CC`. + +:::info + +To get the authorization token needed to execute the request, use [POST /api/auth/login](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Authentication/postLogin). + +Get the project ID from [GET /api/projects](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Projects/getProjects_1). + +::: + +Changesets are used in this workflow. For information on how to create and use changesets, see [Changesets](/docs/common-workflows/modeling/changesets.md). + +## Update the security filter's definition in data model using [PUT /api/model/dataModels/\{dataModelId}/securityFilters/\{securityFilterId}](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Data%20Model/ms-putDataModelSecurityFilter) + +Sample Request Header: + +```http +"accept": "application/json" +"X-MSTR-AuthToken": "frbicqfk7btoggg5bnu450hrqt" +"X-MSTR-MS-Changeset": "C4F6B0E4C87F46EF9B6C5690DFFF87C1" +``` + +Sample Request Body: + +```json +{ + "information": { + "name": "Year > 2020" + }, + "qualification": { + "tree": { + "type": "predicate_form_qualification", + "predicateTree": { + "function": "greater", + "parameters": [ + { + "parameterType": "constant", + "constant": { + "type": "double", + "value": "2020" + } + } + ], + "attribute": { + "objectId": "8D679D5111D3E4981000E787EC6DE8A4", + "subType": "attribute", + "name": "Year" + }, + "form": { + "objectId": "45C11FA478E745FEA08D781CEA190FE5", + "subType": "attribute_form_system", + "name": "ID" + } + } + } + } +} +``` + +Sample Curl: + +```bash +curl -X PUT "https://demo.cloud.microstrategy.com/MicroStrategyLibrary/api/model/dataModels/7F071F619BE244C7B6CDC2626EBB1C6C/securityFilters/8981A1EB828F4888959C0C0A435870CC" -H "accept: application/json" -H "X-MSTR-AuthToken: frbicqfk7btoggg5bnu450hrqt" -H "X-MSTR-MS-Changeset: C4F6B0E4C87F46EF9B6C5690DFFF87C1" -H "Content-Type: application/json" -d '{"information":{"name":"Year > 2020"},"qualification":{"tree":{"type":"predicate_form_qualification","predicateTree":{"function":"greater","parameters":[{"parameterType":"constant","constant":{"type":"double","value":"2020"}}],"attribute":{"objectId":"8D679D5111D3E4981000E787EC6DE8A4","subType":"attribute","name":"Year"},"form":{"objectId":"45C11FA478E745FEA08D781CEA190FE5","subType":"attribute_form_system","name":"ID"}}}}}' +``` + +Sample Response Body: + +You can view the data model's security filter's definition in the response body. + +```json +{ + "information": { + "dateCreated": "2025-08-11T07:37:35.858Z", + "dateModified": "2025-08-11T07:43:23.784Z", + "versionId": "C3945CBF4048805AD0F397B6DF3E3DA6", + "primaryLocale": "en-US", + "objectId": "8981A1EB828F4888959C0C0A435870CC", + "subType": "md_security_filter", + "name": "Year > 2020" + }, + "qualification": { + "text": "Year (ID) > 2020", + "tree": { + "type": "predicate_form_qualification", + "predicateId": "89AECC7DAB354B4A933E83E33928C670", + "predicateText": "Year (ID) > 2020", + "predicateTree": { + "function": "greater", + "parameters": [ + { + "parameterType": "constant", + "constant": { + "type": "double", + "value": "2020.0" + } + } + ], + "attribute": { + "objectId": "8D679D5111D3E4981000E787EC6DE8A4", + "subType": "attribute", + "name": "Year" + }, + "form": { + "objectId": "45C11FA478E745FEA08D781CEA190FE5", + "subType": "attribute_form_system", + "name": "ID" + } + } + } + }, + "topLevel": [], + "bottomLevel": [] +} +``` + +Response Code: 200 (The data model's security filter's definition is updated successfully in the changeset.) diff --git a/docs/common-workflows/mosaic/mosaic.md b/docs/common-workflows/mosaic/mosaic.md new file mode 100644 index 00000000..9c319327 --- /dev/null +++ b/docs/common-workflows/mosaic/mosaic.md @@ -0,0 +1,8 @@ +--- +title: Mosaic +description: This section contains workflows that utilize the REST API to handle Mosaic data model related workflows. +--- + + + +This section contains workflows that utilize the REST API to handle Mosaic data model related workflows. diff --git a/docs/common-workflows/mosaic/publish/manage-data-model-publish.md b/docs/common-workflows/mosaic/publish/manage-data-model-publish.md new file mode 100644 index 00000000..3e990276 --- /dev/null +++ b/docs/common-workflows/mosaic/publish/manage-data-model-publish.md @@ -0,0 +1,19 @@ +--- +title: Publish data models +description: You can use REST API requests to publish data models. +--- + + + +:::tip + +You can try these workflows with [REST API Playground](https://www.postman.com/microstrategysdk/microstrategy-rest-api/collection/5aq5sem/strategy-rest-api-workflows). + +Learn more about Strategy REST API Playground [here](/docs/getting-started/playground.md). + +::: + +You can use REST API requests to publish data models. + +- [Refresh a Data Model](refresh-a-data-model.md) +- [Schedule Refresh a Data Model](schedule-refresh-a-data-model.md) diff --git a/docs/common-workflows/mosaic/publish/refresh-a-data-model.md b/docs/common-workflows/mosaic/publish/refresh-a-data-model.md new file mode 100644 index 00000000..a1ffcaba --- /dev/null +++ b/docs/common-workflows/mosaic/publish/refresh-a-data-model.md @@ -0,0 +1,304 @@ +--- +title: Refresh a data model +description: This workflow demonstrates how to refresh a data model using REST API. +--- + + + +This workflow sample demonstrates how to refresh a data model by creating a data model instance and publish it using the REST API. + +- [Log in](#log-in) +- [Create data model instance](#create-data-model-instance) +- [Get tables in the data model](#get-tables-in-the-data-model) +- [Publish](#publish) +- [Get publish status](#get-publish-status) +- [Delete data model instance](#delete-data-model-instance) + +A detailed description of each step of this workflow is listed below. + +## Log in + +Endpoint: [POST /api/auth/login](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Authentication/postLogin) + +Sample Request + +- Request Headers + +```http +'Content-Type: application/json' +'Accept: application/json' +``` + +- Request Body + +```json +{ + "loginMode": 1, + "username": "administrator", + "password": "" +} +``` + +- Curl + +```bash +curl -X POST -i -c ~/cookie-jar.txt --header 'Content-Type: application/json'\ +--header 'Accept: application/json' -d '{ +"loginMode":1, +"username": "administrator", +"password": "" +}' https://demo.microstrategy.com/MicroStrategyLibrary/api/auth/login' +``` + +Sample Response + +- Response Headers + +```json +{ + "pragma": "no-cache", + "x-mstr-authtoken": "nllmm5lpmkjdsj4d4etgdikc6c", + "cache-control": "no-cache, no-store, max-age=0, must-revalidate", + "date": "Wed, 16 Aug 2017 01:42:31 GMT", + "expires": "0", + "content-type": null +} +``` + +The authorization token "`x-mstr-authtoken`" returns in the response header. It is used in other endpoints to authenticate the user. + +- Response Body: Empty + +- Response Code: 204 (Success: No Content) + +## Create data model instance + +Before you can publish a data model, you need to create a data model instance. + +Endpoint: [POST /api/dataModels/\{dataModelId}/instances](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Data%20Model/createDataModelInstance) + +Sample Request + +- Request Headers + +```http +'Content-Type: application/json' +'Accept: application/json' +'X-MSTR-AuthToken: pgho7427r1e6p0tem7e677jivk' +'X-MSTR-ProjectID: B7CA92F04B9FAE8D941C3E9B7E0CD754' +``` + +- Curl + +```bash +curl --location --request POST 'https://demo.microstrategy.com/MicroStrategyLibrary/api/dataModels/9F4772B837604551B4D3CC916ADC5598/instances' --header 'X-MSTR-AuthToken: 2pgjiac8mvb7n4jfrj1ch6gok4' --header 'X-MSTR-ProjectID: B7CA92F04B9FAE8D941C3E9B7E0CD754' +``` + +Sample Response + +- Response Headers + +```http +'X-MSTR-DataModelInstanceId: CBE2C87449CEFFF7C089AEA0EE6BBA9C' +``` + +The data model instance is returned in the response header. + +- Response Body: Empty + +- Response Code: 204 (Success: No Content) + +## Get tables in the data model + +You need to retrieve tables in the data model, as table IDs need to be specified in the request body of publish API. Select the tables that you want to refresh and define the refresh policy for each table. You can use query parameters, such as `offset` and `limit`, to control the pagination of tables returned in the response. + +Endpoint: GET /api/model/dataModels/\{dataModelId}/tables + +Sample Request + +- Request Headers + +```http +'Content-Type: application/json' +'Accept: application/json' +'X-MSTR-AuthToken: pgho7427r1e6p0tem7e677jivk' +'X-MSTR-ProjectID: B7CA92F04B9FAE8D941C3E9B7E0CD754' +``` + +- Request Body: Empty + +- Curl + +```bash +curl --location 'https://demo.microstrategy.com/MicroStrategyLibrary/api/model/dataModels/9F4772B837604551B4D3CC916ADC5598/tables?offset=0&limit=-1' \ +--header 'X-MSTR-AuthToken: 2pgjiac8mvb7n4jfrj1ch6gok4' \ +--header 'X-MSTR-ProjectID: B7CA92F04B9FAE8D941C3E9B7E0CD754' \ +--header 'Content-Type: application/json' +``` + +Sample Response + +- Response Body: + +```json +{ + "offset": 0, + "limit": -1, + "total": 2, + "tables": [ + { + "information": { + "dateCreated": "2025-08-04T01:25:01.671Z", + "dateModified": "2025-08-04T02:20:51.363Z", + "versionId": "B754E270234CDD4B1004E5BF1FB5F4B1", + "acg": 255, + "primaryLocale": "en-US", + "objectId": "B8A627B44A7A421C81741B868401E446", + "subType": "logical_table", + "name": "ytd_day" + } + }, + { + "information": { + "dateCreated": "2025-08-04T01:25:01.671Z", + "dateModified": "2025-08-04T02:20:51.363Z", + "versionId": "D7A6DE2C594782F4EB98E18BC6A28F75", + "acg": 255, + "primaryLocale": "en-US", + "objectId": "612801B773AF4EFD974FF1F54FFAFB32", + "subType": "logical_table", + "name": "city_mnth_sls" + } + } + ] +} +``` + +- Response Code: 200 (Success: OK) + +## Publish + +Now you can publish the data model with the newly created data model instance. The data model refresh settings are included in the request body, which specifies the refresh policy for each table in the data model. The refresh policy can be 'replace', 'add', 'update', or 'upsert'. + +Endpoint: [POST /api/dataModels/\{dataModelId}/publish](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Data%20Model/publishDataModel) + +Sample Request + +- Request Headers + +```http +'Content-Type: application/json' +'Accept: application/json' +'X-MSTR-AuthToken: pgho7427r1e6p0tem7e677jivk' +'X-MSTR-ProjectID: B7CA92F04B9FAE8D941C3E9B7E0CD754' +'X-MSTR-DataModelInstanceId: CBE2C87449CEFFF7C089AEA0EE6BBA9C' +``` + +- Request Body + +```json +{ + "tables": [ + { + "id": "0D1436DF3004418086D8BD3FD985EC4A", + "refreshPolicy": "replace" + } + ] +} +``` + +- Curl + +```bash +curl --location 'https://demo.microstrategy.com/MicroStrategyLibrary/api/dataModels/9F4772B837604551B4D3CC916ADC5598/publish' \ +--header 'X-MSTR-AuthToken: 2pgjiac8mvb7n4jfrj1ch6gok4' \ +--header 'X-MSTR-ProjectID: B7CA92F04B9FAE8D941C3E9B7E0CD754' \ +--header 'X-MSTR-DataModelInstanceId: CBE2C87449CEFFF7C089AEA0EE6BBA9C' \ +--header 'Content-Type: application/json' \ +--data '{ + "tables": [ + { + "id": "0D1436DF3004418086D8BD3FD985EC4A", + "refreshPolicy": "replace" + } + ] +}' +``` + +Sample Response + +- Response Headers + +- Response Body: Empty + +- Response Code: 204 (Success: No Content) + +## Get publish status + +It may take some time for the data model to be published. To check the status of the publish operation, use the following endpoint. + +Endpoint: [GET /api/dataModels/\{dataModelId}/publishStatus](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Data%20Model/pollPublishStatus) + +Sample Request + +- Request Headers + +```http +'Content-Type: application/json' +'Accept: application/json' +'X-MSTR-AuthToken: pgho7427r1e6p0tem7e677jivk' +'X-MSTR-ProjectID: B7CA92F04B9FAE8D941C3E9B7E0CD754' +'X-MSTR-DataModelInstanceId: CBE2C87449CEFFF7C089AEA0EE6BBA9C' +``` + +- Curl + +```bash +curl --location 'https://demo.microstrategy.com/MicroStrategyLibrary/api/dataModels/9F4772B837604551B4D3CC916ADC5598/publishStatus' \ +--header 'X-MSTR-AuthToken: 2pgjiac8mvb7n4jfrj1ch6gok4' \ +--header 'X-MSTR-ProjectID: B7CA92F04B9FAE8D941C3E9B7E0CD754' \ +--header 'X-MSTR-DataModelInstanceId: CBE2C87449CEFFF7C089AEA0EE6BBA9C' +``` + +Sample Response + +- Response Body: + +```json +{ + "status": 1 +} +``` + +- Response Code: 200 (Success: OK) + +## Delete data model instance + +After the data model is published, you can delete the data model instance if it is no longer needed. + +Endpoint: [DELETE /api/dataModels/\{dataModelId}/instances/\{instanceId}](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Data%20Model/deleteDataModelInstance) + +Sample Request + +- Request Headers + +```http +'Content-Type: application/json' +'Accept: application/json' +'X-MSTR-AuthToken: pgho7427r1e6p0tem7e677jivk' +'X-MSTR-ProjectID: B7CA92F04B9FAE8D941C3E9B7E0CD754' +``` + +- Curl + +```bash +curl --location --request DELETE 'https://demo.microstrategy.com/MicroStrategyLibrary/api/dataModels/9F4772B837604551B4D3CC916ADC5598/instances/CBE2C87449CEFFF7C089AEA0EE6BBA9C' \ +--header 'X-MSTR-AuthToken: 2pgjiac8mvb7n4jfrj1ch6gok4' \ +--header 'X-MSTR-ProjectID: B7CA92F04B9FAE8D941C3E9B7E0CD754' +``` + +Sample Response + +- Response Body: Empty + +- Response Code: 204 (Success: No Content) diff --git a/docs/common-workflows/mosaic/publish/schedule-refresh-a-data-model.md b/docs/common-workflows/mosaic/publish/schedule-refresh-a-data-model.md new file mode 100644 index 00000000..de480bbb --- /dev/null +++ b/docs/common-workflows/mosaic/publish/schedule-refresh-a-data-model.md @@ -0,0 +1,673 @@ +--- +title: Schedule refresh a data model +description: This workflow demonstrates how to schedule a refresh for a data model. +--- + + + +This workflow sample demonstrates how to schedule a refresh for a data model using the REST API. + +- [Log in](#log-in) +- [Get all subscriptions](#get-all-subscriptions) +- [Create a subscription](#create-a-subscription) +- [Update a subscription](#update-a-subscription) +- [Get a subscription by ID](#get-a-subscription-by-id) + +A detailed description of each step of this workflow is listed below. + +## Log in + +Endpoint: [POST /api/auth/login](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Authentication/postLogin) + +Sample Request + +- Request Headers + +```http +'Content-Type: application/json' +'Accept: application/json' +``` + +- Request Body + +```json +{ + "loginMode": 1, + "username": "administrator", + "password": "" +} +``` + +- Curl + +```bash +curl -X POST -i -c ~/cookie-jar.txt --header 'Content-Type: application/json'\ +--header 'Accept: application/json' -d '{ +"loginMode":1, +"username": "administrator", +"password": "" +}' https://demo.microstrategy.com/MicroStrategyLibrary/api/auth/login' +``` + +Sample Response + +- Response Headers + +```json +{ + "pragma": "no-cache", + "x-mstr-authtoken": "nllmm5lpmkjdsj4d4etgdikc6c", + "cache-control": "no-cache, no-store, max-age=0, must-revalidate", + "date": "Wed, 16 Aug 2017 01:42:31 GMT", + "expires": "0", + "content-type": null +} +``` + +The authorization token "`x-mstr-authtoken`" is returned in the response header. It is used in other endpoints to authenticate the user. + +- Response Body: Empty + +- Response Code: 204 (Success: No Content) + +## Get all subscriptions + +To retrieve all subscriptions within a project, use the following endpoint. `offset` and `limit` parameters can be used for pagination. For example, if you want to retrieve the first 10 subscriptions, you can set `offset=0` and `limit=10` in the request. + +Endpoint: [GET /api/subscriptions](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Subscriptions/getSubscriptions) + +Sample Request + +- Request Headers + +```http +'Content-Type: application/json' +'Accept: application/json' +'X-MSTR-AuthToken: nllmm5lpmkjdsj4d4etgdikc6c' +'X-MSTR-ProjectID: B7CA92F04B9FAE8D941C3E9B7E0CD754' +``` + +- Curl + +```bash +curl --location 'https://demo.microstrategy.com/MicroStrategyLibrary/api/subscriptions?offset=0&limit=10' \ +--header 'Accept: application/json' \ +--header 'X-MSTR-AuthToken: nllmm5lpmkjdsj4d4etgdikc6c' \ +--header 'X-MSTR-ProjectID: B7CA92F04B9FAE8D941C3E9B7E0CD754' \ +``` + +Sample Response + +- Response Body: + +```json +{ + "subscriptions": [ + { + "name": "Updated Subscription", + "id": "0730C69A4EBAA20BD967EA86274F0C2F", + "multipleContents": false, + "editable": true, + "allowDeliveryChanges": false, + "allowPersonalizationChanges": false, + "allowUnsubscribe": false, + "allowUnsubscribeFromEmail": false, + "dateCreated": "2025-07-29T05:48:30+0000", + "dateModified": "2025-07-29T05:52:37+0000", + "owner": { + "id": "54F3D26011D2896560009A8E67019608", + "name": "Administrator" + }, + "schedules": [ + { + "id": "E24F501E802911E1BBCB892C4924019B", + "name": "Personal View", + "type": "event_based", + "expired": true + } + ], + "contents": [ + { + "id": "9F4772B837604551B4D3CC916ADC5598", + "name": "_test api", + "type": "data_model", + "projectId": "B7CA92F04B9FAE8D941C3E9B7E0CD754" + } + ], + "recipients": [ + { + "id": "54F3D26011D2896560009A8E67019608", + "name": "Administrator", + "isGroup": false, + "type": "user", + "includeType": "TO", + "childSubscriptionId": "2A3D6DFB4FE66AF22B228E89DCE4847D" + } + ], + "delivery": { + "mode": "HISTORY_LIST", + "contactSecurity": false, + "historyList": { + "doNotCreateUpdateCaches": false, + "overwriteOlderVersion": false, + "reRunHl": false + }, + "notificationEnabled": false + }, + "alert": false + } + ] +} +``` + +- Response Code: 200 (Success: OK) + +## Create a subscription + +To schedule a refresh for a data model, create a subscription. In the `contents` section of the request body, you need to specify the type as `data_model`. + +Endpoint: [POST /api/subscriptions](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Subscriptions/createSubscription) + +Sample Request + +- Request Headers + +```http +'Content-Type: application/json' +'Accept: application/json' +'X-MSTR-AuthToken: ot5sr2resn9jjjm3fo30lch2lq' +'X-MSTR-ProjectID: B7CA92F04B9FAE8D941C3E9B7E0CD754' +``` + +- Request Body + +```json +{ + "name": "Data Model Subscription Example", + "allowDeliveryChanges": false, + "allowPersonalizationChanges": false, + "allowUnsubscribe": false, + "sendNow": false, + "schedules": [ + { + "id": "FF7BB3C811D501F0C00051916B98494F" + } + ], + "contents": [ + { + "id": "9F4772B837604551B4D3CC916ADC5598", + "type": "data_model", + "refreshCondition": { + "tables": [ + { + "id": "0D1436DF3004418086D8BD3FD985EC4A", + "refreshPolicy": "upsert" + } + ] + } + } + ], + "delivery": { + "mode": "HISTORY_LIST" + } +} +``` + +Strategy supports attribute form qualification in the `refreshCondition.filters` section. Refer to the qualification field in [Attribute form qualifications](https://microstrategy.github.io/rest-api-docs/common-workflows/modeling/manage-filter-objects/create-a-filter-object/#attribute-form-qualifications) to create your own filter expression." See the following example request body: + +- Request Body + +```json +{ + "name": "Data Model Subscription Example", + "allowDeliveryChanges": false, + "allowPersonalizationChanges": false, + "allowUnsubscribe": false, + "sendNow": false, + "schedules": [ + { + "id": "FF7BB3C811D501F0C00051916B98494F" + } + ], + "contents": [ + { + "id": "9F4772B837604551B4D3CC916ADC5598", + "type": "data_model", + "refreshCondition": { + "filters": [ + { + "type": "refresh", + "qualification": { + "tree": { + "type": "predicate_form_qualification", + "predicateTree": { + "function": "equals", + "parameters": [ + { + "parameterType": "constant", + "constant": { + "type": "string", + "value": "jan" + } + } + ], + "attribute": { + "objectId": "74BA634076BE435F913BA476BFEA2E9B", + "subType": "attribute" + }, + "form": { + "objectId": "45C11FA478E745FEA08D781CEA190FE5", + "subType": "attribute_form_system" + }, + "dataLocale": "en-US" + } + } + } + } + ], + "tables": [ + { + "id": "0D1436DF3004418086D8BD3FD985EC4A", + "refreshPolicy": "upsert" + } + ] + } + } + ], + "delivery": { + "mode": "HISTORY_LIST" + } +} +``` + +- Curl + +```bash +curl --location 'https://demo.microstrategy.com/MicroStrategyLibrary/api/subscriptions/' \ +--header 'Accept: application/json' \ +--header 'X-MSTR-AuthToken: ot5sr2resn9jjjm3fo30lch2lq' \ +--header 'X-MSTR-ProjectID: B7CA92F04B9FAE8D941C3E9B7E0CD754' \ +--header 'Content-Type: application/json' \ +--data '{ + "name": "Data Model Subscription Example", + "allowDeliveryChanges": false, + "allowPersonalizationChanges": false, + "allowUnsubscribe": false, + "sendNow": false, + "schedules": [ + { + "id": "FF7BB3C811D501F0C00051916B98494F" + } + ], + "contents": [ + { + "id": "9F4772B837604551B4D3CC916ADC5598", + "type": "data_model", + "refreshCondition": { + "tables": [ + { + "id": "0D1436DF3004418086D8BD3FD985EC4A", + "refreshPolicy": "upsert" + } + ] + } + } + ], + "delivery": { + "mode": "HISTORY_LIST" + } +}' +``` + +Sample Response + +- Response Body: + +```json +{ + "name": "Data Model Subscription Example", + "id": "0730C69A4EBAA20BD967EA86274F0C2F", + "multipleContents": false, + "editable": true, + "allowDeliveryChanges": false, + "allowPersonalizationChanges": false, + "allowUnsubscribe": false, + "allowUnsubscribeFromEmail": false, + "dateCreated": "2025-07-29T05:48:30+0000", + "dateModified": "2025-07-29T05:48:30+0000", + "owner": { + "id": "54F3D26011D2896560009A8E67019608", + "name": "Administrator" + }, + "schedules": [ + { + "id": "FF7BB3C811D501F0C00051916B98494F", + "name": "All the Time", + "type": "time_based", + "nextDelivery": "2025-07-29T06:00:00+0000", + "expired": false + } + ], + "contents": [ + { + "id": "9F4772B837604551B4D3CC916ADC5598", + "name": "_test api", + "type": "data_model", + "projectId": "B7CA92F04B9FAE8D941C3E9B7E0CD754", + "refreshCondition": { + "tables": [ + { + "id": "0D1436DF3004418086D8BD3FD985EC4A", + "refreshPolicy": "upsert" + } + ] + } + } + ], + "recipients": [ + { + "id": "54F3D26011D2896560009A8E67019608", + "name": "Administrator", + "isGroup": false, + "type": "user", + "includeType": "TO", + "childSubscriptionId": "2A3D6DFB4FE66AF22B228E89DCE4847D" + } + ], + "delivery": { + "mode": "HISTORY_LIST", + "contactSecurity": false, + "historyList": { + "doNotCreateUpdateCaches": false, + "overwriteOlderVersion": false, + "reRunHl": false + }, + "notificationEnabled": false + }, + "nextDelivery": "2025-07-29T06:00:00+0000", + "alert": false +} +``` + +- Response Code: 201 (Success: Created) + +## Update a subscription + +To update an existing subscription, send a PUT request to the subscription endpoint with the updated details. + +Endpoint: [PUT /api/subscriptions/\{subscriptionId}](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Subscriptions/updateSubscription) + +Sample Request + +- Request Headers + +```http +'Content-Type: application/json' +'Accept: application/json' +'X-MSTR-AuthToken: ot5sr2resn9jjjm3fo30lch2lq' +'X-MSTR-ProjectID: B7CA92F04B9FAE8D941C3E9B7E0CD754' +``` + +- Request Body + +```json +{ + "name": "Updated Subscription", + "contents": [ + { + "id": "9F4772B837604551B4D3CC916ADC5598", + "type": "data_model", + "refreshCondition": { + "tables": [ + { + "id": "0D1436DF3004418086D8BD3FD985EC4A", + "refreshPolicy": "upsert" + } + ] + } + } + ], + "schedules": [ + { + "id": "E24F501E802911E1BBCB892C4924019B", + "name": "Personal View", + "type": "unknown" + } + ], + "recipients": [ + { + "id": "54F3D26011D2896560009A8E67019608", + "name": "Administrator", + "isGroup": false, + "type": "user", + "includeType": "TO", + "childSubscriptionId": "7283682811E5CA909DFA0080EFB579EC" + } + ], + "delivery": { + "mode": "HISTORY_LIST", + "historyList": { + "doNotCreateUpdateCaches": false, + "overwriteOlderVersion": true, + "reRunHl": false + } + } +} +``` + +- Curl + +```bash +curl --location --request PUT 'https://demo.microstrategy.com/MicroStrategyLibrary/api/subscriptions/0730C69A4EBAA20BD967EA86274F0C2F' \ +--header 'X-MSTR-AuthToken: ot5sr2resn9jjjm3fo30lch2lq' \ +--header 'X-MSTR-ProjectID: B7CA92F04B9FAE8D941C3E9B7E0CD754' \ +--header 'Content-Type: application/json' \ +--data '{ + "name": "Updated Subscription", + "contents": [ + { + "id": "9F4772B837604551B4D3CC916ADC5598", + "type": "data_model", + "refreshCondition": { + "tables": [ + { + "id": "0D1436DF3004418086D8BD3FD985EC4A", + "refreshPolicy": "upsert" + } + ] + } + } + ], + "schedules": [ + { + "id": "E24F501E802911E1BBCB892C4924019B", + "name": "Personal View", + "type": "unknown" + } + ], + "recipients": [ + { + "id": "54F3D26011D2896560009A8E67019608", + "name": "Administrator", + "isGroup": false, + "type": "user", + "includeType": "TO", + "childSubscriptionId": "7283682811E5CA909DFA0080EFB579EC" + } + ], + "delivery": { + "mode": "HISTORY_LIST", + "historyList": { + "doNotCreateUpdateCaches": false, + "overwriteOlderVersion": true, + "reRunHl": false + } + } +}' +``` + +Sample Response + +- Response Body: + +```json +{ + "name": "Updated Subscription", + "id": "0730C69A4EBAA20BD967EA86274F0C2F", + "multipleContents": false, + "editable": true, + "allowDeliveryChanges": false, + "allowPersonalizationChanges": false, + "allowUnsubscribe": false, + "allowUnsubscribeFromEmail": false, + "dateCreated": "2025-07-29T05:48:30+0000", + "dateModified": "2025-07-29T05:52:37+0000", + "owner": { + "id": "54F3D26011D2896560009A8E67019608", + "name": "Administrator" + }, + "schedules": [ + { + "id": "E24F501E802911E1BBCB892C4924019B", + "name": "Personal View", + "type": "event_based", + "expired": true + } + ], + "contents": [ + { + "id": "9F4772B837604551B4D3CC916ADC5598", + "name": "_test api", + "type": "data_model", + "projectId": "B7CA92F04B9FAE8D941C3E9B7E0CD754", + "refreshCondition": { + "tables": [ + { + "id": "0D1436DF3004418086D8BD3FD985EC4A", + "refreshPolicy": "upsert" + } + ] + } + } + ], + "recipients": [ + { + "id": "54F3D26011D2896560009A8E67019608", + "name": "Administrator", + "isGroup": false, + "type": "user", + "includeType": "TO", + "childSubscriptionId": "2A3D6DFB4FE66AF22B228E89DCE4847D" + } + ], + "delivery": { + "mode": "HISTORY_LIST", + "contactSecurity": false, + "historyList": { + "doNotCreateUpdateCaches": false, + "overwriteOlderVersion": false, + "reRunHl": false + }, + "notificationEnabled": false + }, + "alert": false +} +``` + +- Response Code: 200 (Success: OK) + +## Get a subscription by ID + +To retrieve a specific subscription by its ID, use the following endpoint. + +Endpoint: [GET /api/subscriptions/\{subscriptionId}](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Subscriptions/getSubscriptionById) + +Sample Request + +- Request Headers + +```http +'Content-Type: application/json' +'Accept: application/json' +'X-MSTR-AuthToken: ot5sr2resn9jjjm3fo30lch2lq' +'X-MSTR-ProjectID: B7CA92F04B9FAE8D941C3E9B7E0CD754' +``` + +- Curl + +```bash +curl --location 'https://demo.microstrategy.com/MicroStrategyLibrary/api/subscriptions/0730C69A4EBAA20BD967EA86274F0C2F' \ +--header 'Accept: application/json' \ +--header 'X-MSTR-AuthToken: ot5sr2resn9jjjm3fo30lch2lq' \ +--header 'X-MSTR-ProjectID: B7CA92F04B9FAE8D941C3E9B7E0CD754' +``` + +Sample Response + +- Response Body: + +```json +{ + "name": "Updated Subscription", + "id": "0730C69A4EBAA20BD967EA86274F0C2F", + "multipleContents": false, + "editable": true, + "allowDeliveryChanges": false, + "allowPersonalizationChanges": false, + "allowUnsubscribe": false, + "allowUnsubscribeFromEmail": false, + "dateCreated": "2025-07-29T05:48:30+0000", + "dateModified": "2025-07-29T05:52:37+0000", + "owner": { + "id": "54F3D26011D2896560009A8E67019608", + "name": "Administrator" + }, + "schedules": [ + { + "id": "E24F501E802911E1BBCB892C4924019B", + "name": "Personal View", + "type": "event_based", + "expired": true + } + ], + "contents": [ + { + "id": "9F4772B837604551B4D3CC916ADC5598", + "name": "_test api", + "type": "data_model", + "projectId": "B7CA92F04B9FAE8D941C3E9B7E0CD754", + "refreshCondition": { + "tables": [ + { + "id": "0D1436DF3004418086D8BD3FD985EC4A", + "refreshPolicy": "upsert" + } + ] + } + } + ], + "recipients": [ + { + "id": "54F3D26011D2896560009A8E67019608", + "name": "Administrator", + "isGroup": false, + "type": "user", + "includeType": "TO", + "childSubscriptionId": "2A3D6DFB4FE66AF22B228E89DCE4847D" + } + ], + "delivery": { + "mode": "HISTORY_LIST", + "contactSecurity": false, + "historyList": { + "doNotCreateUpdateCaches": false, + "overwriteOlderVersion": false, + "reRunHl": false + }, + "notificationEnabled": false + }, + "alert": false +} +``` + +- Response Code: 200 (Success: OK) diff --git a/docs/whats-new.md b/docs/whats-new.md index d3e37eca..0568aa1b 100644 --- a/docs/whats-new.md +++ b/docs/whats-new.md @@ -4,6 +4,21 @@ sidebar_label: What's new Description: What's New in the REST API. --- +## Strategy ONE (August 2025) + +- [Refresh a Data Model](common-workflows/mosaic/publish/refresh-a-data-model.md). +- [Schedule Refresh a Data Model](common-workflows/mosaic/publish/schedule-refresh-a-data-model.md). +- [Create a Security Filter object in a Data Model](common-workflows/mosaic/manage-data-model-security-filter-objects/create-a-security-filter-object-in-data-model.md). +- [Update a Security Filter object in a Data Model](common-workflows/mosaic/manage-data-model-security-filter-objects/update-a-security-filter-object-in-data-model.md). +- [Retrieve a Security Filter Definition in a Data Model](common-workflows/mosaic/manage-data-model-security-filter-objects/retrieve-a-security-filter-definition-in-data-model.md). +- [Retrieve all Security Filters in a Data Model](common-workflows/mosaic/manage-data-model-security-filter-objects/retrieve-all-security-filters-in-data-model.md). +- [Retrieve a Security Filter's Member in a Data Model](common-workflows/mosaic/manage-data-model-security-filter-objects/retrieve-a-security-filters-member-in-data-model.md). +- [Modify a Security Filter's Member in a Data Model](common-workflows/mosaic/manage-data-model-security-filter-objects/modify-a-security-filters-member-in-data-model.md). +- [Delete a Security Filter Object in a Data Model](common-workflows/mosaic/manage-data-model-security-filter-objects/delete-a-security-filter-object-in-data-model.md). +- [Retrieve an Attribute's Elements in a Data Model](common-workflows/mosaic/manage-data-model-attribute-objects/retrieve-an-attributes-elements-in-data-model.md). +- [Get ACL of an object in a Data Model](common-workflows/mosaic/manage-data-model-object-acl/retrieve-a-data-model-object-acl.md). +- [Update ACL of an object in a Data Model](common-workflows/mosaic/manage-data-model-object-acl/update-a-data-model-object-acl.md). + ## Strategy ONE (July 2025) - [Project duplication across environments](common-workflows/administration/project-duplication/cross-env-project-duplication.md). Duplicate a project across two environments. diff --git a/sidebars.js b/sidebars.js index a458ed74..daa70480 100644 --- a/sidebars.js +++ b/sidebars.js @@ -1087,6 +1087,68 @@ const sidebars = { }, ], }, + { + type: "category", + label: "Mosaic", + link: { + type: "doc", + id: "common-workflows/mosaic/mosaic", + }, + items: [ + { + type: "category", + label: "Publish data models", + link: { + type: "doc", + id: "common-workflows/mosaic/publish/manage-data-model-publish", + }, + items: [ + "common-workflows/mosaic/publish/refresh-a-data-model", + "common-workflows/mosaic/publish/schedule-refresh-a-data-model", + ], + }, + { + type: "category", + label: "Manage data model security filter objects", + link: { + type: "doc", + id: "common-workflows/mosaic/manage-data-model-security-filter-objects/manage-data-model-security-filter-objects", + }, + items: [ + "common-workflows/mosaic/manage-data-model-security-filter-objects/create-a-security-filter-object-in-data-model", + "common-workflows/mosaic/manage-data-model-security-filter-objects/update-a-security-filter-object-in-data-model", + "common-workflows/mosaic/manage-data-model-security-filter-objects/retrieve-a-security-filter-definition-in-data-model", + "common-workflows/mosaic/manage-data-model-security-filter-objects/retrieve-all-security-filters-in-data-model", + "common-workflows/mosaic/manage-data-model-security-filter-objects/retrieve-a-security-filters-member-in-data-model", + "common-workflows/mosaic/manage-data-model-security-filter-objects/modify-a-security-filters-member-in-data-model", + "common-workflows/mosaic/manage-data-model-security-filter-objects/delete-a-security-filter-object-in-data-model", + ], + }, + { + type: "category", + label: "Manage data model attributes objects", + link: { + type: "doc", + id: "common-workflows/mosaic/manage-data-model-attribute-objects/manage-data-model-attribute-objects", + }, + items: [ + "common-workflows/mosaic/manage-data-model-attribute-objects/retrieve-an-attributes-elements-in-data-model", + ], + }, + { + type: "category", + label: "Manage data model object acl", + link: { + type: "doc", + id: "common-workflows/mosaic/manage-data-model-object-acl/manage-data-model-object-acl", + }, + items: [ + "common-workflows/mosaic/manage-data-model-object-acl/retrieve-a-data-model-object-acl", + "common-workflows/mosaic/manage-data-model-object-acl/update-a-data-model-object-acl", + ], + }, + ], + }, ], }, {