# customfields-projects-redmine

> Redmine project overview based on projects' custom fields and wiki.

Latest version **0.1.1** (published 2017-07-16) · GPL-3.0 license · 0 weekly downloads

## Install

```sh
npm install customfields-projects-redmine
pnpm add customfields-projects-redmine
yarn add customfields-projects-redmine
bun add customfields-projects-redmine
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.1.1 |
| Published | 2017-07-16 |
| First published | 2017-07-15 |
| Weekly downloads | 0 |
| License | GPL-3.0 |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 9 |
| Known vulnerabilities | 0 (+2 in 1 direct dependencies) |
| Install scripts | no |
| Author | DJ Caësar 9114 |
| Maintainers | djcaesar9114 |
| Keywords | Redmine, nodejs, custom fields, project, management, wiki |

## Links

- npm: https://www.npmjs.com/package/customfields-projects-redmine
- Repository: https://github.com/djcaesar9114/customfields-projects-redmine
- Issues: https://github.com/djcaesar9114/customfields-projects-redmine/issues
- npm.io page: https://npm.io/package/customfields-projects-redmine

## Dependencies (9)

- [pug](https://npm.io/package/pug.md) ^2.0.0-rc.1
- [jade](https://npm.io/package/jade.md) ^1.11.0
- [path](https://npm.io/package/path.md) ^0.12.7
- [colors](https://npm.io/package/colors.md) ^1.1.2
- [config](https://npm.io/package/config.md) ^1.26.1
- [express](https://npm.io/package/express.md) ^4.15.3
- [textile-js](https://npm.io/package/textile-js.md) ^2.0.3
- [body-parser](https://npm.io/package/body-parser.md) ^1.17.2
- [node-redmine](https://npm.io/package/node-redmine.md) ^0.2.0

## Recent versions

- 0.1.1 (latest) — 2017-07-16
- 0.1.0 — 2017-07-15

## README

* [version française](./docs/fr/README.md)

[![paypal](https://www.paypalobjects.com/en_US/i/btn/btn_donateCC_LG.gif)](https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=7WPD78QUVJ9D4&lc=FR&item_name=DJ%20Ca%c3%absar%209114&item_number=customfields%2dprojects%2dredmine&currency_code=EUR&bn=PP%2dDonationsBF%3abtn_donateCC_LG%2egif%3aNonHosted)
___

# Need

When an institution has to handle a great number of projects, it can be interesting for people having a transversal role (Chief Information Officer, Privacy Officer, Chief Financial Officer, etc.) to have a global overview without having to call every project manager.
Let's take the example of a French Privacy Officer: he'd like to know the reference of the project's declaration, its date of declaration, the type of data he handles, etc. He doesn't need to know the detail of every project and it could be tedious to have to wait the answer of each project manager in his inbox when a question is submitted, whereas every information can be entered in a collaborative tool.
It's this need that is satisfied here.

# Intended users

This application is intended for people having a transversal role among projects. If these projects are already managed with Redmine, this won't change anything for project managers.

# Requirements

* NodeJS
* Redmine

*__note:__ I haven't tested every verion, but I know that with nodeJS 8+ and Redmine 3.3.0+ the application works perfectly. Thanks for letting me know the versions you work with and whether the app is working or not.*

# How does it work?

The application checks if a project is eligible depending on a boolean custom field, and displays statistics and info.

## Features

### Header

In the header you can find the (parametrable) title, icons of the features and (parametrables) logos.

> ![Menu icons][menu]

### Home ![the home icon][icone_accueil]

This is a basic page explaining the features.

### Project overview ![the project overview icon][icone_recapitulatif]

It's a table showing projects' completion regarding the selected fields. You can export the table, select columns to display and even search the table. You can get to a project page by clicking on its name.

> ![Project overview][recapitulatif_projets]

### Projects' statistics ![the stats icon][icone_statistiques]

This page shows a global overview of custom fields' completion.

> ![Projects' statistics][statistiques_projets]

If you click on a stat (the green bar of a completed field or the red bar of an uncompleted field), the list of projects concerned by this stat is shown:

> ![List of projects concerned by a stat][statistiques_projets_resultats]

It is then possible to click on a project to get to its page.

### Projects' wiki pages ![the wiki icon][icone_wiki]

This icon is not displayed if there is no wiki page configured.
You have to select a project and a page.

> ![Wiki pages of a project][wiki_projet]

If a wiki page doesn't exist, an error message is displayed indicating that the wiki page doesn't exist.

> ![Wiki page doesn't exist][wiki_projet_manquant]

### Project overview ![the project page icon][icone_pageProjet]

All the information of a project is shown here if it's correctly completed. It's possible to get to the Redmine of the project if you click its name, and you can print the page if you click on the printer.

> ![Project overview][resume_projet]

### Create a project ![the project creation icon][icone_creerProjet]

It is a form automatically generated with configured custom fields:

> ![Project creation form][creer_projet]

Every input can be deleting by clicking on the black cross next to it; it is possible to reset the form by clicking on the red button.

> ![Filled project creation form][creer_projet_rempli]

If the project has been created, you'll get the following message:

> ![Project created][creer_projet_succes]

## Redmine configuration

You have to create in Redmine a boolean custom field associated to each project. As soon as a project will have this custom field set to "true", it will be displayed in the application:

> ![Create an eligible custom field in Redmine][champ_eligible_redmine]

This custom field has to be "used as filter" and "searchable". My advice is to set the default value to "false" and not to make it required.

You can then create every custom field useful for the application.

For all these fields you have to get their id (a integer) because it's these ids you'll have to enter in the application configuration.

## Application configuration

### Installation

#### using NPM

...soon...

#### from Github

```sh
$ git clone https://github.com/djcaesar9114/customfields-projects-redmine
$ cd customfields-projects-redmine
$ npm install
```

### Configuration

There are two elements to configure in the application:
* the key used to contact Redmine API;
* `default.json` and `production.json` configuration files in the `/config` folder.

Every time you change the configuration, you have to reload the application.

#### Redmine API key

The application needs the Redmine API key of a user having the rights to see all project information. My advice is to create a particular user such as "customfields-projects-redmine" and to use its key.
When you have this key, create a file named `redmineAPIKey.key` in the application folder (i.e. in the same folder as `index.js`), and write the key as in this example:

```javascript
var key = '9114934c4ce0bc97363ff3086983d576db08d115';
exports.key = key;
```

**Why not put the key in the parameters?**
*I'm used to never sharing identifiers granting access to personal data. Puttin the key in a separate file allows me to never communicate it accidentally if I publish a version of the application in which I left the key somewhere.*

#### Configuration files

There is at least a configuration file to fill: `default.json`. If you have different settings in production, you have to fill `production.json`. Every variable found in `production.json` will replace those of `default.json`

```JSON
{
  "Application":{
    // application port
    "port": 9114
  },
  "IHM": {
    // application title
    "titre": "Récapitulatif CNIL des projets",
    // [OPTIONAL] images in header, with height and link
    "images": [
      {
        "name": "cnil_logo-large.png",
        "title": "CNIL",
        "height": "20px",
        "link": "http://cnil.fr"
      },
      {
        "name": "djcaesar9114_logo_officiel_transparent.png",
        "title": "DJ Caësar 9114",
        "height": "20px",
        "link": "http://djcaesar9114.com"
      }
    ]
  },
  "Redmine": {
    // Redmine URL
    "url": "https://monredmine.url",
    // [OPTIONAL] maximum number of checked projects, 100 by default
    "maxProjets": 200,
    // id of the custom field used for eligibility of a project
    "champEligible": 18,
    // ids of the custom fields used in the application. Don't put ID_CHAMP_ELIGIBLE in it!
    "champRetenus": [16, 17, 19, 20, 21, 22, 23],
    // id of projects you don't want to appear in the list
    "projetsCendures": [20, 21],
    // [OPTIONAL] wiki pages of the projects
    "pagesWiki": [
      {
        titre: 'Informations traitées',
        url: 'Partie_1'
      },
      {
        titre: 'Mentions légales',
        url: 'Partie_2'
      }
    ]
  }
}
```

### Launch the app

If you don't have any difference with default and production configuration, (i.e. you don't have `production.json` file), you can launch:

```sh
$ node index.js
```

If you have a difference, you have to set a variable first:

```sh
$ export NODE_ENV=production
$ node index.js
```

If you want to save log files, you can naturally do this:

```sh
$ node index.js >> /var/log/customfields-projects-redmine.log
```

### Logs

The application is verbose:
* **[PROJET]:** describes the action on a project:
  * *éligible:* the eligible project is taken;
  * *non éligible:* the ineligible project is not taken;
  * *sauté:* the project is not taken, whatever its eligibility is;
  * if no project is eligible, a message appears;
* **[ERREUR REDMINE]:** describes the Redmine error encountered;
* **[CHAMP]:** describes the custom field treated;
* **[TYPES CHAMPS]:** JSON of all the custom fields and their information;
* **[FORMULAIRE] Envoyé:** sent form information;
* **[ID GÉNÉRÉ]:** created project's generated id;
* **[WIKI]:** tells what wiki page is loaded and its HTML content.

# Thanks

Thanks a lot to all of you on the internet (Stackoverflow, for example) who have answered my questions:
* [Ehsan](https://stackoverflow.com/users/1002584/ehsan) for his really simple method to convert a date (and yes, I needed that!): https://stackoverflow.com/a/27087163/1098303
* [Dogbert](https://stackoverflow.com/users/320615/dogbert) for his technique on conditionnal classes in Pug: https://stackoverflow.com/a/14144327/1098303

The mysterious author of this article: http://www.finalclap.com/faq/257-javascript-supprimer-remplacer-accent

And of course the developers of the technologies I used:
* [Redmine](http://www.redmine.org/): I'm a great fan of Redmine. I use it a lot, and not only for coding. Merci Jean-Philippe!
* [NodeJS](https://nodejs.org): I think I will never write any PHP line now. Oh, except if I have to translate a script to Node;
* [Bootstrap](http://getbootstrap.com/): when you are CSS-challenged like me, it's really helpful;
* [node-redmine](https://www.npmjs.com/package/node-redmine): it saved me a lot of time when it came to use Redmine API with Node;
* [express](http://expressjs.com/): very famous web framework;
* [pug](https://pugjs.org): after having tried a lot of template engines, I finally have converted to this one;
* [textile-js](https://www.npmjs.com/package/textile-js): it saved me a lot of time, not really wanting to develop a Textile/HTML converter;
* [colors](https://www.npmjs.com/package/colors): to write beautiful logs;
* [body-parser](https://www.npmjs.com/package/body-parser): essential when it comes to form manipulation;
* [config](https://www.npmjs.com/package/config): thanks for easing app configs...
* [dataTables](https://datatables.net/): do I have to introduce this JS library outstandingly handling tables?
* [jspdf](https://parall.ax/products/jspdf): allows you to save PDF from a page, but you'll prefer using printJS for complicated cases...
* [printJS](http://printjs.crabbly.com/): simplifies a lot printing, but beware of printing in a file to save the planet!
* [canvasJS](https://canvasjs.com/): to draw beautiful charts.

[menu]: ./docs/images/menu.png "Menu icons"
[icone_accueil]: ./docs/images/icone_accueil.png "Home icon"
[icone_recapitulatif]: ./docs/images/icone_recapitulatif.png "Projects overview icon"
[icone_statistiques]: ./docs/images/icone_statistiques.png "Projects statistics icon"
[icone_wiki]: ./docs/images/icone_wiki.png "Projects wiki icons"
[icone_pageProjet]: ./docs/images/icone_pageProjet.png "Project overview icon"
[icone_creerProjet]: ./docs/images/icone_creerProjet.png "Project creation icon"
[creer_projet]: ./docs/images/creer_projet.png "Screenshot of the project creation form"
[creer_projet_rempli]: ./docs/images/creer_projet_rempli.png "Screenshot of a filled project creation form"
[creer_projet_succes]: ./docs/images/creer_projet_succes.png "Message displayed after the successful creation of a project"
[wiki_projet]: ./docs/images/wiki_projet.png "Wiki page of a project"
[resume_projet]: ./docs/images/resume_projet.png "Project overview"
[wiki_projet_manquant]: ./docs/images/wiki_projet_manquant.png "Wiki page not found"
[statistiques_projets]: ./docs/images/statistiques_projets.png "Projects statistics"
[statistiques_projets_resultats]: ./docs/images/statistiques_projets_resultats.png "List of the projects concerned with the stat"
[recapitulatif_projets]: ./docs/images/recapitulatif_projets.png "Projects overview"
[champ_eligible_redmine]: ./docs/images/champ_eligible_redmine.png "Eligible custom field in Redmine"

---
_Source: https://npm.io/package/customfields-projects-redmine · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._