Help documentation

Property definitions are the basis of the way you configure a project. Once a project is configured, the list of property definitions is a useful thing to have so that you can determine the card table structure for the project. One of the uses of this API is to get the column names of each property definition to be used when you update a card resource.

Before using this API, we recommend that familiarize yourself with property definitions.

The attributes of a property definition resource are described below, along with their data type. Also included with each attribute is whether you are allowed to update the value. System generated fields like id are provided only as information about the property definition and cannot be updated through the API.

property definitions resource xml - attributes

• id: Integer; read only, system assigned unique identifier for a property definition.
• name: String; this is the name of the property definition.
• description: String.
• data_type: String; this field determine what data type of the property definition. Below shows what each value means. You can use following values when creating a new card property.
  • string - text property
  • numeric - numeric property
  • date - date property
  • user - user property
  • formula - formula property
  • card - card property

• is_numeric: Boolean; determines if the property definition is a numeric property. Only Managed/Unmanaged numeric properties have this set to true.
• hidden: Boolean; determines if team members can see the property in the card anywhere other than in MQL reports.
• restricted: Boolean; determines if a managed property definition can have any more values added to it through card show/edit pages. This corresponds to 'locked' in the Mingle card properties page.
• transition_only: Boolean; this determines if the property can be updated directly or only through a transition.
• project: Resource; name and identifier of a project this property belongs to; both String, readonly.
• column_name: String; read only, this field is the name of the database column that the property definition creates in the cards table of the project. These column names determine the attributes in a card resource for this project.
• position: Integer; read only, indicates the level of this property in a tree. e.g. 1 indicates this property exist in a 1 level tree relationship property which connects the first and the second card type in tree.
• property_values_description: Resource; read only, indicates the property type such as 'Managed text list', 'Managed number list', 'Automatically generated from the team list', 'Formula' or 'Any card'.
• card_types: Array; list all the card types this property is available to.
• property_value_details: Array; read only, list all the values for this card property. This attribute is only available for 'Managed text list' or 'Managed number list' type of card property.
• is_managed: Boolean; this field determine whether this property is "Managed list" or "Any". This is a required attribute when creating a text or a numeric card property.
• formula: String; the property formula. This attribute is only available and required when creating a formula type of card property.
• null_is_zero: Boolean; whether or not to replace numeric (not set) values with zero when calculating the formula result. This attribute is only available when creating a formula type of card property.

Reference

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

Example

    GET

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

Explanation

The above is an example of a GET request to a Mingle server running at your.mingle.server, port 8080. The request is made with the authorization credentials of yourname/password. The URL of /api/v2/projects/test_project/property_definitions.xml represents the listing of all property definition resources for the project with identifier test_project.

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"?>
<property_definitions type="array">
  <property_definition>
    <id type="integer">116</id>
    <name>Owner</name>
    <description>
    </description>
    <data_type>user</data_type>
    <is_numeric type="boolean">false</is_numeric>
    <hidden type="boolean">false</hidden>
    <restricted type="boolean">false</restricted>
    <transition_only type="boolean">false</transition_only>
    <project url="http://localhost:8080/api/v2/projects/test_project.xml">
      <name>test project</name>
      <identifier>test_project</identifier>
    </project>
    <column_name>cp_owner_user_id</column_name>
    <position nil="true"></position>
    <property_values_description>Automatically generated from the team list</property_values_description>
  </property_definition>
  ...
  <property_definition>
    <id type="integer">111</id>
    <name>Release</name>
    <description nil="true"></description>
    <data_type>card</data_type>
    <is_numeric type="boolean">false</is_numeric>
    <hidden type="boolean">false</hidden>
    <restricted type="boolean">false</restricted>
    <transition_only type="boolean">false</transition_only>
    <project url="http://localhost:8080/api/v2/projects/test_project.xml">
      <name>test project</name>
      <identifier>test_project</identifier>
    </project>
    <column_name>cp_release_card_id</column_name>
    <position type="integer">1</position>
    <property_values_description>Any card used in tree</property_values_description>
  </property_definition>
</property_definitions>
        

Reference

          Request Method: GET
          URL: /api/v2/projects/project_identifier/property_definitions/property_id.xml
          Parameters: NA
        

Example

          GET

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

Explanation

The above is an example of a GET request to a Mingle server running at your.mingle.server, port 8080. The request is made with the authorization credentials of yourname/password. The URL of /api/v2/projects/test_project/property_definitions/114.xml represents the listing of a property definition resource for the project with identifier test_project.

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"?>
<property_definition>
  <id type="integer">114</id>
  <name>Status</name>
  <description>
  </description>
  <data_type>string</data_type>
  <is_numeric type="boolean">false</is_numeric>
  <hidden type="boolean">false</hidden>
  <restricted type="boolean">false</restricted>
  <transition_only type="boolean">false</transition_only>
  <project url="http://localhost:8080/api/v2/projects/test_project.xml">
    <name>test project</name>
    <identifier>test_project</identifier>
  </project>
  <column_name>cp_status</column_name>
  <position nil="true"></position>
  <property_values_description>Managed text list</property_values_description>
  <property_value_details type="array">
    <property_value>
      <id type="integer">117</id>
      <value>New</value>
      <color nil="true"></color>
      <position type="integer">1</position>
    </property_value>
    <property_value>
      <id type="integer">118</id>
      <value>Open</value>
      <color nil="true"></color>
      <position type="integer">2</position>
    </property_value>
    <property_value>
      <id type="integer">119</id>
      <value>Closed</value>
      <color nil="true"></color>
      <position type="integer">3</position>
    </property_value>
  </property_value_details>
</property_definition>
        

Reference

  Request Method: POST
  
  URL: /api/v2/projects/project_identifier/property_definitions.xml
  
  Parameters: 
      property_definition[name]=String (required)
      property_definition[data_type]=String (required)
      property_definition[is_managed]=String (required only if creating a numeric or text type of card property)
      property_definition[formula]=String (required only if creating a formula type of card property)
      property_definition[null_is_zero]=Boolean (only available when creating a formula type of card property)
      property_definition[description]=String
      property_definition[card_types][][name]=String
      

Example

  POST

  http://yourname:password@your.mingle.server:8080/api/v2/projects/test_project/property_definitions.xml
  
    property_definition[name]=Status
    property_definition[data_type]=String
    property_definition[is_managed]=true
    property_definition[card_types][][name]=Story
      

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 property on the project with identifier "test_project". This card property will be a managed text property which is called 'Status' and would be available for a card type 'Story'.

  Formula property 
        
    property_definition[data_type]=formula
    property_definition[formula]=size * 1
    property_definition[null_is_zero]=true
      

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