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.


Examples of using the REST API to get, update, and delete an entry from a form

You can use the REST API to perform basic operations on entries on forms.

Clients such as curl, Postman, or BMC TestHttpClient tool can make calls to REST APIs. For information on how to get, update or delete an entry using the BMC TestHTTPClient tool, see the knowledge article on BMC Communities  TestHttpClient - Command line tool to test HTTP(S) services Open link .

Get a single entry

You can use the GET operation to get an entry from the form. The following table lists details about this GET operation.

URL qualifier

/entry/{formName}/{entryId}

formName - The form for which an entry is to be read. 
entryId - The entry ID.

MethodGET
Headers
HeaderValue
Authorizationtoken
(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

(Optional) X-AR-TR-Core-IdThe core ID in a trace ID
(Optional) X-AR-TR-CounterThe counter in a trace ID
(Optional) X-AR-Trace-IdThe complete trace ID
(Optional) X-AR-TR-Is-Counter-LockedThe lock counter
Parameters

Name

Description

fieldsSelects what parts of the JSON document to return (for example, ?fields=entryId1,entryId2).
expandExpands the related entries (associations).

For more information, see Common parameters.

ReturnsAn entry object
All possible 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.

NotesThe entry object will contain field values for all data fields to which the user has permission.

    Request URL

    GET http://localhost:8008/api/arsys/v1/entry/SimpleForm/000000000000002
    

    Request header

    Authorization: AR-JWT eyJhbGciOiJIUzI1NiJ9.
    eyJleHAiOjE0MTc2NTM1ODgsInN1YiI6IkFsbGVuIiwibmJmIjoxNDE3NjQ5ODY4LCJpc3MiOi
    JXLUNTRUlFUk9FLTI5LmFkcHJvZC5ibWMuY29tIiwianRpI
    joiSURHQUFCRFVDMllHSUFONkJGUTJBQUFFUEZBNVFXIiwiX2NhY2hlSWQiOjQ3LCJpYXQiOjE0MTc2NDk5ODh9.
    V4LGLcEdwD8V_I4rzoWYYSZmEMA82LBB_lEfz4Xnz9Y

    Following is a sample code snippet for the GET operation.

    package com.example;
    
    import java.nio.charset.StandardCharsets;
    
    import org.apache.http.HttpEntity;
    import org.apache.http.client.methods.CloseableHttpResponse;
    import org.apache.http.client.methods.HttpGet;
    import org.apache.http.impl.client.CloseableHttpClient;
    import org.apache.http.impl.client.HttpClients;
    import org.apache.http.util.EntityUtils;
    
    public class Get {
    
        public static void main(String[] args) throws Exception {
            String token = args[0];
    
            // start HTTP GET to get an entry
            CloseableHttpClient httpClient = HttpClients.createDefault();
            HttpGet httpGet = new HttpGet(
                    "http://localhost:8008/api/arsys/v1/entry/SimpleForm/000000000000002");
    
            // add the token to the header
            httpGet.addHeader("Authorization", "AR-JWT " + token);
    
            // make the call and print the status
            try (CloseableHttpResponse response = httpClient.execute(httpGet)) {
                HttpEntity entity = response.getEntity();
                String jsonEntry = EntityUtils.toString(entity, StandardCharsets.UTF_8);
                System.out.println(jsonEntry);
            }
        }
    
    }

    Response Body

    HTTP/1.1 200 OK
    Date: Wed, 03 Dec 2014 22:53:46 GMT
    Content-Type: application/json
    Server: Jetty(8.1.15.v20140411)
    {
      "values":{
        "Request ID":"000000000000103",
        "Submitter":"Allen",
        "Create Date":"2014-12-03T22:53:37.000+0000",
        "Assigned To":null,
        "Last Modified By":"chris",
        "Modified Date":"2014-12-03T22:53:37.000+0000",
        "Status":"New",
        "Short Description":"testing 123",
        "Status History":{
          "New":{
            "user":"chris",
            "timestamp":"2014-12-03T22:53:37.000+0000"
          }
        }
      },
      "_links":{
        "self":[
          {
            "href":"http://localhost:8008/api/arsys/v1/entry/SimpleForm/000000000000103"
          }
        ]
      }
    }

    Update an entry

    You can use the PUT operation to modify an entry on a form. The following table lists details about the PUT operation for updating a single entry on a form.

    URL qualifier

    /entry/{formName}/{entryId}

    formName - The form for which an entry is to be updated. 
    entryId - The entry ID.

    MethodPUT
    Headers
    HeaderValue
    Authorizationtoken
    Content-Typeapplication/json
    (Optional) If-Unmodified-SinceHTTP Date
    (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

    (Optional) X-AR-TR-Core-IdThe core ID in a trace ID
    (Optional) X-AR-TR-CounterThe counter in a trace ID
    (Optional) X-AR-Trace-IdThe complete trace ID
    (Optional) X-AR-TR-Is-Counter-LockedThe lock counter
    Request BodyAn entry object in a JSON format
    Returns

    HTTP status code 204 indicates a successful update.

    If the client sends If-Unmodified-Since and the entry is modified since that time, then the entry is not updated and status code 412 is returned.

    Errors

    If the request is not successful, one of the following error codes are returned:

    • 400 - Request body is incorrect
    • 403 - Forbidden
    • 404 - Form does not exist
    • 500 - Internal Server Error

    For more information, see HTTP status codes.

      The following example returns an updated entry in a Simple form.

      Request URL

      PUT http://localhost:8008/api/arsys/v1/entry/SimpleForm/000000000000002
      

      Request headers

      Authorization: AR-JWT eyJhbGciOiJIUzI1NiJ9.
      eyJleHAiOjE0MTc2NTM1ODgsInN1YiI6IkFsbGVuIiwibmJmIjoxNDE3NjQ5ODY4LCJpc3MiOi
      JXLUNTRUlFUk9FLTI5LmFkcHJvZC5ibWMuY29tIiwianRpI
      joiSURHQUFCRFVDMllHSUFONkJGUTJBQUFFUEZBNVFXIiwiX2NhY2hlSWQiOjQ3LCJpYXQiOjE0MTc2NDk5ODh9.
      V4LGLcEdwD8V_I4rzoWYYSZmEMA82LBB_lEfz4Xnz9Y
      
      Content-Length: 59
      Content-Type: application/json

      Request Body

      {
        "values":{
          "Submitter":"Allen",
          "Short Description":"testing 123"
        }
      }

      The following is a sample code snippet for the PUT operation.

      package com.example;
      
      import org.apache.http.StatusLine;
      import org.apache.http.client.methods.CloseableHttpResponse;
      import org.apache.http.client.methods.HttpPut;
      import org.apache.http.entity.ContentType;
      import org.apache.http.entity.StringEntity;
      import org.apache.http.impl.client.CloseableHttpClient;
      import org.apache.http.impl.client.HttpClients;
      
      public class Put {
      
          public static void main(String[] args) throws Exception {
              String token = args[0];
      
              // start HTTP PUT to modify an entry
              CloseableHttpClient httpClient = HttpClients.createDefault();
              HttpPut httpPut = new HttpPut(
                      "http://localhost:8008/api/arsys/v1/entry/SimpleForm/000000000000002");
      
              // build the JSON entry
              String json = "{ \"values\" : { ";
              json += "\"Short Description\" : \"updated via REST\"";
              json += " } }";
              httpPut.setEntity(new StringEntity(json, ContentType.APPLICATION_JSON));
              httpPut.addHeader("Authorization", "AR-JWT " + token);
      
              // make the call and print the status
              try (CloseableHttpResponse response = httpClient.execute(httpPut)) {
                  StatusLine status = response.getStatusLine();
                  System.out.println(status);
              }
          }
      
      }

      Update an entry with attachments

      The PUT operation also enables you to modify an attachment for a particular entry or from a list of entries.

      URL qualifier

      /entry/{formName}/{entryId}

      formName - The form for which an entry is to be updated. 
      entryId - The entry ID.

      MethodPUT
      Headers
      HeaderValue
      Authorizationtoken
      Content-Typemultipart/form-data
      (Optional) If-Unmodified-SinceHTTP Date
      (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

      (Optional) X-AR-TR-Core-IdThe core ID in a trace ID
      (Optional) X-AR-TR-CounterThe counter in a trace ID
      (Optional) X-AR-Trace-IdThe complete trace ID
      (Optional) X-AR-TR-Is-Counter-LockedThe lock counter
      Request Body

      A multipart/form-data entity. Each part of a multipart entity has a name, a Content-Type and the value.

      There is one part named as entry with Content-Type as application/json and the value is a JSON entry. There are 0 or more parts with names like attach-{fieldName} with any Content-Type and any value. The name is a prefix indicating that it is an attachment binary data, the part after the hyphen is the name of the attachment field. This updates an entry with attachment data.

      Returns

      HTTP status code 204 indicates a successful update.

      If the client sends If-Unmodified-Since and the entry is modified since that time, then the entry is not updated and status code 412 is returned.

      Errors

      If the request is not successful, one of the following error codes are returned:

      • 400 - Request body is incorrect
      • 403 - Forbidden
      • 404 - Form does not exist
      • 500 - Internal Server Error

      For more information, see HTTP status codes.

      Delete an entry

      The DELETE operation enables you to delete an entry from a form. The following table lists details about this DELETE operation.

      URL qualifier

      /entry/{formName}/{entryId}

      formName - The form for which entry is to be deleted.
      entryId - The entry ID.

      MethodDELETE
      Headers
      HeaderValue
      Authorizationtoken
      (Optional) X-AR-Client-Type Client 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

      (Optional) X-AR-TR-Core-IdThe core ID in a trace ID
      (Optional) X-AR-TR-CounterThe counter in a trace ID
      (Optional) X-AR-Trace-IdThe complete trace ID
      (Optional) X-AR-TR-Is-Counter-LockedThe lock counter
      ReturnsNo request body, but HTTP status 204 indicates successful deletion.
      All possible error codes

      If the request is not successful, one of the following error codes are returned:

      • 403 - Forbidden
      • 404 - Form does not exist
      • 500 - Internal Server Error

      For more information, see HTTP status codes.

      NotesYou can also use the option FORCE to force delete all the list of entries, for example, ?options=FORCE.

        The following example allows you to delete an entry from the form.

        Request URL

        DELETE http://localhost:8008/api/arsys/v1/entry/SimpleForm/000000000000002
        

        Request header

        Authorization: AR-JWT eyJhbGciOiJIUzI1NiJ9.
        eyJleHAiOjE0MTc2NTM1ODgsInN1YiI6IkFsbGVuIiwibmJmIjoxNDE3NjQ5ODY4LCJpc3MiOi
        JXLUNTRUlFUk9FLTI5LmFkcHJvZC5ibWMuY29tIiwianRpI
        joiSURHQUFCRFVDMllHSUFONkJGUTJBQUFFUEZBNVFXIiwiX2NhY2hlSWQiOjQ3LCJpYXQiOjE0MTc2NDk5ODh9.
        V4LGLcEdwD8V_I4rzoWYYSZmEMA82LBB_lEfz4Xnz9Y

        Following is a sample code snippet for the DELETE operation.

        package com.example;
        
        import org.apache.http.StatusLine;
        import org.apache.http.client.methods.CloseableHttpResponse;
        import org.apache.http.client.methods.HttpDelete;
        import org.apache.http.impl.client.CloseableHttpClient;
        import org.apache.http.impl.client.HttpClients;
        
        public class Delete {
        
            public static void main(String[] args) throws Exception {
                String token = args[0];
        
                // start HTTP DELETE to delete an entry
                CloseableHttpClient httpClient = HttpClients.createDefault();
                HttpDelete httpDelete = new HttpDelete(
                        "http://localhost:8008/api/arsys/v1/entry/SimpleForm/000000000000002");
        
                // add the token to the header
                httpDelete.addHeader("Authorization", "AR-JWT " + token);
        
                // make the call and print the status
                try (CloseableHttpResponse response = httpClient.execute(httpDelete)) {
                    StatusLine status = response.getStatusLine();
                    System.out.println(status);
                }
        	}
        }

        Response Body

        HTTP/1.1 204 No Content
        Date: Wed, 03 Dec 2014 22:38:14 GMT
        Server: Jetty(8.1.15.v20140411)

        Related topic

        Learning about the REST API



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

        Comments