Costlocker reports

Generate XLSX/HTML reports from Costlocker API. UI version is available at https://reports.costlocker.com (source code).

Installation

Clone + composer

• requires PHP >= 7.0, curl and gd extension

git clone https://github.com/costlocker/reports.git
cd reports
composer install --no-dev
bin/console report --help

Docker

Github Docker Registry

Circle.ci builds an image and publish it Github Docker Registry.

docker login --username username --password password docker.pkg.github.com/costlocker/reports
docker run --rm -it docker.pkg.github.com/costlocker/reports/master:371dda4 bin/console report --help

Custom build

docker build --file .circleci/Dockerfile --tag reports-costlocker ./
docker run --rm -it \
    --volume "$(realpath ./my-report.json):/app/my-report.json" \
    --volume "$(realpath ./var/logs):/app/var/logs" \
    --volume "$(realpath ./var/exports):/app/var/exports" \
    --volume "$(realpath ./var/googleDrive):/app/var/googleDrive" \
    reports-costlocker \
    bin/console report --help

Export configuration

Report is created in /var/exports. Optionally you can:

• Send report to e-mail
• Upload report to Google Drive

E-mail

Configure SMTP in .env.

cp .env.example .env
nano .env

Google Drive

You have to create an OAuth Client and copy configuration to /var/googleDrive.

File	Description
client.json	Google client registered via API console
token.json	Access token, you can download first token from https://developers.google.com/oauthplayground

mv ~/Downloads/client.json var/googleDrive/client.json
mv ~/Downloads/token.json var/googleDrive/token.json

Reports

Usage

Previous versions used CLI options for generating reports. Since v3 report is completely configued in JSON file (JSON schema).

# 0) Info about reports
bin/console report --help

# 1) Prepare config
## 1a) Create default config + manual edit
bin/console report Projects.Overview
nano config-Projects.Overview.json
## 1b) You can pass config in options
bin/console report Projects.Overviews --host "https://new.costlocker.com|<YOUR_API_KEY>" --email "john@example.com"

# 2) Generate report
bin/console report --config config-Projects.Overview.json
ls -lAh var/exports

Available reports

Title	Report type
Projects Billing & Tags	Projects.BillingAndTags
Billing Changes in Projects	Projects.BillingDiff
Projects Overview	Projects.Overview
Company Overview	Company.Overview
Grouped timesheet for recurring project	Timesheet.RecurringProject
Yearly tracked hours	Timesheet.TrackedHours
Weekly timesheet for groups	Timesheet.Week

New report

Reports are using ETL terminology:

• Extract data from Costlocker API
• Transform data to XLS or HTML
• Load data to your system (filesystem, Google Drive, e-mail)

New report must implement Extractor and Transformer. Take a look at available reports. For example check ProjectsOverviewExtractor and ProjectsOverviewToXls. Let us know if it's still unclear!

Contributing

Contributions from others would be very much appreciated! Send pull request/issue. Thanks!

License

Copyright (c) 2017, 2018, 2019 Costlocker SE. MIT Licensed, see LICENSE for details.