This documentation supports the 9.0 version of Remedy Action Request System.

To view the latest version, select the version from the Product version menu.

Operations on entry objects

The REST API uses a resource to perform HTTP operations. A resource is an object with a type, associated data, relationships to other resources, and a set of methods that operate on it. The following are resources on which the actions are performed:

  • the form
  • an entry on a form
Type URL Actions
form /entry/{formName} Performs HTTP requests on just the form and allows you to create or search all entries on the form.
an entry on a form /entry/{formName}/{entryId} Performs HTTP requests on an entry on a form and allows you to get, modify, and delete that particular entry.

This section provides the following topics:

Supported operations

The following table explains the HTTP methods used in BMC Remedy AR System:

Operation Description URL HTTP method Equivalent API call
Get an entry Returns the details of an entry on a form. /entry/{formName}/{entryId} GET Get Entry
Get multiple entries Returns the details of all the entries on a form. /entry/{formName} GET Get List Entries With Fields
Get an attachment Returns an attachment for a particular entry or for the list of entries. /entry/{formName}/{entryId}/attach/{fieldName} GET not applicable
Get an association Returns the list of associated entries for a particular entry.  /entry/{formName}/{entryId}/assoc/{associationName} GET not applicable
Create an entry Creates new entry on the form. /entry/{formName} POST Create Entry
Merge an entry Merges an existing entry into a form. /mergeEntry/{formName} POST Merge entry
Modify an entry  Updates a single entry on a form. /entry/{formName}/{entryId} PUT Set Entry
Delete an entry Deletes an entry on a form. /entry/{formName}/{entryId} DELETE Delete Entry
Get information of form schema Retrieves the information of the form schema. /entry/{formName} OPTIONS not applicable

Common parameters

The following table explains the list of parameters commonly used in the REST operations:

Name Description Example
fields

Returns parts of the entry object (fields and association links).

You can use values() with a comma-separated list of field names inside the parentheses to return only those field values.

You can use assoc to get links to all related entries.

You can also use assoc() with a comma-separated list of association names inside the parenthesis to get links following those associations.

fields=values(Status,Notes)

fields=assoc

fields=assoc(Worklog,Testlog)

fields=values(Status,Notes),assoc(WorkLog)

q

Sends a search qualification.

Use a URL-encoded value for the search qualification.

q=%27Submitter%27%20%3D%20%22Allen%22

%27Submitter%27%20%3D%20%22Allen%22 is the URL-encoded version of 'Submitter' = "Allen" to find entries that Allen has submitted.

offset

Specifies the number (non-negative integer) of entries to offset the results by. Used for paginating results.

offset=50

Offsets the result by 50 entries

limit Specifies the  number (non-negative integer) of entries to limit the results by. Used for paginating results.

limit=10

Gets no more than 10 entries

expand

Expands the related entry (associations). You can use assoc() with a comma-separated list of association names inside the parenthesis to embed copies of the related entries following those associations.

expand=assoc(WorkLog)

returns embedded copies of the work log entries for this entry, following the WorkLog association

sort

Sorts results on a search by field name and direction. Multiple field names can be used, separated by commas.

The direction is indicated by appending .asc for ascending and .desc for descending after the field name.

sort=Status.asc,Create Date.desc

Sorts first by Status in ascending order and then by Create Date in descending order.

HTTP status codes

When responding to requests, the REST API uses some of the HTTP status codes. The following table gives a summary of the different status codes that are returned. Each operation specifies the response code you receive on successful calls or errors.

Code Name Usage
200 OK This code is the default response for a successful API call. If the documentation does not specify a HTTP status code that is returned on a successful call, it is assumed to be 200.
201 Created This code is used when you create new resources. REST includes the Location header in the response body, which denotes where the new resource is found.
204 No Content This code is similar to 200, but with no response body. This code is commonly used for DELETE operations.
400 Bad Request This code is used if the request body is not correct. For example, a JSON document is sent but it is not the correct format or the client sends a date value in the wrong format.
401 Unauthorized This code is used if the user is not authenticated. 
403 Forbidden This code is used when the call is authenticated, but the user does not have access to the resource. For example, an entry operation on a form to which the user does not have permission.
404 Not found This code is used when a resource does not exist.
500 Internal Server Error This code is the default response for any error that occurs when an API call is being processed.

JSON representation of an error

The HTTP status codes are the response that classify the failure of the request. The HTTP status code is provided in the response header, whereas, the additional information for the error is provided in the response body. The following code sample represents the format of the message you receive when you encounter an error:

[
    {
       "messageType": "ERROR",
       "messageText": "Form does not exist on the server",
       "messageAppendedText": "someFormName",
       "messageNumber": 303
    }
    ...
]
Name Data type Description
messageType String Type of message returned. For example, OK, ERROR, WARNING, FATAL, BAD STATUS.
messageText String The actual text of the error message.
messageAppendedText String The text that augments the error message.
messageNumber Integer The AR error number associated with the error message.

Related topics

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

