Example of using the REST API to retrieve menu details

Use GetMenu and ExpandMenu endpoints to retrieve all the information in a menu, such as labels and values.

The GetMenu and ExpandMenu endpoints help to perform faster design-level integration between an AR System application and a third-party application without using Developer Studio.

Example: You have a menu that displays the continents in the world. When you select a continent, another menu will ask 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

Integrating-AR-System-forms-with-a-third-party-application-by-using-the-REST-API

Endpoints-in-AR-REST-API

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 the details about using the 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

Retrieves menu metadata for Menu1:

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


Retrieves 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 a REST request

The default value is 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 the JSON format

Error codes

If the request is not successful, one of the following error code 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 a 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 the response. The following table lists the details of the operation:

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 a REST request

The default value is 120 seconds.

Returns

Menu items in the JSON format

Error codes

If the request is not successful, one of the following error code 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*