This page focuses on the tasks a Confluence administrator needs to do in order to set up, troubleshoot or migrate PocketQuery.
Installation and Setup
For detailed information on how to install and setup PocketQuery, please refer to the Getting started guide.
Configuring Access to the PocketQuery administration
PocketQuery provides an administration interface that can be accessed by Confluence administrators and all users of an arbitrary, configurable user group. All connections to datasources, queries, converters and templates are managed there. By default only Confluence administrators are allowed to access the PocketQuery administration to set up datasources and queries. If you want more users to be able to administer PocketQuery connections, you can choose to give access to additional groups of users.
To configure these groups, in the "General Configuration" find the new category "PocketQuery" (if you just installed the add-on, you might need to reload the page for this section to appear) and select the entry "Configuration".
Here you can configure an 'Administrators group' and an 'Editors group'. Enter the name of your user groups and save.
All users in this group (additionally to Confluence administrators) will have full access to the PocketQuery administration. They will be able to manage all datasources, queries, templates and converters.
All users in this group will have limited access to the PocketQuery administration. They will not be able to manage datasources, but are allowed to maintain all queries, templates and converters.
If you don't want part of your PocketQuery admins to fiddle around with your datasources, this is the right group for you.
Collecting Usage Statistics
PocketQuery can collect data on which macro is rendered how often and provide you with statistics. The data will be stored within your Confluence database and will not be sent to Scandio or any third party. To activate them, go to the section "PocketQuery" within the "General Configuration" and enable the option "Enable PocketQuery usage statistics".
This is what the statistics in your PocketQuery administration will look like:
The PocketQuery usage data will be stored within your Confluence database in a new table (using the "Active Objects" mechanism). The table contains a timestamp ("date"), the id of the page or blogpost the macro is included in ("content_entity_id"), the name of the query ("query_name") and an own unique id ("id"). Each data set represents one rendering of a PocketQuery macro.
As a result, you can use PocketQuery itself to further analyze this data! Have a look at the PocketQuery Macro Usage Queries we created for you.
Timeout and Data Limits
PocketQuery allows you to globally configure a timeout and data limits for both queries and REST calls.
The amount of seconds a query or REST call is allowed to take before it is aborted. By default this is set to 0 which means there is no timeout.
Your JDBC driver needs to support the remote query timeout server configuration option (queryTimeout).
Query Data Limit
The maximum number of rows processed per query that will be processed by PocketQuery. If the result of your query is bigger than this number, it is simply cut off, just like a LIMIT clause would do. By default this is set to 0 which means all rows are processed.
REST Data Limit
The maximum number of bytes accepted from a REST call by PocketQuery. If the result of your REST call is bigger than this number, the execution of your query is aborted. By default this is set to 0 which means all results are accepted.
By default, PocketQuery is very modest with logging in order to avoid flooding your log files. However, PocketQuery will become very talkative if you add a logging entry with the level DEBUG at Confluence Admin > Logging and Profiling:
Activate this, if you want to analyze the behaviour of PocketQuery. Information will be written to your atlassian-confluence.log file (if not configured otherwise in your instance).
Global Import / Export
You can export and import all PocketQuery data to and from XML. This mechanism is supposed to be used for backups and migration purposes. Go to Confluence Admin ("General Configuration) > PocketQuery > Import/Export:
Clicking “Export” will export all databases, queries, templates and converters to an XML file that can be imported later on.
If you import entities with names that already exist in your instance, these entities will be overwritten by the import. Overwritten data is not recoverable!
Read From Path
This feature is more for Confluence plugin developers - hello to you from Scandio :-)
Instead of writing the SQL and Velocity code for queries and templates, you can also deploy these resources as files in another Confluence plugin. These files can then be referenced in the query and template text area fields. This can be very useful, especially because you can have your PocketQuery queries and template in version control. This way you can also track changes to these files, revert back, etc.
Query example: if you have a *.sql file in your plugin at src/main/resources/pocketquery/queries/CountriesByLanguage.sql, you can include the SQL code in that file by using this code as your statement:
Template example: if you have a *.vm file in your plugin at src/main/resources/pocketquery/templates/CountriesByLanguage.vm, you can include the Velocity code in that file by using this code as your template: