mantisrb is an API that works with the Savon gem to talk to a Mantis
bug tracker through SOAP calls. Mantis' SOAP interface is called MantisConnect
(see example for an API view).
Install:
gem install mantisrbCreate a session to the Mantis server:
session = Mantis::Session.new "http://mantisurl.com/mantis", "YourUsername", "YourPassword", "(optional) HTTP Username", "(optional) HTTP Password"Various components are described below:
Configuration details about the Mantis installation can be retrieved, such as finding out the status types, access levels, and view states:
session.config.priorities # get priorities
session.config.statuses # possible issue statuses
session.config.version # Mantis version
session.config.access_levelsMore information on this can be found in {Mantis::Config}.
Get a list of projects that your user can access:
session.projects.listCreate a project:
project_id = session.projects.create params={
name: "project name" # Minimally, this is all you need
}Or provide more details (some shown below):
project = session.projects.create {
name: "project thing",
status: "development"
enabled: true,
view_state: :public # or 'public', or session.projects.status.public,
inherit_from_global: true
}
project.name # "project thing"
project.id # 10 or whatever for referencing
project......More details on what is in a project can be found in {Mantis::XSD::ProjectData}.
Getting issues is easy, too:
by id:
session.issues.by_id 110 # if you know the id
session.issues.exists? 110 # if you don't know if it's there
session.issues.by_name "problem name I solved" # name of Mantis issue that
you want to search explicitly by (no wildcards or regex'ing, sorry)
session.projects.issues "project name" # get first 100 issues by Project Nameby ugly Mantis summary searching:
session.issues.summary_matches "some regex" # Do some ssearching (mind, it
is going to be pretty slow)by project id:
session.issues.by_project_id project_id, page_#, issues_per_page # The
fully flexible way of getting a list of issues
session.issues.by_project_id project_id # gets you an Enumerable to go
through things
session.issues.by_project_id project_id, limit # number of issues to get at
onceCreating them isn't too bad (know your options):
issue = session.issues.create {
summary: "issue description somewhere here",
priority: :high,
due_date: "10/13/2011 08:45 AM" # or other formats as DateTime will
accept
}Required fields for an issue:
- project (
idornameof project will work) - summary
- description
- category name (you can get this from the project)
Information on what is in an Issue can be found in the {Mantis::XSD::IssueData} class.
Issues can be updated with comments or completion with this quick call to an issue:
session.issues.checkin(issue_id, comment, completed?) # defaults to falseThere are a number of other features that you can manipulate through the API, so check out the documentation for more. See {Mantis::Issues} for more information on the other types (relationships, attachments, etc.)
Filters are Mantis' way of saving a configured search. You likely know what they are if you have used Mantis, so if not, please take a brief look at this blogpost to see what you can use filters for.
Get a filter by id:
session.filters.by_project_id 110 # get all filters you can search by for the project_idGet issues for a particular filter:
session.filters.get_issues project_id # get first 100 issues for a given
filter
session.filters.get_issues project_id, page_num, issues_per_page
# fully-formatted searchCreation/Deletion/Etc., actions on Filters are unsupported as Mantis' SOAP API does not support it.
When creating issues, you will need to know what category the issue belongs to, so this should be helpful.
Get all categories for a project:
session.projects.categories(project_id)Add a category
session.projects.add_category(45, "Triage")
session.projects.add_category(<project_id>, <category_name>)Delete a category
session.projects.delete_category(<project_id>, <category_name>)Rename a category
session.projects.rename_category params={
project_id: <id>,
old_category: <category_name>,
new_category: <new_category_name>,
project_assigned_to: <id> # leaving this out will keep it in the same
project
}You can see which environments have been tested on Travis CI. JRuby support is lacking, as it appears there might be an issue with Nokogiri and Savon gems (to be determined). Any help in getting JRuby to work (w/ JRUBY_OPTS=--1.9) would be greatly appreciated.
I've licensed mantisrb with the MIT License, which should be permissive
enough for you to muck around and fiddle with. It's open-source, so
contributions are welcomed and encouraged.
For any questions / suggestions / contributions, contact me at:
Email: klauer - at - gmail - dot - com for more information or send me a pull-request.
There are alot of things I don't have done in this, but you should be able to get by for the most part with:
- querying projects/issues/filters, etc
- CRUD tasks on issues/projects/filters/categories, etc.
- Mocking - I have yet to get mocking to work on this project, and I could use someone's help in getting that up. That would make finishing the testing SOOO much easier.
- Testing - I have a long way to go
Unfortunately, MantisConnect just isn't as full-featured as their web application. If you want feature parity with Mantis, I have yet to find an API that will work with it, besides attempting to stub out all of the calls that are normally performed from the browser in an API, or possibly hard-wiring your application into the Mantis Database tables.
I have at a minimum, implemented every method call that MantisConnect provides.
If mantisrb doesn't provide something, it's probably not in their SOAP API.