Awasu API: Reports

The Awasu API has been extended to allow reports to be created, updated and deleted.

  • To create a new report, send an HTTP POST request to $/reports/create with the report configuration as the POST data.

  • 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 reports to be updated are identified via the standard id/name/regex parameters in the request URL.

  • To delete one or more reports, send an HTTP GET request to $/reports/delete, identifying which reports to delete via the standard id/name/regex parameters.

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>

 

Report type

The type of report is configured via the dataSource@type attribute:

  • 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.

  • 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>
        </dataSource>
    
    Channel folders can be specified either by ID or name.

    The includeItems attribute can be one of: All ; New ; Unread ; None.

  • 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. For example, the following will update the TO address in an existing report's configuration:

    <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 remove 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 any 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.

For example:

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

 

Directory aliases

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