Oracle Primavera Cloud REST API

Entity Filtering

Specify entity filters in the form of headers to restrict the contents of endpoint responses to objects that match the particular criteria. For example, to ensure the /resource?type=resource endpoint only returns objects with a status of active, add header filters with a value as resourceStatus=active

Note: Some API services do not support this functionality. See Service Feature Support for more information on the functionality supported by each API service.

The Oracle Primavera Cloud API supports several entity filtering options. The following table lists supported entity filter operations:

Note: Some API object fields cannot be used for entity filtering for particular endpoints. To learn more, see Unsupported Fields for Entity Filtering.

Name	Operator	Description	Examples
Equals	=	Excludes response objects that do not contain fields with values matching the value specified in the header filters.	To only return objects with a `resourceId` value of 1001, provide the value for header filters as: `resourceId=1001` To only return objects with no value for the field `description,` provide the value for header filters as: `description=null` To only return objects with a `description` value equal to null, provide the value for header filters as: `description='null'`
Does not Equal	!=	Only includes response objects that contain fields with values that do not match the value specified in the header filters.	To only return resources with `resourceId` values that are not equal to 1001, provide the value for header filters as: `resourceId!=1001` To only return objects with a value present for the field `description,` provide the value for header filters as: `description!=null` To only return objects with `description` values that are not equal to null, provide the value for header filters as: `description!='null'`
Less than or Equal to	<=	Include response objects that contain fields with values less than or equal to the value specified in the header filters. This filter operation only supports numeric values.	To only return resources with `defaultUnitsPerHour` values less than or equal to 8, provide the value for header filters as: `defaultUnitsPerHour<=8`
Greater than or Equal to	>=	Include response objects that contain fields with values greater than or equal to the value specified in the header filters. This filter operation only supports numeric values.	To only return resources with `defaultUnitsPerHour` values greater than or equal to 8, provide the value for header filters as: `defaultUnitsPerHour>=8`
Less than	<	Include response objects that contain fields with values less than the value specified in the header filters. This filter operation only supports numeric values.	To only return resources with `defaultUnitsPerHour` values less than 8, provide the value for header filters as: `defaultUnitsPerHour<8`
Greater than	>	Include response objects that contain fields with values greater than the value specified in the header filters. This filter operation only supports numeric values.	To only return resources with `defaultUnitsPerHour` values greater than 8, provide the value for header filters as: `defaultUnitsPerHour>8`

Special Characters

Entity filtering can be done on fields with values containing special characters by starting and ending the special characters with a single quote (') in the header filters. For example, workspaceCode='Workspace+1'.

Combining Filters

You can combine entity filter conditions using logical operators. For example, the header filters can have a value as: resourceName=John;resourceType=LABOR. This combines resourceName and resourceType value filters using a logical AND (;). The following table lists the supported logical operators for combining entity filters.

Name	Operator	Description	Examples
AND	;	The logical AND operator restricts response objects to entities that match all specified filter values.	To only return objects with `resourceId` values of 1001 and `calendarId` values of 1201, provide the value for header filters as: `resourceId=1001;calendarId=1201`
OR	,	The logical OR operator restricts response objects to entities that match one or more of the specified filter values.	To only return objects with `resourceId` values not equal to 1001 or with `calendarId` values equal to 1201, provide the value for header filters as: `resourceId!=1001,calendarId=1201`

Use parentheses ( ) to combine logical operators and construct complex filters. For example, to match an object with a resource ID of 1001 OR 1002, AND a calendar ID of 1201, enclose the contents of the OR filter in parentheses, as shown here: ( resourceId=1001,resourceId=1002);calendarId=1201. Filter values enclosed in parentheses are applied first. When combining logical operators, the API will only return response objects that match all of the applied filters.

Wildcards

Use wildcard entity filters to limit response objects based on textual patterns. For example, the header filters can have a value as: resourceName=jacob*. This endpoint returns resource objects containing a resourceName value of "jacob" followed by any string. The following table lists supported entity filter wildcards:

Name Operator Description Examples

Any String

The Any String wildcard matches any string value of one or more characters.

You can only use a wildcard to match textual patterns within a string.

To only return objects with resourceName values containing the string "smith" preceded by any number of alphanumeric characters, provide the value for header filters as: resourceName=*smith

Wildcard Support Exceptions

This filter operation only supports the string and enum data types.
An * (asterisk) cannot be passed as data. It is considered as a wildcard in all cases.
The special characters _, %, and ? behave as wildcards when passed as data in combination with * (asterisk).

Filtering for Compound Data Types

It is possible to filter on compound or complex data types like DateTime. To do so, see the following example.

Note: Equals and Not Equals operators are not supported in the DateTime/TimezoneSensitiveDateTime type fields. The supported date format is: yyyy-MM-dd'T'HH:MM:ss.

Data Type	Header Filters
DateTime/TimezoneSensitiveDateTime	`approveDate>=2018-05-29T00:00:00`

Filtering for Nested Objects

You can also apply the filters on a nested object. To do so, all conditions related to that nested object should be in sequence. For example, projectCashflows is a nested object in a project. To apply filters on project APIs with projectCashflows fields, all projectCashflows related conditions should be in sequence.