Comments

  1. Kimberly Kantola

    Regarding Attachments, I see you can use the rest service to get them, how about using the rest service to add an attachment to an entry either when it is being created or updated?  Can that be done or do you need to use the Java API for that?

    Jul 05, 2016 06:46
    1. Christopher Seieroe

      You can do it through the REST API. In the "Supported Operations" table on this page, it has links for creating and updating entries. Those two pages have the details on how to do it. For example, follow the "Create an entry" link and look for the section titled "Create an entry with attachments."

      Jul 05, 2016 06:53
      1. Kimberly Kantola

        Found those pages, thank you very much for pointing me in the right direction.

        Jul 06, 2016 12:45
  2. Sk shahnawaz ul Haque

    Hi,

    Is there any API using which I can get Remedy records which are modified after a certain time? I tried to invoke a REST call having the following query parameter (originally URL encoded): 

    'Modified-date'>"2017-06-24T12:12:01.000+0000"

    The response however contains all the records of the particular form. So, I guess the greater than operator (>) is not working here. Please suggest.

    Thanks,

    Shahnawaz

    Jun 27, 2017 05:21
    1. Anagha Deshpande

      Hello Sk Shahnawaz,

      I will check this with the SME and will write back to you.

      Regards,

      Anagha 

      Jun 27, 2017 10:21
      1. Anagha Deshpande

        Hello Sk Shahnawaz,

        You have tried  'Modified-date'>"2017-06-24T12:12:01.000+0000" query parameter.

        Please try the following query parameter, that will work:

        'Modified-Date>"2017-06-24T12:12:01.000.

        Here, D is capitalized and there no need to add “+000”.

        Hope this helps.

        Regards,

        Anagha


        Jul 06, 2017 10:19
  3. Kevin Candelaria

    Tip: You can search for multiple qualifications by going to the form and using the qualification builder then url encode it.

    Example for HPD:Help Desk you can advanced search:

    ('Last Modified Date' > "02/01/2017 12:00:00 AM" AND 'Last Modified Date' < "07/31/2017 12:00:00 AM" OR 'Submit Date' > "02/01/2017 12:00:00 AM" AND 'Submit Date' < "07/31/2017 12:00 AM") AND ('Status*-History.Resolved.USER' = "BOBALLEN")

     

    In your REST API Program you can use the encoded value:

     

    q%3D%28%27Last%20Modified%20Date%27%20%3E%20%2202%2F01%2F2017%2012%3A00%3A00%20AM%22%20AND%20%27Last%20Modified%20Date%27%20%3C%20%2207%2F31%2F2017%2012%3A00%3A00%20AM%22%20OR%20%27Submit%20Date%27%20%3E%20%2202%2F01%2F2017%2012%3A00%3A00%20AM%22%20AND%20%27Submit%20Date%27%20%3C%20%2207%2F31%2F2017%2012%3A00%20AM%22%29%20AND%20%28%27Status%2A-History.Resolved.USER%27%20%3D%20%22BOBALLEN%22%29

     

    Hope this helps users trying to GET using multiple search criteria 

    Aug 22, 2017 01:55
    1. Anagha Deshpande

      Hello Kevin,

      Thanks for your inputs.

      Regards,

      Anagha

      Aug 22, 2017 10:14
  4. Divya B

    how can i get api for the incident, which opens in the new tab.

    Nov 29, 2017 12:10
    1. Anagha Deshpande

      Hello Divya,

      I will check this with the SME and will write back to you.

      Regards,

      Anagha

      Nov 30, 2017 05:30
    1. Kamalakannan Srinivasan

      Hi Divya,

      Thank you for your comment.

      We are not sure of the relevance of new tab in case of REST APIs. But considering you are looking for retrieving an incident via REST API, it is exactly the same as getting an entry from any other form.

      In this case, you will have to get entries from HPD:Help Desk form from ITSM. If you are also looking for links to child entries for the incident (for example, work log, relationship), you can also use associations.

      Regards,

      Kamal

      Dec 03, 2017 11:09
  5. Divya B

    Thank you.

    Dec 14, 2017 12:10
  6. Priyanka Gupta

    Can I get a single document with all the REST API calls I can make? Also, do you have information on deleting an entry?

    Apr 05, 2018 02:31
    1. Anagha Deshpande

      Hello Priyanka,

      The Supported operations section on this page lists all the operations you can do with the REST APIs. The information for deleting an entry is here.

      Regards,

      Anagha


      Apr 05, 2018 10:30
  7. Priyanka Panda

    Hi,

    Do you have any API to get the tickets assigned to a particular group and then an API to get the ticket details.



    Apr 17, 2018 07:10
    1. Anagha Deshpande

      Hello Priyanka,

      I will check your query with the SME and will respond back.

      Regards,

      Anagha

      Apr 17, 2018 08:40
      1. Anagha Deshpande

        Hello Priyanka,

        Apologies for a delayed response.

        You can use GET call with qualification to achieve this.

        Regards,

        Anagha


        Jun 22, 2018 12:44
  8. Matt Marcelli

    Hello,

    What URL should I be using to query the API? I am currently using the free trial and my test URL is https://remedy-myit2.trybmc.com/ux/smart-it/#/

    Apr 30, 2018 01:37
    1. Anagha Deshpande

      Hello Matt,

      I will check this with the SME and will respond back.

      Regards,

      Anagha

      May 01, 2018 10:41