<commit_before>cfr
===

Community File Repository<commit_msg>Documentation<commit_after>![image](http://www.webdetails.pt/images/wd_pentaho_horizontal.png) 
***

# Community File Repository (CFR)
***

## Overview

CFR (Community File Repository) is a new C*Tool made by [Webdetails](http://www.webdetails.pt) that allows you to setup and use a file repository from inside or outside Pentaho. You can use it to manage your file needs, allowing uploads and downloads from inside your dashboards. 

### Motivation

Frequently, we come across several file management needs in the context of the Pentaho platform:

- A user that wishes to let the users browse and download some documents when viewing a dashboard;
- An easy way for a user to upload some files to the BA Server (maybe to be used by an ETL job);
- The ability to explore, create and delete items in the Solution Repository when in a dashboard.

As always, when we are faced with the same kind of task more than two times, we start wondering if there’s a new CTool that can help us (and everyone who uses our stuff) automate that task. In this scenario, we came up with CFR - Community File Repository.


###Main features

- Ability to upload and download files from the repository
- Ability to create folders and delete items from the repository
- Small audit database lets you track who changed the repository and when.
- Provides a FileBrowser component for CDE that lets you browse the repository
- Provides a FileUploader component for CDE that lets you upload files for the repository
- Two distinct repositories available (just change a configuration setting):
	- Pentaho Solution Repository (whether DB or File based)
	- Filesystem Based repository (based on a folder on your BA Server machine or some other accessible machine)	


## Install & Config

This is a Pentaho plugin, so you can install it as normal.  

### Build and install the plugin 

The two opperations mode available are: aggregate and columnizer. 

- Clone public Git repository available [here](the https://github.com/webdetails/cfr.git)

- To build the plugn you can run on the command line: `ant dist-plugin`. This will create a .zip file inside `/dist` folder

- Unzip the file and copy the entire cfr folder to your `system` folder located inside your `pentaho-solutions` folder 

### Settings 

Inside your plugin folder there is a file `settings.xml` where you can define how the plugin will work.  

Files and folders are by default stored in `system/.cfr`. You can also configure some other root folder by editing the configuration file `settings.xml` and adding an attribute for your file repository with the full name of the starting folder.

~~~~~~
<basePath>
	/your/base_folder/for_cfr_files
</basePath>
~~~~~~

You can define another class, changing the value of `repositoryClass`. Right now, you can choose `pt.webdetails.cfr.repository.PentahoRepositoryFileRepository` for the Pentaho Solution Repository or `pt.webdetails.cfr.repository.DefaultFileRepository` for a file system based repository.

~~~~~~
<repositoryClass>
	pt.webdetails.cfr.repository.DefaultFileRepository
</repositoryClass>
~~~~~~

You can roll up your own version of a repository or develop a wrapper to whatever you’re using to manage your files. Just implement the `pt.webdetails.cfr.repository.IFileRepository`, drop the resulting class or jar in the `system/cfr/lib` folder and reference the class from `settings.xml`.

~~~~~~
<repositoryClass>
	pt.webdetails.cfr.repository.IFileRepository
</repositoryClass>
~~~~~~

## Workink with plugin

Using plugin can be made trough a user interface UI or using web requests. 

### User Interface 

You can use plugin using a friendly user interface

** User interface URL: ** `http://<pentaho-ba-server-host>:<port>/pentaho/content/cfr/home`

It will be presented a page where you can upload or download files (using the folder outside of pentaho  you can put files there over the traditional process "copy/move")  

### Web Requests


#### Files and folders operations 

To create, delete, list or get files and folders there are some exposed inetrfaces you can use.  

###### Exposed Interfaces 

** Base URL: ** `http://<pentaho-ba-server-host>:<port>/pentaho/content/cfr`

- **/createFolder** --> creates a folder

	**Query Parameters:**

	path --> specifies the folder we want to create

	**Examples:**

	/createFolder?path=/folder/subfolder --> creates the specified folder

- **/remove** --> removes a file of folder

	**Query Parameters:**

	fileName --> specifies the file or folder to delete 

	**Examples:**
	
	/remove?path=/folder/subfolder/file.txt --> removes the file with name "file.txt" located inside "subfolder"
	
	/remove?path=/folder/subfolder --> removes folder with name "subfolder"

- **/listFilesJSON** --> returns a [Json](http://www.json.org/) object with all files and folder. For root folder if no parameter specified 

	**Query Parameters:**

	dir --> (optional) specifies wich folder we want to list content

	**Examples:**

	/listFilesJSON --> returns a [Json](http://www.json.org/) object with all files and folders in root dir
	
	/listFilesJSON?dir=/folder/subfolder --> returns a [Json](http://www.json.org/) object with all files elements inside the specified folder

- **/createFolder** --> creates a folder

	**Query Parameters:**

	path --> specifies the folder we want to create

	**Examples:**

	/createFolder?path=/folder/subfolder --> creates the specified folder




#### Permissions management

The access to the files repository is granted by default to the files owner and to all the user administrators. If granting access to files to other users is needed it must be setted using the interfaces exposed below.

###### Exposed Interfaces 

** Base URL: ** `http://<pentaho-ba-server-host>:<port>/pentaho/content/cfr`

- **/setPermissions** --> 	Setting permissions is only allowed to the folder/file owner to which we want to set permissions or to any system administrator

	**Query Parameters:**
	
	path --> specifies the folder or file in which we want to set the permissions
	
	id --> specifies the role or username to which we want to grant the permissions
	
	permission --> this is an optional parameter, by default it assumes the read value. It is used to specify the permissions to be granted [for now only the read permissions are handled]
	
	**Examples:**
	
	/setPermissions?path=/test/&id=suzy --> sets read permissions for user suzy on repository folder test/ [this allows access to all the files contained in the folder]
	
	/setPermissions?path=test.txt&id=joe --> sets read permissions for user joe on file test.txt
	
	/setPermissions?path=/&id=suzy&permission=read&permission=write --> sets read and write permissions for user suzy on repository root folder [this functionality isn't yet totally implemented]

- **/getPermissions**
	Query Parameters:

	path --> specifies the folder or file in which we want to check the permissions

	id --> specifies the role or username to which we want to check the permissions

- ** /deletePermissions ** --> deleting permissions is only allowed to the folder/file owner or to any system administrator

	**Query Parameters:**

	path --> specifies the folder or file in which we want to revoke permissions

	id --> specifies the role or username to which we want to revoke the permissions
	
	**Examples:**

	/deletePermissions?path=test.txt&id=suzy --> revokes permission to file test.txt to user suzy

##FAQ

0. **How do I change the type of repository ?**
Edit settings.xml and change the value of repositoryClass. Right now, you can choose pt.webdetails.cfr.repository.PentahoRepositoryFileRepository for the Pentaho Solution Repository or pt.webdetails.cfr.repository.DefaultFileRepository for a file system based repository.

0. **How can I use another repository ?**
You can roll up your own version of a repository or develop a wrapper to whatever you’re using to manage your files. Just implement the pt.webdetails.cfr.repository.IFileRepository, drop the resulting class or jar in the system/cfr/lib folder and reference the class from settings.xml.

0. **Where are the files stored in the DefaultFileRepository?**
They are stored in system/.cfr. You can also configure some other root folder by editing settings.xml and adding an attribute defaultFileRepositoryRoot with the full name of the starting folder for your repository.

0. **Can I upload a file over a web request?**
Yes, we can build and execute a POST request specifying the correct options. For more details on this, please contact [Webdetails](http://www.webdetails.pt/) 

***

*Author:* <NAME>, <NAME> and Rafael	
*Created on:* 20/08/2013 
*Version:* 1.0
***











{'fraction_non_alphanumeric': 0.083687291929744, 'fraction_numerical': 0.0016071633566754678, 'mean_word_length': 4.232432432432432, 'pattern_counts': {'":': 0, '<': 17, '<?xml version=': 0, '>': 44, 'https://': 1, 'lorem ipsum': 0, 'www.': 6, 'xml': 6}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2666726', 'n_tokens_mistral': 2310, 'n_tokens_neox': 2186, 'n_words': 1129}