README.md

mantisrb

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).

Usage

Install:

gem install mantisrb

Create a session to the Mantis server:

session = Mantis:Session.new "http://mantisurl.com/mantis", "YourUsername", "YourPassword"

Various components are described below:

Config

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_levels

More information on this can be found in {Mantis::Config}.

Projects

Get a list of projects that your user can access:

    session.projects.list

Create 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}.

Issues

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 Name

by 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
    once

Creating 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 (id or name of 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.

Issue Check-in

Issues can be updated with comments or completion with this quick call to an issue:

    session.issues.checkin(issue_id, comment, completed?) # defaults to false

There 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

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_id

Get 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 search

Creation/Deletion/Etc., actions on Filters are unsupported as Mantis' SOAP API does not support it.

Categories in Projects

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
    }

Compatibility

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.

License, Open-Source-ness, and other Miscellany

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.