Version 2020

Metric Expression Prompts

The metric expression element prompt is one of the most commonly used prompt types. It allows the caller to provide an expression to filter the date in a report or dossier. For example, you can define a prompt as Get data when Avg Revenue per Customer is greater than 10.

Use REST APIs to perform the following actions on metric expression prompts:

Get Information About a Metric Expression Prompt

Use the following REST API endpoints to get information about metric expression prompts applied to dossier, document, and report objects in the metadata, as well as instances of those objects:

  • GET /documents/{id}/prompts
  • GET /documents/{id}/instances/{instanceId}/prompts
  • GET /reports/{reportId}/prompts
  • GET /reports/{reportId}/instances/{instanceId}/prompts

Provide the ID of the document, dossier, or report in the path of the request. You also need to provide the instance ID if you are getting information about a prompt applied to an instance of a document, dossier, or report. The response contains the prompt information. All available parameters for the prompt definition are shown below.

Location Name Description Data Type
  id The ID of the prompt string

 

key

The unique key of the prompt. Including the key helps avoid issues when the same prompt is present multiple times on a dossier, document, or report.

string

  name The name of the prompt string

 

title

The title of the prompt

string

 

type

The type of prompt

Enum: [ VALUE, ELEMENTS, EXPRESSION, OBJECTS, LEVEL ]

striing

  required An indicator that specifies if a prompt is required boolean
  closed An indicator that specifies if a prompt is closed boolean

The sample code below contains a metric expression prompt definition in a format that is supported by the API.

{
    "key": "12FF3D5D43A6A17E8847FB9304FEA1E1@0@10",
    "name": "test prompt",
    "title": "test prompt",
    "type": "EXPRESSION",
    "required": true,
    "closed": false,
    "max": 2,
    "min": 1,
    "defaultAnswer": {
        "content": "{Avg Revenue per Customer} > 10",
        "expression": {
            "level": {
                "type": "attribute",
                "objects": [
                    {
                        "id": "4C05177011D3E877C000B3B2D86C964F",
                        "name": "day"
                    }
                ]
            },
            "operator": "Greater",
            "operands": [
                {
                    "type": "metric",
                    "id": "4C05177011D3E877C000B3B2D86C964F",
                    "name": "Revenue"
                },
                {
                    "type": "constant",
                    "dataType": "Real",
                    "value": "10"
                }
            ]
        }
    },
    "answers": {
        "content": "{Avg Revenue per Customer} > 10",
        "expression": {
            "level": {
                "type": "attribute",
                "objects": [
                    {
                        "id": "4C05177011D3E877C000B3B2D86C964F",
                        "name": "day"
                    }
                ]
            },
            "operator": "Greater",
            "operands": [
                {
                    "type": "metric",
                    "id": "4C05177011D3E877C000B3B2D86C964F",
                    "name": "Revenue"
                },
                {
                    "type": "constant",
                    "dataType": "Real",
                    "value": "10"
                }
            ]
        }
    }
}

The sample code below contains a metric expression prompt definition in a format that is not supported by the API.

{
    "key": "12FF3D5D43A6A17E8847FB9304FEA1E1@0@10",
    "name": "test prompt",
    "title": "test prompt",
    "type": "EXPRESSION",
    "required": true,
    "max": 2,
    "min": 1,
    "defaultAnswer": { 
     	"content": "{Avg Revenue per Customer} > 10",
        "xml": "xml": "<exp nc="3">{Avg Revenue per Customer} > 10 <nd et="10" nt="4" dmt="7" ddt="-1" is_indp_csi="1" cc="2"><nd et="1" nt="5" dmt="1" ddt="-1" is_indp_csi="1" cc="0"><mt rfd="9">Avg Revenue per Customer</mt></nd><nd et="1" nt="3" dmt="1" ddt="3" is_indp_csi="1" cc="0"><cst ddt="5">10</cst></nd><op fnt="8" fg="0" apply_order="0" node="0"/></nd></exp>"
    },
    "answers":{ 
     	"content": "{Avg Revenue per Customer} > 10",
        "xml": "xml": "<exp nc="3">{Avg Revenue per Customer} > 10 <nd et="10" nt="4" dmt="7" ddt="-1" is_indp_csi="1" cc="2"><nd et="1" nt="5" dmt="1" ddt="-1" is_indp_csi="1" cc="0"><mt rfd="9">Avg Revenue per Customer</mt></nd><nd et="1" nt="3" dmt="1" ddt="3" is_indp_csi="1" cc="0"><cst ddt="5">10</cst></nd><op fnt="8" fg="0" apply_order="0" node="0"/></nd></exp>"
    }
  }

Besides the commonly-used fields, the metric expression prompt also contains the fields shown below.

Field Description
min The minimum number of qualifications that must be supplied to answer the prompt. The qualification here has the same meaning as operator.

max

The maximum number of qualifications that can be supplied to answer the prompt.
defaultAnswer

 

content Describes the default answer expression's content.

expression

Reuse the JSON Data API view filter's format. This field appears when the prompt's expression is supported by the prompt.
xml

