Help documentation

Card types are the various things you track in your project. For example a newly started project under active development could have card types such as story, risk, defect etc., while a project in maintenance mode might have bug, issue, enhancement, feature request etc. The card types API allows you to get access to the card types that are available in your project and their associated card properties.

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

card type resource xml - attributes

• id: Integer; read only, the system generated id for a card type.
• name: String.
• color: String; the color of the card type in RGB color model.
• position: Integer; the order of the card type in a project. User can change this position.
• property_definitions: Array; return attributes of the properties that are available for this card type, with a link to the full property definition resource.

You can get card types that are available in a project. Any properties that are available for each card type will be provided as well.

Reference

        Request Method: GET
        URL: /api/v2/projects/project_identifier/card_types.xml
        Parameters: N/A
      

Example

        GET

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

      

Explanation

The above is an example of a GET to list all card types that exist 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"?>
<card_types type="array">
  <card_type>
    <id type="integer">32</id>
    <name>Story</name>
    <color>#c526ff</color>
    <position type="integer">1</position>
    <property_definitions type="array">
      <property_definition url="http://localhost:8080/api/v2/projects/simple/property_definitions/107.xml">
        <name>Status</name>
        <position nil="true"></position>
        <data_type>string</data_type>
        <is_numeric type="boolean">false</is_numeric>
      </property_definition>
      <property_definition url="http://localhost:8080/api/v2/projects/simple/property_definitions/109.xml">
        <name>Priority</name>
        <position nil="true"></position>
        <data_type>string</data_type>
        <is_numeric type="boolean">false</is_numeric>
      </property_definition>
    </property_definitions>
  </card_type>
  <card_type>
    <id type="integer">33</id>
    <name>Bug</name>
    <color>
    </color>
    <position type="integer">2</position>
    <property_definitions type="array">
      <property_definition url="http://localhost:8080/api/v2/projects/simple/property_definitions/107.xml">
        <name>Status</name>
        <position nil="true"></position>
        <data_type>string</data_type>
        <is_numeric type="boolean">false</is_numeric>
    </property_definitions>
  </card_type>
</card_types>

          

Reference

        Request Method: GET
        URL: /api/v2/projects/project_identifier/card_types/card_type_id.xml
        Parameters: NA
      

Example

        GET

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

      

Explanation

The above is an example of a GET to list a card type with the id 32; in a project with the 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"?>
    <card_type>
      <id type="integer">32</id>
      <name>Story</name>
      <color>#c526ff</color>
      <position type="integer">1</position>
      <property_definitions type="array">
        <property_definition url="http://localhost:8080/api/v2/projects/simple/property_definitions/107.xml">
          <name>Status</name>
          <position nil="true"></position>
          <data_type>string</data_type>
          <is_numeric type="boolean">false</is_numeric>
        </property_definition>
        <property_definition url="http://localhost:8080/api/v2/projects/simple/property_definitions/109.xml">
          <name>Priority</name>
          <position nil="true"></position>
          <data_type>string</data_type>
          <is_numeric type="boolean">false</is_numeric>
        </property_definition>
      </property_definitions>
    </card_type>
      

Reference

        Request Method: POST
        URL: /api/v2/projects/project_identifier/card_types.xml
        Parameters: 
           card_type[name]: Required
           card_type[property_definitions][][name]: String
           card_type[color]
      

Example

          POST

          http://yourname:password@your.mingle.server:8080/api/v2/projects/test_project/card_types.xml
  
          card_type[name]=Story
          card_type[property_definitions][][name]=Status
          card_type[color]=red
      

Explanation

The above is an example of a POST request to a Mingle server running at your.mingle.server, port 8080. The request is made with the authorization credentials of yourname/password. Upon execution of this request, the post parameters will be used to create a card type on the project with identifier "test_project". The card type name will be "Story" and the card type color will be "red". The card type will also be associated with the "Status" card property.

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 type resource that was created.