====== Generating CKAN reports ======

===== Who is this guide for =====

  * Monitoring and evaluation officer who produces data for reporting
  * Editor and data officer who assist with reporting 
  * Program development officer who uses site analytics data for presentation and fundraising purposes  

===== What this guide teaches =====

  * How to run a BASH script which gathers reporting data from the contents stored on the ckan instance
  * How to to clone a github repository 

===== Things to know beforehand =====

  * This task requires some basic programming knowledge 
  * How to edit a BASH source code file
  * How to execute a BASH script
  * In order to complete this task, you will need access to the password repostory on [[https://ratticdb.proteus-tech.com:7078/|the rattic db instance maintained by Proteus]]

==== Setting up your machine to be able to execute the script ====

Depending on the operating system you are using, you would need to do the following:

- **OSX** and **Linux** users do not need to install any additional software but only be familiar with the Terminal console shipped with all operating system versions.
- **Windows** users will need to install terminal software such as https://putty.org/ in order to execute the script.
==== Cloning or downloading the library of scripts from the data_workstream repostory  ====

Within [[http://github.com/OpenDevelopmentMekong/data_workstream/|the data_workstream repository]] on the OpenDevelopmentMekong github organization, many different utility scripts and other pieces of code can be found and used for several purposes.

There are two ways to download them:

  - Download the zip file from [[https://github.com/OpenDevelopmentMekong/data_workstream/archive/master.zip|the following link]]. After downloading the .zip file, please extract it to the folder of your choice.
  - Clone the code repository using your favourite git client (advanced)

==== Configuring the reporting parameters  ====

The following parameters can be configured:

  - **DATE_FROM**: The initial date of the timeframe to get the reports about (e.g: 2017-06-01)
  - **DATE_TO**: The final date of the timeframe to get the reports about (e.g: 2017-12-31)
  - **PRIVATE**: Whether to gather private or public records (e.g: True)
  - **FILE_NAME**: The filename to store the results of the script.

In order to configure this parameters, the file **datasets_by_taxonomy.sh** needs to be opened with a text or code editor. The variables can be found on lines 5-8.

{{ :admin:screenshot_from_2018-02-16_15-18-52.png?nolink&600 |}}

These parameters need to be adapted prior to the execution of the script to make sure that the results contained the wished data.

==== Executing the script  ====

Once configured, the script can now executed. In order to do so:

  - Make sure the file **datasets_by_taxonomy.sh** has execution permissions. 
  - Get the [[https://ratticdb.proteus-tech.com:7078/cred/detail/197/|PostgreSQL Production]] password from the password manager system and copy it.
  - Run the script via the following command:

<code>./datasets_by_taxonomy.sh POSTGRESQL_PASS</code>

where POSTGRESQL_PASS is the password copied on step 2.

The script will run for some time (depending on the power of the computer and the network connection) and generate a CSV file with the filename specified on the parameters.