# Vendor Sales Reports Overview
## **What is Vendor Sales Report**
**Vendor Sales Reports** may be used by vendors who sell add-ons 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](https://developer.atlassian.com/display/UPM/Accessing+Sales+Reports+with+the+REST+API).
The job does the following for **each vendor account** you register:
1. **first run:** downloads 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:
| Field | Description |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Vendor ID | Marketplace Vendor ID of your organization |
| Vendor Name | Name of the vendor |
| Account Email Address | The Atlassian ID to connect to the Marketplace. This account must be privileged to access transaction details. |
| Account Password | Pwd of the account to connect. Passwords are stored in encrypted form. |
| Sales Group | User group whose members will see pricing information and may get notifications of new sales depending on Notification Type |
| Date View Group | Members 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 Type | The 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