The xml that represents the prompt's expression. This field appears when the prompt's expression is not supported.

answers

 

content

Describes the answer expression's content.
expression Reuse the JSON Data API view filter's format. This field appears when the prompt's expression is supported by the prompt.

xml

The xml that represents the prompt's expression. This field appears when the prompt's expression is not supported.

Get the Metric Expression Prompt's Available Answer

Use the following REST API endpoint to get a metric expression prompt's available answer:

GET /reports/{reportId}/instances/{instanceId}/prompts/{promptIdentifier}/objects

The metric this endpoint returns can be used when you generate the expression to answer the prompt. The operator should work on metrics.

The sample code below contains a metric expression prompt's available answer.

{
    "objects": [
        {
            "name": "Profit",
            "id": "4C051DB611D3E877C000B3B2D86C964F",
            "type": "metric"
        }
    ]
}

Answer a Metric Expression Prompt

Use the following REST API endpoints to answer a metric expression prompt applied to a dossier, document, or report:

  • PUT /documents/{id}/instances/{instanceId}/prompts/answers
  • PUT /reports/{reportId}/instances/{instanceId}/prompts/answers

Provide Specific Prompt Answers

You provide answers to a metric expression prompt in the body parameter of the request. Identify the prompt by providing the prompt ID, name or key, and specify the prompt type as EXPRESSION. Then, specify the expression used to answer the prompt. The format of the expression is the same as the JSON Data API's view filter. Only metric qualification operators are supported for metric expression prompts.

All available parameters for the prompt answer are shown below.

Location Name Description Data Type Required?
  key

The unique key of the prompt. Including the key helps avoid issues when the same prompt is present multiple times on a dossier, document, or report.

string  
  id The object ID of the prompt

string

 
  name The name of the prompt string  

 

type

The type of prompt

Enum: [ VALUE, ELEMENTS, EXPRESSION, OBJECTS, LEVEL ]

string

ü

  useDefault An indicator that specifies if the default answer should be used. If this is set to true, the values are ignored. boolean  

The sample code below answers a metric expression prompt.

{
    "prompts": [
        {
            "id": "753C65EB402C44D3A991F285D3CB7F6D",
            "key": "753C65EB402C44D3A991F285D3CB7F6D@0@10",
            "name": "test",
            "useDefault": false,
            "type": "EXPRESSION",
            "answers": {
                "content": "{Avg Revenue per Customer} > 10",
                "expression": {
                    "level": {
                        "type": "attribute",
                        "objects": [
                            {
                                "id": "4C05177011D3E877C000B3B2D86C964F",
                                "name": "day"
                            }
                        ]
                    },
                    "operator": "Greater",
                    "operands": [
                        {
                            "type": "metric",
                            "id": "4C05177011D3E877C000B3B2D86C964F",
                            "name": "Revenue"
                        },
                        {
                            "type": "constant",
                            "dataType": "Real",
                            "value": "10"
                        }
                    ]
                }
            }
        }
    ]
}

Since some operations are not supported in the JSON Data API view filter, we provide a way for you to use XML to answer the prompt, as shown in the code sample below.

{
    "prompts": [
        {
            "id": "753C65EB402C44D3A991F285D3CB7F6D",
            "key": "753C65EB402C44D3A991F285D3CB7F6D@0@10",
            "name": "test",
            "useDefault": false,
            "type": "EXPRESSION",
            "answers": {
                "content": "{Avg Revenue per Customer} > 10",
                "xml": "<exp nc="3">{Avg Revenue per Customer} > 10 <nd et="10" nt="4" dmt="7" ddt="-1" is_indp_csi="1" cc="2"><nd et="1" nt="5" dmt="1" ddt="-1" is_indp_csi="1" cc="0"><mt rfd="9">Avg Revenue per Customer</mt></nd><nd et="1" nt="3" dmt="1" ddt="3" is_indp_csi="1" cc="0"><cst ddt="5">10</cst></nd><op fnt="8" fg="0" apply_order="0" node="0"/></nd></exp>"
            }
        }
    ]
}

Some things to keep in mind:

  • You only need to provide one id, key, or name. Key is preferred.
  • The useDefault field is optional, since the default value is false.
  • Content in the answer is optional. Its values do not affect the resulting answer. The default value is "".

A lighter version of the sample code is provided below.

{
    "prompts": [
        {
            "key": "753C65EB402C44D3A991F285D3CB7F6D@0@10",
            "type": "EXPRESSION",
            "answers": {
                "expression": {
                    "level": {
                        "type": "attribute",
                        "objects": [
                            {
                                "id": "4C05177011D3E877C000B3B2D86C964F",
                                "name": "day"
                            }
                        ]
                    },
                    "operator": "Greater",
                    "operands": [
                        {
                            "type": "metric",
                            "id": "4C05177011D3E877C000B3B2D86C964F",
                            "name": "Revenue"
                        },
                        {
                            "type": "constant",
                            "dataType": "Real",
                            "value": "10"
                        }
                    ]
                }
            }
        }
    ]
}