Skip to main content

Hierarchy qualification prompts

Available since 2021 Update 1

A hierarchy qualification prompt allows users to filter data in a report or document based on the qualification of multiple attributes from the hierarchies. For example, you can determine a single hierarchy or list of hierarchies from which users can select attributes and make qualifications on these attributes to define their filters.

Use REST APIs to perform the following actions on hierarchy qualification prompts:

Get information about a hierarchy qualification prompt​

Use the following REST API endpoints to get information about hierarchy qualification 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

Provide the ID of the document, dashboard, or report in the path of the request. In addition, you need to supply 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. All available parameters for the prompt definition are shown below.

NameDescriptionData Type
idThe ID of the promptstring
keyThe unique key of the prompt. Including the key helps avoid issues when the same prompt is present multiple times on a dashboard, document, or report.string
nameThe name of the promptstring
titleThe title of the promptstring
typeThe type of prompt; Enum: [ VALUE, ELEMENTS, EXPRESSION, OBJECTS, LEVEL ]string
requiredAn indicator that specifies if a prompt is requiredboolean
closedAn indicator that specifies if a prompt is closedboolean

The sample code below contains a hierarchy qualification prompt definition.

{
  "key": "12FF3D5D43A6A17E8847FB9304FEA1E1@0@10",
  "id": "12FF3D5D43A6A17E8847FB9304FEA1E1",
  "name": "test prompt",
  "title": "test prompt",
  "type": "EXPRESSION",
  "closed": false,
  "required": true,
  "max": 2,
  "min": 1,
  "displayForms": "all", // all|browseForms|reportDisplayForms|customForms
  "maxElementsPerSelection": -1,
  "defaultAnswer": {
    "content": "Category ID In 1, 2, 3, 4, 5",
    "xml": "<exp></exp>",
    "expression": {
      "operator": "In",
      "operands": [
        {
          "type": "form",
          "attribute": {
            "id": "8D679D3711D3E4981000E787EC6DE8A4",
            "name": "Category"
          },
          "form": {
            "id": "45C11FA478E745FEA08D781CEA190FE5",
            "name": "ID"
          }
        },
        {
          "type": "constants",
          "dataType": "Real",
          "values": ["1", "2", "3", "4", "5"]
        }
      ]
    }
  },
  "answers": {
    "content": "Category In List Books, Movies",
    "xml": "<exp></exp>",
    "expression": {
      "operator": "In",
      "operands": [
        {
          "type": "attribute",
          "id": "8D679D3711D3E4981000E787EC6DE8A4",
          "name": "Category"
        },
        {
          "type": "elements",
          "elements": [
            {
              "id": "h1;8D679D3711D3E4981000E787EC6DE8A4",
              "name": "Books"
            },
            {
              "id": "h2;8D679D3711D3E4981000E787EC6DE8A4",
              "name": "Electronics"
            }
          ]
        }
      ]
    }
  }
}

Besides the commonly-used fields, the hierarchy qualification prompt also contains the following field:

maxElementsPerSelection The maximum number of elements that can be supplied to answer the prompt per selection. The default setting of -1 means there is no limit to the maximum number of elements.

Get the hierarchy qualification prompt's available objects​

Use the following REST API endpoints to get a hierarchy qualification prompt's available objects:

  • GET /api/reports/{id}/instances/{instanceId}/prompts/{promptIdentifier}/objects
  • GET /api/documents/{id}/instances/{instanceId}/prompts/{promptIdentifier}/objects

In a hierarchy qualification prompt, the available objects returned by this endpoint are hierarchies, which contain an ID and name. The hierarchy prompt provides the user with a list of available objects. These objects can come from three different sources:

  • Predefined list of objects
  • Result of a search object
  • List of all attributes and hierarchies

The sample code below contains a hierarchy qualification prompt's available objects.

{
  "objects": [
    {
      "id": "C11D3E4981000E8D679D3787EC6DE8A4",
      "name": "Time",
      "type": "HIERARCHY"
    }
  ]
}

Get the attributes of a hierarchy​

After getting a hierarchy qualification prompt's available objects, the user may need to get the attributes of some hierarchies to construct their own view filter expression. Use the following REST API endpoints to retrieve the attributes of a hierarchy.

GET /api/hierarchies/{hierarchyId}/attributes

The sample code below contains the definition of the attributes of a hierarchy.

{
  "attributes": [
    {
      "name": "Month",
      "id": "8D679D4411D3E4981000E787EC6DE8A4",
      "type": "attribute",
      "forms": [
        {
          "id": "45C11FA478E745FEA08D781CEA190FE5",
          "name": "ID"
        },
        {
          "id": "CCFBE2A5EADB4F50941FB879CCF1721C",
          "name": "DESC"
        },
        {
          "id": "4B97DFC611D5AEDAC000E38A4CC5F24F",
          "name": "DATE"
        }
      ]
    }
  ]
}

Answer a hierarchy qualification prompt​

Use the following REST API endpoints to answer a hierarchy qualification prompt applied to a dashboard, document, or report:

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

Provide specific prompt answers​

You provide answers to a hierarchy qualification 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. This expression can be used with attribute elements.

All available parameters for the prompt answer are shown below.

NameDescriptionData TypeRequired?
keyThe unique key of the prompt. Including the key helps avoid issues when the same prompt is present multiple times on a dashboard, document, or report.string
idThe object ID of the promptstring
nameThe name of the promptstring
typeThe type of prompt; Enum: [ VALUE, ELEMENTS, EXPRESSION, OBJECTS, LEVEL ]stringyes
useDefaultAn 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 an attribute qualification prompt.

{
  "prompts": [
    {
      "key": "12FF3D5D43A6A17E8847FB9304FEA1E1@0@10",
      "id": "12FF3D5D43A6A17E8847FB9304FEA1E1",
      "name": "test prompt",
      "type": "EXPRESSION",
      "answers": {
        "content": "Category In List 1, 2, 3, 4, 5",
        "expression": {
          "operator": "In",
          "operands": [
            {
              "type": "form",
              "attribute": {
                "id": "8D679D3711D3E4981000E787EC6DE8A4",
                "name": "Category"
              },
              "form": {
                "id": "45C11FA478E745FEA08D781CEA190FE5",
                "name": "ID"
              }
            },
            {
              "type": "constants",
              "dataType": "Real",
              "values": ["1", "2", "3", "4", "5"]
            }
          ]
        }
      }
    }
  ]
}

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 "".