This documentation supports the 19.11 version of Remedy Action Request System, which is available only to BMC Helix subscribers (SaaS).
To view an earlier version, select the version from the Product version menu.

Retrieving menu details by using AR REST API

To retrieve all of the information in a menu, such as labels and values, use GetMenu and ExpandMenu endpoints. The GetMenu and ExpandMenu endpoints help to perform faster design level integration between a Remedy application and a third-party application without using Remedy Developer Studio. 

For example, you have a menu that displays continents in the world. When you select a continent, another menu asks you to select a specific country. You can use the GetMenu endpoint to retrieve metadata of the Continent menu. Later you can use the ExpandMenu endpoint to retrieve details of the Continent menu.

Prerequisites 

  • Before using the GetMenu endpoint, you must use the getField endpoint to retrieve field metadata.
  • Before using the ExpandMenu endpoint, you must use the GetMenu endpoint to retrieve menu metadata for a menu.

GET

The details of the GET operation to retrieve menu metadata are listed below: 

DescriptionThe GetMenu API takes the name of the menu and the menu criteria as input and returns the menu properties, such as the menu content.
URL qualifier

/menu/{MenuName}?menu_criteria=criteria1,criteria2...

MenuName — Specify the name of the menu that you want to retrieve.

Syntax

http://<AR Server host>:<Port number>/api/arsys/v1.0/menu/{MenuName}?menu_criteria=criteria1,criteria2...

Example

Retrieve menu metadata for Menu1.

http://<AR Server host>:<Port number>/api/arsys/v1.0/menu/Menu1

Retrieve limited metadata for Menu1 that matches the LAST_CHANGED criteria.

http://<AR Server host>:<Port number>/api/arsys/v1.0/menu/Menu1?menu_criteria=LAST_CHANGED

MethodGET
Headers
Header nameValue
AuthorizationAR-JWT <token>
Content-Typeapplication/json
(optional) X-AR-Client-TypeClient Type ID
(optional) X-AR-RPC-QueueRPC queue to which the client calls are routed
(optional) X-AR-Timeout

Timeout (in seconds) for REST request

Default value —120 seconds

Parameters
Parameter nameDescription
menu_criteria

The API returns the requested data if you provide the criteria. To specify the criteria, use the following values:

  • MENU_DEFINITION
  • HELP_TEXT
  • CHANGE_DIARY
  • PROPERTY_LIST
  • OWNER
  • LAST_CHANGED
  • TIME_STAMP
ReturnsMenu metadata in JSON format
Error codes

If the request is not successful, one of the following error codes is returned:

  • 400 - Request body is incorrect
  • 403 - Forbidden
  • 404 - Menu does not exist
  • 500 - Internal Server Error

For more information, see HTTP status codes.

Example of response header for Get method

Date →<Current server date>
X-Frame-Options →SAMEORIGIN
Content-Security-Policy →frame-ancestors 'self'
X-Content-Type-Options →nosniff
X-XSS-Protection →1; mode=block
Status →200
X-AR-TR-Core-Id →evANniBcScqSEwE2LSxZIB
X-AR-TR-Counter →1
Content-Type →application/json
Cache-Control →no-store
Content-Length →406

Sample response for different menu types


    {  "menu_name": "<Menu Name>",
      "refresh_code": "<Refresh Code>",
      "help_text": "<Help text for the menu>",
      "owner": "<Owner Username>",
      "last_changed_by": "<Last change by Username>",
      "menu_type": "QUERY",
      "change_history": [
        {
          "changed_by":
    "<UserName>",
          "changed_time": "<Timestamp>",
          "text":
    "<Text>"
        },
        ...
      ],
      "properties": [
        {
          "<key>":
    "<value>"
        },
        ...
      ],
      "menu_information": {
        "form_name": "<Form Name>",
        "server_name": "<Server Name>",
        "label_fields": [
          "<field id1>",
          "<field id2>"
        ],
        "value_field_id": "<field id>",
        "sort_on_label":
    "<TRUE/FALSE>",
        "qualification_string":
    "<Qualification string>",
        "qualification_current_fields" :
    [
          "<current_field1>",
          "<current_field2>"  
        ],
        "qualification_keywords" : [
          "<keyword1>",
          "<keyword2>"  
        ],    
        "sample_form_name": "",
        "sample_server_name":
    ""
      },
      "_links": {
            "self": [
                {
                    "href": "<Get Menu url>"
                }
            ]
        }
    }


    {
      "menu_name": "<Menu Name>",
      "refresh_code": "<Refresh Code>",
      "help_text": "<Help text for the menu>",
      "owner": "<Owner Username>",
      "last_changed_by": "<Last change by Username>",
      "menu_type": "QUERY",
      "change_history": [
        {
          "changed_by": "<UserName>",
          "changed_time": "<Timestamp>",
          "text": "<Text>"
        },
        ...
      ],
      "properties": [
        {
          "<key>": "<value>"
        },
        ...
      ],
      "menu_information": {
            "server_name": "<Server Name>",
            "label_index": "<Label Index>",
            "value_index": "<Value Index>",
            "sql_command": "<Sql query>"
       },
      "_links": {
            "self": [
                {
                    "href": "<Get Menu url>"
                }
            ]
        }
    }


    {
      "menu_name": "<Menu Name>",
      "refresh_code": "<Refresh Code>",
      "help_text": "<Help text for the menu>",
      "owner": "<Owner Username>",
      "last_changed_by": "<Last change by Username>",
      "menu_type": "QUERY",
      "change_history": [
        {
          "changed_by": "<UserName>",
          "changed_time": "<Timestamp>",
          "text": "<Text>"
        },
        ...
      ],
      "properties": [
        {
          "<key>": "<value>"
        },
        ...
      ],    
            "menu_information": {
            "menu_items": [
                   {
                           "label": "",
                           "value": ""
                   }
            ]
            },
      "_links": {
            "self": [
                {
                    "href": "<Get Menu url>"
                }
            ]
        }
    }


    {
      "menu_name": "<Menu Name>",
      "refresh_code": "<Refresh Code>",
      "help_text": "<Help text for the menu>",
      "owner": "<Owner Username>",
      "last_changed_by": "<Last change by Username>",
      "menu_type": "QUERY",
      "change_history": [
        {
          "changed_by": "<UserName>",
          "changed_time": "<Timestamp>",
          "text": "<Text>"
        },
        ...
      ],
      "properties": [
        {
          "<key>": "<value>"
        },
        ...
      ],   
           "menu_information": {
           "server_name": "<Server Name>",
           "name_type": "<Name Type>",
           "value_format": "<Value Format>",
           "schema_type": "<Schema Type>",
           "include_hidden_form": "TRUE/FALSE"
       },
      "_links": {
            "self": [
                {
                    "href": "<Get Menu url>"
                }
            ]
        }
    }


    {
        "menu_name": "<Menu Name>",
      "refresh_code": "<Refresh Code>",
      "help_text": "<Help text for the menu>",
      "owner": "<Owner Username>",
      "last_changed_by": "<Last change by Username>",
      "menu_type": "QUERY",
      "change_history": [
        {
          "changed_by": "<UserName>",
          "changed_time": "<Timestamp>",
          "text": "<Text>"
        },
        ...
      ],
      "properties": [
        {
          "<key>": "<value>"
        },
        ...
      ],
        "menu_information": {
            "location": "<location 1/2>",
            "file_name": "<file name>"
       },
      "_links": {
            "self": [
                {
                    "href": "<Get Menu url>"
                }
            ]
        }
    }

    Expand Menu

    After retrieving the menu metadata by using the GetMenu endpoint, use the ExpandMenu endpoint to retrieve the menu details.

    For example, when you retrieve metadata of the Continent menu, use the ExpandMenu endpoint to retrieve details, such as list of countries in each continent.

     The Expand Menu operation to retrieve details about menu items are listed below: 

    DescriptionThe ExpandMenu API takes the name of the menu as a path parameter and returns the expanded menu content in response.
    URL qualifier

    /api/arsys/v1.0/menu/expand

    Request body

    JSON object

    Syntax

    http://<AR Server host>:<Port number>/api/arsys/v1.0/menu/expand

    Example

    Expand menu for the Company_Details menu name.

    http://<AR Server host>:<Port number>/api/arsys/v1.0/menu/expand

    {
    	"name": "Company_Details"	
    }
    MethodPOST
    Headers
    HeaderValue
    Authorizationtoken
    Content-Typeapplication/json
    (optional) X-AR-Client-TypeClient Type ID
    (optional) X-AR-RPC-QueueRPC queue to which the client calls are routed
    (optional) X-AR-Timeout

    Timeout (in seconds) for REST request

    Default value —120 seconds

    ReturnsMenu items in JSON format
    Error codes

    If the request is not successful, one of the following error codes is returned:

    • 400 - Request body is incorrect
    • 403 - Forbidden
    • 404 - Form does not exist
    • 500 - Internal Server Error

    For more information, see HTTP status codes.

    Example of response header for the expand menu request

    Date →<Current server date>
    X-Frame-Options →SAMEORIGIN
    Content-Security-Policy →frame-ancestors 'self'
    X-Content-Type-Options →nosniff
    X-XSS-Protection →1; mode=block
    Status →200
    X-AR-TR-Core-Id →8Z0KEnv6Q2i-luK-JWYNAw
    X-AR-TR-Counter →1
    Content-Type →application/json
    Cache-Control →no-store
    Transfer-Encoding →chunked

    Example of JSON for the expand menu request

    To evaluate a qualification, you must specify the qualification_substitute_info key in the query menu.

    {
      "name": "TestQueryMenu_dfb88",
      "qualification_substitute_info": {
        "form_name": "TestForm_dfb88",
        "field_values": {
          "536870915": 100
        },
        "keyword_values": {
          "USER": "Demo"
        }
      },
      "max_entries": 5,
      "total_count": true
    }

    Response after menu expansion

    {
      "items": [
        {
          "type": "Value",
          "label": "Data10",
          "value": "180"
        },
        {
          "type": "Value",
          "label": "Data2",
          "value": "100"
        },
        {
          "type": "Value",
          "label": "Data4",
          "value": "120"
        },
        {
          "type": "Value",
          "label": "Data5",
          "value": "130"
        },
        {
          "type": "Value",
          "label": "Data6",
          "value": "140"
        }
      ],
      "total_count": 7
    }

    Example of multi-level menu expansion

    {   
    "items": [       
    {           
    "type": "Value",           
    "label": "Assigned To",           
    "value": "Assigned To"       
    },       
    {           
    "type": "Value",           
    "label": "Create Date",           
    "value": "Create Date"       
    },       
    {          
    "type": "Value",           
    "label": "Last Modified By",           
    "value": "Last Modified By"       
    },       
    {           
    "type": "Value",           
    "label": "Modified Date",           
    "value": "Modified Date"       
    },       
    {           
    "type": "Value",           
    "label": "Qualification",           
    "value": "Qualification"       
    },       
    {           
    "type": "Value",           
    "label": "Request ID",           
    "value": "Request ID"       
    },       
    {           
    "type": "Value",           
    "label": "Short Description",           
    "value": "Short Description"       
    },       
    {          
    "type": "Value",           
    "label": "Status",           
    "value": "Status"       
    },       
    {           
    "type": "SubMenu",           
    "label": "Status History",           
    "content": [               
    {                   
    "type": "Value",                   
    "label": "Status History",                   
    "value": "Status History"            
       },               
    {                   
    "type": "SubMenu",                   
    "label": "TIME",                   
    "content": [                       
    {                           
    "type": "Value",                           
    "label": "New",       
    "value": ""                       
    },                       
    {                           
    "type": "Value",                           
    "label": "Assigned",                           
    "value": ""                       
    },                       
    {                           
    "type": "Value",                           
    "label": "Fixed",                           
    "value": ""                       
    },                       
    {                  
     type":
    "Value",                           
    "label": "Rejected",                           
    "value": ""                       
    },                      
    {                           
    "type": "Value",                           
    "label": "Closed",                           
    "value": ""                      
    }                   
    ]               
    },               
    {                   
    "type": "SubMenu",                   
    "label": "USER",                  
    "content": [                 
          {                           
    "type": "Value",                           
    "label": "New",                          
    "value": ""                       
    },                       
    {                           
    "type": "Value",                           
    "label": "Assigned",                           
    "value": ""                       
    },                       
    {                           
    "type": "Value",                           
    "label": "Fixed",                   
    "value": ""                       
    },                       
    {                         
    "type": "Value",                           
    "label": "Rejected",                           
    "value": ""                      
    },                       
    {                           
    "type": "Value",                           
    "label": "Closed",                           
    "value": ""                       
    }                   
    ]               
    }           
    ]       
    },       
    {           
    "type": "Value",           
    "label": "Submitter",           
    "value": "Submitter"       
    }   
    ]
    }

    Related topics

    Retrieving field metadata using REST API

    REST operations on AR System forms

    Endpoints in AR REST API




    Was this page helpful? Yes No Submitting... Thank you

    Comments