Default language.

Example of using the REST API to retrieve menu details

To retrieve all 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 . 

For example, assume 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.

Related topics

Example-of-using-the-REST-API-to-retrieve-field-metadata

Learning-about-the-REST-API

Endpoints-in-AR-REST-API

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 menu

The GetMenu API takes the name of the menu and the menu criteria as input and returns the menu properties, such as the menu content. The following table lists details about using this GET operation to retrieve menu metadata.

URL qualifier

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

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

Syntax

http://ARSystemServerHost:portNumber/api/arsys/v1.0/menu/{MenuName}?menu_criteria=criteria1,criteria2...

Example


Retrieve menu metadata for Menu1:


http://ARSystemServerHost:portNumber/api/arsys/v1.0/menu/Menu1


Retrieve limited metadata for Menu1 that matches the LAST_CHANGED criteria:


http://ARSystemServerHost:portNumber/api/arsys/v1.0/menu/Menu1?menu_criteria=LAST_CHANGED

Method

GET

Headers

Header name

Value

Authorization

AR-JWT <token>

Content-Type

application/json

(Optional) X-AR-Client-Type

Client Type ID

(Optional) X-AR-RPC-Queue

RPC queue to which the client calls are routed

(Optional) X-AR-Timeout

Timeout (in seconds) for REST request

Default value —120 seconds

Parameters

Parameter name

Description

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

Returns

Menu 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 Error-handling-for-the-REST-API.

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 ExpandMenu API takes the name of the menu as a path parameter and returns the expanded menu content in response. The following table lists details about this operation.

Description

The 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://ARSystemServerHost:portNumber/api/arsys/v1.0/menu/expand

Example

Expand menu for the Company_Details menu name.

http://ARSystemServerHost:portNumber/api/arsys/v1.0/menu/expand

{
"name": "Company_Details"
}

Method

POST

Headers

Header

Value

Authorization

token

Content-Type

application/json

(Optional) X-AR-Client-Type

Client Type ID

(Optional) X-AR-RPC-Queue

RPC queue to which the client calls are routed

(Optional) X-AR-Timeout

Timeout (in seconds) for REST request

Default value —120 seconds

Returns

Menu 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 Error-handling-for-the-REST-API.

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 multilevel 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"       
}   
]
}

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*