Example of using the REST API to retrieve an association

Association is an object that defines relationships in the AR System metadata objects. The associations enable you to manage relationships between forms for various AR System functions.

GET associations for single entry

You can use the GET operation to get associations for a particular entry on a form. The following table lists the details of the GET operation:

URL qualifier

/entry/{formName/{entryId}/assoc/{AssociationName}

formName is the name of the form for which an entry must be read.
entryId is the entry ID.

Method

GET

Header

Header	Value
Authorization	token
(Optional) X-AR-Client-Type	Client Type ID
(Optional) X-AR-RPC-Queue	RPC queue to which the client calls are routed
(Optional) X-AR-Timeout	Timeout (in seconds) for a REST request The default value is 120 seconds.
(Optional) X-AR-TR-Core-Id	The core ID in a trace ID
(Optional) X-AR-TR-Counter	The counter in a trace ID
(Optional) X-AR-Trace-Id	The complete trace ID
(Optional) X-AR-TR-Is-Counter-Locked	The lock counter

Returns

Returns links for all associated entries.

All possible error codes

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

400 - Request body is incorrect
403 - Forbidden
404 - Form does not exist
500 - Internal server error

For more information, see Error-handling-for-the-REST-API.

Example 1

The following example returns all associations on a form as links that show the related entries:

Request URL

/entry/PurchaseOrder/000000000000001?fields=assoc

Response Body

// entry plus links to search for related entries
{
   "values" : {
        ...
    },
   "_links" : {
       "assoc-PurchaseOrderLineItems" : {
           "href" : "/entry/PurchaseOrder/000000000000001/assoc/PurchaseOrderLineItems"
        }
    }
}

Example 2

The following example returns a list of entries for a specific association:

Request URL

/entry/PurchaseOrder/000000000000001?fields=assoc(PurchaseOrderLineItems)

Response Body

// entry plus links to related entries
{
   "values" : {
        ...
   },
   "_links" : {
       "assoc-PurchaseOrderLineItems" : [{
           "href" : "/entry/LineItem/000000000000006"
       }, {
           "href" : "/entry/LineItem/000000000000008"
       }]
   }
}

Example 3

The following example expands the entries returned for an association:

Request URL

/entry/PurchaseOrder/000000000000001?expand=assoc(PurchaseOrderLineItems)

Response Body

// entry plus embedded related entries
{
   "values" : {
        ...
   },
   "_embedded" : {
       "assoc-PurchaseOrderLineItems" : [{
           "values" : {...},
           "_links" : { "self" : { "href" : "/entry/LineItem/000000000000006" } }
       }, {
           "values" : {...},
           "_links" : { "self" : { "href" : "/entry/LineItem/000000000000008" } }
       }]
   }
}

GET associations for multiple entries

You can use the GET operation to get the associations for multiple entries on a form. The following table lists the details of the GET operation:

URL qualifier

/entry/{formName}?fields=assoc(AssociationName)

formName is the name of the form for which an entry must be read.

Method

GET

Header

Header	Value
Authorization	token
(Optional) X-AR-Client-Type	Client Type ID
(Optional) X-AR-RPC-Queue	RPC queue to which the client calls are routed
(Optional) X-AR-Timeout	Timeout (in seconds) for a REST request The default value is 120 seconds.
(Optional) X-AR-TR-Core-Id	The core ID in a trace ID
(Optional) X-AR-TR-Counter	The counter in a trace ID
(Optional) X-AR-Trace-Id	The complete trace ID
(Optional) X-AR-TR-Is-Counter-Locked	The lock counter

Parameters

Name	Description
fields	Selects the parts of the JSON document that must be returned. For example: ?fields=entryId1,entryId2
q	Search qualification
offset	Offset for the entries to return
limit	The number of entries to limit the result to
sort	Order to sort the results For example: ?sort=submitDate.desc
expand	Expands the related entries (associations).

For more information, see Endpoints-in-AR-REST-API.

Returns

Returns all associations for all the entries on a form.

Errors

If the request is not successful, the following error code is returned:

400 - The request body is incorrect.

For more information, see Error-handling-for-the-REST-API.

Example

Request URL
/entry/PurchaseOrder?q='Status'="Pending"&expand=assoc(PurchaseOrderLineItems)
Response Body
// multiple entries plus embedded related entries
{
   "entries": [
{
   "values" : {
       "Entry ID": "00000000000001",
        ...
   },
   "_embedded" : {
       "assoc-PurchaseOrderLineItems" : [{
           "values" : {...},
           "_links" : { "self" : { "href" : "/entry/LineItem/000000000000006" } }
       }, {
           "values" : {...},
           "_links" : { "self" : { "href" : "/entry/LineItem/000000000000008" } }
       }]
   }
},
{
   "values" : {
       "Entry ID": "00000000000002",
        ...
   },
   "_embedded" : {
       "assoc-PurchaseOrderLineItems" : [{
           "values" : {...},
           "_links" : { "self" : { "href" : "/entry/LineItem/000000000000013" } }
       }]
   }
},
...
]

Example of using the REST API to retrieve an association

GET associations for single entry

Example 1

Example 2

Example 3

GET associations for multiple entries

Example

On this page