Creator Parameter API

Abstract

Reference documentation for how to configure the Ad Hoc Report Creator embeddable client via HTTP query parameters in order to set the current report, filters, sort, and more.


The Pull Reports™ Ad Hoc Report Creator responds to HTTP parameters encoded within the browser's location. Use these parameters to construct a URL to load a specific <report> within the creator, set filters, and sort or include columns.

For instance, if the web page into which the Ad Hoc Report Creator is embedded is http://www.mycompany.com/reports/index.html, then a url structured as

http://www.mycompany.com/reports/index.html?catalogId=mycatalog&reportId=myreport&filter=%40id%20%3E%20100

will load the <report> of id myreport within <catalog> with id mycatalog and apply the filter @id > 100.

HTTP parameters

catalogId

Designates the <catalog> id to load. Ignored if the catalogId init option is specified during Ad Hoc Report Creator initialization.

columns

Designates the columns to be included within the Result Preview panel. The columns parameter value is formatted identically to the Export Report REST API columns parameter.

distinct

Boolean value which sets the "Distinct" checkbox of the Result Preview panel.

filter

Designates the filters to be applied to the results within the Result Preview and Filter Summary panels. The filter parameter value is formatted identically to the Export Report REST API filter parameter.

limit

Designates the result limit of the Result Preview panel. Allowable values are 10 or 100.

offset

Designates the result offset of the Result Preview panel.

reportId

Designates the <report> id to load. If specified, the catalogId parameter must also be specified, and the reportId parameter must correspond to a report within the catalog.

sort

Designates the sort to be applied to the columns of the Result Preview panel. The sort parameter value is formatted identically to the Export Report REST API sort parameter.

Browser Usage Notes

Browser History

Most operations within the Pull Reports™ Ad Hoc Report Creator are responsive to the browser's back and forward buttons. This allows a user to undo/re-do an operation such as adding or removing a filter by simply using the back and forward buttons.

Bookmarking the Creator

Since the current state of the Ad Hoc Report Creator is captured within the browser's location, a user may bookmark or email the creator URL to a colleague. When a user returns to the creator, it will read the component state from the browser's location and return the creator to its expected state. An exception to this behavior is if the underlying <report> configuration changes in a way that is incompatible with the saved state. Examples of such incompatible changes are the removal of a <table> or the change of an id attribute value.

Bookmarking the Export Results

Similar to the creator, the export results are also bookmark-able since the export parameters are encoded within the bookmarked URL. Additionally, each time the export is rerun, the values are fetched again from the database, so the results are always current.

However, also like the creator, the export result bookmarks will potentially break due to incompatible <report> configuration changes.