Help

Transitions are project specific steps in your process workflow. Once your project is setup and configured with the appropriate transitions, you can use the API to get transitions that are available to you on each card and also to execute a transition on a particular card. The transition itself can be identified by the name and the card by its number. Certain transitions require the user to enter a comment or make it mandatory to set certain property values. You can do these as well using the API.

Before you execute transitions using the API, we recommend that familiarize yourself with some key concepts dealing with transitions.

The structure of the transition resource, and its attributes are described below, along with their data type. Also included with each attribute is whether you are allowed to update the value.

transition resource xml - attributes

• id: Integer; read only, the system generated id for a transition.
• name: String.
• require_comment: Boolean, indicates whether a comment is required to execute this transition.
• transition_execution_url: String, URL to execute this transition
• user_input_required: Array, return all of the required property's attributes.
• user_input_optional: Array, return all of the optionally required property's attributes.

You can get transitions that are available to execute on each card and what must be supplied to execute that transition; such as names of required/optionally required property name.

Reference

    Request Method: GET
    URL: /api/v2/projects/project_identifier/cards/card_number/transitions.xml
    Parameters: NA
    

Example

    GET
    
    http://yourname:password@your.mingle.server:8080/api/v2/projects/test_project/cards/212/transitions.xml
    

Explanation

The above is an example of a GET to list all transitions that are available to you on a card with the number 212; 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.

<transitions type="array">
  <transition>
    <id type="integer">98</id>
    <name>Move Card to open</name>
    <require_comment type="boolean">false</require_comment>
    <transition_execution_url>http://localhost:8080/api/v2/projects/test_project/transition_executions/98.xml</transition_execution_url>
    <user_input_required type="array">
    </user_input_required>
    <user_input_optional type="array">
    </user_input_optional>
  </transition>
</transitions>

Reference

    Request Method: POST
    URL: /api/v2/projects/project_identifier/transition_executions/id.xml
    Parameters: NA
    transition_execution[card]: Integer, number of the card to execute the transition on, required
    transition_execution[comment]: String, comment to be added when executing the transition, required if transition is created with "require comment" set to true
    transition_execution[properties][][name]: String, each value for a parameter with this key is the name of a property that needs to be set while executing the transition, required if transition is created with "require user to input" for the particular property
    transition_execution[properties][][value]: String, each value for a parameter with this key is the value for the property in the corresponding position in the transition_execution[properties][][name] parameter values
      

Example

    POST

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

    transition_execution[card]=212
    transition_execution[comment]=close defect
    transition_execution[properties][][name]=fixed in version
    transition_execution[properties][][value]=release 1 branch
    transition_execution[properties][][name]=fixed in revision
    transition_execution[properties][][value]=1234
      

Explanation

The above is an example of a POST to execute a transition called "close defect" on a card with the number 212; in a project with identifier "test_project". The request is made with the authorization credentials of yourname/password. When the transition is applied, a comment will be added. The transition_execution[properties] parameter can be understood as follows. The first value for transition_execution[properties][][name] is "fixed in version" and the first value in transition_execution[properties][][value] is "release 1 branch". This means that upon execution of the transition, the value of "fixed in revision" will be set to "release 1 branch". The second value for transition_execution[properties][][name] is "fixed in revision" and the corresponding value in transition_execution[properties][][value] is "1234". Thus, upon execution of the transition, the value of "fixed in revision" will be set to "1234". This can be repeated for as many properties that were configured as "(require user input)" or "(user input optional)" when the transition was setup.

Result

If you were authorized to perform the operation, and the operation succeeded, you will be returned a location attribute in the http header of the response, which is a url from which you can get the card resource that was updated by the transition. You should get an xml document that looks something like the following.

<transition_execution>
  <status>completed</status>
</transition_execution>