Note that currently you must install Elastik at the top level of a website (eg http://elastik.server.com
not http://server.com/elastik
)
/includes/config.php.dist
to /includes/config.php
, and edit the resulting file.
Read the comments in the file for more instructions.FILE_STORAGE
can be set in /includes/config.php
to 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)./includes/templates_c
is writable by the webserver, as this is where Smarty will
save it's compiled templates.php includes/scripts/upgradeDataBase.php
or go to http://HOSTNAME/installElastik.php
to install the database.http://HOSTNAME/adminSuperUsers.php
to add the first system administrator./includes
/mod.*/includes
/theme.*/includes
php includes/scripts/upgradeDataBase.php
or go to http://HOSTNAME/installElastik.php
in 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:
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:
Project Administrators can:
Project users can be given different rights by administrators.
All project users can view:
If they have the "write tickets" permission, they can:
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:
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:
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:
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:
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 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.
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.
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:
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.