Creating and updating reports via the HTTP API

The HTTP API has been updated to allow reports to be created and updated. To create a new report, send an HTTP POST request to $/reports/create with the report configuration as the post data (described below).

To update one or more existing reports, send an HTTP POST request to $/reports/update with the settings to be changed as the post data. The format is identical to that of the create request and only the settings specified in the post data will be applied, all other settings will remain unchanged. The reports to be updated are identified via the standard id/name/regex parameters in the request URL.

The format of the configuration data used to create and update reports is the same as that returned by a $/reports/list request, except that there is no top-level <channelReports> node. For example, the following POST request sent to $/reports/create will create a new report:

    <channelReport>
        <name> My New Report </name>
        <dataSource type="channelFilter">
            <channelFilterName> All </channelFilterName>
        </dataSource>
    </channelReport>

Creating a channel filter report

To create a report based on a channel filter, the POST data should include the following:

    <dataSource type="channelFilter" markItemsAsRead="yes" groupByChannel="yes" includeItems="new">
        <channelFilterName> ... </channelFilterName>
    </dataSource>
The includeItems attribute can be one of: All ; New ; Unread ; None.

Creating a channel folder report

To create a report based on channel folders, the POST data should include the following:

    <dataSource type="channelFolders" markItemsAsRead="yes" groupByChannel="yes" includeItems="all" includeSubFolders="no">
        <channelFolder id="..." />
        <channelFolder> ... </channelFolder>
    </dataSource>
Channel folders can be specified either by ID or name.
The includeItems attribute can be one of: All ; New ; Unread ; None.

Creating a workpad report

To create a report based on a workpad, the POST data should include the following:

    <dataSource type="workpad" markItemsAsRead="yes" removeItems="yes" runOnChange="no">
        <workpad id="..."> ... </workpad>
    </dataSource>
The workpad can be specified either by ID or name.

FTP, email and post-processing command

FTP, email and the post-processing command are configured via XML sub-nodes. If they are only partially present, the values specified will be used to create/update the report and all other values will remain as they are. For example, the following will update the TO address in an existing report's configuration, leaving everything else unchanged:

    <email>
        <toAddress> joe@blow.com </toAddress>
    </email>
To remove the configuration from a report, simply include an empty XML node. For example, the following will disable any post-processing command:
    <postProcessingCommand />

The report can be configured to check the post-processing command's return code as follows:

    <postProcessingCommand>
        <returnCodes type="..."> ... </returnCodes>
    </postProcessingCommand>
where a comma-separated list of return codes are specified and the type attribute can be one of: NoCheck ; EqualTo ; NotEqualTo

Template parameters

When updating an existing report, template parameters specified in the post data are applied to existing template parameters configured in the report i.e. they will update the parameter's value if it already exists, or create a new one if it doesn't. To remove a template parameter from the report's configuration, include a delete="yes" attribute e.g.

    <templateParam name="param1"> value1 </templateParam> <!-- create/update param1 -->
    <templateParam name="param2" /> <!-- create/update param2 (empty value)-->
    <templateParam name="param3" delete="yes" /> <!-- remove param3 -->

Miscellaneous

The format of items included in the report can be configured as follows:

    <feedContent> ... </feedContent>
where ... can be one of: Default ; Full ; Excerpt ; PlainText ; None

Any settings that include a directory path (e.g. template filename or output filename) can use one of the following directory aliases: