customfields-projects-redmine v0.1.1

• version française

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.

Home

This is a basic page explaining the features.

Project overview

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.

Projects' statistics

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

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:

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

Projects' wiki pages

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

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

Project overview

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.

Create a project

It is a form automatically generated with configured custom fields:

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.

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

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:

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

$ 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:

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

{
  "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:

$ node index.js

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

$ export NODE_ENV=production
$ node index.js

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

$ 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 for his really simple method to convert a date (and yes, I needed that!): https://stackoverflow.com/a/27087163/1098303
• 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: I'm a great fan of Redmine. I use it a lot, and not only for coding. Merci Jean-Philippe!
• NodeJS: I think I will never write any PHP line now. Oh, except if I have to translate a script to Node;
• Bootstrap: when you are CSS-challenged like me, it's really helpful;
• node-redmine: it saved me a lot of time when it came to use Redmine API with Node;
• express: very famous web framework;
• pug: after having tried a lot of template engines, I finally have converted to this one;
• textile-js: it saved me a lot of time, not really wanting to develop a Textile/HTML converter;
• colors: to write beautiful logs;
• body-parser: essential when it comes to form manipulation;
• config: thanks for easing app configs...
• dataTables: do I have to introduce this JS library outstandingly handling tables?
• jspdf: allows you to save PDF from a page, but you'll prefer using printJS for complicated cases...
• printJS: simplifies a lot printing, but beware of printing in a file to save the planet!
• canvasJS: to draw beautiful charts.