Loading

Help documentation

Back to previous page

Events API

Introduction

The event API was introduced in Mingle 3.3 and provides programmatic access to Mingle historical data. This API is readonly.

It has always been possible to subscribe to history in Mingle. However, those subscriptions are oriented toward human readability - generally in a feed reader. In comparison, the event API is oriented toward programmatic access. This programmatic orientation provides many benefits and possibilities for clients to integrate with and consume Mingle data. Potential usages of this API include:

  • Aggregated feeds between Mingle projects or even other products
  • Custom filtered Mingle feeds
  • Activity monitoring
  • Integrating Mingle with other products
  • Custom metrics analysis, such as cycle-time analysis and scope change analysis

Structure of the event API

The event API is an atom feed. As an atom feed, the event API is comprised of a feed root element with the feed attributes described below.

Feed

feed resource xml - attributes
  • title: String; The title of this feed.
  • id: String; The URL for this feed.
  • link: XML Element; There are several links associated with the feed. These provide information about the feed, in particular it provides information which allows you to navigate through the feed.
  • updated: Datetime; The time that the last entry on this feed occurred.
  • entry: Resource; The feed will contain one or more entry elements which describe the Mingle events in the feed. Details can be found in the Entries section on this page.

The URLs that are contained within the events feed are based on the site URL that was entered during installation. If the URLs are incorrect, see advanced mingle configuration to learn how to change the site URL.

Entries

Entries are the core of the the API. Each entry represents one or more Mingle events. Entries are broadly one of the following: card, page, revision, or feed corrections . Although each type of event differ, all events have some common elements.

entry resource xml - attributes
  • id: String; Identifier of this entry.
  • title: String; Friendly title for entry.
  • updated: Datetime; The time that the last entry on this feed occurred.
  • author: Resource; The user who caused this event. Revision events may only contain a name element, if the person who checked in is not associated with a Mingle user. If a Mingle user is known, the following elements may be present: name, email, uri, and mingle:icon.
  • link: XML Element; Links associated with the entry. The link contains several attributes about the resource: href (link to resource), rel (definition of the resource), type (type of the resource, e.g., "text/html"), and title.
  • category: XML Element; Categories associated with the entry. The category contains term and scheme attributes. Term identifies the types of changes that occurred in this entry, e.g., "property-change". There will be one category for each entry with a term of card, page, revision, or feed-correction. This defines the source of the entry.
  • content: XML Element; Details about the changes that occurred in this entry. E.g., what property changed along with the old and new values. Content will contain a changes XML element which contains individual change elements.

Card events

Page events

Plan objective events

Revision events

Feed correction events

Feed navigation

Get a list of events from your project

You can list the events that happened in your project.

Reference

Request Method: GET

URL: /api/v2/projects/project_identifier/feeds/events.xml

Parameters: NA

Example

GET

http://yourname:password@your.mingle.server:8080/api/v2/projects/test_project/feeds/events.xml

Explanation

The above is an example of a GET to retrieve the most recent events in a project with identifier "test_project". The request is made with the authorization credentials of yourname/password.

Result

If you were authorized to perform the operation, and the resource was available, you should get an xml document that looks something like the following.

