List non-expired batches.

Specify the limit of the number of results returned in one page. Also known as page size. Optional parameter and defaults to 10 results per page. If specified, must be greater or equal to 1.

Specify the index of the first item returned in the results. Defaults to 0 (the first item). Used with pagination. If specified, must be greater than or equal to 0. If greater than the number of results, the service will return status code 400 (Bad Request).

The search $filter allows callers to filter the returned results loosely based on the OData 4.01 $filter syntax (See http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html#sec_QueryOptions for a full description of the OData query options).

User Attributes

User attributes can be used as part of the filter with the attribute name enclosed within $batch( ) or $file( ) e.g. $batch(Attribute Name) or $file(Attribute Name). User Attribute names are not case sensitive, e.g. $batch(Product) and $Batch(product) are the same.

This allows the string operators below to be used, for example: $filter=$batch(Product) eq 'AVCS' or $filter=endswith($file(Week Number), '/52')

Batches and files within the batch have user attributes. For filtering, a batch is considered to have the combination of its own attributes and all the attributes of the files in that batch. Operators will then match on any of the attributes, so an operator could match on one or more of the batch's attributes, or any of the file's attributes.

A batch that has no instances of the attribute and no files with an instance of the attribute will be considered to have a null value for that attribute. Combined with the null literal, this can be used to test for the presence or absence of a user attribute. (e.g. $filter=$batch(Product) eq null will return batches that don't have a Product attribute and $filter=$file(Product) eq null will return all batches for which files don't have a Product attribute.)

Note: user attribute values can only be compared with a literal value. It is not possible to compare one user attribute value with another user attribute value. e.g. $filter=$batch(Product) eq $batch(Service) or $filter=$file(Product) eq $file(Service) is an invalid filter and will return HTTP Status Code 400 - Bad Request.

Additionally, you can search for any batch user attribute that has a value that contains a search term. $batchContains('searchTerm') will look for any batch with any attribute that contains the 'searchTerm'. Whereas $batch() and $file() are string functions, i.e. they return the value of the attribute to then be compared with an operator below, $batchContains() is a boolean function and returns true or false. $batchContains() can be combined with boolean operators such as and and or.

System Attributes

System attribute names are not case sensitive. For example: batchPublishedDate is the same as batchpublisheddate.

The service supports queries on the following system attributes:

• businessUnit - Matches a string, e.g. $filter=businessUnit eq 'ADDS'. Partial matches are supported using the string operators below. e.g. $filter=startswith(businessUnit,'Test').
• batchPublishedDate - The date the batch was published (committed) (not the individual files, or the initial batch created date). Only matches against a date literal or expression. Dates must be specified in full date-time notation as defined by RFC 3339, section 5.6, for example, 2017-07-21T17:32:28Z. The system supports the comparison operators listed below e.g. $filter=batchPublishedDate gt 2020-12-23T17:45:12Z.
• expiryDate - Only matches against a date literal or expression. Dates must be specified in full date-time notation as defined by RFC 3339, section 5.6, for example, 2017-07-21T17:32:28Z. The system supports the comparison operators listed below. e.g. $filter=expiryDate lt 2020-01-05T19:56:48Z.
• filename - Matches a string which is the filename of any of the files within a batch, e.g. $filter=filename eq 'AUL37137.004'. This will also support partial filename matches using the string operators below. e.g. $filter=endswith(filename,'.iso').
• filesize - Matches an integer that is the the file size in bytes of any of the files in the batch. The match can be made using eq and ne operator as well as the comparison operators listed below. e.g. $filter=fileSize gt 1000000 finds any batch that contains one or more files that is bigger than 1000000 bytes (1MB).
• mimetype - Matches a string that is the MIME Type of any of the files in the batch. Partial matches can be made with the string operators listed below. e.g. $filter=startswith(mimeType, 'text') would match text/json and text/plain but not application/json.

The following system attributes have been considered and are not currently in scope:

• hash - Search for this binary object?
• totalBatchSize - Match against the sum of all the file sizes of the files in the batch? Much harder to translate to a SQL query, but possibly more useful to the users?

Note: System Attribute values can only be compared with a literal value. It is not possible to compare one System Attribute value with another System Attribute value. e.g. $filter=batchedPublishedDate gt expiryDate is an invalid filter and will return HTTP Status Code 400 - Bad Request.

Supported Operators

Comparison between two values of different types will fail (e.g. you can't compare a string value and a date, the query will return status code 400 (Bad Request)).

• And (and) - This binary operator can be used between two expressions and will return true if both the left and right expression are true.
• Or (or) - This binary operator can be used between two expressions and will return true if either the left expression or the right expression is true.
• Not (not) - The not operator returns true if the operand returns false, otherwise it returns false. e.g. `$filter=not endswith($batch(Product),'ilk') or not endswith($file(Product),'ilk').
• Equals (eq) - Comparison of two values to see if they are the same. For string values, the comparison is case-insensitive, so 'Bob' eq 'BOB' will return true. For Date-Time values, the comparison is exact so 2017-07-21T17:32:28Z eq 2017-07-21T17:32:29Z will return false.
• Not Equals (ne) - Comparison of two values to see if they are different. For string values, the comparison is case-insensitive, so 'Bob' ne 'BOB' will return false. For Date-Time values, the comparison is exact so 2017-07-21T17:32:28Z ne 2017-07-21T17:32:29Z will return true.
• Comparison operators (only applies to numeric system attributes (i.e. filesize) or date system attributes (i.e. batchPublishedDate and expiryDate)).
  • Greater Than (gt) e.g. fileSize gt 1000000 or batchPublishedDate gt 2020-12-23T17:45:12Z.
  • Greater Than or Equals (ge) e.g. fileSize ge 1000000 or batchPublishedDate ge 2020-12-23T17:45:12Z.
  • Less Than (lt) e.g. fileSize lt 1000000 or batchPublishedDate lt 2020-12-23T17:45:12Z.
  • Less Than or Equals (le) e.g. fileSize le 1000000 or batchPublishedDate le 2020-12-23T17:45:12Z.
• String operators:
  • Contains (contains()).
  • Starts With (startswith()).
  • Ends With (endswith()) - This operator returns true if the value of the attribute is a string and ends with the provided literal. e.g. endswith(filename,'.iso').

Note: the system does not support any other Functions or Arithmetic Operators.

Literal values

The system supports the following literal values:

• Null (null).
• True (true).
• False (false).
• Integer values (e.g. -128).
• String values (e.g. 'Say Hello,then go').
• String values with single quote (e.g. 'Rob O'Neil') - Replace 1 single quote with 2 single quotes to search a value having single quote. e.g. 'Rob O''Neil'
• DateTimeOffset values (e.g. 2012-12-03T07:16:23Z). Dates must be specified in the RFC 3339 format. They can contain a date-time offset, but will be converted to UTC before comparison.

Operator Precedence

Operators are listed by category in order of precedence from highest to lowest. Operators in the same category have equal precedence:

The Grouping operator (open and close parenthesis ( )) controls the evaluation order of an expression. The Grouping operator returns the expression grouped inside the parenthesis, e.g.:

  $filter=($batch(Product Type) eq 'AVCS') and ($batch(Week Number) eq '12' or $batch(Week Number) eq '13')

Examples:

$filter=$batch(Product Type) eq 'AVCS' and $batch(Week Number) eq '12' and batchPublishedDate gt 2020-10-21T00:00:00Z - All AVCS files for Week Number 2020/12 created after 21 Oct 2020.

$filter=batchPublishedDate gt 2020-10-21T00:00:00Z - All files created after midnight on 21 Oct 2020.

$filter=expiryDate lt 2020-12-21T00:00:00Z - All files due to expire before 21 Dec 2020.

$filter=$batchContains('AVCS')`