Default language.

Retrieving an association using REST API


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

This section provides the following topics:

GET associations

Description

Gets links for all associated entries.

URL qualifier

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

formName - The form for which an entry is to be read. 
entryId - 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 REST request

Default value —120 seconds

Returns

Returns links for all associated entries

All possible error codes

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.

GET associations for single entry

The GET operation is used to get associations for a particular entry on the form. The details of the GET operation are listed below:

Description

Get associations present on the form for a particular entry.

URL qualifier

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

formName - The form for which an entry is to be read. 
entryId - 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 REST request

Default value —120 seconds

Parameters

Name

Description

fields

Selects what parts of the JSON document to return (for example, ?fields=entryId1,entryId2)

expand

Expands the related entries (associations).

For more information, see Common parameters.

Returns

Returns all associations for a single entry on a form.

All possible error codes

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.

Examples

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

This operation allows you to get associations for multiple entries. The details of GET operation are tabulated here below:

Description

Get associations for multiple entries present on the form..

URL qualifier

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

formName - The form for which an entry is to 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 REST request

Default value —120 seconds

Parameters

Name

Description

fields

Selects what parts of the JSON document to return (for example, ?fields=entryId1,entryId2)

q

Search qualification

offset

Offset for the entries to return

limit

Number of entries to limit the result to

sort

Order to sort the results in (for example, ?sort=submitDate.desc)

expand

Expands the related entries (associations).

For more information, see Common parameters.

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 - Request body is incorrect.

For more information, see HTTP status codes.

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" } }
       }]
   }
},
...
]


Related topics

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*