Help documentation

User resources are located by issuing a GET request to the server with the user's id as a parameter. You can get an individual user's id by looking up a project's team list which returns a list of project member resources, including the id for each user. All updates of a user use the id. If you would like to update the value of a user property, you would use the id, as with updating an individual user's attribute.

Before you manipulate user using the API, we recommend that familiarize yourself with some key concepts dealing with users and user property definitions.

More information about Mingle users can be found in other help topics:

• Managing user profiles
• User roles

The structure of a user 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. System generated fields like id are provided only as information about the card and cannot be updated through the API.

user resource xml - attributes

• id: Integer; read only, system assigned unique identifier for a user. Use this to get a identifier uniquely.
• name: String.
• login: String; the Mingle sign-in name for the user.
• email: String.
• light: Boolean; determines if the user is a Light user or not, default is false.
• icon_path: String; may be blank if the user has no icon, may not be specified when creating or updating a user via the api.
• activated: Boolean; determines if a user is activated in Mingle or not, default is true.
• admin: Boolean; determines if a user is a Mingle Administrator or not, default is false.
• version_control_user_name: String.
• jabber_user_name: String.
• password: String; update only, this field is not provided on a GET of a user resource.
• password_confirmation: String; update only, must be identical to password on an update, this field is not provided on a GET of a user resource.

Reference

    Request Method: GET
    URL: /api/v2/users.xml
    Parameters: NA
      

Example

    GET

    http://yourname:password@your.mingle.server:8080/api/v2/users.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 is the location of all user resources for the project with identifier "test_project". You have to have "Mingle administrator" permissions to make this call.

Result

If you have sufficient permissions to perform the action and the action was successful, you should get an xml document that looks something like the following.

<?xml version="1.0" encoding="UTF-8"?>
<users type="array">
  <user>
    <id type="integer">5</id>
    <name>Jackson</name>
    <login>jackson</login>
    <email>Jackson@youremail.com</email>
    <light type="boolean">false</light>
    <icon_path nil="true"></icon_path>
    <activated type="boolean">true</activated>
    <admin type="boolean">false</admin>
    <version_control_user_name nil="true">jackson</version_control_user_name>
    <jabber_user_name nil="true">jackson</jabber_user_name>
  </user>
  ...
  <user>
    <id type="integer">7</id>
    <name>Tracy</name>
    <login>tracy</login>
    <email>Tracy@youremail.com</email>
    <light type="boolean">false</light>
    <icon_path nil="true">/user/icon/7/tracy.png</icon_path>
    <activated type="boolean">true</activated>
    <admin type="boolean">false</admin>
    <version_control_user_name nil="true">tracy</version_control_user_name>
    <jabber_user_name nil="true">tracy</jabber_user_name>
  </user>
</users>

Reference

    Request Method: GET
    URL: /api/v2/users/id.xml
    Parameters: NA
    

Example

    GET

    http://yourname:password@your.mingle.server:8080/api/v2/users/42.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 is the location of the user resource corresponding to the user with id 42 that is a member of the project with identifier "test_project".

Result

Upon execution, if you have appropriate permissions, you will be returned an array of users resources.

<?xml version="1.0" encoding="UTF-8"?>
<user>
  <id type="integer">7</id>
  <name>Tracy</name>
  <login>tracy</login>
  <email>Tracy@youremail.com</email>
  <light type="boolean">false</light>
  <icon_path nil="true">/user/icon/7/tracy.png</icon_path>
  <activated type="boolean">true</activated>
  <admin type="boolean">false</admin>
  <version_control_user_name nil="true">tracy</version_control_user_name>
  <jabber_user_name nil="true">tracy</jabber_user_name>
</user>

You must have Mingle administrator privileges to make this call to the API.

Reference

    Request Method: POST
    URL: /api/v2/users.xml
    Parameters: 
    user[name]
    user[login]
    user[email]
    user[password]
    user[password_confirmation]
    user[version_control_user_name]
    user[jabber_user_name]
    user[admin]
    user[light]
      

