Vendor Sales Reports

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.

Configure vendor account connections to the Marketplace in the App's Configuration page:

FieldDescription
Vendor IDMarketplace Vendor ID of your organization
Vendor NameName of the vendor
Account Email AddressThe Atlassian ID to connect to the Marketplace. This account must be privileged to access transaction details.
Account PasswordPwd of the account to connect. Passwords are stored in encrypted form.
Sales GroupUser group whose members will see pricing information and may get notifications of new sales depending on Notification Type
Date View GroupMembers of this user group will be able to search and view transaction details without pricing information. They will not get notifications of new sales.
Notification TypeThe way the members of the Sales Group should get notified: None, In-app, Email, In-app and Email.

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:

Live Search Transaction Data

A new macro, "Vendor sales data browser" has been added to v3.0.0. This allows you to search for SEN numbers, AT numbers or company names in the transaction database and display the results dynamically.

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