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.


Example of using the REST API to create an entry on a form

You can use the REST API to retrieve information from a form schema to determine what information is needed for a specific form. Then, you can create and get entries from the form.

Retrieve information from a form schema

You can use the OPTIONS operation to retrieve information. The following table lists details about this OPTIONS operation.

URL qualifier

/entry/{formName}

formNameThe form for which an entry is to be created.

MethodOPTIONS
Headers
Header

Value

AuthorizationToken
ReturnsThe information about the schema of the form.

Create an entry

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

You can use the POST operation to create an entry. The following tables list details about this POST operation.

URL qualifier

/entry/{formName}

formName - The form for which an entry is to be created.

MethodPOST
Headers
Header

Value

AuthorizationToken
Content-TypeApplication/json
Parameter


NameDescription
fieldsSelects what parts of the JSON document to return (for example, fields=values(fieldName1,fieldName2))

For more information, see Common parameters for entry APIs.

Request bodyAn entry object in JSON format.
Returns

Create an operation without a fields parameter

Does not return the request's body content, but returns one of the following status codes:

  • HTTP status code 201 with the Location header set to the URL of the new entry resource
  • HTTP status code 204
Notes

Display-only forms and join forms do not generate an entry ID when they are created, and status code 204 is returned. If an entry ID is generated, such as on a regular form, status code 201 with the Location header is returned. When display-only forms and join forms are created, field parameters are not honored.

    This example provides information to create an entry in a Simple form.

    Request URL

    POST http://localhost:8008/api/arsys/v1/entry/SimpleForm
    

    Request headers

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

    Request body

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

    Following is a sample code snippet for the POST operation.

    package com.example;
    
    import org.apache.http.Header;
    import org.apache.http.client.methods.CloseableHttpResponse;
    import org.apache.http.client.methods.HttpPost;
    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 Post {
    
        public static void main(String[] args) throws Exception {
            String token = args[0];
    
            // start HTTP POST to create an entry
            CloseableHttpClient httpClient = HttpClients.createDefault();
            HttpPost httpPost = new HttpPost("http://localhost:8008/api/arsys/v1/entry/SimpleForm");
    
            // build the JSON entry
            String json = "{ \"values\" : { ";
            json += "\"Submitter\" : \"Allen\", ";
            json += "\"Short Description\" : \"testing 123\"";
            json += " } }";
            httpPost.setEntity(new StringEntity(json, ContentType.APPLICATION_JSON));
            httpPost.addHeader("Authorization", "AR-JWT " + token);
    
            // make the call and print the Location
            try (CloseableHttpResponse response = httpClient.execute(httpPost)) {
                Header locationHeader = response.getFirstHeader("Location");
                System.out.println(locationHeader.getValue());
            }
        }
    
    }

    This example provides information to create an entry in a Simple form.

    Request URL

    POST http://localhost:8008/api/arsys/v1/entry/SimpleForm?fields=values(Submitter, Assigned To)
    

    Request headers

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

    Request body

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

    Response body

    {
      "values": {
        "Submitter": "Allen",
        "Assigned To": "Bob"
      },
      "_links": {
        "self": [
          {
            "href": "http://<local host>:<port>/api/arsys/v1/entry/SimpleForm"
          }
        ]
      }
    }
    

    Following is a sample code snippet for the POST operation.

    package com.example;
    
    import org.apache.http.Header;
    import org.apache.http.client.methods.CloseableHttpResponse;
    import org.apache.http.client.methods.HttpPost;
    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 Post {
    
        public static void main(String[] args) throws Exception {
            String token = args[0];
    
            // start HTTP POST to create an entry with fields parameter
            CloseableHttpClient httpClient = HttpClients.createDefault();
            HttpPost httpPost = new HttpPost("http://localhost:8008/api/arsys/v1/entry/SimpleForm?fields=values(field1, field2)");
    
            // build the JSON entry
            String json = "{ \"values\" : { ";
            json += "\"Submitter\" : \"Allen\", ";
            json += "\"Short Description\" : \"testing 123\"";
            json += " } }";
            httpPost.setEntity(new StringEntity(json, ContentType.APPLICATION_JSON));
            httpPost.addHeader("Authorization", "AR-JWT " + token);
    
            // make the call and print the Location
            try (CloseableHttpResponse response = httpClient.execute(httpPost)) {
                Header locationHeader = response.getFirstHeader("Location");
                System.out.println(locationHeader.getValue());
    			HttpEntity entity = response.getEntity(); 
    		// Read the contents of an entity and return it as a String. 
    			String content = EntityUtils.toString(entity); 
    			System.out.println(content); 
            }
        }
    
    }

    Create an entry with attachments

    You can use the POST operation to create an entry with attachments. The following tables list details about this POST operation.

    URL qualifier

    /entry/{formName}

    formNameThe form for which an entry is to be created.

    MethodPOST
    Headers

    Header

    Value

    AuthorizationToken
    Content-TypeMultipart/form-data
    Request body

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

    One part is named as the entry with Content-Type as application/json, and the value is a JSON entry. Zero or more parts have 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 creates an entry with attachment data.

    Returns

    Does not return the request's body content, but returns one of the following status codes:

    • HTTP status code 201 with the Location header set to the URL of the new entry resource
    • HTTP status code 204
    NotesDisplay-only forms and join forms do not generate an entry ID when they are created, and the status code 204 is returned. If an entry ID is generated, such as on a regular form, status code 201 with the Location header is returned.

      This example provides information to create an entry with an attachment in a Simple form.

      Request URL

      POST http://localhost:8008/api/arsys/v1/entry/AttachTest

      Request headers

      Authorization: AR-JWT eyJhbGciOiJIUzI1NiJ9.
      eyJzdWIiOiJxSmNGRjgwY0JOeTgyUDRkUm1vTz
      RHZ1dKQ1QrZ3pzYUpybVwvMFRwMktMYkJXeUd4ZWt1VG1VMW1r
      NXkzcE9aRk9NRlhVM1JTZ3BDbjRNUmR4MVRQRnpGQ2hpNE5KaGk3ZUxCNVlFOFFz
      VVJuYm1HbklHaVc0UT09IiwibmJmIjoxNDQ3NzkzMjQ5LCJfaW1wZXJzb25hdGVkVXNl
      ciI6bnVsbCwiaXNzIjoiVy1DU0VJRVJPRS0yOS5hZHByb2QuYm1jLmNvbSIsIl9jYWNoZUlkIjox
      NDAsImV4cCI6MTQ0Nzc5Njk2OSwiaWF0IjoxNDQ3NzkzMzY5LCJqdGkiOiJJREdBQUJEVUMyWU
      dJQU5YWkk4N0FBQkJPV0RORTkifQ.S4PqNJ_LNLqHxfbI6nn7lJA_aI4_-qDVx4hqR3TfprQ
      
      Content-Length: 17553
      Content-Type: multipart/form-data;boundary=W3NByNRZZYy4ALu6xeZzvWXU3NVmYUxoRB

      Request body

      --W3NByNRZZYy4ALu6xeZzvWXU3NVmYUxoRB
      Content-Disposition: form-data; name="entry"
      Content-Type: application/json; charset=UTF-8
      Content-Transfer-Encoding: 8bit
      
      { 
      	"values" : 
      		{ "Submitter" :"Allen", "Short Description" : "testing 123", "Attachment1" : "sample.jpg"
      		} 
      }
      
      --W3NByNRZZYy4ALu6xeZzvWXU3NVmYUxoRB
      Content-Disposition: form-data;
      name="attach-Attachment1"; filename="sample.png"
      Content-Type: application/octet-stream
      Content-Transfer-Encoding: binary
      
      <binary data removed for brevity>
      --W3NByNRZZYy4ALu6xeZzvWXU3NVmYUxoRB--
      

      Following is a sample code snippet for the POST operation with attachments.

      package com.example;
      
      import java.io.File;
      
      import org.apache.http.Header;
      import org.apache.http.HttpEntity;
      import org.apache.http.client.methods.CloseableHttpResponse;
      import org.apache.http.client.methods.HttpPost;
      import org.apache.http.entity.ContentType;
      import org.apache.http.entity.mime.MultipartEntityBuilder;
      import org.apache.http.impl.client.CloseableHttpClient;
      import org.apache.http.impl.client.HttpClients;
      
      public class PostAttachment {
      
          public static void main(String[] args) throws Exception {
              String token = args[0];
              String filename = args[1];
      
              // start HTTP POST to create an entry
              CloseableHttpClient httpClient = HttpClients.createDefault();
              HttpPost httpPost = new HttpPost("http://localhost:8008/api/arsys/v1/entry/AttachTest");
      
              // build the JSON entry
              String json = "{ \"values\" : { ";
              json += "\"Submitter\" : \"Allen\", ";
              json += "\"Short Description\" : \"testing 123\", ";
              json += "\"Attachment1\" : \"sample.jpg\"";
              json += " } }";
      
              // build the multipart entity
              HttpEntity entity = MultipartEntityBuilder.create()
                      .addTextBody("entry", json, ContentType.APPLICATION_JSON)
                      .addBinaryBody("attach-Attachment1", new File(filename))
                      .build();
              httpPost.setEntity(entity);
              httpPost.addHeader("Authorization", "AR-JWT " + token);
      
              // make the call and print the Location
              try (CloseableHttpResponse response = httpClient.execute(httpPost)) {
                  Header locationHeader = response.getFirstHeader("Location");
                  System.out.println(locationHeader.getValue());
              }
          }
      
      }
      
      

      Get multiple entries

      You can use the GET operation to get multiple entries from a form. The following table lists details about this GET operation.

      URL qualifier

      /entry/{formName}

      formNameThe form for which an entry is to be read.

      MethodGET
      Header
      HeaderValue
      AuthorizationToken
      ReturnsAn array of entry objects in JSON format.
      NotesThe default behavior is to internally call Get List Entry With Fields, which does not initiate Get Entry workflow.

        This example provides information to get multiple entries in a Simple form.

        Request URL

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

        Request headers

        Authorization: AR-JWT eyJhbGciOiJIUzI1NiJ9.
        eyJleHAiOjE0MTc2NTM1ODgsInN1YiI6IkFsbGVuIiwibm
        JmIjoxNDE3NjQ5ODY4LCJpc3MiOiJXLUNTRUlFUk9FLTI5Lm
        FkcHJvZC5ibWMuY29tIiwianRpIjoiSURHQUFCRFVDMllHSUFONkJGUTJBQUFFUEZBNVFXIiwiX
        2NhY2hlSWQiOjQ3LCJpYXQiOjE0MTc2NDk5ODh9.V4LGLcEdwD8V_I4rzoWYYSZmEMA82LBB_lEfz4Xnz9Y

        This example provides information about the Rest API request parameters to get multiple entries. 

        Request URL

        http://local host:8008/api/arsys/v2.0/entry/SampleForm/?q=('Status'="Assigned")&sort=Real
        Number Field.asc&offset=1&limit=2&fields=values(Request ID,Real
        Number Field)

        Request headers

        Authorization: AR-JWT eyJhbGciOiJIUzI1NiJ9.
        eyJleHAiOjE0MTc2NTM1ODgsInN1YiI6IkFsbGVuIiwibm
        JmIjoxNDE3NjQ5ODY4LCJpc3MiOiJXLUNTRUlFUk9FLTI5Lm
        FkcHJvZC5ibWMuY29tIiwianRpIjoiSURHQUFCRFVDMllHSUFONkJGUTJBQUFFUEZBNVFXIiwiX
        2NhY2hlSWQiOjQ3LCJpYXQiOjE0MTc2NDk5ODh9.V4LGLcEdwD8V_I4rzoWYYSZmEMA82LBB_lEfz4Xnz9Y

        Response body

        [{
            "values": {
                "Request ID": "000000000000004",
                "Real Number Field": 3245.215566
            },
            "_links": {
                "self": [{
                    "href": "http://local host:8008/api/arsys/v1/entry/QueryParamTest/000000000000004"
                }]
            }
        }, {
            "values": {
                "Request ID": "000000000000001",
                "Real Number Field": 223232.213266
            },
            "_links": {
                "self": [{
                    "href": "http://local host:8008/api/arsys/v1/entry/QueryParamTest/000000000000001"
                }]
            }
        }]



        Following is a sample code snippet for the POST operation for multiple entries.

        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 GetMultiple {
        
            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");
        
                // 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);
                }
            }
        
        }
        
        

        This example provides information to create an entry with an attachment in a Simple form.

        Request URL

        http://local host:8008/api/arsys/v2.0/entry/SampleForm/?q=('Status'="Assigned")&sort=Real
        Number Field.asc&offset=1&limit=2&fields=values(Request ID,Real
        Number Field)

        Request headers

        Authorization: AR-JWT eyJhbGciOiJIUzI1NiJ9.
        eyJzdWIiOiJxSmNGRjgwY0JOeTgyUDRkUm1vTz
        RHZ1dKQ1QrZ3pzYUpybVwvMFRwMktMYkJXeUd4ZWt1VG1VMW1r
        NXkzcE9aRk9NRlhVM1JTZ3BDbjRNUmR4MVRQRnpGQ2hpNE5KaGk3ZUxCNVlFOFFz
        VVJuYm1HbklHaVc0UT09IiwibmJmIjoxNDQ3NzkzMjQ5LCJfaW1wZXJzb25hdGVkVXNl
        ciI6bnVsbCwiaXNzIjoiVy1DU0VJRVJPRS0yOS5hZHByb2QuYm1jLmNvbSIsIl9jYWNoZUlkIjox
        NDAsImV4cCI6MTQ0Nzc5Njk2OSwiaWF0IjoxNDQ3NzkzMzY5LCJqdGkiOiJJREdBQUJEVUMyWU
        dJQU5YWkk4N0FBQkJPV0RORTkifQ.S4PqNJ_LNLqHxfbI6nn7lJA_aI4_-qDVx4hqR3TfprQ
        
        Content-Length: 17553
        Content-Type: multipart/form-data;boundary=W3NByNRZZYy4ALu6xeZzvWXU3NVmYUxoRB

        Request body

        --W3NByNRZZYy4ALu6xeZzvWXU3NVmYUxoRB
        Content-Disposition: form-data; name="entry"
        Content-Type: application/json; charset=UTF-8
        Content-Transfer-Encoding: 8bit
        
        { 
        	"values" : 
        		{ "Submitter" :"Allen", "Short Description" : "testing 123", "Attachment1" : "sample.jpg"
        		} 
        }
        
        --W3NByNRZZYy4ALu6xeZzvWXU3NVmYUxoRB
        Content-Disposition: form-data;
        name="attach-Attachment1"; filename="sample.png"
        Content-Type: application/octet-stream
        Content-Transfer-Encoding: binary
        
        <binary data removed for brevity>
        --W3NByNRZZYy4ALu6xeZzvWXU3NVmYUxoRB--
        

        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)
        {
        "entries": [
        	{
              "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"
                    }
                  ]
        	    }
            }
          ],
          "_links":{
        		"self":[
        	            {"href":"http://localhost:8008/api/arsys/v1/entry/SimpleForm"
                        }
                      ]
                  }
        }

        Related topics

        Learning about the REST API

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

        Comments

        1. Volker Scheithauer

          provide examples with required fields only for: incident, change and ci creation

          Jul 31, 2020 12:20
          1. Jan Zacharjasiewicz

            https://docs.bmc.com/docs/itsm2002/the-rest-api-references-976798064.html

            Feb 12, 2021 01:45
        2. Ismail eltorgoman

          the header should have the key X-Requested-By: XMLHttpRequest I spent several days to create an incident and the issue was in this key

          Feb 15, 2024 06:42