Value prompts

Available since 2021 Update 1

tip

You can try out this workflow at REST API Playground.

Learn more about MicroStrategy REST API Playground here.

A value prompt allows the results to be filtered based on a specific value, such as a specific date, number, or word/phrase.

You can use REST APIs to perform the following action on value prompts:

• Answer a value prompt
  • Provide specific prompt answers
• Get information about a value prompt
• Value prompt definition
• Possible prompt execution errors for value prompts

Answer a value prompt

You use the following REST API endpoints to answer a value prompt applied to a dashboard, document, or report:

• PUT /api/documents/{id}/instances/{instanceId}/prompts/answers

• PUT /api/reports/{reportId}/instances/{instanceId}/prompts/answers

Provide specific prompt answers

You provide answers to a value prompt in the body parameter of the request. You must provide the prompt ID and specify the prompt type as "VALUE".

Sample code for answering a value prompt for each data type is provided below:

• Numeric prompt

  {
    "prompts": [
      {
        "key": "9BC4631D436CAA78D7A70AB2D0635D88@0@10",
        "type": "VALUE",
        "answers": "2015"
      }
    ]
  }

• Date prompt

  {
    "prompts": [
      {
        "key": "A46842D548C3F0CEEDD3979528480FE5@0@10",
        "type": "VALUE",
        "answers": "2017-09-27T23:37:39.000+0000"
      }
    ]
  }

• Text prompt

  {
    "prompts": [
      {
        "key": "CF604AA948AF21CBC67AF98FBA614E0F@0@10",
        "type": "VALUE",
        "answers": "q"
      }
    ]
  }

• Big decimal

  {
    "prompts": [
      {
        "key": "6F96306444CD3F2597B3FF92E2220356@0@10",
        "type": "VALUE",
        "answers": "123"
      }
    ]
  }

Get information about a value prompt

You use the following REST API endpoints to get information about value prompts applied to dashboard, document, and report objects in the metadata, as well as instances of those objects:

• GET /api/documents/{id}/prompts

• GET /api/documents/{id}/instances/{instanceId}/prompts

• GET /api/reports/{reportId}/prompts

• GET /api/reports/{reportId}/instances/{instanceId}/prompts

You provide the ID of the document, dashboard, or report in the path of the request, as well as the instance ID if you are getting information about a prompt applied to an instance of a document, dashboard, or report. The response contains the prompt information.

Value prompt definition

The model for the definition of a value prompt can be represented with the following fields:

• id GUID of the prompt.
• name Name of the prompt. This is the most user-friendly value that can be used to identify the prompt.
• key Unique identifier of the prompt. It is important to use this to identify the prompt if the same prompt is used more than once in the report, document or dashboard.
• title Title of the prompt.
• required Specifies whether this prompt is required or optional.
• type Prompt type. For value prompts, the value is "VALUE".
• min Minimum value of prompt answer.

tip

This value depends on the data type of the value prompt. It can be date, number, string, and so on.

• max Maximum value of prompt answer.

tip

This value depends on the data type of the value prompt. It can be date, number, string, and so on.

• defaultAnswer Default prompt answer

• answers Answer to be used for prompt.

• dataType Data type of prompt value (from EnumDSSXMLDataType). The following data types are supported by value prompts:

  • Numeric prompt
  • Date prompt
  • Text prompt
  • Big decimal

Sample JSON for a value prompt definition is provided below.

[
  {
    "id": "0CE45CA4483E29FFB0AF969D68588E95",
    "key": "0CE45CA4483E29FFB0AF969D68588E95@0@10",
    "name": "NamePrompt",
    "title": "Name Prompt",
    "type": "VALUE",
    "required": true,
    "answers": "Darren",
    "defaultAnswer": "Darren",
    "dataType": 8
  }
]

Sample code for the value prompt definition for each data type is provided below:

• Numeric prompt

  {
    "key": "9780961349394064B659679AA3D0A822@0@10",
    "name": "Value (Number)",
    "title": "Number",
    "type": "VALUE",
    "required": true,
    "max": 50,
    "min": 0.25,
    "dataType": "NUMERIC"
  }

