Chat now with support
Chat with Support

Unified Communications Analytics 8.6.1 - Resource Kit

About the Object item

The first required item for a query is the object item against which you are querying. The object items are found in the output of the DataModelSamples PowerShell sample. You provide the object type in quotes, such as the following: For("EmailMessage"). This part of the query is required for both object and aggregate query types.

About the Time clause

The next step in the query is to establish the time slice to which you want to limit your query. You add the time clause as an explicit item so that you do not need to include the time clause in the main Where clause. The list of supported time clauses is as follows:

 
Table 4. Time clauses used in queries.
Time clause
Definition
Syntax

WithinLast

Within the last X periods

Specified as WithinLast(PeriodCount, PeriodIdentifier)

Before

Before a particular date

Specified as Before(DateValue)

When a date is specified, the query uses the end of the specified date so the query will include the date. (The time portion of the date is ignored.)

After

After a particular date

Specified as After(DateValue)

When a date is specified, the query uses the start of the specified date so the query will include the date. (The time portion of the date is ignored.)

Between

Between two dates

Specified as Between(StartStartDate, EndDateValue)

For each date, the date follows the same rules as Before and After. (The time portion of the date is ignored.)

For classes that require a date value, all dates must be UTC date/times. The best way to establish the date is to use the following two-step process:

$startDate = Get-Date -Date "2014-09-01 00:00:00Z"
$startDate = $startDate.ToUniversalTime()

Here is an example:

After($startDate)

For clauses that reference a time period, UC Analytics supports a number of pre-defined periods. They are as follows:

•
Minute
•
Hour
•
Day
•
Week
•
Month
•
Quarter
•
Year

To use a time clause that references a period, you must associate the given period as a local variable that is referenced in the actual clause. The periods are part of the RelativeDate attribute and are as follows:

•
$minutes = [UC.Analytics.Insights.ResourceKit.ODataClientLibrary.RelativeDate]::Minute
•
$hours = [UC.Analytics.Insights.ResourceKit.ODataClientLibrary.RelativeDate]::Hour
•
$days = [UC.Analytics.Insights.ResourceKit.ODataClientLibrary.RelativeDate]::Day
•
$weeks = [UC.Analytics.Insights.ResourceKit.ODataClientLibrary.RelativeDate]::Week
•
$months = [UC.Analytics.Insights.ResourceKit.ODataClientLibrary.RelativeDate]::Month
•
$quarters = [UC.Analytics.Insights.ResourceKit.ODataClientLibrary.RelativeDate]::Quarter
•
$years = [UC.Analytics.Insights.ResourceKit.ODataClientLibrary.RelativeDate]::Year

For example, if you want to look at messages in the last five weeks, you would add the $weeks item and establish the following time clause:

WithinLast(5, $weeks)

About the Where clause

The Where clause in the query definition is used to specify conditions that restrict the selected items. As with most query syntax, the Where clause follows a simple structure:

{AttributeName} {Operator} {Value}

To establish a filter, you must establish a reference to the filter type:

$filter = [UC.Analytics.Insights.ResourceKit.ODataClientLibrary.Filter]
Specifying the Filter operator
Specifying the Attribute name and value
Specifying the Filter operator

UC Analytics supports the following comparison filter operators that must be specified as local variables:

 
Table 5. Operators for comparison filters
Operator
Definition

Equal

$equal = [UC.Analytics.Insights.ResourceKit.ODataClientLibrary.FilterOperator]::Equal

NotEqual

$notequal = [UC.Analytics.Insights.ResourceKit.ODataClientLibrary.FilterOperator]::NotEqual

GreaterThan

$greaterthan = [UC.Analytics.Insights.ResourceKit.ODataClientLibrary.FilterOperator]:: GreaterThan

GreaterThanOrEqual

$greaterthanorequalto = [UC.Analytics.Insights.ResourceKit.ODataClientLibrary.FilterOperator]:: GreaterThanOrEqual

LessThan

$lessthan = [UC.Analytics.Insights.ResourceKit.ODataClientLibrary.FilterOperator]:: LessThan

LessThanOrEqua

$lessthanorequalto = [UC.Analytics.Insights.ResourceKit.ODataClientLibrary.FilterOperator]:: LessThanOrEqual

Specifying the Attribute name and value

Next, you must specify the attribute name. The naming convention for the attributes is explained in Finding a full attribute name and applies in this clause. Enter the full name of the attribute on which you want to filter.

For the value, there are different values that you can enter. The value that you need to specify depends on what is listed as the attribute type. Possible values are listed here:

•
String: Enter the text in double quotes.
•
Int32, Int64, Double: Enter the numeric value without any quotes.
•
Some of the numeric values are enumerated types that provide the mapping.
•
The mapping items are provided in the output of DataModelSamples.ps1. For example, Email Message Sensitivity has its own item EmailMessage/Sensitivity, with one of four items. To query based on Private, you would use 4.
•
DateTime: Specify the UTC date time using the format described earlier in the document.
•
Boolean: Specify one of the PowerShell Boolean values: $TRUE $FALSE

Based on this simple Where clause, you would enter:

Where($filter::Clause("EmailAddress.Person.Department ", $equal, "R&D"))

About more complex Where clauses

Though a simple Where will work, you can use more complicated Where clauses. See the following examples for more complex scenarios:

Filtering on multi-valued attributes
Specifying the Not operator
Specifying the AND / OR operator
Filtering on multi-valued attributes

Some fields are collections of records. One example is Recipients. UC Analytics provides the ability to establish a query based on the following criteria for these multi-valued fields:

•
Any: At least one of the items in the collection satisfies the criteria.
•
All: All the items in the collection satisfy the criteria.

The query for the underlying recipient follows the previous example. The additional field is added above it to provide the total filter.

For example, to query on any recipient with something specified in the recipient name:

Where($filter::Clause("Recipients", $any, $filter::Clause("EmailAddress.Person.Name", $equal, "Joe Smith")))

To use either of these two fields, you must define the associated local variables:

•
$any = [UC.Analytics.Insights.ResourceKit.ODataClientLibrary.FilterOperator]::Any
•
$all = [UC. Analytics.Insights.ResourceKit.ODataClientLibrary.FilterOperator]::All
Specifying the Not operator

The Not operator is a common Boolean operator. UC Analytics provides support for this construct using the same style as the multi-valued attribute. The only difference is that you define a filter expression that you reference to the specified filter clause.

You must specify the Not operator:

$not = [UC.Analytics.Insights.ResourceKit.ODataClientLibrary.FilterOperator]::Not

For example, you could query on any recipient that does not have a value in the recipient name:

Where($filter::Expression($not, $filter::Clause("EmailAddress.Person.Name", $equal, "Joe Smith")))
Specifying the AND / OR operator

Much like the Not operator, the AND / OR operators are common. These operators are used in a similar manner as the Not operator, but with two filter clauses.

You must specify the additional operators:

•
$and = [UC.Analytics.Insights.ResourceKit.ODataClientLibrary.FilterOperator]::And
•
$or = [UC.Analytics.Insights.ResourceKit.ODataClientLibrary.FilterOperator]::Or

For example, to query on any recipient that does not have a value in the recipient name:

Where($filter::Expression($and, $filter::Clause("EmailAddress.Person.City", $equal, "New York"), $filter::Clause("EmailAddress.Person.Department", $equal, "R&D")))

You can achieve the AND operator by providing two consecutive Where conditions. The following statement is the same as the previous Where condition for AND:

Where($filter::Clause("EmailAddress.Person.City", $equal, "New York")), `
Where($filter::Clause("EmailAddress.Person.Department", $equal, "R&D")), `

You can use this clause in both query types.

Related Documents

The document was helpful.

Select Rating

I easily found the information I needed.

Select Rating