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

Retrieving an association using REST API

GET associations

GET associations for single entry

Examples

GET associations for multiple entries

Example

Related topics

Comments