- 1. How to install Elastik
- 2. Users & Access Rights
- 3. Sample Workflow
- 4. Module EmailUpdateDigest
- 5. Module FileAttachments
- 6. Module IssueDuplicates
- 7. Module SavedSearches
- 8. Module SuggestFollower
- 9. Module ErrorReportingService
- 10. Writing Themes
- 11. Writing Modules
- 12. API
- A. Coding Standards
- B. License
- A webserver running PHP 5.2 or higher. (If the server runs Windows, you will need PHP 5.3 or higher to use some of the optional command line scripts.)
- A MySQL database.
- Optionally, some features require a location on disk they can save files to.
Note that currently you must install Elastik at the top level of a website (eg http://elastik.server.com not http://server.com/elastik)
- Create a blank database and configure access.
- Copy all the files from the Elastik project to a folder, and set the web server up to serve it.
- Copy
/includes/config.php.distto/includes/config.php, and edit the resulting file. Read the comments in the file for more instructions. - From version 0.4, the optional setting
FILE_STORAGEcan be set in/includes/config.phpto a location on disk where Elastik will store files. If this is not provided, some features will be disabled. The location should exist, be writable by the web server and not served by the webserver itself (if you do this, people will be able to bypass security and download any data). - Make sure the folder
/includes/templates_cis writable by the webserver, as this is where Smarty will save it's compiled templates. - Run the command line script
php includes/scripts/upgradeDataBase.phpor go tohttp://HOSTNAME/installElastik.phpto install the database. - Go to
http://HOSTNAME/adminSuperUsers.phpto add the first system administrator. -
For optional security, all requests to the following folders can be refused.
-
/includes -
/mod.*/includes -
/theme.*/includes
-
- Copy all the files from the latest version of Elastik over the old files.
- Delete all php files in the includes/templates_c folder.
- Run the command line script
php includes/scripts/upgradeDataBase.phpor go tohttp://HOSTNAME/installElastik.phpin a browser to install any upgrades to the database.
Users are identified by their email address in Elastik. To add a user, you simply add them to a client or project.
If that user does not exist, they will be created and an invitation to join will be emailed to them automatically. They go to a special webpage to set a password.
If that user does exist, the new access rights will be added to there existing account. They will not receive an email.
System Administrators can:
- add other system administrators.
- see anything in the system. However the normal "Choose Client" menus will only show you clients you specifically have access to.
- create new clients.
At the moment, to remove system administrators you must edit the database by hand.
Search for the user in the UserAccount table and set the SuperUser column to 0.
Client Administrators can:
- add or remove other client administrators.
- create new projects.
- create or manage Ticket Status Schemas.
Project Administrators can:
- alter the fields in a project.
- alter the categories in a project, what status workflows they use and what fields appear at which points.
- add or remove other project administrators or users, with rights that are explained in the next section.
Project users can be given different rights by administrators.
All project users can view:
- all tickets and their history.
- the profile of any other user in the project.
If they have the "write tickets" permission, they can:
- create new tickets.
- edit existing tickets.
- move tickets through defined status workflows.
If they have the "comment" permission, they can comment on any ticket.
We will set up a sample workflow for software bugs being reported, confirmed, assigned to a member of staff and then resolved.
When a user creates a bug, we want them to be prompted for relevant information:
The created ticket would look like this:
Then another staff member would confirm the bug, and confirm more information as they do:
Then a manager would assign the bug to a member of staff:
They would work on it until they had solved it, or decided not to solve it:
The finished ticket would look like this:
Install Elastik, and set up a user account and a client. When you create a new project, it will suggest fields and categories for you but uncheck all the suggestions. We will start from scratch in a blank project.
In your new project, go to "Ticket Fields" in the "Settings" menu. Add the following fields in this order:
- A string field called "Summary"
- A text field called "Details"
- A text field called "How to reproduce"
- A text field called "Environment"
- A select field called "Priority". After adding the field, add the options "Critical", "High", "Medium" and "Low"
- A multiple user (or user) field called "Assigned To"
- A select field called "Conclusion". After adding the field, add the options "Fixed", "Can't fix" and "Won't fix".
After all this, the fields should look like this. I have added some descriptions.
The order is important not just so it looks nice, but because some fields have special meaning. The first string field in a ticket is used as the title in page headers. The first text or WYSIWYG field is used as a summary of the ticket and shown by default when searching tickets.
At this point, you can choose which fields to make compulsory at all times. Note that this will only apply when the field is visible - but we will look at this later. For now, make the first 4 fields compulsory.
Go to "Ticket Status Schemas" in the "Settings" menu, and create a new Schema called "Bug reports".
Add the following statuses in this order:
- Reported
- Confirmed
- Can't Confirm
- Assigned
- Closed
Because you added "Reported" first, it should automatically have been marked as the starting status. This means all tickets using this schema will start here.
You can edit each ticket and set an appropriate colour.
Now, add the following transitions:
- from "Reported" to "Confirmed", add a transition called "Confirm"
- from "Confirmed" to "Assigned", add a transition called "Assign"
- from "Assigned" to "Closed", add a transition called "Close"
This takes care of the normal successful workflow, when a bug is reported, confirmed and dealt with. But we must also take care of failures:
- from "Reported" to "Can't Confirm", add a transition called "Can't Confirm"
The schema should now look something like this:
Go to "Ticket Categories" in the "Settings" menu and create a new category called "Bug reports", using the "Bug Reports" schema.
The category should now look something like this:
From the category, click on "View and Alter Fields on Create". Here you can choose which fields users will fill in when they create a ticket.
When a user is first reporting a bug, the only fields should be "Summary", "Details", "How to reproduce" and "Environment". Select these and save
It's also possible to prompt people to fill in fields when they are changing from one status to the other. Select "View and Alter Fields on Transitions" from the Ticket category.
- When a user confirms a bug, we want them to fill out what priority it is. So for the Transition "Confirm" from "Reported" to "Confirmed" select the "Priority" field.
- For the Transition "Assign" from "Confirmed" to "Assigned" select the "Assigned To" field.
- For the Transition "Close" from "Assigned" to "Closed" select the "Conclusion" field.
When a ticket is in a status, you can choose to only show certain fields. There is no point showing a field if the user has not got to that part in the workflow yet.
Select "View and Alter Fields on Statuses" from the Ticket category.
- For the status "Reported" and "Can't Confirm", select "Summary", "Details", "How to reproduce" and "Environment".
- For the status "Confirmed", select the same fields as the last one and add "Priority".
- For the status "Assigned", select the same fields as the last one and add "Assigned To".
All the configuration for the workflow is now done, and you should be able to try some test tickets yourself.
To practice more, try extending this. For instance a manager may be looking at a confirmed bug and decide they aren't going to fix it and they want to close it immediately. At the moment they would have to do two steps - assign the ticket to a member of staff then close it. Add a transition from "Confirmed" to "Closed" which allows them to close the ticket in one step. Let them set the "Conclusion" field as they do this.
This module sends a regular digest email per project to a user notifying them of updates to tickets.
This can be turned on or off.
This can be set for any minimum time interval. It won't send emails if there is nothing to send but it also won't send emails more regularly than this interval.
It can be set to check all tickets, or only tickets they watch.
The default is tickets they watch are emailed once per day.
Enable the module in /includes/config.php and run /installElastik.php to install
database tables.
The script /mod.EmailUpdatesDigest/includes/run.php must be run by cron, Task Scheduler or
another system on a regular basis.
The more it runs the faster users will get notified of updates (if a user specifies to be informed every 5 minutes but the script only runs every hour there will be delays), but check the load is not to great.
Enable the module in /includes/config.php and run /installElastik.php
to install database tables.
A directory must be created to save the files in. The web server should have permissions to write to this folder. This folder should not be served by the webserver; if it is, people will be able to by-pass the security checks and download any file.
Copy /mod.FileAttachments/includes/config.php.dist to
/mod.FileAttachments/includes/config.php.
Edit it and set the location of the folder you just created.
The super-user in the system can edit and add to the list of file types allowed by going to
/mod.FileAttachments/adminFileTypes.php
For every project, the project administrators can decide what types of files are allowed to be uploaded.
The module IssueDuplicates allows users to mark tickets as duplicates of other tickets.
Normally Ticket trackers come with all kinds of views or reports; tasks assigned to you, open tasks or tasks in various statuses, critical bugs, that kind of thing. But one of the consequences of a completely flexible system is that you can't do that: as your users can set up the process at will, you can't write reports for them.
For instance, one software company I worked at had the original programmer do the work then a 2nd programmer check the technical details of the work. Then finally whoever requested the modification would check the work to ensure it matched the specifications. A system to model that process might have 3 "Assigned To" fields, and who was actually responsible for a ticket at any given point would depend on what it's status was. Its impossible to pre-plan views for that.
To help with this problem, we have the SavedSearches module. It enables custom searches to be saved and run again at any point in the future.
Enable the module in /includes/config.php and run /installElastik.php to
install database tables.
A user can perform a ticket search, then save the search and run it at any point in the future. They can also choose to display a small number of tickets from the search on their project dashboard, and choose how many tickets.
Project administrators (and other users with the relevant permission) can save a search, and then every user in the project can run the search at will. Users can choose to put the search on their dashboards (administrators can choose whether the search is there by default) and each user can choose how many tickets to see.
This is available since Elastik 0.4.
This module allows users to suggest that other users should follow a ticket. The user will get an email with a link to the ticket and any additional comment that was entered.
This module is in early stages and should be thought of as alpha software.
The ErrorReportingService provides widgets to install into other PHP applications that will collect errors and send them to Elastik, where the details will be available for viewing. The project administrator can choose to have new errors automatically converted into tickets.
Some PHP applications already collect errors, and this may interfere with the Elastik widget.
Note that it is not a good idea to collect errors from an Elastik application and report them to the same Elastik application - if there is an error in the error reporting service you may set up a infinite loop.
Enable the module in /includes/config.php and run /installElastik.php to
install database tables.
In the Elastik application that will collect the errors, create a new project.
In the settings page, go to "Error Reporting Service" and create a new site. If you want errors converted to new tickets, select that option here.
You must now configure the other application to send errors to Elastik. There are different ways to do this, and these are covered in the following sections. Afterwards, there are a few final steps to be taken that are covered in another section.
Errors are reported over HTTP. Use when the application and Elastik are on different servers. Data is sent from the application to Elastik - ensure there are no firewalls or other network restrictions.
Copy the file mod.ErrorReportingService/includes/RemoteReportingWidget.php into the application you want to collect errors from.
Include the file, and at a minimum the lines below. This is an example only - you must use your own settings from the site.
This can only be used when the application and Elastik are on the same machine. This is available since Elastik 0.4.
Copy the file mod.ErrorReportingService/includes/LocalReportingWidget.php into the application you want to collect errors from.
Include the file, and at a minimum the lines below. This is an example only - you must use your own settings from the site.
Errors are reported by writing them to file storage. Later, a background process loads the files from disk and reports them into Elastik. This is available since Elastik 0.4.
This is more effort to set up, but means that when errors occur the user gets a faster reponse from the system.
Copy the file mod.ErrorReportingService/includes/BackgroundReportingWidget.php into the application you want to collect errors from.
Include the file, and at a minimum the lines below. This is an example only - you must use your own settings from the site.
You need to create a folder to write errors to. Elastik errors should be the only thing in this folder. If you have several applications that are configured as seperate sites, but the errors are being sent to the same Elastik application, they can use the same folder and you only have to run one background process.
Optionally, file permissions can be changed as soon as the error is written.
Now you need to configure the background process.
If Elastik is on the same server, just run (change paths for your server, of course):
If Elastik is on a different server, copy the files
mod.ErrorReportingService/includes/runBackgroundProcessForRemoteElastik.php and mod.ErrorReportingService/includes/RemoteReportingWidget.php
to the server and place them in the same directory as each other. Run:
Note both of these run once then stop. Setup crontab or a similar system to run these regularly.
After an error is sent succesfully, it is deleted from the disk. Make sure the process has the right permissions to delete the errors.
In the following code, ClassName is the class name of your collecting widget. This will depend on what method you used.
Add the line to ping the server:
Run the code, then look at the site page and ensure the ping was recorded. If not, there was a problem communicating between the 2 sites that must be investigated. Afterwards, remove this line - you do not want to include this all the time as it will slow down your site.
By default the reports include cookie data - if you don't want this you can include the following:
By default, all types of errors are captured. If you want to ignore any types you can include one of the following lines:
You can change the error message that appears to the user:
Themes can be written to overwrite the GUI and emails the site sends.
You can only set one theme at a time at the moment. This is set in config.php.
Themes should have the following structure
-
/theme.ThemeName/ -
/theme.ThemeName/includes/ -
/theme.ThemeName/includes/LICENSE.txt -
/theme.ThemeName/includes/templates/
It is recommended to add a file /theme.ThemeName/includes/.htaccess that has one line:
"Deny from all"
Place a plain text copy of the license in this file. Elastik is released under the BSD License, so we recommend the BSD license or the LGPL License. See the appendix on licenses for more details.
Each module should have a name consisting of characters and numbers only, like SavedSearches.
There should be a folder and file structure under the root of the elastik website with the following folders and files:
-
/mod.ModName/ -
/mod.ModName/includes/ -
/mod.ModName/includes/LICENSE.txt -
/mod.ModName/includes/Module.php -
/mod.ModName/includes/dbmigrations/ -
/mod.ModName/includes/templates/ -
/mod.ModName/includes/templates/mod.ModName.credits.htm
The files will be explained in the following sections.
It is recommended to add a file /mod.ModName/includes/.htaccess that has one line:
"Deny from all"
The Module.php file should contain a class called ModuleModName which extends class BaseModule.
This file defines some basic details about the module. All functions marked abstract must be provided.
It also contains callbacks - a list of functions that are called when events happen. This allows modules to perform functions in the system.
Please read the comments in /includes/BaseModule.class.php for full details.
The credits file is called when the user looks at the credits page in the system.
It must exist, and should contain no header or footer. It can be a simple one line statement of authorship and license wrapped in <p> tags.
Place a plain text copy of the license in this file. Elastik is released under the BSD License, so we recommend the BSD license or the LGPL License. See the appendix on licenses for more details.
Any class files that you want to provide should have a name that starts with ModModName and be in a file
called /mod.ModName/includes/ModModNameClassName.class.php
eg. ModSavedSearchesUserSavedSearch is in
/mod.SavedSearches/includes/ModSavedSearchesUserSavedSearch.class.php
Elastik provides a API for Template Designers to do client side JavaScript/AJAX with or others to consume.
Every format interface is in a separate folder in the project root.
The three formats are:
-
XML -
CSV -
JSON
Every file in every one of those folders should have documentation in the header describing what it takes in and passes out. Please check them for further details.
- Use tab characters not spaces.
- Put open braces on same line
function test() { if ( ... ) { ... code ... } }
- Variable and function names are capitalised with first letter lower case eg "function getIssue()"
- Class names are capitalised eg "IssueComment"
- Tickets are called "Tickets" in the user interface but for historical reasons are called "Issues" in code, filenames and the API.
- In files with only PHP code, don't put a closing PHP tag. This is to avoid accidental addition of new lines at the end of the file that could stop header() calls from working later.
- All plain text files should have SVN property "eol-style" set to "native" on them.
- Table and column names are singular eg "Issue" "Title"
- Names are capitalised eg "PostedAt"
- Foreign ID Columns end with "ID" eg "IssueID"
- Time columns end with "At" eg "PostedAt"
- Boolean columns Start with "Is" eg "IsActive"
- Index names must end with "_idx" (lower case).
- Foreign Key Constraint names must end with "_fk" (lower case).
- Index and Foreign Key Constraint names start with the table name and an underscore. eg "IssueHasMultipleSelectField_choice_fk"
- Template file extensions should end in "htm"
- All plain text files should have SVN property "eol-style" set to "native" on them.
- If a variable is set in smarty to be consumed in the template that sometimes has a value and sometimes does not, always make sure the variable is set to null or optionally set to a value. This is so template designers do not have to do an is_set check.
The core code of Elastik, the default theme and most modules are licensed under the BSD license shown below.
Check the LICENSE.txt file in the includes folder to check the license for each module and theme.
Copyright (c) 2010-2011, MAPIX Technologies Ltd, UK http://mapix.com/ All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
- Neither the name of MAPIX Technologies Ltd nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
This book is licensed under a Creative Commons Attribution 3.0 Unported License.