<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:mingle="http://www.thoughtworks-studios.com/ns/mingle">
  <title>Mingle Events: agile</title>
  <id>http://your.mingle.server:8080/api/v2/projects/test_project/feeds/events.xml</id>
  <link href="http://your.mingle.server:8080/api/v2/projects/test_project/feeds/events.xml" rel="current"/>
  <link href="http://your.mingle.server:8080/api/v2/projects/test_project/feeds/events.xml?page=5" rel="self"/>
  <link href="http://your.mingle.server:8080/api/v2/projects/test_project/feeds/events.xml?page=4" rel="next"/>
  <updated>2011-01-20T01:23:05Z</updated>
  <entry>
    <id>http://your.mingle.server:8080/projects/test_project/events/index/443</id>
    <title>Story #120 Delete email created</title>
    <updated>2011-01-20T01:23:05Z</updated>
    <author>
      <name>bob</name>
      <email>bob@your_mingle_server.com</email>
      <uri>http://your.mingle.server:8080/api/v2/users/1.xml</uri>
    </author>
    <link href="http://your.mingle.server:8080/api/v2/projects/test_project/cards/120.xml"
          rel="http://www.thoughtworks-studios.com/ns/mingle#event-source" type="application/vnd.mingle+xml" title="Story #120"/>
    <link href="http://your.mingle.server:8080/projects/test_project/cards/120"
          rel="http://www.thoughtworks-studios.com/ns/mingle#event-source" type="text/html" title="Story #120"/>
    <link href="http://your.mingle.server:8080/api/v2/projects/test_project/cards/120.xml?version=1"
          rel="http://www.thoughtworks-studios.com/ns/mingle#version" type="application/vnd.mingle+xml" title="Story #120 (v1)"/>
    <link href="http://your.mingle.server:8080/projects/test_project/cards/120?version=1"
          rel="http://www.thoughtworks-studios.com/ns/mingle#version" type="text/html" title="Story #120 (v1)"/>
    <category term="card" scheme="http://www.thoughtworks-studios.com/ns/mingle#categories"/>
    <category term="card-creation" scheme="http://www.thoughtworks-studios.com/ns/mingle#categories"/>
    <category term="card-type-change" scheme="http://www.thoughtworks-studios.com/ns/mingle#categories"/>
    <category term="description-change" scheme="http://www.thoughtworks-studios.com/ns/mingle#categories"/>
    <category term="name-change" scheme="http://www.thoughtworks-studios.com/ns/mingle#categories"/>
    <category term="property-change" scheme="http://www.thoughtworks-studios.com/ns/mingle#categories"/>
    <content type="application/vnd.mingle+xml">
      <changes xmlns="http://www.thoughtworks-studios.com/ns/mingle">
        <change type="card-creation"/>
        <change type="card-type-change">
          <old_value nil="true"></old_value>
          <new_value>
            <card_type url="http://your.mingle.server:8080/api/v2/projects/test_project/card_types/24.xml">
              <name>Story</name>
            </card_type>
          </new_value>
        </change>
        <change type="description-change">
        </change>
        <change type="name-change">
          <old_value nil="true"></old_value>
          <new_value>Delete email</new_value>
        </change>
        <change type="property-change">
          <property_definition url="http://your.mingle.server:8080/api/v2/projects/test_project/property_definitions/154.xml">
            <name>Added to Scope in Iteration</name>
            <position nil="true"></position>
            <data_type>card</data_type>
            <is_numeric type="boolean">false</is_numeric>
          </property_definition>
          <old_value nil="true"></old_value>
          <new_value>
            <card url="http://your.mingle.server:8080/api/v2/projects/test_project/cards/37.xml">
              <number type="integer">37</number>
            </card>
          </new_value>
        </change>
        <change type="property-change">
          <property_definition url="http://your.mingle.server:8080/api/v2/projects/test_project/property_definitions/114.xml">
            <name>Story Status</name>
            <position nil="true"></position>
            <data_type>string</data_type>
            <is_numeric type="boolean">false</is_numeric>
          </property_definition>
          <old_value nil="true"></old_value>
          <new_value>New</new_value>
        </change>
      </changes>
    </content>
  </entry>
  ...
  <entry>
    <id>http://your.mingle.server:8080/projects/test_project/events/index/432</id>
    <title>Story #113 Add calendar event via email deleted</title>
    <updated>2011-01-20T12:32:49Z</updated>
    <author>
      <name>sally</name>
      <email>sally@your_mingle_server.com</email>
      <uri>http://your.mingle.server:8080/api/v2/users/2.xml</uri>
    </author>
    <link href="http://your.mingle.server:8080/api/v2/projects/test_project/cards/113.xml"
          rel="http://www.thoughtworks-studios.com/ns/mingle#event-source" type="application/vnd.mingle+xml" title="Defect #113"/>
    <link href="http://your.mingle.server:8080/projects/test_project/cards/113"
          rel="http://www.thoughtworks-studios.com/ns/mingle#event-source" type="text/html" title="Defect #113"/>
    <link href="http://your.mingle.server:8080/api/v2/projects/test_project/cards/113.xml?version=4"
          rel="http://www.thoughtworks-studios.com/ns/mingle#version" type="application/vnd.mingle+xml" title="Defect #113 (v4)"/>
    <link href="http://your.mingle.server:8080/projects/test_project/cards/113?version=4"
          rel="http://www.thoughtworks-studios.com/ns/mingle#version" type="text/html" title="Defect #113 (v4)"/>
    <category term="card" scheme="http://www.thoughtworks-studios.com/ns/mingle#categories"/>
    <category term="card-deletion" scheme="http://www.thoughtworks-studios.com/ns/mingle#categories"/>
    <content type="application/vnd.mingle+xml">
      <changes xmlns="http://www.thoughtworks-studios.com/ns/mingle">
        <change type="card-deletion">
        </change>
      </changes>
    </content>
  </entry>
</feed>

Get a list of objective-related events from your plan

You can get list of objective-related events that happened in your plan.

Reference

Request Method: GET
URL: /api/v2/programs/program_identifier/plan/feeds/events.xml
Parameters: NA

Example

GET

http://yourname:password@your.mingle.server:8080/api/v2/programs/program_identifier/plan/feeds/events.xml

Explanation

The above is an example of a GET to retrieve the most recent events in a plan from the program with identifier "test_program". The request is made with the authorization credentials of yourname/password.

