Help

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. Currently the only supported operation is to get a list of all the property definitions in a project.

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; read only, this field determine what data type of the property definition. Currently can be string, numeric, date, user, or card.
• 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; 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: String, readonly; indicates the property type such as 'Managed text list', 'Managed number list'.

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.

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

<property_definitions type="array">
  <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>
</property_definitions>