Example

    POST

    http://yourname:password@your.mingle.server:8080/api/v2/users.xml


    user[name]=John Smith
    user[login]=john
    user[email]=jsmith@example.com
    user[password]=t0ps3cr3t.
    user[password_confirmation]=t0ps3cr3t.
    user[version_control_user_name]=jsmith
    user[jabber_user_name]=jsmith
    user[admin]=false
    user[light]=false
    

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. The URL is the location of all user resources for the project with identifier "test_project". Posting the parameters creates a user with the specified values on the Mingle instance.

Result

If you have sufficient permissions to perform the action and the action was successful, you will be returned a location attribute in the header of the response, which is a url from which you can get the user resource that was created.

You must have Mingle administrator privileges to make this call to the API.

Reference

    Request Method: PUT
    URL: /api/v2/users/id.xml
    Parameters: 
    user[name]
    user[login]
    user[email]
    user[password]
    user[password_confirmation]
    user[version_control_user_name]
    user[admin]
    user[light]
      

Example

    PUT

    http://yourname:password@your.mingle.server:8080/api/v2/users/42.xml

    user[name]=John Smythe
    user[password]=t0ps53cr3t.
    user[password_confirmation]=t0p53cr3t.
      

Explanation

The above is an example of a PUT 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 is the location the user resource for the user with id 42 in that Mingle instance.

Result

If you have sufficient permissions to perform the action and the action was successful, then user with id will be updated to have a name of "John Smythe" and their password be "t0p53cr3t.". You will be returned a location attribute in the header of the response, which is a url from which you can get the user resource that was updated.

You must have Mingle administrator privileges to make this call to the API.

The structure of a project member 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. System generated fields like id are provided only as information about the user and cannot be updated through the API.

project member resource xml - attributes

• id: Integer; read only, system assigned unique identifier for a user.
• admin: Boolean; determines if a user is a Mingle Administrator or not, default is false.
• readonly_member: Boolean; shows whether a user is read-only on the project.
• user: Resource; name and login of a user who is a member of this project; both String.
• project: Resource; name and identifier of the project; both String.

Reference

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

Example

    GET

    http://yourname:password@your.mingle.server:8080/api/v2/projects/test_project/users.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 is the location of all user resources for the project with identifier "test_project".

Result

Upon execution, you should get an xml document that looks something like the following.

<?xml version="1.0" encoding="UTF-8"?>
<projects_members type="array">
  <projects_member>
    <id type="integer">28</id>
    <admin type="boolean">false</admin>
    <readonly_member type="boolean">true</readonly_member>
    <user url="http://localhost:8080/api/v2/users/5.xml">
      <id type="integer">5</id>
      <name>Jackson</name>
      <login>jackson</login>
      <email>Jackson@us.com</email>
      <light type="boolean">false</light>
      <icon_path nil="true"></icon_path>
      <activated type="boolean">true</activated>
      <admin type="boolean">false</admin>
      <version_control_user_name nil="true">jackson</version_control_user_name>
      <jabber_user_name nil="true">jackson</jabber_user_name>
    </user>
    <project url="http://localhost:8080/api/v2/projects/test_project.xml">
      <name>test project</name>
      <identifier>test_project</identifier>
    </project>
  </projects_member>
  <projects_member>
    <id type="integer">29</id>
    <admin type="boolean">false</admin>
    <readonly_member type="boolean">false</readonly_member>
    <user url="http://localhost:8080/api/v2/users/7.xml">
      <id type="integer">7</id>
      <name>Tracy</name>
      <login>tracy</login>
      <email>Tracy@us.com</email>
      <light type="boolean">false</light>
      <icon_path nil="true">/user/icon/7/tracy.png</icon_path>
      <activated type="boolean">true</activated>
      <admin type="boolean">false</admin>
      <version_control_user_name nil="true">tracy</version_control_user_name>
      <jabber_user_name nil="true">tracy</jabber_user_name>
    </user>
    <project url="http://localhost:8080/api/v2/projects/test_project.xml">
      <name>test project</name>
      <identifier>test_project</identifier>
    </project>
  </projects_member>
</projects_member>