Result

If you were authorized to perform the operation, and the resource was available, you should get an xml document that looks something like the following. The URL of the objective to which the event occurred is also provided.

    <?xml version="1.0" encoding="UTF-8"?>
    <feed xmlns="http://www.w3.org/2005/Atom" xmlns:mingle="http://www.thoughtworks-studios.com/ns/mingle">
      <title>Mingle Plan Events for Program: Events Api</title>
      <id>http://your.mingle.server:8080/api/v2/program/events_api/plan/feeds/events.xml</id>
      <link href="http://your.mingle.server:8080/api/v2/program/events_api/plan/feeds/events.xml" rel="current"/>
      <link href="http://your.mingle.server:8080/api/v2/program/events_api/plan/feeds/events.xml" rel="self"/>
      <updated>2013-02-12T01:30:32Z</updated>
      <entry>
        <id>http://your.mingle.server:8080/events/index/2500143</id>
        <title>Objective removed</title>
        <updated>2013-02-12T01:30:32Z</updated>
        <author>
          <name>user</name>
          <email>user@thoughtworks.com</email>
          <url>http://your.mingle.server:8080/api/v2/users/14281.xml</url>
        </author>
        <link href="http://your.mingle.server:8080/api/v2/programs/events_api/plan/objectives/first.xml" rel="http://www.thoughtworks-studios.com/ns/mingle#event-source" type="application/vnd.mingle+xml" title="Objective: first"/>
        <category term="objective" scheme="http://www.thoughtworks-studios.com/ns/mingle#categories"/>
        <category term="objective-removed" scheme="http://www.thoughtworks-studios.com/ns/mingle#categories"/>
        <content type="application/vnd.mingle+xml">
          <changes xmlns="http://www.thoughtworks-studios.com/ns/mingle">
            <change type="objective-removed">
            </change>
          </changes>
        </content>
      </entry>
      <entry>
        <id>http://your.mingle.server:8080/events/index/2500142</id>
        <title>Objective updated</title>
        <updated>2013-02-12T01:30:26Z</updated>
        <author>
          <name>user</name>
          <email>user@thoughtworks.com</email>
          <url>http://your.mingle.server:8080/api/v2/users/14281.xml</url>
        </author>
        <link href="http://your.mingle.server:8080/api/v2/programs/events_api/plan/objectives/second.xml" rel="http://www.thoughtworks-studios.com/ns/mingle#event-source" type="application/vnd.mingle+xml" title="Objective: second"/>
        <category term="objective" scheme="http://www.thoughtworks-studios.com/ns/mingle#categories"/>
        <category term="end_at-change" scheme="http://www.thoughtworks-studios.com/ns/mingle#categories"/>
        <content type="application/vnd.mingle+xml">
          <changes xmlns="http://www.thoughtworks-studios.com/ns/mingle">
            <change type="end_at-change">
              <old_value>2013-05-22</old_value>
              <new_value>2013-06-12</new_value>
            </change>
          </changes>
        </content>
      </entry>
      <entry>
        <id>http://your.mingle.server:8080/events/index/2500141</id>
        <title>Objective planned</title>
        <updated>2013-02-12T01:30:24Z</updated>
        <author>
          <name>user</name>
          <email>user@thoughtworks.com</email>
          <url>http://your.mingle.server:8080/api/v2/users/14281.xml</url>
        </author>
        <link href="http://your.mingle.server:8080/api/v2/programs/events_api/plan/objectives/third.xml" rel="http://www.thoughtworks-studios.com/ns/mingle#event-source" type="application/vnd.mingle+xml" title="Objective: third"/>
        <category term="objective" scheme="http://www.thoughtworks-studios.com/ns/mingle#categories"/>
        <category term="objective-planned" scheme="http://www.thoughtworks-studios.com/ns/mingle#categories"/>
        <category term="end_at-change" scheme="http://www.thoughtworks-studios.com/ns/mingle#categories"/>
        <category term="name-change" scheme="http://www.thoughtworks-studios.com/ns/mingle#categories"/>
        <category term="start_at-change" scheme="http://www.thoughtworks-studios.com/ns/mingle#categories"/>
        <content type="application/vnd.mingle+xml">
          <changes xmlns="http://www.thoughtworks-studios.com/ns/mingle">
            <change type="objective-planned"/>
            <change type="end_at-change">
              <old_value nil="true"></old_value>
              <new_value>2013-07-31</new_value>
            </change>
            <change type="name-change">
              <old_value nil="true"></old_value>
              <new_value>third</new_value>
            </change>
            <change type="start_at-change">
              <old_value nil="true"></old_value>
              <new_value>2013-07-01</new_value>
            </change>
          </changes>
        </content>
      </entry>
    </feed>