×
 
 
  •  
$helper.renderConfluenceMacro('{bmc-global-announcement:$space.key}')

This documentation supports the 20.02 version of Remedy Action Request (AR) System.

To view an earlier version, select the version from the Product version menu.


Remedy Action Request System 20.02 ... Developing an API program Integrating AR System forms with a third-party application by using the REST API Learning about the REST API

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 Remedy Developer Studio. 

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.

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

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

    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://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"	
}
    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 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"       
}   
]
}

    Related topics

    Example of using the REST API to retrieve field metadata

    Learning about the REST API

    Endpoints in AR REST API




    Was this page helpful? Yes No Submitting... Thank you
    Last modified by Anagha Deshpande on Aug 28, 2020
    integration menu menu_metadata menu_details learning rest_api

    Comments

    1. Amy Hicox

      thank you for this detailed documentation! Can you add detail on the qualification_substitute_info object? What keys are required in this object? What are their meaning?

      Oct 13, 2021 01:42
      1. Anagha Deshpande

        Hello Amy,

        Use the qualification_substitute_info object to fetch data from a form specified in the structure. Use form fields as keys in this object.

        Hope this helps.

        Regards,

        Anagha

        Nov 01, 2021 04:21
        1. Amy Hicox

          Truthfully, I'm not sure how helpful that is. Based on the naming, I sort of presumed that was it, but there are multiple forms and multiple fields involved with menus!

          let's say you've got two forms:

          • Recipe
          • Ingredient

          The Ingredient form contains supporting rows for the parent Recipe form. Say we want a menu on Recipe listing all of the associated Ingredient rows.

          On Recipe we have this field Recipe Name (536870919) and it has a unique index On Ingredient, we have this field Parent Recipe Name (536870920)

          we create a menu: menu_Ingredients, on the Ingredient form, with this qualification: 'Parent Recipe Name' = $536870919$

          then we place that menu on a field on the Recipe form, and when we view Recipe records, it will contain a list of the associated Ingredient records.

          from REST, if I'd like to retrieve the values of menu_Ingredients for the Recipe row where 'Recipe Name = "Cashew Chicken"' ... this is the qualification_substitute_info you'd need to use:

          { form_name: 'Recipe', field_values: { 536870919: 'Cashew Chicken' } }

          note that the form_name does NOT point to the form that the MENU is created against. It points to a form that you may have placed the menu on. NOTE ALSO that the keys of field_values are the VALUE fields in the qualification (i.e. $<someFieldID>$ not 'Parent Recipe Name', for instance)

          Also just by trial and error, I have found that you can't use 'Entry ID' (i.e. $1$) ... that one just doesn't seem to work at all. The server returns an empty string.

          This is far from the only issue that is totally unmentioned here. This needs to be spelled out in the documentation! How else will I know when ... say we upgreade ARS ... if the spec I wrote my code against is correct? If my code breaks how can I know if it's an error in my code or on the ARS side unless these things are explicitly spelled out?!

          Nov 16, 2021 12:57
          1. Anagha Deshpande

            Hello Amy,

            Apologies for the delayed response.

            Could you please try using the following qualification?

            { form_name: 'ingredient', field_values: { Field ID of the parent recipe name (536870920): 'Cashew Chicken' } }

            Hope this helps.

            Regards,

            Anagha

            Feb 08, 2022 03:19

    Log in or register to comment.

    Example of using the REST API to retrieve field metadata
    Example of using the REST API to merge entries
    © Copyright 1991-2021 BMC Software, Inc. © Copyright 1991-2021 BladeLogic, Inc.
    Legal notices

    Powered by Atlassian Confluence and Scroll Viewport

    © Copyright 2005-2024 BMC Software, Inc. Use of this site signifies your acceptance of BMC’s Terms of Use . BMC, the BMC logo, and other BMC marks are assets of BMC Software, Inc. These trademarks are registered and may be registered in the U.S. and in other countries.