README
Table of Contents :
1. General Informations
2. Webservice Installation
3. Evolutions since Mantis Connect 1.0a4
4. Informations about tests
5. Development of new features
Annexe:
A. Documentation generation with PhpDocumentor
B. External Links
1. General Informations
This version of Mantis Connect has been developed using : Mantis 1.0.8, NuSoap 0.7.2, PHP 5.1.6, Apache 2.2.4 and MySql 2.9.1.1.
Developement made by Alexandre Laborie from Axidea company : http://www.axidea.fr/.
2. Webservice Installation
In Mantis root folder, create a webservice folder where Mantis connect files will be. Change FILE_MANTIS_CONNECT constant config_inc.php file in test-unitaire folder. To ensure a correct install you have to run the test senario with correct results. To do this, you need an empty Mantis database with only a admin account, then you'll have to log in Mantis and do the following actions:
- Add following users : dv (type : developer), dv2 (type : developer), rap (type : reporter), inv (type : guest). Then put users corresponding passwords in scenario_bug.php file (line 19) of test-integration folder. The 5th entry is an existing user with a wrong password and the 6th a user that doesn't exist.
- Add three projects in Mantis, the project 1 is public is named 'tgv', the project 2 is private is nammed 'top secret project', the project 3 is public is nammed 'ameli'. Then, add created projects Ids in scenario_bug.php file (line 37).
- Add to project 1, categories : 'front face' et 'back face'.
- Add dv as a developper in project 2 .
- Add a public bug in a public project. Add two attachments to this bug. Then create another public bug but in a private project. Add a file to this bug. Then put the Ids of the last two bugs that you just added, as well as the ID of the last file added in the file scenario_bug.php (Respectively line 30 and 34).
Do not forget that the following conditions must be met :
- The test script should be the only one to handle Mantis throughout its execution.
- All permissions must be set to Mantis default (except dv user who has developper privileges in project 2).
/!\ WARNING : The test script sends a batch of e-mail notifications. In order not to overload your mail server, use local email mechanism
/!\ WARNING : The execution time of the script is fairly long, about 120 seconds on an Athlon 2800 + with 1GB of RAM. So be patient!
From now on you can run the test script. If all test results are correct (indicated by a green background), the webservice is operational, otherwise check the configuration of webservice and Mantis, as well as the prerequisites listed above.
3. Evolutions since Mantis Connect 1.0a4
From version 1.0a4 of Mantis Connect (Available here: http://sourceforge.net/projects/mantisconnect/), the following enhancements have been made:
- Refactoring of Mantis Connect architecture
- Improving the permission system: complete modification of the permission system to make it more efficient and consistent with the permissions of Mantis.
- Override mantis errors: controls error of webservices are lighter because of the Mantis error handler which is overriden, avoiding dupplicate checks (once in Mantis and another both MantisConnect). Now there is only one error control (except in exceptional circumstances).
- During the restructuring of the project, we took the party to use as little as possible NuSoap ComplexType and use instead the basic types. Now, when a complex variable must be returned, it is serialized and converted into string (php serialize() function).
- Adding of PhpDocumentor compatible comments in order to generate documentation easily.
- Cutting mc_issue_api.php in two files, mc_bug_api.php and mc_bugnote_api.php, To be consistent with the boundaries of Mantis files .
- Webservices add:
- For the management of bugs (mc_bug_api.php), in addition to these old features have been added : update a bug, assign a bug, change the status of a bug, bug move from project to anothe rproject, start / stop the monitoring of a bug, copy a bug, get the bug history, send a reminder to a list of user, retrieve the number of bugnotes of a bug, retrieve the date(timestamp) of the latest update, reopening a bug, tests to determine whether a user is the reporter of the bug, tests to determine whether a user is assigned to a bug and test to check the bug read-only status.
- For the management of attachments (mc_file_api.php) following features have been implemented : test if a bug has attachments, test if a user can view attachments, test whether a user has permission to download attachments, test if a user can delete attachments, test whether a user has permission to add files to a bug, test whether a user has permission to add files to a project, delete a file, delete all files associated with a bug, delete all files related to a project and return the attached files of a bug.
The choice was made not to add a upload webservice for the attched file, because it is not it's job. Indeed, by conducting tests, we quickly realized that the processing time of webservice is far too long, even for files of a few hundred kilobytes. This will be the user interface to take care of this part.
- For filters management (mc_filter_api.php), in addition to these old features have been added: test whether a user can delete a filter, return the default filter, retrieve a filter stored in the database, return the name of a filter, get the usable filters for a user and for a given project, add / modify a filter saved in database and delete a filter in database. The webservice which get the bug list after having applied a filter has been improved, with an opportunity to have more option.
- For relationship management (mc_relationship_api.php) following features have been implemented : test the existence of a relationship, test whether a bug can be resolved without risk depending on its relations, adding a relationship, update a relationship and delete a relationship.
4. Informations about tests
For the development of this new version of Mantis Connect, a series of tests were carried out to ensure the functioning of the webservice. These tests are available and gives an example of webservice usage.
The tests are divided into two folders, test-integration and test-unitaire. The scripts in the test-unitaire folder test only a single webservice. If you use them be sure to change the informations that are stored in the $ aParametres array. The script in test-integration folder test a scenario with a serie of webservices.
5. Development of new features
Below are the stages of development for a new webservice:
- It must be decided what file you are going to work. In Mantis Connect, we took the party to follow the same file structure as that found in Mantis. This means that the Mantis Connect file mc_bug_api.php calls functions that are found in the Mantis file core/bug_api.php. In case you create a new file, do not forget to add it in the file mc_core.php of Mantis Connect.
- The function name must be defined. In Mantis Connect there is a standard; All functions that start with mc will be directly callable by the client. But all the functions that start with mci will be used by the server.
- The management of user permissions could not be easier. We call the mciCheckAccess function, giving as first parameter an array containing a list of all the rights that we are going to control and as second parameter an array containing a list of variables used for permissions checking. Nothing more should be done. If certain permissions are violated, it will return automatically a soap error. The list of all permissions is available at the beginning of the file mci_access_api.php.
- Then you have to write the contents of the webservice.
- Finally we must register function to the server Soap. Therefore, we must declare the new webservice in mantisconnect.php file. The definition of webservice requires to specify a name, a list of parameters entered, the type of the return value and a description of the action of webserice.
Then you only need to test the new webservice. You can take as a model the tests contained in the test-unitaire directory.
If you create webservices that make use of user permissions that are not implemented, you must add those permissions in the file mci_access_api.php. For this start by creating a new permission constant at the beginning of the file. Then create a function that checks the user permission. You may wish to call the mciMantisRules if it is a simple check.
Once the function is created, add a pointer to function in the mciCheckAccess (at the end of the file). Then you can use the new user permission in your webserivces.
A. Documentation generation with PhpDocumentor
For documentation generation, we need PhpDocumentor. Once downloaded and installed, from the home page, click on the Config tab. Select the Mantis Connect directory in the first field and click Change.
Then from the dropdown list, choose the configuration file doc_ws.ini. Click Go. You create a new and updated documentation. On the other hand we must make one last manipulation because PhpDocumentor does not take into account our README file written in HTML. A shell script has been created to copy the README_FR.html in the documentation folder (shell command : $>sh doc_ws_sh).
B. External Links
Axidea : http://www.axidea.fr/
Mantis : http://www.mantisbt.org/
Mantis Connect : http://www.futureware.biz/mantisconnect/
NuSoap : http://dietrich.ganx4.com/nusoap/
PhpDocumentor : http://www.phpdoc.org/