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

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

Understanding JSON

The body of an HTTP request or response message is a document written in JavaScript Object Notation (JSON), which is a lightweight, text-based data interchange format. Although it has its roots in JavaScript, JSON is language independent and uses simple data structures. JSON format is often used for transmitting structured data over a network connection. It is primarily used to transmit data between a server and a web application.

For more information about JSON and JSON parsers, see JSON.org. JSON parsers provide serialization and deserialization methods that make encoding and decoding of the messages easier.

This section provides the following topics:

JSON representation of AR System data types

The BMC Remedy AR System uses many data types in its domain objects. The following AR System data types are represented in the JSON format:

Character and Enum

Character and enum data types use the JSON strings data type. The JSON string data type begins and ends with double quotation marks and contains Unicode characters in a sequence.

// Character value
"foo" : "Hello World!"
 
// Enum value - uses the String value,
// not the integer value or any labels
"Status" : "Assigned"

Integer, decimal, and real

Integer, decimal, and real data types use the JSON number type. The JSON number data type is an integer, real number, decimal point, with exponent part and prefix minus sign but it does not contain hexadecimal and octal forms.

// Integer value
"integerField" : 100
 
// Decimal value
"decimalField" : 25.99
 
// Real value
"realField" : 1.2246e-2

Date, time, and date/time

JSON does not have explicit date, time, and date/time value types. The AR System server follows the ISO 8601 format to represent the date, time and date/time values.

// Date value
"dateOnlyField" : "2014-07-28"
 
// Time value
"dateTimeField" : "2014-12-01T12:48:03.000+0000"
 
// Time of Day value (24-hour clock, hh:mm:ss)
"timeOnlyField" : "13:15:59"

Diary

Diary fields contain multiple character entries that are stamped automatically with the date, time, and the name of the user who enters the item. When the client uses Merge entry or the server returns a response for GET entry, REST sends back an array of diary entries.

"diaryField" : [
                   { "user" : "Demo", 
					 "timestamp" : "2014-12-01T12:48:03.000+0000", 
					 "text" : "..." 
					},
                   ...
               ]

Currency

Currency data types contains four separate parts: decimal value, the currency code, the conversion date, and functional values. The functional values are listed as an array of decimal values where the currency code is the JSON name. This format makes it easy for clients to get a particular functional value directly from the functionalValues object name, rather than reconciling a list of decimal and currency pair objects.

"currencyField" : {
                      "decimal" : 100.00,
                      "currency" : "USD",
                      "conversionDate" : "2014-12-01T12:48:03.000+0000",
                      "functionalValues" : { "AUD" : 256.11, "EUR" : 167.00, ... }
                  }

Attachments

REST treats attachments as a sub resource to the entry. Instead of trying to include binary data in a JSON document, REST treats it as its own resource. REST still maintains some metadata for the attachment, like its name and size, that is returned along with the URL. In this case, the URL is <original-entry-url>/attach/<fieldName>.

"attachmentField" : {
                        "name" : "photo.jpg",
                        "sizeBytes" : 12365588,
                        "href" : "http://localhost/ars/entry/SampleForm/000000000000001/attach/attachmentField"
                    }

Status history

The primary use case for status history is to display the user name and time stamp for a given status value. The REST API arranges the history values by status. If a client wants to know information about the New status, they can sort the list and get it directly instead of scanning through the entire list.

"statusHistory" : {
                      "New" : { "user" : "Demo", "timestamp" : "2014-12-01T12:48:03.000+0000"},
                      "Assigned" : { "user" : "Demo", "timestamp" : "2014-12-01T12:48:03.000+0000" }
                  }

Related topics

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

Comments