Deep Links in Select Clause

Since version 2.0 the projectdoc Toolbox also supports Deep Links as an experimental feature. If the property name references a property whose value is a link, a deep link (specified with "->") allows to traverse the document tree.

Deep Links may have deeper depth than 1.

Note that prior to version 2.5 of the projectdoc Toolbox only single valued properties can be used with deep links. So if you are using an older version, if more than one link is found in a property value, only the first will be traversed.

Macros supporting Deep Links:

Property Names

To use property names in Lucene searches, the property names must not contain blanks. So if the search is restricted to user stories with just one story point, use this:

StoryPoints = "1" 

Template authors may use the $[...] marker to translate the property name to its normalized form:

$[Story Points] = "1" 

This is especially useful if the labels are provided by localized resource bundles. In this case the template author has not to bother, if the name contains spaces or not.

Reference Property Values

If the result set should contain only documents where one property matches the value of a property of the current document, use the ${...} placeholder to reference the property in the current document.

$[Story Points] = ${Magic Value}

For the example, the result set will only contain documents, that have the Story Point property set to a value matching that of the Magic Value property of the document the search is part of.

$[Story Points] = $\{Magic Value\}

Exact Match Queries

If the result should be an exact match query, use the following pattern:

$<Story Points> = [Magic Value]

In case the value is not a constant, you may also use a reference to the property of the document:

$<Story Points> = [${Magic Value}]

Escaping Special Characters

Since version 1.9 it is possible to escape special characters with a backslash (\).

$<Name> = [My Name \(with brackets\)]

To escape the escape character also use the escape character.

$<Name> = [My Name \\ containing a slash]

Deep Links in Where Clause

Since version 2.0 of the projectdoc Toolbox Deep Links are supported for property references (on the right side) as an experimental features.

$<Story Points> = [${Master->Ref Story Points}]

Note that you cannot use deep links on the left side of the where clause without Materialization. Since version 4.5 this is supported by property control mat, by space property Materialize by Doctype, or by Doctype Descriptor. Materialization is also possible in prior versions of the projectdoc Toolbox with a little more verbose approach. Read Materialize Properties for more information on this.

Subtree Queries

If you need to constrain the search result to documents with a given ancestor, you can take advantage of artificial properties like AncestorNames and AncestorIds.

$<AncestorNames> = [This Root Page]

Or you could constrain the search result by the current page.

$<AncestorIds> = [${Page ID}]

Ancestor Queries

For some type of properties it is useful to query for a given value or its ancestors. E.g. if you want to have all documents relevant for the Quick Response Team (QRT), a role derived from Ops, you may want to collect all documents marked with either QRT or Ops.

$<Audience> = ^QRT^

This is not only a shortcut for not listening all parents. If you add the following to the role template, the document will show all documents relevant for the role:

$<Audience> = ^${Name}^

Note that in the above example Audience is a property of a document that refers to documents of type Role. The hierarchy is defines on role documents. It may be confusing for new uses if they assume that the hierarchy is defined on the document containing the the Audience property.

If you need to search the hierarchy down the tree, use "°" instead of "^". So "°" stands for downstream, "^" for upstream search.

List Queries

$<Name> ~ (One, Two, Three)

$<Name>=[One] OR $<Name>=[Two] OR $<Name>=[Three]

$<Name> ~ (${Some Names})

Prefix Query

To select all resource documents that are read by a specific user ("jd" in this example) in a given year (specified by the document property Readjd in the format yyyy-MM-dd), use the prefix query:

ReadBy = "jd" AND Readjd = 2014*

Querying List Values

The Tags Property is one that is supported by all document types. It specifies a comma-separated list of values.

To select on those documents by tag values, use this:

Tags = (("test-me" AND "continous-delivery") OR "My-Tag")

Search all Topic Types that are no Fragments

A fragment is a basic document a couple of topic types (table, example, ...) derive from. To select only documents of a type that is not a fragment or one of its subtypes, use the following:

+TypeAncestors:[* TO *] AND -TypeAncestors:Fragment 

Note that in this case all documents have to have their topic type specific. If those that have not should also be part of the result set, use:

+Doctype:topic AND -TypeAncestors:Fragment

Using Dates

Since version 1.10 the projectdoc Toolbox provides normalized date value to be used with Lucene searches. If the property value is specified with the Confluence Date Autocompletion (opened with the shortcut '//'), and for the creation and last modification date, a normalized date is provided as an artificial property.

The name of this artificial property is that of the original property plus the §-sign appended.

Here is an example where the creation date is check against a custom property named Last Update.

$[Creation Date§]: [${Last Update§} TO NOW]

There is also an artificial property value containing the date as a timestamp in milliseconds, prefixed with zeros up to 19 digits (%019d). The name of the artificial property is constructed from the original name plus the suffix Timestamp (separated by a blank). Note that the creation timestamp is called Creation Timestamp (not Creation Date Timestamp).

Using Date Ranges

Confluence provides a couple of search fields to help finding the desired documents.

created:[20150311 TO 20150317]
created:[20150311 TO NOW]

Ranges work with Date Functions. Use the normalized date value to define range boundaries.

Date§: [20190101 TO ${now("", "-6w")}]
Date§: [${now("", "-6w")} TO ${now("", "-4w")}]

The Date property is recommended to be specified with the Confluence Date Autocompletion (opened with the shortcut '//').

Search Functions

A query function is a virtual function call that will replace the call with the return value of the function.

The syntax for using search functions is:

$<PROPERTY NAME>=${function-name(argument-list)}

Functions can be used for a value in a Where clause parameter of a projectdoc macro.

Functions cannot be used for a property name or outside the Where clause.

$<Start Date§>=${now()}

$<Login Name>=${currentUser()}

$<Attendee>=${currentUser("fn")}

currentUser()
currentUser("")
currentUser("id")

currentUser("fn")

$<Date§> >= ${now(-2w)}

$<Date§> >= ${startOfMonth()}
$<Date§> >= ${startOfMonth("")}
$<Date§> >= ${startOfMonth("", "")}

$<Date§> <= ${startOfMonth(-1d)}  // 4.1 and above
$<Date§> <= ${startOfMonth("", "-1d")}

$<Date> = ${now("dd.MM.yyyy", "-6d")}

(+/-)nn(y|M|w|d|h|m)

+2d

5y

-10w

-2d10y

$<Date§> >= ${now("", "-2w")}
$<Date§> >= ${endOfMonth("", "1w")}
$<Date§> >= ${startOfMonth("", "+3d")}

Date§: [${now("", "-6w")} TO ${now("", "-4w")}]

$<Date§> >= ${now("", "-6w")} AND $<Date§> <= ${now("", "-4w")}

$<Date§> >= ${now("", "-2w")}
$<Date§> >= ${endOfMonth("", "1w")}
$<Date§> >= ${startOfMonth("", "+3d")}

$<Date§> >= ${now(-2w)}
$<Date§> >= ${endOfMonth(1w)}
$<Date§> >= ${startOfMonth(+3d)}

Using Checkboxes

You can select property values that are checkbox and use checkboxes in your where clauses.

The checked checkbox has a text value of complete, an unchecked checkbox has a value of incomplete.

See Tasks as Property Values for an example.

Using Not

In general Not in a query is only allowed when it follows an positive expression.

To specify a document property not to have a certain value, use a range query like this:

+ID:[* TO *] AND -ID:6555694

*:* -Parent:[* TO *]

*:* NOT Parent:[* TO *]

Parent:[* TO *]

Tags = "logging" NOT ID = 3704077

Tags = "logging" AND ID NOT 3704077