JNestor Reference Manual

Raul Luna

Legal Notice
Revision History
Revision 1.0Feb 2012
First version

Table of Contents

1. Introduction
Products used in this software
Conventions used in this document
Linux or Windows??
2. Installation
3. Configuring jNestor

List of Tables

1.1. Softtware used

Chapter 1. Introduction

Products used in this software

As many actual software, this software relies in many external libraries to do its job. This isn't a novelty. However, I want to specify this list just in case everybody knows it.

Table 1.1. Softtware used

ProductLicense / What it does
MantisConnect Propietary. It costs 50 euros if you plan to use this software for business (what else you would want this software for, mm??)
Spring 
  

Conventions used in this document

We will start with the usual, how we write certain things in the document: program listings, admonitions, and stuff like that.

[Caution]This will be for special advices

This box will be used when referring to things that, when unproperly done, may damage the correct behaviour of the program.

[Warning]This will be for warnings

We will use this box to refer to things that you have to put special care when doing them.

[Tip]This will be for advices and tricks

We will use this box to refer to things that must help in the configuration.

In general, filenames along this book will appear with this type of text: this-is-a-filename.txt. Moreover, when refering to text that appear as an output of the computer (like the output of a log file), they will appear as this:

2012-52-25 00:52:57 INFO  supermanhamuerto.nestor.MailReader       - Opening session...
2012-52-25 00:52:57 INFO  supermanhamuerto.nestor.MailReader       - url:http://localhost/mantisbt-1.2.8/api/soap/mantisconnect.php
    

On the other hand, when speaking of things that must be typed, the text will appear as this: dir. If the computer outputs the text, it will be shown as this: Hello world!!

Linux or Windows??

Whenever possible, I'll avoid to give the same instructions for Windows™ and Linux, specially if they are more or less the same. This will make the text more readable. This document is highly technical and the audience is accustomed to Linuxize the windows commands or to Windize the linux ones.

Chapter 2. Installation

Download the latest bundle of the website and uncompress it. After uncompressing the contents, you will find some things in it:

Chapter 3. Configuring jNestor

So you have downloaded the zip (or tgz) bundle, uncompressed it and now...what??

The aim of this document is to explain the basics for make Jnestor to do what is designed for, and to suit into your particular case as smoothly as possible.

There is only one configuration file in JNestor: applicationContext.xml. If you know something about java programming, you should be aware that this file is in reality the configuration file for the beans of the application. I've decided to put the configuration in that file because that allow me many advantages:

  • I don't need to make code for the configuration of the application: Spring takes this duty for me, allowing me to concentrate on other tasks

  • I can easily configure things like cuustom actions by wiring them to the proper list of beans

  • Even the log information is stored in the applicationContext.xml file, making thus the unique configuration file for the whole application. You can forget of the hassle of having many configuration files

  • Saving a previous state of the configuration is easier: just make a copy of this file and you are done

[Caution]applicationContext, a blessing and a danger

This model has also disadvantages: this file is and xml file, and because of this, any nuance can cause it to don't load properly. To prevent that cases, I strongly recommend to make copies of this file prior any important modification.

[Note]If you have reached this point...

From time to time, in the configuration process, you will come across with sections like this: in this sections I will double-check the previous configurations, just to be sure the previous changes are working.

Avoid to do something you could lament

Although the instruction I am giving here are for the configuration with the minimum impact, I suggest to take precautions in trying any new software.

So, the first thing we will do is to install a filter for the emails that JNestor will process. Only emails with the subject yor-name or 9778 will be processed, the rest will be left untouched.

In order to do so, open the file applicationContext.xml and search for filter.contains1. You should find something like this:

    <!-- LEAVE BLANK THIS FILTER TO PROCESS ALL EMAILS -->
    <prop key="filter.contains1">.*9778.*</prop>
    

This is a filter who only will process the emails with the figures 9778 in the subject. While configuring JNestor, put whatever you want in substitution of this 9778, and after the configuration, remove this.

Configure mantis access

Guess mantis API url

Mantis url is something like this: http://server/mantis/api/soap/mantisconnect.php. Probably, in the release you have configured the development server I use, which is installed in localhost. Make the proper changes in this url and put in the file.

[Note]If you have reached this point...

Check that the url of mantis works: open a browser and point it to the url you have made. You should see something like this:

The API of mantis, in a browser

In which project do you want the issues be entered??

JNestor only can enter the new issues in a specific project in Mantis. One mailbox, one project: if you have two projects, consider to have two mailboxes and two instances of JNestor running at the same time.

To guess the project number, just enter into mantis and click on Manage -> Manage Projects. The list of projects in Mantis should appear.

Click on the project you want. In the address box of your browser, you should see something like this: http://localhost/mantis/manage_proj_edit_page.php?project_id=1. The number that comes after project_id= is the project number.

[Tip]Tip

If you are not the administrator, there are other ways to guess the project number. If you try to move an issue (edit the issue and then click on the button Move), you will see a list of the available projects. Just see the source code of this page and you will get a list of the projects with the respective id's.

Create an user

You need a mantis who has permission to enter his own issues in mantis. Everything in mantis is entered with an username, even the items put through the API.

To create a user for JNestor, just follow the following steps:

  1. Enter in mantis with administrative privileges and manage -> manage users

  2. Click on the create new account button

  3. And enter the data of the new account. For the purpose of this manual, I've entered an username of jnestor, the rest of the data is irrelevant. You have to enter a correct email address because you have to reset the password afterwards.

    Options screen of firefox

Configure email access

Probably is the most complex part of this, because too many parameters here, all of them inherited from JavaMail. If you work in a corporate enviroment, and have access to the email administrator, is a good idea to ask him (or her) what are the correct values here.

If not, or if you are working with publicly available network accounts, here is my advice: try to configure one email client (Thunderbird, Outlook). If you succeed in this, you are almost done to configure JNestor.

Remove the email filter and you are done

When you are finished, remember the filter we put in the section called “Avoid to do something you could lament” and remove it.

You know, open the file applicationContext.xml and locate the keyworkds filter.contains1 and leave it blank.