PocketQuery 4.x Upgrade Notes

Upgrading from PocketQuery 3.x to 4.x should not require any actions in general. Still, a lot has changed under the hood, which is mostly due to the fact that it’s now possible to rename PocketQuery entities (Queries, Datasources, Templates, Converters).

Entity Keys in Template APIs

A few more low-level templating APIs now require query/template keys rather than template names. This applies to the following methods.

Templating Velocity API (updated docs: Velocity API Available In Templates):

$PocketQuery.executeQuery
$PocketQuery.template

Templating JavaScript API (updated docs: Javascript API Provided By PocketQuery)

PocketQuery.queryColumns
PocketQuery.queryJson
PocketQuery.queryArray

You can obtain the keys for queries and templates from the admin UI (below the name input field):

New dynamic parameter form

We have changed the template for the dynamic parameter forms. This is what will be included if you check the Use change params template macro parameter. In some cases, you have included and adapted this template yourself. The new template can be found here: Template For Dynamic Parameter Change. If you are using the old template code in any of your templates, you will see a warning about some methods being deprecated (getValueFromMapEntry, getParameterFromRequestOrMacro). We have created a FAQ article that should help you to replace these functions: How to replace 4.x deprecated PocketQuery functions in Templates?.

Deprecated Velocity helper methods

A few Velocity helper methods have been deprecated. For these you will see a warning message on the PocketQuery admin dashboard:

$PocketQuery.getParameterFromRequestOrMacro (see “New dynamic parameter form“ above)
$PocketQuery.getValueFromMapEntry (see “New dynamic parameter form“ above)
$PocketQuery.dataTags
$PocketQuery.renderMacroByMarkup (Wiki markup is deprecated by Atlassian, please use $PocketQuery.renderMacro instead)
$PocketQuery.renderWikiMarkup (Wiki markup is deprecated by Atlassian)
$PocketQuery.renderXhtml

Deprecated JsonPath query field

The JSON Path field for queries has been deprecated in favor of Converters. Anything that was done with this field can also be achieved with a Converter. Please look at How to migrate from JSON Path to a Converter.

Changes to PocketQuery.load

There is an undocumented JavaScript API method PocketQuery.load that we have used in some support cases and examples. If you are using it for nested queries, for example, the data object API has changed from:

CODE

data: {
    pageid: $page.id,
    query: '$nestedQuery',
    queryname: '$nestedQuery',
    queryparameterstring: 'issueKey=' + issueKey
}

to:

CODE

data: {
    contentKey: $page.id,
    queryName: '$nestedQuery',
    queryParameters: {
		issueKey: issueKey
	}
}

If you experience any problems while upgrading, please create a ticket. We are happy to help! 🙂