Vendor Sales Reports

Summary

Vendor Sales Reports may be used by vendors who sell plugins via the Atlassian Marketplace.

It contains two major components and features:

  • a scheduled job that fetches sale records via the Atlassian Sales API and stores them in your Confluence database

  • a macro that can dispay sale records in a tabular fashion. The macro output may be used to generate charts using Confluence Charts.

  • in-app notifications on new sales to not miss every single transaction

  • support multiple vendor accounts to aggregate more into a report 

How to Download the Complete Sales History

Vendor Sales Reports comes with a scheduled job running within Confluence's scheduler. It is responsible for downloading the sales records via the Atlassian Sales REST API.

The job does the following for each vendor account you register:

  1. first run: download the earliest set of sales records (the response is limited to 50 items by the API)
  2. subsequent runs: download the next set of records starting from the date of the last item already downloaded

This way the complete sales history is downloaded and stored gradually in your Confluence database.

For those who started using Vendor Sales Report version 1.0-1.3 (i.e. before version 1.4), you will have to do the following to ensure the complete set of sales records are downloaded:

  1. upgrade Vendor Sales Reports to version 1.4 or later
  2. remove the vendor accounts you created earlier and add them again

How to Render Your Sales Records

Vendor Sales Reports comes with a Macro that allows you to render sales records in various ways.

The macro allows you to set criteria on the sales records to be included in the output and set the type of output.

Search for Sales Records

There some parameters of the macro that determine the set of sales records that will be rendered or aggregated by the macro.

The parameters are:

  • startDate: first date of sales to be included
  • endDate: last date of sales to be included
  • reportPeriod: set periods relative to the current date. Values are:
    • All: search for all records determined by startDate/endDate
    • Today: search for sales records from the current day
    • This week/month/year: search for sales records from the current week/month/year
  • addonName: name of the add-on to search for

It is important to understand the following:

  • startDate and endDate must be specified in a format of yyyy-MM-dd, such as 2012-12-31
  • if both start/end date and period is defined, the macro searches for the sales records from the narrowest time frame:
    • if start date is earlier than the first day of the period, the latter will be used otherwise the former
    • if end date is later than the last day of the period, the latter will be used, otherwise the former
  • search can be limited to a single add-on by specifying its name (not the key)

Set Output Type

The macro generates data in a tabular fashion and adds a summary section to the top of the data table. The date in the table may be sorted by clicking on the column headers.

The macro renders data in the following ways:

  • Detailed
  • Aggregated
  • Totals only

Detailed Reports

Set the macro's output type to Detailed.

It will result in a table that shows all fields of all sales records returned by the filter parameters of the macro.

Aggregated Reports

By setting the macro's output type to either of the aggregated value, the output will a briefer summary of your sales activity.

Sales records may be aggregated by day, week, month and year. The aggregated output renders:

  • the aggregated value (day, week, etc)
  • the number of records pertaining to the group keyed by the aggregated value
  • the total sales price of the group
  • the total vendor amount of the group

Totals Only

By setting the macro's output type to Totals Only, you can have a short table containing number of sales records, total of sales price and vendor amounts.

Totals only is a special form of aggregation.

Generate Charts

All output types of the macro renders data in a HTML table. The macro's output may be added to the body of the Confluence Chart macro.

Confluence Charts macro is a flexible means to generate various chart type using the data tables in its body.

An example configuration of the charts macro:

  • type: line
  • width: 1200
  • Display rendered data: after
  • Chart title: Sales records 2012
  • Chart Subtitle: Aggregated monthly
  • Show legend?: true
  • Tables: 1
  • Columns: 1,3,4 (numbers mean respectively: aggregated date, total of sales price, total of vendor amounts)
  • Content orientation: vertical
  • Time series?: true
  • Date format: yyyy MMM
  • Time period: Month

The above configuration of the charts macro will result in a report like this one:

 


Known Issues

There are a few known issues:

  • Parameters of Vendor Sales Macro are not displayed when you want to edit an existing macro instance in a page

  • The sales downloader job is scheduled every 15 minutes. If you sell more than 50 licenses in 15 minutes, you're not only lucky but in a light trouble because Atlassian Sales API limits responses to 50 records. Therefore the records above 50, may not be fetched.

  • Passwords are stored plain text in the database 

Disclaimer

Hereby we declare that we do not take responsibility of any form for damages of any kind you may experience using this plugin.

Screenshots