Concepts: Basics of Collections

Introduction

This article introduces you to calling a collection command, the parameters they accept, and the output they produce.

Reference

A collection command is a type of command that is generally plural by name and produces a list of items in a `Collection` property. Examples of collection commands are `Get-Clients`, `Get-Matters`, and `Get-BillingEntries`. The list of items within the collection can also be  referred to as a "page" within the documentation and cannot exceed the system limit of 1,000 items per page. A collection command may take some parameters to help filter, order, and page the data that will be available in the collection property. Below is a table of parameters that all collection commands may take:

Setup & Execution

Create a new script named "Matter collection tests" and start with the following body:

$matters = Get-Matters -Top 1

Write-Output $matters | ConvertTo-Json -Depth 1

Execute the script and you'll see something like the following results:

{
  "Collection": [
    "AgilityBlue.ViewModels.Workspace.MatterFieldsCacheRecordViewModel"
  ],
  "Top": 1,
  "Skip": 0,
  "TotalCount": 63
}

Points of consideration:

• The first line of the script uses the `Get-Matters` collection command to retrieve a list of matters within your workspace. Collection commands are commands that are plural in name, and always return the same object with the following properties:
  • Collection: These are the items as the result of the collection command. In this instance, the `Get-Matters` command will return a collection of matters.
  • Top: This is the maximum number of records to return per page. This number will be the same as the `Top` input parameter and can be useful to refer to in paging scenarios where there are more records beyond the maximum as indicated in the `TotalCount` property.
    Top Default and Maximum

    If you don't include the `Top` parameter, it will default to 40 items in a collection. The maximum top that you can provide is 1000. If you try to define a top greater than the maximum, you will be presented with an error.
  • Skip: This property is used in paging scenarios where a number of items are skipped to return a page of records starting at a specific zero-based index. For example, let's say you wanted to get page 2 of a collection of items where each collection page returns 1000 records. The formula is "Top * (Page - 1) = Skip", so in this example, it would be "1000 * (2 - 1) = 1000". Essentially, the `Skip` parameter tells the system to retrieve a page of records (the "Top") that start on that record index (the "Skip") in the total collection of records (the "TotalCount"). The `Skip` property here will be the same as the `Skip` input parameter.
  • TotalCount: This is the total count of all records, after any filters are applied, regardless of how many items are returned in the collection.
• The `-Top 1` parameter indicates that we're only interested in having the system return back the first item in the collection. We're doing this here in this example because we don't need to put any extra strain on the system for the type of output we're performing (printing a JSON representation of the collection object).
• The second line of this script pipes the output of the `$matters` variable to the `ConvertTo-Json` command. This is a trick you should consider doing often while developing scripts to analyze the structure of the output of a command if you're unfamiliar with all of the available properties of an object.

Now that we have an idea of the object structure of a collection object, let's modify our script to print out the total number of matters in our workspace based on the "TotalCount" property. Edit the script and change the body to the following:

$matters = Get-Matters -Top 1

Write-Output "There are $($matters.TotalCount) matters in this workspace"

Save the script, navigate to the details page of the script, and execute it. The total number of matters will be output in your results. For example: 

There are 63 matters in this workspace

Points of consideration:

• We removed the JSON output conversion, since we now understand that we're interested in the "TotalCount" property of the collection object. Removing unnecessary output will help with performance considerations further down the line when it's time to optimize the script.
• We can observe that even though there is only one matter object in the "Collection" property, the "TotalCount" property provides us with a count of all of the available matters in the workspace. 
• The TotalCount property is the total number of items after any filters have been applied.
• Bonus: We've used a PowerShell concept called "string interpolation" where we can write an object's property directly within a string without needing to format or append multiple strings together.

Let's modify the script one more time so it shows us a total count for both active and inactive matters. We can achieve this by calling the `Get-Matters` collection command twice where each command takes an OData filter. 

Edit the script to now look like this:

$activeMatters = Get-Matters -Top 1 -Filter "Active eq true"
$inactiveMatters = Get-Matters -Top 1 -Filter "Active eq false"

Write-Output "There are $($activeMatters.TotalCount) active matters in this workspace"
Write-Output "There are $($inactiveMatters.TotalCount) inactive matters in this workspace"

Execute the script and it will produce two lines of text that separate the counts between active and inactive matters in your workspace:

There are 22 active matters in this workspace
There are 41 inactive matters in this workspace

Points of Consideration:

• We've effectively reproduced the previous script twice, but provided a filter for each matter status: one where the collection contains active matters, and one where the collection contains inactive matters.
• The `-Filter` command here accepts the same OData string filter that the REST API would take. The official OASIS OData v4 documentation has much better documentation regarding the subject of filtering, however, keep in mind that Agility Blue may not necessary have every specification implemented in the OASIS standard.
• The filter example here uses the matter's "Active" field to locate the matter collection we're interested in . The Active field is a system boolean field that accepts true/false/null values. If an object allows for custom fields, you would use the ID of the custom field instead of the name. Custom field filtering will be discussed in more detail in a later tutorial!