Expand

When you get an Detailed respresentation of an resource, the default response does not include related resource. For example, here is the response for the Agreement Details endpoint:

Example: GET /agreements/ICMAutomationBusinessDevelopmentAgreement/11ed0695-efc4-4a05-8f33-d2e343bfe653

curl -k -i -H "Content-Type: application/json"\ 

-H "icmauthtoken: {icm-api-token}"\
-X GET 'https://{host-name}/agreements/{contractTypeName}/{agreementID}

When you get an individual agreement, you get the detailed representation of the agreement.

Sample Response

As you can see, the response does not include any ICMPreTeaming, ICMAnnexure2, ICMAnnexure1 and all are returned as null. However, the client can use expand to get the related resources for this agreement.

The expand option goes in the query string of the request:

Not all attributes support expand, attributes supporting expand will be marked as such in model definition in this documentation.

Example GET /agreements/ICMAutomationBusinessDevelopmentAgreement/11ed0695-efc4-4a05-8f33-d2e343bfe653?expand=ICMPreTeaming

Now the server will include the ICMPreTeaming in detail representation:

The expand option takes a comma-separated list of navigation properties to expand. The following request expands both the ICMPreTeaming and the ICMAnnexure1 for an agreement.

GET /agreements/ICMAutomationBusinessDevelopmentAgreement/11ed0695-efc4-4a05-8f33-d2e343bfe653?expand=ICMPreTeaming,ICMAnnexure1

Expansion Depth

By default, API limits the expansion depth to 2. That prevents the client from sending complex requests like expand=ICMPreTeaming(expand=ICMAnnexure1(expand=ICMSOWPeerassociation)) which might be inefficient to query and create large responses.

Partial response in Expand

To return the partial response in expandable attributes; please specify select query paramater for expandable resources.

For Example

GET /agreements/ICMAutomationBusinessDevelopmentAgreement/11ed0695-efc4-4a05-8f33-d2e343bfe653?expand=ICMPreTeaming(select=name,status)

In the above example response will include status and name from ICMPreTeaming .

Filtering in Expand

To filter the response in expandable attribute; please specify filter query paramater.

For Example

GET agreements/ICMAutomationBusinessDevelopmentAgreement/11ed0695-efc4-4a05-8f33-d2e343bfe653?expand=ICMPreTeaming(filter=status $eq 'Draft')

In the above example response of clauses will be filtered by filter expression (name $eq 'Payment Terms') and response of versions will be filtered by filter expression (uploadedBy $eq 'CLM ADMIN').

In the above example response of ICMPreTeaming will be filtered by filter expression (status $eq 'Draft').

Refer Filtering section to know more about on how to build filter expressions.

Sorting in Expand

To sort the response in expandable attribute; please specify sort query paramater. Comma seperated sort expressions is supported for multiple expandable attributes.

For Example

GET /agreements/ICMAutomationBusinessDevelopmentAgreement/11ed0695-efc4-4a05-8f33-d2e343bfe653?expand=ICMPreTeaming(sort = name asc) ,ICMAnnexure1(sort=Status desc)

In the above example response of ICMPreTeaming will be sorted by sort expression (name asc) and response of ICMAnnexure1 will be sorted by sorted expression (Status desc)

Refer Sorting section to know more about on how to build sort expressions.

Pagination in expand

When you expand the resource which returns the list it will always be limit to the default page size for that resource. Default page size will be mentioned on the resource endpoints in this documentation.

If you want the expanded resources to honor the pageSize please send pageSize paramater in expand resource.

For Example

GET /agreements/ICMAutomationBusinessDevelopmentAgreement/11ed0695-efc4-4a05-8f33-d2e343bfe653?expand=ICMPreTeaming(pageSize=10)

In the above example response of ICMPreTeaming will be limited to 10 records

Refer Pagination section to know more.

Combining multiple expression

Many times we would like to get response of expanded resources which are filtered, sorted and respects the pageSize as well.

You can do this by passing all the supported request parameters in expand expression.

For example -

If we want to expand ICMPreTeaming in agreement that should be filtered by status property and also want to sort the response by name and only get 5 records . you can do this by forming the below query.

GET /agreements/ICMAutomationBusinessDevelopmentAgreement/11ed0695-efc4-4a05-8f33-d2e343bfe653?expand=ICMPreTeaming(filter = status $eq 'Draft' | sort = name desc | pageSize=5 | select = name,status)

The pipe character is used to separate the request parameters query inside expand.