• Date prompt

  {
    "key": "A46842D548C3F0CEEDD3979528480FE5@0@10",
    "name": "Value (Date)",
    "title": "Date",
    "type": "VALUE",
    "required": true,
    "max": "2018-09-26T23:37:39.000+0000",
    "min": "2018-09-26T23:37:39.000+0000",
    "answers": "2017-09-27T04:00:00.000+0000",
    "defaultAnswer": "2018-09-26T04:00:00.000+0000",
    "dataType": "DATE"
  }

• Text prompt

  {
    "key": "CF604AA948AF21CBC67AF98FBA614E0F@0@10",
    "name": "Value (Text)",
    "title": "Text",
    "type": "VALUE",
    "required": true,
    "max": 5,
    "min": 1,
    "answers": "q",
    "defaultAnswer": "ab",
    "dataType": "TEXT"
  }

• Big decimal

  {
    "key": "6F96306444CD3F2597B3FF92E2220356@0@10",
    "name": "Value (Big Decimal)",
    "title": "Big decimal",
    "type": "VALUE",
    "required": true,
    "max": 999999999999.4,
    "min": 0,
    "answers": 2000,
    "defaultAnswer": 12,
    "dataType": "NUMERIC"
  }

Possible prompt execution errors for value prompts

Numerous errors can occur during the prompt execution workflow, when answering prompts. Some of these are general errors, and others occur only for specific types of prompts. The errors listed below are specific to value prompts.

• Does not meet minimum date range

  HTTP - 400

  
  {
    "code": "ERR006",
    "message": "The date(2011-08-07T21:09:50.000+0000) provided for prompt name:
     Value (Date) key: 180E0FE14CA4A62957488C8EBE6FE321@0@10 does not meet the
     minimum date range specified(2012-10-08T21:09:50.000+0000) by the prompt",
    "ticketId": "6f5c692f3c294e0b95d2d02fd4a3402a"
  }

• Exceeds maximum date range

  HTTP - 400

  
  {
    "code": "ERR006",
    "message": "The date(2040-08-07T21:09:50.000+0000) provided for prompt name:
     Value (Date) key: 180E0FE14CA4A62957488C8EBE6FE321@0@10 exceeds the maximum
     date range specified(2012-10-08T21:09:50.000+0000) by the prompt",
    "ticketId": "1e8068d7ca044ba1abd828f473feb3d7"
  }

• Does not meet minimum value

  HTTP - 400

  
  {
    "code": "ERR006",
    "message": "The value(0.1456) provided for prompt name: Value (Number)
     key: 2CBAE32748F6ECE80617CF9A6B34003D@0@10 does not meet the minimum
     required value(0.999999999)",
    "ticketId": "7937c4d61aad4f34b9ae7433efe3237e"
  }

• Exceeds maximum value

  HTTP - 400

  
  {
    "code": "ERR006",
    "message": "The value(200000.99) provided for prompt name: Value (Number)
     key: 2CBAE32748F6ECE80617CF9A6B34003D@0@10 exceeds the maximum allowed
     value(100000.99}",
    "ticketId": "6f5c692f3c294e0b95d2d02fd4a3402a"
  }

• Text length too short

  HTTP - 400

  
  {
    "code": "ERR006",
    "message": "The number of characters provided for prompt name: Value (Text)
     key: CF604AA948AF21CBC67AF98FBA614E0F@0@10 does not meet the minimum
     required(2} text length.",
    "ticketId": "9c91e304e5a74881a8579230ea0d463c"
  }

• Text length too long

  HTTP - 400

  
  {
    "code": "ERR006",
    "message": "The number of characters provided for prompt name: Value (Text)
     key: CF604AA948AF21CBC67AF98FBA614E0F@0@10 exceeds the maximum allowed(5)
     text length.",
    "ticketId": "67fb558e27c34d6e816a8a17920a23eb"
  }