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}

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

Method

OPTIONS

Headers

Header	Value
Authorization	Token

Returns

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

Method POST

Headers

Header	Value
Authorization	Token
Content-Type	Application/json

Parameter

Name	Description
fields	Selects what parts of the JSON document to return (for example, `fields=values(fieldName1,fieldName2))`

For more information, see Common parameters for entry APIs.

Request body An 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}

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

Method

POST

Headers

Header	Value
Authorization	Token
Content-Type	Multipart/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

Notes

Display-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}

formName—The form for which an entry is to be read.

Method

GET

Header

Header	Value
Authorization	Token

Returns

An array of entry objects in JSON format.

Notes

The 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"
                }
              ]
          }
}

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

Retrieve information from a form schema

Create an entry

Create an entry with attachments

Get multiple entries

Related topics

Comments