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 actions are performed on an entry on a form.
Type | URL | Actions |
---|---|---|
An entry on a form | /entry/{formName} | Performs HTTP requests on just the form and allows you to create or search all entries on the 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 |
Common parameters for entry operations
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. |
|
q | Sends a search qualification. Use a URL-encoded value for the search qualification. |
|
offset | Specifies the number (non-negative integer) of entries to offset the results by. Used for paginating results. |
Offsets the result by 50 entries |
limit | Specifies the number (non-negative integer) of entries to limit the results by. Used for paginating results. |
Gets no more than 10 entries |
expand | Expands the related entry (associations). You can use assoc() for every association that you want to expand or retrieve the related entries. |
Retrieves data related an entry with respect to association1 and association2. |
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. |
Sorts first by Status in ascending order and then by Create Date in descending order. |
option | Use in delete entry calls. Allowed values:
|
|
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. |
Comments
In the API, it's possible to perform a query that issues a limited results set yet still determine the total number of returns available to the query...is this possible through the REST?
That is a feature that I would like to use. I posted a similar question on BMC Remedy AR System REST API overview. This is analogous to the nMatches parameter that is provided for the Java API and web services.
Hello Jay,
In REST API, nMatches is not available currently. If you believe this is a must feature, you should create an idea on BMC Community or you can request for enhancement, and if it’s voted, BMC product management can consider this.
Regards,
Nidhi
I would also like information on how one can JOIN to a second form in a query. I posted in December of last year to Communities and Support, but have seen no follow-up.
Hello Jay,
Currently REST APIs only provide basic entry operations working with a single form. In REST, there is no provision to query multiple forms via dynamic joins similar to Java API.
Regards,
Nidhi
Hi,
The above definition on associations does not seem to work as documented:
We are at 9.1.3 SP3.
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.
Specifically, a comma-separated list of association names inside the parenthesis.
According to the above, this should work but does not:
https://server/api/arsys/v1/entry/HPD:Help Desk?q='Incident Number'="INC000001667188"&fields=values(Incident Number,Description)&expand=assoc(HPD:INC:Associations,HPD:INC:Worklog)
It does not fail but does not give the correct results. The above call only returns one set of expanded associations not both.
However in testing, we found this will work - separating the expand assoc into two separate parameter calls.
http://server/api/arsys/v1/entry/HPD:Help Desk?q='Incident Number'="INC000001667188"&fields=values(Incident Number,Description)&expand=assoc(HPD:INC:Associations)&expand=assoc(HPD:INC:Worklog)
Can you verify that it should work as documented above or is there maybe a bug?
Regards, Allen Morgan NASDAQ
Hello Allen Morgan,
Apologies for the late response.
We have updated the topic.
Regards,
Anagha
Hi, Is there restriction on the number of calls that can be made per day? or any kind of API restriction?
Hello Priyanka,
Apologies for the late response.
There are no restrictions on the number of calls that you can make per day.
Regards,
Anagha
Is it possible to restrict some operation, for example, enable the REST API, but only GET operation?
The only way to limit it would be through filters that limit a person's ability to do various actions. The Rest API opens the form to whatever permissions the user has, same as they would have through the user/mid-tier, but without Active Link restrictions...so if they have permissions to do the action, and the business rules (filters) allow it, then they can perform that action
Hello Hellyson,
Apologies for the late response.
You cannot restrict any operation.
Regards,
Anagha
I am looking for retrieving filtered data. I am able to filter data by using one filter q='Corporate ID'="xyz".However, I want to apply multiple filters. Is it possible to add more than one filter for search qualification i.e. search based on q='Status' ="Closed" and q='Reported Date'="2018-08-23". If yes, what is the syntax to pass the filters?
Anushree, It is a normal Remedy Query in the format of 'Field' = "Value" OR 'Field' = "Value" AND etc....so you can build out your qualification/query any way you would like as long as it's a valid Remedy query.
Thanks for the help. I would also like information on how to filter data for fields having date format. The condition is to fetch data for having close date greater than a particular date. For example, q='Closed date' >'2018-06-20'. I am not able to get filtered data with this condition. Can you please suggest a way to pass the date in these kind of queries to fetch data?
Anushree, As I said, it's a standard Remedy Query ' is for field names, not field values...in your case q='Closed date' >"2018-06-20" IF the format of date on your server is in that format....in my US based server it would be q='Closed date' >"06/20/2018"
Can someone help us how to translate the below query into API parameters for "BMC_ASSET/BMC.CORE/BMC_BaseElement?query-parameter" Where item in (‘Workstation’, ‘Laptop’, ‘Tablet’, ‘Server’, ‘Router’, ‘Switch’, ‘Desktop’) and SerialNumber is not null and CreateDate > ‘1388612543’
Hello Mahidhar,
We will get back to you on this shortly.
Regards,
Anagha
Hello Mahidhar,
Apologies for the late response.
Currently, BMC does not support IN parameter for the REST API.
Regards,
Anagha
How does the Expand parameter work with multiple associations? The documentation says it can be done by listing multiple associations as a CSV, but I can't get this working, or find any examples of it in use.
Hello Chris,
We are working on your query. We will respond shortly.
Regards,
Anagha
Hello Chris,
Apologies for the late response.
We have updated the topic to reflect how the Expand parameter works with multiple associations.
Regards,
Anagha