View Template Structure

A view template has the following elements:

Element	Format	Description
viewTemplateName	String	The name of the view
type	Enum	`system` Predefined system view template `custom` Custom view template
status	Enum	`published` View templates in this status can be used for queries `draft` For use when designing the view template, before publication. Queries cannot be made against view templates in this status `deactivated` Queries cannot be made against view templates in this status
documentType	String	The type of transaction data this view template queries. Possible values are: `Requisition` `DirectOrder` `CopyOrder` `ERPOrder` `Receipt` `Invoice` `InvoiceReconciliation`
selectAttributes	Collection<String>	The fields that will be included in the response to queries using this view template. Custom fields are supported. To specify a custom field, concatenate the prefix `cus_` and the field name, as follows: `cus_<fieldname>`. For example, `cus_mycustomfield`. For a complete list of supported fields, query the get /metadata endpoint of the Operational Reporting for Procurement - View Management API. See Use of /Metadata to Request a List of Selection Fields and Attributes for instructions. Note To include reviewer comments on approvable documents, specify the `ApprovalRecords.Comment` field in the `SelectAttributes` list. All subfields of `ApprovalRecords.Comment` will then be included in the query response, and the `Text` subfield will contain reviewer comments. To determine whether this feature is available for a particular document type, use theGET /metadata endpoint. See Use of /Metadata to Request a List of Selection Fields and Attributes for details.
filterExpressions	Collection<Object>	A collection of objects that defines filters for the view template. Each object contains name, field, op, anddefaultValue elements. For example: { "filterExpressions":[{ "name":"createdDateFrom", "field":"TimeCreated", "op":">=", "defaultValue":"2017-01-01T00:00:00Z" }, { "name":"createdDateTo", "field":"TimeCreated", "op":"<=", "defaultValue":"2017-01-10T00:00:00Z" }] } Note Your custom reporting view template must have at least one of the following: a filter expression based on unique names, or a pair of date filters (that is, a FROM filter and a TO filter, specifying a date range of at most 31 days) For details about using filters based on unique names, see "Unique name filters" below.
name	String	Element of a filter expression. A name given to this filter expression
field	String	Element of a filter expression. Specifies the field to which this filter expression applies
op	Enum	Element of a filter expression. The operator for the comparison to be performed in this filter expression. For a list of supported operators, see next table
defaultValue	Object	Element of a filter expression. A value to be applied to the filter expression in the absence of a request override

Filter expressions can use the following operators:

Operator	Description
`AND`	The logical intersection operator. Documents must meet both specified criteria to be included in the results set.You can use APIs to perform the following reporting view template actions:
`=`	Arithmetic equality.
`!=`	Arithmetic inequality.
`<>`	Arithmetic inequality.
`>`	Greater than.
`<`	Less than.
`>=`	Greater than or equal.
`<=`	Less than or equal.
`LIKE`	Has pattern.
`NOT LIKE`	Does not have pattern.
`IN`	Similar to the SQL IN operator. The value must be included in a set of values.
`NOT IN`	Similar to the SQL NOT IN operator. The value must not be included in a set of values.
`IS NULL`	The field is null.
`IS NOT NULL`	The field is not null.

Unique Name Filters

You can construct a reporting view template using a UniqueNames-based filter, according to the following example:

{
"selectAttributes" : [ 
	"UniqueName", 
	"Active", 
	"TotalCost", 
	"StatusString", 
	"TimeCreated", 
	"TimeUpdated",
	"ApprovalRecords.Date",
	"ApprovalRecords.User",
	"ApprovalRecords.State",
	"ApprovalRecords.Comment"],
"filterExpressions": [{
	"name": "UniqueNames",
	"field": "UniqueName",
	"op": "IN",
	"defaultValue": ["PR10", "PR11"]
}],
"documentType" : "Requisition",
"status" : "published"
}

In the asynchronous usage, you can override the filter provided in the reporting view template by passing a new filter in the body of the /jobs request. Here is a syntax example:

{
"viewTemplateName" : "ExamplePRUniqueNameView",
"filters" :
	{
	“UniqueNames” : ["PR10", "PR11", “PR12”, “PR13”]
	}
}

View templates that use unique names filters are limited in the following ways:

The maximum number of unique names that may be specified in a reporting view template and reporting job is 1000.
The maximum number of unique names that may be specified in the request for the synchronous use case is 40.

You can use the following two options to retrieve ApprovableRecords Comments:

Include ApprovableRecords.Comment field in the viewTemplate, but without any specific subfields. This will retrieve all records in a result set, that is the records that have comments and the records without comments. All available subfields will be included in the Comment field results automatically (Title, Text, etc.).
If you specifically include individual subfields, such as ApprovalRecords.Comment.ExternalComment or ApprovalRecords.Comment.Title, then it is implied that only the records that have comments are requested and only the records with comments will be returned.