05. Developer's Guide

Authentication

The activeCollab authentication system can be extended to include other "authentication sources", such is LDAP, or the database of another web application (your website's CMS or forum, for example). This can be achieved by using Authentication Providers and in this chapter we'll show you how to do just that.

Authentication Providers

An Authentication Provider is a piece of custom code that you need to develop in order to check users against any authentication source you wish. Most of the code is already prepared. You'll only need to add things specific to your authentication source.

Important Note

Authentication Providers are not a replacement for activeCollab authentication, they are a bridge to connect it to other applications. The provider will still need to return an instance of a User class that exists in the activeCollab users table.

Here are four important methods in the Authentication Provider:

  1. initialize() - Called automatically on every request. This method is good for checking if you already have someone logged in (based on a cookie, server or session variable etc);
  2. authenticate() - Check a user's credentials against an authentication source. This method is called after the login form is submitted and forwards the data entered in the login form;
  3. logUserIn() - Set a user as logged in and does everything required in such a situation: set a session ID; save a cookie so a user gets authenticated on the next request; contact another application to let it know that the user is logged in. etc;
  4. logUserOut() - Makes sure that the user is logged out and it is great to undo everything you did with the logUserIn() method: such as destroying session and cookie variables; informing external application that the user left and so on.

Extending Authentication System

In this example we will cover how to make a provider that extends the system by attempting to log a user in against another user database (a website CMS or forum for example). If this fails, then we will try to authenticate the user against the activeCollab user database.

We will start by creating a CustomAuthenticationProvider.class.php within the /activecollab/angie/classes/auth/providers folder. We'll use this code for the foundation:

require_once 'BasicAuthenticationProvider.class.php';

/**
 * Custom authentication provider implementation
 */
class CustomAuthenticationProvider extends BasicAuthenticationProvider {
}

Note that we are using BasicAuthenticationProvider as a foundation for our provider. This way we get a cookie and session handling automatically, without the need to implement them once again.

Let's implement the behavior now. In this example, we want to check if a user exists and that their password is valid in another database after they click hit the Submit button on an activeCollab form. For that, we will need to override the authentication method, like this:

function authenticate($credentials) {
  // Inherit activeCollab authentication
  $active_collab_auth = parent::authenticate($credentials);
  // It failed, go for other source
  if(is_error($active_collab_auth)) {
    // Connect to database
    if(!$link = mysql_connect('localhost', 'root', '')) {
      return new Error('Failed to connect');
    } // if
    if(!mysql_select_db('other_application')) {
      return new Error('Failed to select other_application database');
    } // if
    // Collect credentials
    $email    = trim(array_var($credentials, 'email'));
    $password = array_var($credentials, 'password');
    $remember = (boolean) array_var($credentials, 'remember', false);
    // Find user in other database
    $result = mysql_query("SELECT password FROM users WHERE email = '" . mysql_real_escape_string($email) . "'");
    if($result) {
      if($row = mysql_fetch_assoc($result)) {
        // Password is OK
        if($row['password'] == $password) {
          // Let's see if we already have this user
          $user = Users::findByEmail($email);
          // It not lets create a new account
          if(!instance_of($user, 'User')) {
            $user = new User();
            $user->setAttributes(array(
            'email' => $email,
            'password' => $row['password'],
            ));
            $user->setCompanyId(11);
            $user->resetToken();
            $save = $user->save();
            if(is_error($save)) {
              return new Error('Failed to create an account. Reason: ' . $save->getMessage());
            } // if
          } // if
          // And done, log user in
          return $this->logUserIn($user, array(
          'remember' => $remember,
          'new_visit' => true,
          ));
        } // if
      } // if
    } // if
    return new Error('User is not registered');
  } else {
    return $active_collab_auth;
  } // if
} // authenticate

To enable this newly created provider, open the config/config.php file and add the following line to the block with constant definitions:

define('AUTH_PROVIDER', 'CustomAuthenticationProvider');

Overriding Authentication System

In this example, we assume that your system administrator has configured the system so that Apache knows you by the username you used to login to your computer and that it makes this information available to PHP in the authenticated_user variable. In this setup, we can completely skip the login screen and log you in directly, based on the data provided by the system.

We will call this authentication provider ApacheAuthenticationProvider and we'll define it in /activecollab/angie/classes/auth/providers/ApacheAuthenticationProvider.class.php. Because we're not using the normal activeCollab login process, we can skip the authentication() method and implement the initialization() method instead:

class ServerAuthenticationProvider extends AuthenticationProvider {
  function initialize() {
    $user = Users::findById($_SERVER['user_id']);
    if(instance_of($user, 'User')) {
      return $this->logUserIn($user);
    } else {
       return new Error('User not recognized');
    } // if
  } // initialize
}

If you are properly logged in within your network, the system will skip the login screen and automatically log you in every time you visit activeCollab .

Integrating activeCollab Login with Your Website

If you wish, you can integrate activeCollab within your website and enable registered users to login easily. To achieve this activeCollab lets you do the following:

  1. Define a custom login form. This form submits user credentials to activeCollab and lets a user log into the system directly from your website;
  2. Define a URL that is used to redirect users back to your website after they log out.

In the following articles you'll find a more detailed explanation on how to set this up.

Custom Login Form

You can add a form that will authenticate users with activeCollab directly from your website. To do this, you need to add a form with specific fields that submits a POST request to activeCollab's login page.

Required fields for this are:

  1. login[email]
  2. login[password]
  3. login[remember]

Additionally you need to include a "submitted" hidden field with a "submitted" value for activeCollab to accept the submitted data.

Here is the example form markup:

<form method="post" action="http://www.activecollab.com/my/ac/public/index.php?path_info=login">
  Email: <input type="text" name="login[email]" />
  Password: <input type="password" name="login[password]" />
  Remember me: <input type="checkbox" name="login[remember]" />
  <input type="hidden" name="submitted" value="submitted" />
  <button type="submit">Go baby go!</button>
</form>

Feel free to change it to fit your needs, but please make sure that the names of the fields are not changed and that the form action points to the login form of your activeCollab. installation.

Logout URL

Since activeCollab 2 you can choose the URL that users will be redirected to when they logout.

By default, they will be redirected back to the login page, but if you provide another location (a certain page of your website, for example) then users will land there instead after they logout from activeCollab. To set-up the landing page up, open Administration > General settings page:

At the bottom of the General Settings page there is When User Logs Out switch:

  1. Choose to Redirect him to a custom URL;
  2. Once you select this, a text input field will be displayed where you can insert the URL that will be used, which must be a valid URL. If it's not valid, activeCollab will ignore it and redirect users back to the login page.

When you make the changes and submit the form, try logging out to confirm that everything is working as it should.

Themes

activeCollab lets you change the look and feel of the application without changing any core files. To do this you can use activeCollab Themes:

One interesting fact about themes is that every user can have a theme of their own, which they can select from the Change Settings page in their profile area. Administrators can also select a default theme that is automatically used when new users are created. When the default theme is changed by an administrator, all user specific settings are dropped and every user's theme is reset to the default one.

Besides the themes that are shipped with activeCollab ('Sandbox' and 'Default') you can use also use any custom themes that you've created.

How do Themes Work?

Themes work by building on activeCollab's default styling with CSS files that are added once the basic styling elements (page layout, form widgets and other basic page elements) have been loaded. These basic elements serve to make activeCollab fully usable, but with a minimum number of graphic elements on the page.

To see how activeCollab looks with only basic files included, select the Sandbox theme on your profile page.

When changes to basic styling are required, activeCollab uses theme files to override these existing settings and adds colors and other graphic elements. The Default theme that is shipped with activeCollab is an example of a theme that extends Sandbox and is also something that you can use as an example for creating your own.

Creating a Theme

To create your own theme in activeCollab you will need some CSS knowledge (and to be creative!). To make your theme, simply follow these steps:

  1. Navigate to /public/assets/themes;
  2. Create a new folder. The folder name will be used as the theme name by activeCollab in the Select Theme field (as shown on the screenshot bellow);
  3. Create the theme.css inside the theme folder you have just created. This file will automatically be used by activeCollab for all users who choose this theme from their profile pages.
  4. Optionally create the /images folder inside the theme folder you've just created. Inside the theme.css file write the CSS rules that will override the existing styling and create the look you want.

API

The activeCollab API (Application Programming Interface) is a set of methods that can be called (accessed) from another application. These methods are used to read and manipulate the data stored by the system.

Making a Request

Methods are executed by calling specific URLs and fetching the formatted output. URLs are formatted in the following format:

http://site.com/activecollab/public/api.php?path_info=#COMMAND#&token=#TOKEN#

Some requests may require more parameters. These parameters are added as regular query string (GET) parameters to the URL. Here is an example with two additional parameters:

http://site.com/activecollab/public/api.php?path_info=#COMMAND#&token=#TOKEN#&variable1=value1&variable2=value2

The API URL that you need to use to send a request (and your token) are available on the API Setting page of your profile page in activeCollab:

1. Output Formats

Currently supported output formats are XML and JSON. There are two ways of specifying output format:

  1. The recommended method which is to set the Accept request header. To get JSON, set it to 'application/json', or or 'application/xml' to get XML.
  2. The second method (which is added for convenience and to make testing easier) is to add a 'format' variable to a query string. Set it to 'json' to get JSON or 'xml' to get the XML formatted output. Here's an example: 
http://example.com/api.php?path_info=people/1&format=json

Response status is returned with status codes. For example, you will get 200 on success, 403 if you don't have permissions to access the page or 404 when you are trying to get an object that does not exist. You can learn more about HTTP status codes in HTTP 1.1 documentation.

Note

When submitting data to activeCollab by using a POST method, there needs to be a variable named "submitted" with a value of "submitted". If you don't provide it, then activeCollab will reject your request (probably with BAD REQUEST error).

Authentication

In order to use the activeCollab API, first you will need to authenticate yourself to the system, which you can do using your API key. This key is available on the API Settings page of your activeCollab user profile:

When creating a request, the API key must be passed as a "token" GET variable. The sample request URL would then look like this:

http://example.com/public/api.php?path_info=projects&token=1-55lTBjCvCALC6Jksg3vo2xQeymySDqFwkReL1H8s
Note

Your API key can be reset at any time. All you need to do is to click the Reset Key link. Please also be aware that your API key will be automatically reset whenever you change your password!

Controling API Status

There are three states within the activeCollab API:

To change the API state check for the API_STATUS in your config/config.php file. If that configuration directive does not exist, add the following line to the file:

define('API_STATUS', 1);

Values this directive can have are:

API Changes

This section contains information about changes made to the API that could affect its behavior and may break backward compatibility.

Note

This API documentation section was introduced when activeCollab 2.1 was launched.

1. activeCollab 2.1

activeCollab 2.0 introduced many improvements, though consequently some have resulted in changes that can break backward compatibility:

  1. /project/:project_id/checklists/:checklist_id/edit returns checklist root element instead of the item;
  2. /project/:project_id/files/:file_id/edit returns file root element instead of the item;
  3. /project/:project_id/pages does not display properties of the root page for a given project. Instead, it lists categories for the pages section. When a category_id is provided in the request, pages posted in that category will be listed;
  4. Page versions are presented differently than revisions in previous releases;
  5. Attachments are presented differently than attachments in previous releases;
  6. /projects/groups now returns project_groups > project_group structure instead of items > item
  7. /status/add returns the message root element instead of the items;
  8. /projects/:project_id/comments/:comment_id/edit returns comment root element instead of the items;
  9. /projects/:project_id/tasks/add?parent_id=:parent_id returns the task root element instead of the items;
  10. /projects/:project_id/tasks/:task_id/edit returns the task root element instead of the items.

System Information

In this chapter we list all the commands that you can use to get information about the activeCollab installation you are communicating with.

1. /info

Returns system information about the installation you are working with. This information includes system versions; info about logged in users; the mode the API is in etc.

Method: GET

Information that you will receive when using this request is:

  • api_version - Version of the activeCollab API;
  • system_version - The version of activeCollab you are communicating with;
  • system_edition - activeCollab edition, corporate or small biz (added in activeCollab 2.3.1);
  • logged_user - URL of currently logged in users (added in activeCollab 1.1.2);
  • read_only - 1 if API is in read only mode, 0 if it supports both read and write requests (added in activeCollab 1.1.3).

Example response:

<info>
  <api_version>
    <![CDATA[2.0]]>
  </api_version>
  <system_version>
    <![CDATA[2.0.2]]>
  </system_version>
  <system_edition>
    <![CDATA[corporate]]>
  </system_edition>
  <logged_user>
    <![CDATA[http://activecollab.dev/people/1/users/1]]>
  </logged_user>
  <read_only>0</read_only>
</info>

Working with Roles

activeCollab supports several methods for listing the System Roles that a user can have, as well as for reading the permissions included in each role.

1. /roles/system

Lists all system roles and role details (permissions included). For security reasons, if user is not system administrator or people manager only default role ID is returned!

Method: GET

Since: activeCollab 1.1.4

Example response:

<system_roles>
  <system_role>
    <id>...</id>
    <name>...</name>
    <is_default>0</is_default>
    <permissions>
      <system_access>1</system_access>
      ...
    </permissions>
  </system_role>
</system_roles>

2. /roles/project

Lists all project roles and displays their permissions.

Please note that the system returns all project roles without checking user permissions. Each user will be able to execute this operation and see all available project roles.

Method: GET

Since: activeCollab 1.1.4

Example Response:

<project_roles>
  <project_role>
    <id>...</id>
    <name>...</name>
    <permissions>
      <discussion>1</discussion>
      ...
    </permissions>
  </project_role>
</project_roles>

3. /roles/:role_id

Displays the details from a specific role. This command can return both system and project roles and their settings.

Please note that role details are listed without checking user permissions, so each user will be able to read details of each role.

Method: GET

Since: activeCollab 1.1.4

Example of the system role response:

<system_role>
  <id>...</id>
  <name>...</name>
  <is_default>0</is_default>
  <permissions>
    <system_access>1</system_access>
    ...
  </permissions>
</system_role>

Example of the project role Response:

<project_role>
  <id>...</id>
  <name>...</name>
  <permissions>
    <discussion>1</discussion>
    ...
  </permissions>
</project_role>

Working with Companies and Users

activeCollab offers several commands which are designed to allow other applications to create and manage company or user accounts.

1. Company Fields

  1. name (string) - Company name. Value of this field is required and needs to be unique in the entire system.

2. User Fields

  1. email (string) - The user's email address. The value of this field is required when a user account is created and must be properly formatted. There can also only be one user associated with any given email address in the system.
  2. password (string) - The user's password. A value for this field is required when a user account is created. Minimal length of the password is 3 characters.
  3. first_name (string) -The user's first name
  4. last_name (string) - The user's last name
  5. role_id (integer) - ID of the user's System Role. Only administrators or people with manage_people permissions included in their System Role are able to change the value of this field.
Note

When a new user account is created, a user can set the role_id to a custom value only if he/she is an Administrator or has the manage_people permission in their Role. If a user who creates an account is not an Administrator or People manager, then the user's role will be set to the default role configured on the Administration > Roles page.

3. /people

Lists all the companies defined in the System, no matter if they are Active or Archived.

Method: GET

Example response:

<companies>
  <company>
    <id>...</id>
    <name>...</name>
    <created_on>...</created_on>
    <permalink>...</permalink>
    <office_address>...</office_address>
    <office_phone>...</office_phone>
    <office_fax>...</office_fax>
    <office_homepage>...</office_homepage>
  </company>
</companies>

4. /people/add-company

This command will create a new company, and if the post is successful, then details of the newly created company will be returned.

Method: POST

Request example:

submitted=submitted
company[name]=New Company

Example response:

<company>
  <id>...</id>
  <name>...</name>
  <created_on>...</created_on>
  <permalink>...</permalink>
  <office_address></office_address>
  <office_phone></office_phone>
  <office_fax></office_fax>
  <office_homepage></office_homepage>
</company>

5. /people/:company_id

Displays the properties of a specific company.

Method: GET.

Example response:

<company>
  <id>...</id>
  <name>...</name>
  <created_on>...</created_on>
  <permalink>...</permalink>
  <office_address></office_address>
  <office_phone></office_phone>
  <office_fax></office_fax>
  <office_homepage></office_homepage>
  <users>
    ...
  </users>
  <logo_url>...</logo_url>
</company>

6. /people/:company_id/edit

Updates properties of an existing company. On success, updated company details are returned.

Method: POST.

Request example:

submitted=submitted
company[name]=Updated Company Name

Response example:

<company>
  <id>...</id>
  <name>...</name>
  <created_on>...</created_on>
  <permalink>...</permalink>
  <office_address></office_address>
  <office_phone></office_phone>
  <office_fax></office_fax>
  <office_homepage></office_homepage>
</company>

7. /people/:company_id/delete

You can use this to delete a company and all of its users. Projects that this company and its users were assigned to will not be deleted! If successful, the system will return a HTTP status of 200 OK.

Note

There is one company which can't be deleted - the Owner Company!

Method: POST.

Request example:

submitted=submitted

8. /people/:company_id/add-user

Creates a user account in the selected company. If successful, the function will display details of the newly created user account.

Note

Only Administrators and people with manage_people permission included in their System Role can set role_id value. If a user who creates the new account is not an Administrator or People Manager, the default role ID will be used.

Method: POST.

Request example:

submitted = submitted
user[email] = ilija@a51dev.com
user[password] = new-password
user[password_a] = new-password
user[role_id] = 1

Response:

<user>
  <id>...</id>
  <company_id>...</company_id>
  <first_name>...</first_name>
  <last_name>...</last_name>
  <email>...</email>
  <last_visit_on>...</last_visit_on>
  <permalink>...</permalink>
  <role_id>...</role_id>
  <is_administrator>...</is_administrator>
  <is_project_manager>...</is_project_manager>
  <is_people_manager>...</is_people_manager>
  <token>...</token>
</user>

9. /people/:company_id/users/:user_id

Shows details of a specific user.

Method: GET

Example response:

<user>
  <id>...</id>
  <first_name>...</first_name>
  <last_name>...</last_name>
  <email>...</email>
  <last_visit_on>...</last_visit_on>
  <permalink>...</permalink>
  <role_id>...</role_id>
  <is_administrator>...</is_administrator>
  <is_project_manager>...</is_project_manager>
  <is_people_manager>...</is_people_manager>
  <token>...</token>
  <company>
    <id>...</id>
    <name>...</name>
    <created_on>...</created_on>
    <permalink>...</permalink>
    <office_address>...</office_address>
    <office_phone>...</office_phone>
    <office_fax>...</office_fax>
    <office_homepage>...</office_homepage>
  </company>
  <avatar_url>...</avatar_url>
</user>

10. /people/:company_id/users/:user_id/edit

Updates details of an existing user.

Method: POST.

Request example:

submitted = submitted
user[first_name] = John
user[last_name] = Doe

Example response:

<user>
  <id>...</id>
  <first_name>...</first_name>
  <last_name>...</last_name>
  <email>...</email>
  <last_visit_on>...</last_visit_on>
  <permalink>...</permalink>
  <role_id>...</role_id>
  <is_administrator>...</is_administrator>
  <is_project_manager>...</is_project_manager>
  <is_people_manager>...</is_people_manager>
  <token>...</token>
  <company>
    <id>...</id>
    <name>...</name>
    <created_on>...</created_on>
    <permalink>...</permalink>
    <office_address>...</office_address>
    <office_phone>...</office_phone>
    <office_fax>...</office_fax>
    <office_homepage>...</office_homepage>
  </company>
  <avatar_url>...</avatar_url>
</user>

11. /people/:company_id/users/:user_id/delete

Delete a specific user account. if successful, a HTTP 200 OK status will be returned.

Note

Data created by this user - project, tickets, discussions, comments, etc. will not be deleted.

Method: POST.

Request example:

submitted = submitted

Working with Projects

Commands listed in this chapter are used for management of your projects via the API.

1. Project Fields

  1. name (string) - Project name;
  2. overview (text) - Project overview;
  3. default_visibility (integer) - Default visibility that is pre-selected for objects in this project. 0 for private, 1 for normal;
  4. starts_on (date) - Date when the project starts;
  5. group_id (integer) - ID of the project group;
  6. company_id (integer) - ID of the client company;
  7. leader_id (integer) - ID of the user who is the Project Leader;
  8. status (string) - Project status. This field is available only for the edit-status action and has four possible values: active, paused, completed and canceled.

2. /projects

Displays all projects that the authenticated user has access to. This function will show all - active, paused, completed and canceled projects.

Method: GET

Example response:

<projects>
  <project>
    <id>1</id>
    <name>
      <![CDATA[First Project]]>
    </name>
    <overview>
      <![CDATA[<p>This is overview of the first project</p>]]>
    </overview>
    <status>
      <![CDATA[active]]>
    </status>
    <type>...</type>
    <permalink>...</permalink>
    <leader_id>...</leader_id>
    <company_id>...</company_id>
    <group_id>...</group_id>
  </project>
</projects>

3. /projects/add

Creates a new project.

Method: POST.

Additionally you can include a project_template_id variable, which should be a valid project ID. If this variable is included, the new project will be created using an existing project (determined by the ID that has been passed) as a template.

Example request:

submitted=submitted
project[name] = Testing API
project[leader_id] = 1

Response:

<project>
  <id>2</id>
  <name>
    <![CDATA[Created through API]]>
  </name>
  <overview></overview>
  <status>
    <![CDATA[active]]>
  </status>
  <permalink>...</permalink>
  <leader_id>...</leader_id>
  <company_id>...</company_id>
  <group_id>...</group_id>
</project>

4. /projects/:project_id

Shows properties of the specific project. Besides project properties, this request also returns:

  1. Brief information about the Projet Leader;
  2. Brief information about the client;
  3. Permissions that any logged in user has in each project area.

Method: GET

Example response:

<project>
  <id>2</id>
  <name>
    <![CDATA[Created through API]]>
  </name>
  <overview></overview>
  <status>
    <![CDATA[active]]>
  </status>
  <permalink>...</permalink>
  <leader>...</leader>
  <company_id>0</company_id>
  <group_id>0</group_id>
  <logged_user_permissions>
    <role>
      <![CDATA[administrator]]>
    </role>
    <permissions>
      <milestone>3</milestone>
      <discussion>3</discussion>
      <file>3</file>
      <page>3</page>
      <ticket>3</ticket>
      <timerecord>3</timerecord>
    </permissions>
  </logged_user_permissions>
  <icon_url>...</icon_url>
</project>

5. /projects/:project_id/edit

Updates project properties.

Method: POST.

Request example:

submitted = submitted
project[name] = New name
project[company_id] = 16
<project>
  <id>2</id>
  <name>
    <![CDATA[New name]]>
  </name>
  <overview></overview>
  <status>
    <![CDATA[active]]>
  </status>
  <permalink>...</permalink>
  <leader_id>15</leader_id>
  <company_id>16</company_id>
  <group_id>0</group_id>
</project>

6. /projects/:project_id/edit-status

Updates the project status, which can have four different values:

  1. Active;
  2. Paused;
  3. Completed;
  4. Canceled.

Method: POST.

Request example:

submitted = submitted
project[status] = completed

Response:

<project>
  <id>2</id>
  <name>
    <![CDATA[Project Name]]>
  </name>
  <overview></overview>
  <status>
    <![CDATA[completed]]>
  </status>
  <permalink>...</permalink>
  <leader_id>15</leader_id>
  <company_id>16</company_id>
  <group_id>0</group_id>
</project>

7. /projects/:project_id/delete

Delete a selected project. If successful, system will return a HTTP status 200 OK message.

Note

This operation is final and when it is executed you will not be able to restore it. There is no undo option!

Method: POST.

Request example:

submitted=submitted

8. /projects/:project_id/user-tasks

Returns all tasks assigned to a logged in user for that particular project.

Method: GET

Since: activeCollab 1.1.2

<assignments>
  <assignment>
    <id>10</id>
    <type>
      <![CDATA[Ticket]]>
    </type>
    <name>
      <![CDATA[One ticket]]>
    </name>
    <body>...</body>
    <state>3</state>
    <visibility>0</visibility>
    <created_on>2009-03-24 13:44:34</created_on>
    <created_by_id>15</created_by_id>
    <updated_on></updated_on>
    <updated_by_id>0</updated_by_id>
    <version>1</version>
    <permalink>...</permalink>
    <priority>0</priority>
    <due_on>...</due_on>
    <completed_on>...</completed_on>
    <completed_by_id>0</completed_by_id>
    <project_id>2</project_id>
    <parent_id>0</parent_id>
    <milestone_id>0</milestone_id>
    <permissions>
      <can_edit>1</can_edit>
      <can_delete>1</can_delete>
      <can_change_visibility>1</can_change_visibility>
      <can_move>1</can_move>
      <can_copy>1</can_copy>
      <can_change_complete_status>1</can_change_complete_status>
    </permissions>
    <ticket_id>1</ticket_id>
  </assignment>
</assignments>

Working with Project People

1. /projects/:project_id/people

Displays the list of people involved with the project and the permissions included in their Project Role. Project Permissions are organized per module and have four possible values:

  • 0 - no access;
  • 1 - has access, but can't create or manage objects;
  • 2 - has access and permission to create objects in a given module;
  • 3 - has access, creation and management permissions in a given module.

Method: GET

Since: activeCollab 1.1.4

Response:

<project_users>
  <project_user>
    <user_id>15</user_id>
    <role>
      <![CDATA[administrator]]>
    </role>
    <permissions>
      <milestone>3</milestone>
      <discussion>3</discussion>
      <file>3</file>
      <page>3</page>
      <ticket>3</ticket>
      <timerecord>3</timerecord>
    </permissions>
    <permalink>...</permalink>
  </project_user>
  <project_user>
    <user_id>16</user_id>
    <role>
      <![CDATA[custom]]>
    </role>
    <permissions>
      <milestone>1</milestone>
      <discussion>1</discussion>
      <file>1</file>
      <page>2</page>
      <ticket>2</ticket>
      <timerecord>2</timerecord>
    </permissions>
  </project_user>
</project_users>

2. /projects/:project_id/people/add

By using this command, you can add one or more users to the project and set their Project Permissions. This command accepts two parameters:

  1. users - An array of users that you want to add to the project;
  2. project_permissions - An array of permission settings. Two values are relevant in this array:
    1. project_permissions[role_id] - ID of the project role a user will have in the project. This parameter is optional. If value is not present, the system will use project_permissions[permissions].
    2. project_permissions[permissions] - Array of permissions for different sections that this user should have in the project. This parameter is ignored when project_permissions[role_id] is present.

Method: POST

Since: activeCollab 2.0.3

This example request will add users with ID 39 and 52 to the project and set their project role to role #10:

submitted=submitted
users[]=39
users[]=52
project_permissions[role_id]=10

This example request will add users with ID 15 and 72 to the project, and set their permissions for tickets and discussions module to Has access. All their other module permissions will be set to No access:

submitted = submitted
users[] = 15
users[] = 72
project_permissions[permissions][discussion] = 1
project_permissions[permissions][ticket] = 1

3. /projects/:project_id/people/:user_id/change-permissions

This command is used for changing the set of Project Permissions for the selected user in a given project.

This command accepts two parameters:

  1. project_permissions[role_id] - ID of the Project Role that a user will have in the project. This parameter is optional. If a value is not set, the system will use project_permissions[permissions].
  2. project_permissions[permissions] - Array of permissions for different sections that the user should have in the project. This parameter is ignored when project_permissions[role_id] is present.

In this example, the Project Permissions for this user and his Project Role will be changed to Project Role #10:

submitted=submitted
project_permissions[role_id]=10

This example request will change a user's Project Permission so that he/she has access to the Tickets and Discussions modules. All other module permissions will be set to No access:

submitted = submitted
project_permissions[permissions][discussion] = 1
project_permissions[permissions][ticket] = 1

4. /projects/:project_id/people/:user_id/remove-from-project

This command will remove a specific user from the project. If successful, this function will return a HTTP 200 OK status.

Method: POST

Since: activeCollab 2.0.3

Working with Project Groups

Project Group commands let you organise manage project groups from an external application.

Note

The ability to work with project groups through the API was added in activeCollab 1.1.4 and is not available in older versions.

1. Project Group Fields

  1. name (string) - Group name. Value of this field is required and it needs to be unique.

2. projects/groups

Lists all available project groups in your activeCollab.

Method: GET.

Example response:

<project_groups>
  <project_group>
    <id>1</id>
    <name>
      <![CDATA[Default]]>
    </name>
  </project_group>
  <project_group>
    <id>2</id>
    <name>
      <![CDATA[First Group]]>
    </name>
  </project_group>
</project_groups>__

3. projects/groups/add

Creates a new project group. The name of the group needs to be unique.

Method: POST.

Request example:

submitted=submitted
project_group[name] = Development

Response:

<project_group>
  <id>4</id>
  <name>
    <![CDATA[Development]]>
  </name>
</project_group>

4. projects/groups/:project_group_id

Displays group details, including all projects that belong to a group.

Method: GET.

<project_group>
  <id>2</id>
  <name>
    <![CDATA[First Group]]>
  </name>
  <projects>
    <project>
      <id>1</id>
      <name>
        <![CDATA[First Project]]>
      </name>
      <overview>
        <![CDATA[<p>This is overview of the first project</p>]]>
      </overview>
      <status>
        <![CDATA[active]]>
      </status>
      <permalink>...</permalink>
      <leader_id>15</leader_id>
      <company_id>16</company_id>
      <group_id>2</group_id>
    </project>
  </projects>
</project_group>

5. projects/groups/:project_group_id/edit

This command updates the existing project group name.

Method: POST.

Request example:

submitted=submitted
project_group[name] = Update group name

Response:

<project_group>
  <id>2</id>
  <name>
    <![CDATA[Update group name]]>
  </name>
</project_group>

6. projects/groups/:project_group_id/delete

Removes a project group from the database. If successful, the system will return a HTTP status 200 OK message.

Method: POST.

Note

Be aware that only empty project groups can be deleted.

Request example:

submitted=submitted

Working with Discussions

Discussions are a key part of activeCollab where people can discuss various aspects of a project in an environment similar to online forums. Each project has a separate discussion area.

1. Discussion Fields

  1. name (string) - Discussion topic. This field is required when topic is created;
  2. body (string) - First message body. This field is required when topic is created;
  3. tags (string) - List of comma-separated tags;
  4. visibility (integer) - Discussion visibility. 0 is private and 1 is normal visibility;
  5. milestone_id (integer) - ID of parent milestone;
  6. parent_id (integer) - ID of parent category.

2. /projects/:project_id/discussions

Displays all discussions in a project.

Method: GET.

Example response:

<discussions>
  <discussion>
    <id>11</id>
    <type>
      <![CDATA[Discussion]]>
    </type>
    <name>
      <![CDATA[Updated Name]]>
    </name>
    <body>
      <![CDATA[This is first message!]]>
    </body>
    <state>...</state>
    <visibility>...</visibility>
    <created_on>...</created_on>
    <created_by_id>...</created_by_id>
    <updated_on>...</updated_on>
    <updated_by_id>...</updated_by_id>
    <version>...</version>
    <permalink>...</permalink>
    <project_id>...</project_id>
    <parent_id>...</parent_id>
    <milestone_id>...</milestone_id>
    <permissions>
      <can_edit>1</can_edit>
      <can_delete>1</can_delete>
      <can_change_visibility>1</can_change_visibility>
      <can_move>1</can_move>
      <can_copy>1</can_copy>
    </permissions>
  </discussion>
</discussions>

3. /projects/:project_id/discussions/add

Creates a new discussion in the specified project

Method: POST.

Request example:

submitted=submitted
discussion[name] = New Discussion
discussion[body] = This is first message!

Response:

<discussion>
  <id>11</id>
  <type>
    <![CDATA[Discussion]]>
  </type>
  <name>
    <![CDATA[New Discussion]]>
  </name>
  <body>
    <![CDATA[This is first message!]]>
  </body>
  <state>...</state>
  <visibility>...</visibility>
  <created_on>...</created_on>
  <created_by_id>15</created_by_id>
  <updated_on>...</updated_on>
  <updated_by_id>...</updated_by_id>
  <version>...</version>
  <permalink>...</permalink>
  <project_id>...</project_id>
  <parent_id>...</parent_id>
  <milestone_id>...</milestone_id>
  <permissions>
    <can_edit>1</can_edit>
    <can_delete>1</can_delete>
    <can_change_visibility>1</can_change_visibility>
    <can_move>1</can_move>
    <can_copy>1</can_copy>
  </permissions>
</discussion>

4. /projects/:project_id/discussions/:discussion_id

Displays discussion details. In addition to discussion details, this command also returns all comments posted, as part of comments property.

Method: GET

Response:

<discussion>
  <id>11</id>
  <type>
    <![CDATA[Discussion]]>
  </type>
  <name>
    <![CDATA[New Discussion]]>
  </name>
  <body>
    <![CDATA[This is first message!]]>
  </body>
  <state>...</state>
  <visibility>...</visibility>
  <created_on>...</created_on>
  <created_by_id>...</created_by_id>
  <updated_on>...</updated_on>
  <updated_by_id>...</updated_by_id>
  <version>...</version>
  <permalink>...</permalink>
  <project_id>...</project_id>
  <parent_id>...</parent_id>
  <milestone_id>...</milestone_id>
  <comments>
    <comment>
      <id>12</id>
      <type>
        <![CDATA[Comment]]>
      </type>
      <name>
        <![CDATA[Comment on New Discussion]]>
      </name>
      <body>
        <![CDATA[<p>First discussion</p>]]>
      </body>
      <state>...</state>
      <visibility>...</visibility>
      <created_on>...</created_on>
      <created_by_id>...</created_by_id>
      <updated_on>...</updated_on>
      <updated_by_id>...</updated_by_id>
      <version>...</version>
      <permalink>...</permalink>
      <project_id>...</project_id>
      <parent_id>...</parent_id>
      <milestone_id>...</milestone_id>
      <permissions>
        <can_edit>1</can_edit>
        <can_delete>1</can_delete>
        <can_change_visibility>1</can_change_visibility>
        <can_move>0</can_move>
        <can_copy>0</can_copy>
      </permissions>
    </comment>
  </comments>
  <permissions>
    <can_edit>1</can_edit>
    <can_delete>1</can_delete>
    <can_change_visibility>1</can_change_visibility>
    <can_move>1</can_move>
    <can_copy>1</can_copy>
  </permissions>
</discussion>

5. /projects/:project_id/discussions/:discussion_id/edit

Updates existing discussion details.

Method: POST.

Request example:

submitted=submitted
discussion[name] = Updated Name
parent_id = 1

Response:

<discussion>
  <id>11</id>
  <type>
    <![CDATA[Discussion]]>
  </type>
  <name>
    <![CDATA[Updated Name]]>
  </name>
  <body>
    <![CDATA[This is first message!]]>
  </body>
  <state>...</state>
  <visibility>...</visibility>
  <created_on>...</created_on>
  <created_by_id>...</created_by_id>
  <updated_on>...</updated_on>
  <updated_by_id>...</updated_by_id>
  <version>...</version>
  <permalink>...</permalink>
  <project_id>...</project_id>
  <parent_id>...</parent_id>
  <milestone_id>...</milestone_id>
  <permissions>
    <can_edit>1</can_edit>
    <can_delete>1</can_delete>
    <can_change_visibility>1</can_change_visibility>
    <can_move>1</can_move>
    <can_copy>1</can_copy>
  </permissions>
</discussion>

Working with Checklists

The commands described in this chapter will enable you to manage Checklists within a project in your edition of activeCollab. Each project has its own separate set of Checklists.

Note

By default, the Checklists module is not installed in activeCollab Corporate edition and these commands are not available. To install it, go to the Administration > Modules page and install it from the list of Available Modules.

1. Checklist Fields

  1. name (string) - Object name or a short one line summary. The value of this field is required when a Checklist is created.;
  2. body (text) - Full checklist description. Use HTML for formatting;
  3. tags (string) - List of comma-separated object tags;
  4. visibility (integer) - Object visibility. 0 is private and 1 is normal visibility;
  5. milestone_id (integer) - ID of parent milestone.

2. /projects/:project_id/checklists

Displays all active Checklists for a given project.

Method: GET.

Example response:

<checklists>
  <checklist>
    <id>13</id>
    <type>
      <![CDATA[Checklist]]>
    </type>
    <name>
      <![CDATA[Updated name]]>
    </name>
    <body>
      <![CDATA[Full description of this checklist]]>
    </body>
    <state>...</state>
    <visibility>...</visibility>
    <created_on>...</created_on>
    <created_by_id>...</created_by_id>
    <updated_on>...</updated_on>
    <updated_by_id>...</updated_by_id>
    <version>...</version>
    <permalink>...</permalink>
    <priority>...</priority>
    <due_on>...</due_on>
    <completed_on>...</completed_on>
    <completed_by_id>...</completed_by_id>
    <project_id>...</project_id>
    <parent_id>...</parent_id>
    <milestone_id>...</milestone_id>
    <permissions>
      <can_edit>1</can_edit>
      <can_delete>1</can_delete>
      <can_change_visibility>1</can_change_visibility>
      <can_move>1</can_move>
      <can_copy>1</can_copy>
      <can_change_complete_status>1</can_change_complete_status>
    </permissions>
  </checklist>
</checklists>

3. /projects/#project_id/checklists/archive

Lists all completed Checklists in the project.

Method: GET.

Example response:

<checklists>
  <checklist>
    <id>13</id>
    <type>
      <![CDATA[Checklist]]>
    </type>
    <name>
      <![CDATA[Updated name]]>
    </name>
    <body>
      <![CDATA[Full description of this checklist]]>
    </body>
    <state>...</state>
    <visibility>...</visibility>
    <created_on>...</created_on>
    <created_by_id>...</created_by_id>
    <updated_on>...</updated_on>
    <updated_by_id>...</updated_by_id>
    <version>...</version>
    <permalink>...</permalink>
    <priority>...</priority>
    <due_on>...</due_on>
    <completed_on>...</completed_on>
    <completed_by_id>...</completed_by_id>
    <project_id>...</project_id>
    <parent_id>...</parent_id>
    <milestone_id>...</milestone_id>
    <permissions>
      <can_edit>1</can_edit>
      <can_delete>1</can_delete>
      <can_change_visibility>1</can_change_visibility>
      <can_move>1</can_move>
      <can_copy>1</can_copy>
      <can_change_complete_status>1</can_change_complete_status>
    </permissions>
  </checklist>
</checklists>

4. /projects/:project_id/checklists/add

This command will create a new checklist.

Method: POST.

Request example:

submitted=submitted
checklist[name] = New checklist
checklist[body] = Full description of this checklist
checklist[visibility] = 1

Response:

<checklist>
  <id>13</id>
  <type>
    <![CDATA[Checklist]]>
  </type>
  <name>
    <![CDATA[New checklist]]>
  </name>
  <body>
    <![CDATA[Full description of this checklist]]>
  </body>
  <state>...</state>
  <visibility>...</visibility>
  <created_on>...</created_on>
  <created_by_id>...</created_by_id>
  <updated_on>...</updated_on>
  <updated_by_id>...</updated_by_id>
  <version>...</version>
  <permalink>...</permalink>
  <priority>...</priority>
  <due_on>...</due_on>
  <completed_on>...</completed_on>
  <completed_by_id>...</completed_by_id>
  <project_id>1</project_id>
  <parent_id>...</parent_id>
  <milestone_id>...</milestone_id>
  <permissions>
    <can_edit>1</can_edit>
    <can_delete>1</can_delete>
    <can_change_visibility>1</can_change_visibility>
    <can_move>1</can_move>
    <can_copy>1</can_copy>
    <can_change_complete_status>1</can_change_complete_status>
  </permissions>
</checklist>

5. /projects/:project_id/checklists/:checklist_id

Displays checklist details.

This request also returns array of tasks attached to this checklist in the tasks property.

Method: GET.

Example response:

<checklist>
  <id>13</id>
  <type>
    <![CDATA[Checklist]]>
  </type>
  <name>
    <![CDATA[New checklist]]>
  </name>
  <body>
    <![CDATA[Full description of this checklist]]>
  </body>
  <state>...</state>
  <visibility>...</visibility>
  <created_on>...</created_on>
  <created_by_id>...</created_by_id>
  <updated_on>...</updated_on>
  <updated_by_id>...</updated_by_id>
  <version>...</version>
  <permalink>...</permalink>
  <priority>...</priority>
  <due_on>...</due_on>
  <completed_on>...</completed_on>
  <completed_by_id>...</completed_by_id>
  <project_id>...</project_id>
  <parent_id>...</parent_id>
  <milestone_id>...</milestone_id>
  <tasks>
    ...
  </tasks>
  <permissions>
    <can_edit>1</can_edit>
    <can_delete>1</can_delete>
    <can_change_visibility>1</can_change_visibility>
    <can_move>1</can_move>
    <can_copy>1</can_copy>
    <can_change_complete_status>1</can_change_complete_status>
  </permissions>
</checklist>

6. /projects/:project_id/checklists/:checklist_id/edit

Updates the properties of an existing checklist.

Method: POST.

Request example:

submitted=submitted
checklist[name] = Updated name

Response:

<checklist>
  <id>13</id>
  <type>
    <![CDATA[Checklist]]>
  </type>
  <name>
    <![CDATA[Updated name]]>
  </name>
  <body>
    <![CDATA[Full description of this checklist]]>
  </body>
  <state>...</state>
  <visibility>...</visibility>
  <created_on>...</created_on>
  <created_by_id>...</created_by_id>
  <updated_on>...</updated_on>
  <updated_by_id>...</updated_by_id>
  <version>...</version>
  <permalink>...</permalink>
  <priority>...</priority>
  <due_on>...</due_on>
  <completed_on>...</completed_on>
  <completed_by_id>...</completed_by_id>
  <project_id>...</project_id>
  <parent_id>...</parent_id>
  <milestone_id>...</milestone_id>
  <permissions>
    <can_edit>1</can_edit>
    <can_delete>1</can_delete>
    <can_change_visibility>1</can_change_visibility>
    <can_move>1</can_move>
    <can_copy>1</can_copy>
    <can_change_complete_status>1</can_change_complete_status>
  </permissions>
</checklist>

Working with Files

Each project has a separate section where files can be uploaded, discussed and file versions tracked. The commands described on the following pages will allow you to manage all these files.

1. File Fields

  1. name (string) - File name;
  2. body (text) - File description;
  3. tags (string) - List of comma-separated object tags;
  4. visibility (integer) - Object visibility. 0 is private and 1 is normal visibility;
  5. milestone_id (integer) - ID of the parent milestone;
  6. parent_id (integer) - File category ID.

All fields are optional as long as valid file is uploaded.

2. /projects/:project_id/files

Lists all the files from a given project.

Method: GET.

Example response:

<files>
  <file>
    <id>17</id>
    <type>
      <![CDATA[File]]>
    </type>
    <name>
      <![CDATA[New-Name.png]]>
    </name>
    <body>
      <![CDATA[Optional file description]]>
    </body>
    <state>...</state>
    <visibility>...</visibility>
    <created_on>...</created_on>
    <created_by_id>...</created_by_id>
    <updated_on>...</updated_on>
    <updated_by_id>...</updated_by_id>
    <version>...</version>
    <permalink>...</permalink>
    <project_id>...</project_id>
    <parent_id>...</parent_id>
    <milestone_id>...</milestone_id>
    <permissions>
      <can_edit>1</can_edit>
      <can_delete>1</can_delete>
      <can_change_visibility>1</can_change_visibility>
      <can_move>1</can_move>
      <can_copy>1</can_copy>
    </permissions>
  </file>
</files>

3. /projects/:project_id/files/upload-single

This command will enable you to upload a single file from your computer to activeCollab.

If the name property is not provided, the system will use the original file name.

Method: POST.

Additional requirement for a file to be uploaded (any name will work, but we recommend that you name the file field 'attachment').

Request example:

submitted = submitted
file[name] = new_file.png
file[body] = Optional file description

Response:

<file>
  <id>17</id>
  <type>
    <![CDATA[File]]>
  </type>
  <name>
    <![CDATA[new_file.png]]>
  </name>
  <body>
    <![CDATA[Optional file description]]>
  </body>
  <state>...</state>
  <visibility>...</visibility>
  <created_on>...</created_on>
  <created_by_id>...</created_by_id>
  <updated_on>...</updated_on>
  <updated_by_id>...</updated_by_id>
  <version>...</version>
  <permalink>...</permalink>
  <project_id>...</project_id>
  <parent_id>...</parent_id>
  <milestone_id>...</milestone_id>
  <permissions>
    <can_edit>1</can_edit>
    <can_delete>1</can_delete>
    <can_change_visibility>1</can_change_visibility>
    <can_move>1</can_move>
    <can_copy>1</can_copy>
  </permissions>
</file>

4. /projects/:project_id/files/:file_id

Displays file details.

In addition to file details, information about each file revision is provided as a value in the revisions property.

Method: GET.

<file>
  <id>17</id>
  <type>
    <![CDATA[File]]>
  </type>
  <name>
    <![CDATA[new_file.png]]>
  </name>
  <body>
    <![CDATA[Optional file description]]>
  </body>
  <state>...</state>
  <visibility>...</visibility>
  <created_on>...</created_on>
  <created_by_id>...</created_by_id>
  <updated_on>...</updated_on>
  <updated_by_id>...</updated_by_id>
  <version>...</version>
  <permalink>...</permalink>
  <project_id>...</project_id>
  <parent_id>...</parent_id>
  <milestone_id>...</milestone_id>
  <permissions>
    <can_edit>1</can_edit>
    <can_delete>1</can_delete>
    <can_change_visibility>1</can_change_visibility>
    <can_move>1</can_move>
    <can_copy>1</can_copy>
  </permissions>
  <revisions>
    ...
  </revisions>
</file>

5. /projects/:project_id/files/:file_id/edit

Updates file details.

Method: POST.

Example request:

submitted = submitted
file[name] = New-Name.png

Response:

<file>
  <id>17</id>
  <type>
    <![CDATA[File]]>
  </type>
  <name>
    <![CDATA[New-Name.png]]>
  </name>
  <body>
    <![CDATA[Optional file description]]>
  </body>
  <state>...</state>
  <visibility>...</visibility>
  <created_on>...</created_on>
  <created_by_id>...</created_by_id>
  <updated_on>...</updated_on>
  <updated_by_id>...</updated_by_id>
  <version>...</version>
  <permalink>...</permalink>
  <project_id>...</project_id>
  <parent_id>...</parent_id>
  <milestone_id>...</milestone_id>
  <permissions>
    <can_edit>1</can_edit>
    <can_delete>1</can_delete>
    <can_change_visibility>1</can_change_visibility>
    <can_move>1</can_move>
    <can_copy>1</can_copy>
  </permissions>
</file>

Working with Milestones

1. Milestone Fields

  1. name (string) - Milestone summary. The value of this field is required when a milestone is created;
  2. body (text) - File Description;
  3. start_on (date) - Date when the milestone starts. A value for this field is required when a milestone is created;
  4. due_on (date) - Date when the milestone is due. A value for this field is required when a milestone is created;
  5. priority (integer) - Milestone priority. Priority can have five integer values ranging from -2 (lowest) to 2 (highest). 0 is normal;
  6. assignees (array) - Array of people assigned to the object. First array element is list of assignees (as an array). Second parameter is an ID of the person responsible for a task (ID must be in the first list);
  7. tags (string) - List of comma-separated tags for milestone;
  8. visibility (integer) - Object visibility. 0 is private and 1 is normal visibility.

2. /projects/:project_id/milestones

Lists all active milestones for a specific project.

Method: GET.

Response example:

<milestones>
  <milestone>
    <id>18</id>
    <type>
      <![CDATA[Milestone]]>
    </type>
    <name>
      <![CDATA[Update name]]>
    </name>
    <body>...</body>
    <state>...</state>
    <visibility>...</visibility>
    <created_on>...</created_on>
    <created_by_id>...</created_by_id>
    <updated_on>...</updated_on>
    <updated_by_id>...</updated_by_id>
    <version>...</version>
    <permalink>...</permalink>
    <priority>...</priority>
    <completed_on>...</completed_on>
    <completed_by_id>...</completed_by_id>
    <project_id>...</project_id>
    <parent_id>...</parent_id>
    <permissions>
      <can_edit>1</can_edit>
      <can_delete>1</can_delete>
      <can_change_visibility>1</can_change_visibility>
      <can_move>1</can_move>
      <can_copy>1</can_copy>
      <can_change_complete_status>1</can_change_complete_status>
    </permissions>
    <start_on>2008-05-05</start_on>
    <due_on>2008-05-08</due_on>
  </milestone>
</milestones>

3. /projects/:project_id/milestones/add

Creates a new milestone.

Method: POST.

Example request:

submitted = submitted
milestone[name] = Test milestone
milestone[start_on] = 2008-05-05
milestone[due_on] = 2008-05-08

Response:

<milestone>
  <id>18</id>
  <type>
    <![CDATA[Milestone]]>
  </type>
  <name>
    <![CDATA[Test milestone]]>
  </name>
  <body>
  </body>
  <state>...</state>
  <visibility>...</visibility>
  <created_on>...</created_on>
  <created_by_id>...</created_by_id>
  <updated_on>...</updated_on>
  <updated_by_id>...</updated_by_id>
  <version>...</version>
  <permalink>...</permalink>
  <priority>...</priority>
  <completed_on>...</completed_on>
  <completed_by_id>...</completed_by_id>
  <project_id>...</project_id>
  <parent_id>...</parent_id>
  <permissions>
    <can_edit>1</can_edit>
    <can_delete>1</can_delete>
    <can_change_visibility>1</can_change_visibility>
    <can_move>1</can_move>
    <can_copy>1</can_copy>
    <can_change_complete_status>1</can_change_complete_status>
  </permissions>
  <start_on>2008-05-05</start_on>
  <due_on>2008-05-08</due_on>
</milestone>

4. /projects/:project_id/milestones/:milestone_id

Displays milestone details.

Method: GET

Example response:

<milestone>
  <id>18</id>
  <type>
    <![CDATA[Milestone]]>
  </type>
  <name>
    <![CDATA[Test milestone]]>
  </name>
  <body>...</body>
  <state>...</state>
  <visibility>...</visibility>
  <created_on>...</created_on>
  <created_by_id>...</created_by_id>
  <updated_on>...</updated_on>
  <updated_by_id>...</updated_by_id>
  <version>...</version>
  <permalink>...</permalink>
  <priority>...</priority>
  <completed_on>...</completed_on>
  <completed_by_id>...</completed_by_id>
  <project_id>...</project_id>
  <parent_id>...</parent_id>
  <assignees>...</assignees>
  <permissions>
    <can_edit>1</can_edit>
    <can_delete>1</can_delete>
    <can_change_visibility>1</can_change_visibility>
    <can_move>1</can_move>
    <can_copy>1</can_copy>
    <can_change_complete_status>1</can_change_complete_status>
  </permissions>
  <start_on>2008-05-05</start_on>
  <due_on>2008-05-08</due_on>
</milestone>

5. /projects/:project_id/milestones/:milestone_id/edit

Updates milestone details

Method: POST.

Request example:

submitted = submitted
milestone[name] = Update name

Response:

milestone>
  <id>18</id>
  <type>
    <![CDATA[Milestone]]>
  </type>
  <name>
    <![CDATA[Update name]]>
  </name>
  <body>...</body>
  <state>...</state>
  <visibility>...</visibility>
  <created_on>...</created_on>
  <created_by_id>...</created_by_id>
  <updated_on>...</updated_on>
  <updated_by_id>...</updated_by_id>
  <version>...</version>
  <permalink>...</permalink>
  <priority>...</priority>
  <completed_on>...</completed_on>
  <completed_by_id>...</completed_by_id>
  <project_id>...</project_id>
  <parent_id>...</parent_id>
  <permissions>
    <can_edit>1</can_edit>
    <can_delete>1</can_delete>
    <can_change_visibility>1</can_change_visibility>
    <can_move>1</can_move>
    <can_copy>1</can_copy>
    <can_change_complete_status>1</can_change_complete_status>
  </permissions>
  <start_on>2008-05-05</start_on>
  <due_on>2008-05-08</due_on>
</milestone>

Working with Tickets

1. Ticket Fields

  1. name (string) - Ticket summary. A value for this field is required when a Ticket is created;
  2. body (text) - Full ticket description;
  3. tags (string) - List of comma-separated object tags;
  4. visibility (integer) - Object visibility. 0 is private and 1 is normal visibility;
  5. priority (integer) - Priority can have one of five integer values, ranging from -2 (lowest) to 2 (highest). 0 is normal;
  6. due_on (date) - Ticket due date;
  7. assignees (array) - Array of people assigned to the Ticket. The first element of the array is a list of assignees (as an array). Second parameter is an ID of the person responsible for the Ticket (ID must be in the first list);
  8. milestone_id (integer) - ID of the parent milestone;
  9. parent_id (integer) - ID of the parent object (category, ticket for tasks etc.);
  10. ticket_id (integer) - Ticket's unique ID in the project.

2. /projects/:project_id/tickets

Lists all active tickets in a project.

Method: GET

<tickets>
  <ticket>
    <id>9</id>
    <type>
      <![CDATA[Ticket]]>
    </type>
    <name>
      <![CDATA[Updated summary]]>
    </name>
    <body>...</body>
    <state>...</state>
    <visibility>...</visibility>
    <created_on>...</created_on>
    <created_by_id>...</created_by_id>
    <updated_on>...</updated_on>
    <updated_by_id>...</updated_by_id>
    <version>...</version>
    <permalink>...</permalink>
    <priority>...</priority>
    <due_on>...</due_on>
    <completed_on>...</completed_on>
    <completed_by_id>...</completed_by_id>
    <project_id>...</project_id>
    <parent_id>...</parent_id>
    <milestone_id>...</milestone_id>
    <permissions>
      <can_edit>1</can_edit>
      <can_delete>1</can_delete>
      <can_change_visibility>1</can_change_visibility>
      <can_move>1</can_move>
      <can_copy>1</can_copy>
      <can_change_complete_status>1</can_change_complete_status>
    </permissions>
    <ticket_id>1</ticket_id>
  </ticket>
</tickets>

3. /projects/:project_id/tickets/archive

Displays all completed tickets in a project.

Method: GET

<tickets>
  <ticket>
    <id>9</id>
    <type>
      <![CDATA[Ticket]]>
    </type>
    <name>
      <![CDATA[Updated summary]]>
    </name>
    <body>...</body>
    <state>...</state>
    <visibility>...</visibility>
    <created_on>...</created_on>
    <created_by_id>...</created_by_id>
    <updated_on>...</updated_on>
    <updated_by_id>...</updated_by_id>
    <version>...</version>
    <permalink>...</permalink>
    <priority>...</priority>
    <due_on>...</due_on>
    <completed_on>...</completed_on>
    <completed_by_id>...</completed_by_id>
    <project_id>...</project_id>
    <parent_id>...</parent_id>
    <milestone_id>...</milestone_id>
    <permissions>
      <can_edit>1</can_edit>
      <can_delete>1</can_delete>
      <can_change_visibility>1</can_change_visibility>
      <can_move>1</can_move>
      <can_copy>1</can_copy>
      <can_change_complete_status>1</can_change_complete_status>
    </permissions>
    <ticket_id>1</ticket_id>
  </ticket>
</tickets>

4. /projects/:project_id/tickets/add

Creates a new ticket for the project.

Method: POST.

Request example:

submitted = submitted
ticket[name] = This is summary

Response:

<ticket>
  <id>19</id>
  <type>
    <![CDATA[Ticket]]>
  </type>
  <name>
    <![CDATA[This is summary]]>
  </name>
  <body>...</body>
  <state>...</state>
  <visibility>...</visibility>
  <created_on>...</created_on>
  <created_by_id>...</created_by_id>
  <updated_on>...</updated_on>
  <updated_by_id>...</updated_by_id>
  <version>...</version>
  <permalink>...</permalink>
  <priority>...</priority>
  <due_on>...</due_on>
  <completed_on>...</completed_on>
  <completed_by_id>...</completed_by_id>
  <project_id>...</project_id>
  <parent_id>...</parent_id>
  <milestone_id>...</milestone_id>
  <permissions>
    <can_edit>1</can_edit>
    <can_delete>1</can_delete>
    <can_change_visibility>1</can_change_visibility>
    <can_move>1</can_move>
    <can_copy>1</can_copy>
    <can_change_complete_status>1</can_change_complete_status>
  </permissions>
  <ticket_id>2</ticket_id>
</ticket>

5. /projects/:project_id/tickets/:ticket_id

Displays ticket details.

Method: GET

Note

When you are making a request, please use the ticket ID for that particular project, not the project object ID.

<ticket>
  <id>9</id>
  <type>
    <![CDATA[Ticket]]>
  </type>
  <name>
    <![CDATA[My ticket]]>
  </name>
  <body>...</body>
  <state>...</state>
  <visibility>...</visibility>
  <created_on>...</created_on>
  <created_by_id>...</created_by_id>
  <updated_on>...</updated_on>
  <updated_by_id>...</updated_by_id>
  <version>...</version>
  <permalink>...</permalink>
  <priority>...</priority>
  <due_on>...</due_on>
  <completed_on>...</completed_on>
  <completed_by_id>...</completed_by_id>
  <project_id>...</project_id>
  <parent_id>...</parent_id>
  <milestone_id>...</milestone_id>
  <comments>
    ...
  </comments>
  <tasks>
    ...
  </tasks>
  <attachments>
    ...
  </attachments>
  <assignees>
    ...
  </assignees>
  <permissions>
    <can_edit>1</can_edit>
    <can_delete>1</can_delete>
    <can_change_visibility>1</can_change_visibility>
    <can_move>1</can_move>
    <can_copy>1</can_copy>
    <can_change_complete_status>1</can_change_complete_status>
  </permissions>
  <ticket_id>1</ticket_id>
</ticket>

6. /projects/:project_id/tickets/:ticket_id/edit

Updates properties of the existing ticket.

Method: POST.

Note

When you are making a request, please use the ticket ID for that particular project, not the project object ID.

Reqest example:

submitted = submitted
ticket[name] = Updated summary

Response:

<ticket>
  <id>9</id>
  <type>
    <![CDATA[Ticket]]>
  </type>
  <name>
    <![CDATA[Updated summary]]>
  </name>
  <body>...</body>
  <state>...</state>
  <visibility>...</visibility>
  <created_on>...</created_on>
  <created_by_id>...</created_by_id>
  <updated_on>...</updated_on>
  <updated_by_id>...</updated_by_id>
  <version>...</version>
  <permalink>
    <![CDATA[http://localhost/corporate_12/public/index.php?path_info=projects%2F1%2Ftickets%2F1]]>
  </permalink>
  <priority>...</priority>
  <due_on>...</due_on>
  <completed_on>...</completed_on>
  <completed_by_id>...</completed_by_id>
  <project_id>...</project_id>
  <parent_id>...</parent_id>
  <milestone_id>...</milestone_id>
  <permissions>
    <can_edit>1</can_edit>
    <can_delete>1</can_delete>
    <can_change_visibility>1</can_change_visibility>
    <can_move>1</can_move>
    <can_copy>1</can_copy>
    <can_change_complete_status>1</can_change_complete_status>
  </permissions>
  <ticket_id>1</ticket_id>
</ticket>

Working with Time

1. Time Fields

  1. body (text) - Full description;
  2. user_id (integer) - ID of the user whose time is logged. A value for this field is required when a time record is added;
  3. value (float) - Number of hours logged. Two formats are allowed: 5:30 (Five hours and 30 minutes) and 5.5. (five and a half hours). Value of this field is required when a time record is added;
  4. record_date (date) - Date when the time was spent. A value for this field is required when the time record is added;
  5. billable_status (integer) - Represents a record's status. This field was added in activeCollab 1.1.5 to replace the is_billable / is_billed field combination. There are four possible values:
    • 0 - not billable,
    • 1 - billable,
    • 2 - billable and pending payment,
    • 3 - billed;
  6. parent_id (integer) - ID of the parent object (task or a ticket).
Legacy fields

In activeCollab 1.1.5 is_billable and is_billed fields were replaced with a billable_status field. These two fields are still available for compatibility reasons:

  1. is_billable (boolean) - defines if the record billable or not.
  2. is_billed (boolean) - defines if the time has already been billed or not (ignored if is_billable is set to FALSE)

2. /projects/:project_id/time

This command displays all the time records for a given project.

Method: GET

<time_records>
  <time_record>
    <id>20</id>
    <type>
      <![CDATA[TimeRecord]]>
    </type>
    <name>
      <![CDATA[3.75 hours]]>
    </name>
    <body>...</body>
    <state>...</state>
    <visibility>...</visibility>
    <created_on>...</created_on>
    <created_by_id>...</created_by_id>
    <updated_on>...</updated_on>
    <updated_by_id>...</updated_by_id>
    <version>...</version>
    <permalink>...</permalink>
    <project_id>...</project_id>
    <parent_id>...</parent_id>
    <milestone_id>...</milestone_id>
    <permissions>
      <can_edit>1</can_edit>
      <can_delete>1</can_delete>
      <can_change_visibility>1</can_change_visibility>
      <can_move>0</can_move>
      <can_copy>0</can_copy>
    </permissions>
    <billable_status>0</billable_status>
    <value>3.75</value>
    <record_date>2008-05-01</record_date>
    <is_billable>0</is_billable>
    <is_billed>0</is_billed>
    <user_id>1</user_id>
  </time_record>
</time_records>

3. /projects/:project_id/time/add

Adds a new time record to the time log in a defined project.

Method: POST

Request example:

submitted = submitted
time[user_id] = 1
time[value] = 3:30
time[record_date] = 2008-05-01

Response:

<time_record>
  <id>20</id>
  <type>
    <![CDATA[TimeRecord]]>
  </type>
  <name>
    <![CDATA[3.5 hours]]>
  </name>
  <body>...</body>
  <state>...</state>
  <visibility>...</visibility>
  <created_on>...</created_on>
  <created_by_id>...</created_by_id>
  <updated_on>...</updated_on>
  <updated_by_id>...</updated_by_id>
  <version>...</version>
  <permalink>...</permalink>
  <project_id>1</project_id>
  <parent_id>...</parent_id>
  <milestone_id>...</milestone_id>
  <permissions>
    <can_edit>1</can_edit>
    <can_delete>1</can_delete>
    <can_change_visibility>1</can_change_visibility>
    <can_move>0</can_move>
    <can_copy>0</can_copy>
  </permissions>
  <billable_status>0</billable_status>
  <value>3.5</value>
  <record_date>2008-05-01</record_date>
  <is_billable>...</is_billable>
  <is_billed>...</is_billed>
  <user_id>1</user_id>
</time_record>

4. /projects/:project_id/time/:record_id

Displays record details.

Method: GET

Example response:

<time_record>
  <id>20</id>
  <type>
    <![CDATA[TimeRecord]]>
  </type>
  <name>
    <![CDATA[3.5 hours]]>
  </name>
  <body>...</body>
  <state>...</state>
  <visibility>...</visibility>
  <created_on>...</created_on>
  <created_by_id>...</created_by_id>
  <updated_on>...</updated_on>
  <updated_by_id>...</updated_by_id>
  <version>...</version>
  <permalink>...</permalink>
  <project_id>...</project_id>
  <parent_id>...</parent_id>
  <milestone_id>...</milestone_id>
  <permissions>
    <can_edit>1</can_edit>
    <can_delete>1</can_delete>
    <can_change_visibility>1</can_change_visibility>
    <can_move>0</can_move>
    <can_copy>0</can_copy>
  </permissions>
  <billable_status>0</billable_status>
  <value>3.5</value>
  <record_date>2008-05-01</record_date>
  <is_billable>0</is_billable>
  <is_billed>0</is_billed>
  <user_id>1</user_id>
</time_record>

5. /projects/:project_id/time/:record_id/edit

Updates the time record properties.

Method: POST

Request example:

submitted = submitted
time[value] = 3:45

Response:

<time_record>
  <id>20</id>
  <type>
    <![CDATA[TimeRecord]]>
  </type>
  <name>
    <![CDATA[3.75 hours]]>
  </name>
  <body>...</body>
  <state>...</state>
  <visibility>...</visibility>
  <created_on>...</created_on>
  <created_by_id>...</created_by_id>
  <updated_on>...</updated_on>
  <updated_by_id>...</updated_by_id>
  <version>...</version>
  <permalink>...</permalink>
  <project_id>...</project_id>
  <parent_id>...</parent_id>
  <milestone_id>...</milestone_id>
  <permissions>
    <can_edit>1</can_edit>
    <can_delete>1</can_delete>
    <can_change_visibility>1</can_change_visibility>
    <can_move>0</can_move>
    <can_copy>0</can_copy>
  </permissions>
  <billable_status>...</billable_status>
  <value>3.75</value>
  <record_date>2008-05-01</record_date>
  <is_billable>0</is_billable>
  <is_billed>0</is_billed>
  <user_id>1</user_id>
</time_record>

Working with Pages

1. Page Fields

  1. name (string) - Page title. The value of this field is required when page is created;
  2. body (text) - Page body. The value of this field is required when page is created;
  3. tags (string) - List of comma-separated tags;
  4. visibility (integer) - Object visibility. 0 is private and 1 is normal visibility;
  5. milestone_id (integer) - ID of the parent milestone;
  6. parent_id (integer) - ID of the parent object (category, ticket (for tasks) and so on). The value of this field is required when a page is created.

2. /projects/:project_id/pages

This command lists all page categories in a given project.

Method: GET

<categories>
  <category>
    <id>3</id>
    <type>
      <![CDATA[Category]]>
    </type>
    <name>
      <![CDATA[General]]>
    </name>
    <body>...</body>
    <state>...</state>
    <visibility>...</visibility>
    <created_on>...</created_on>
    <created_by_id>...</created_by_id>
    <updated_on>...</updated_on>
    <updated_by_id>...</updated_by_id>
    <version>1</version>
    <permalink>...</permalink>
    <project_id>...</project_id>
    <parent_id>...</parent_id>
    <milestone_id>...</milestone_id>
    <permissions>
      <can_edit>1</can_edit>
      <can_delete>1</can_delete>
      <can_change_visibility>1</can_change_visibility>
      <can_move>0</can_move>
      <can_copy>0</can_copy>
    </permissions>
  </category>
</categories>

3. /projects/:project_id/pages/add

Creates a new page.

Method: POST.

Request example:

submitted = submitted
page[name] = New Page
page[body] = Page content
page[parent_id] = 12

Response:

<page>
  <id>21</id>
  <type>
    <![CDATA[Page]]>
  </type>
  <name>
    <![CDATA[New Page]]>
  </name>
  <body>
    <![CDATA[Page content]]>
  </body>
  <state>...</state>
  <visibility>...</visibility>
  <created_on>...</created_on>
  <created_by_id>...</created_by_id>
  <updated_on>...</updated_on>
  <updated_by_id>...</updated_by_id>
  <version>...</version>
  <permalink>...</permalink>
  <project_id>...</project_id>
  <parent_id>3</parent_id>
  <milestone_id>...</milestone_id>
  <permissions>
    <can_edit>1</can_edit>
    <can_delete>1</can_delete>
    <can_change_visibility>1</can_change_visibility>
    <can_move>0</can_move>
    <can_copy>0</can_copy>
  </permissions>
  <revision_num>1</revision_num>
</page>

4. /projects/:project_id/pages/:page_id

Displays page details with a list of all subpages and revisions.

Method: GET

Example response:

<page>
  <id>21</id>
  <type>
    <![CDATA[Page]]>
  </type>
  <name>
    <![CDATA[New Page]]>
  </name>
  <body>
    <![CDATA[<p>Page content. Made a couple of changes to make a new version</p>]]>
  </body>
  <state>...</state>
  <visibility>...</visibility>
  <created_on>...</created_on>
  <created_by_id>...</created_by_id>
  <updated_on>...</updated_on>
  <updated_by_id>...</updated_by_id>
  <version>...</version>
  <permalink>...</permalink>
  <project_id>...</project_id>
  <parent_id>...</parent_id>
  <milestone_id>...</milestone_id>
  <comments>
    ...
  </comments>
  <tasks>
    ...
  </tasks>
  <attachments>
    ...
  </attachments>
  <permissions>
    <can_edit>1</can_edit>
    <can_delete>1</can_delete>
    <can_change_visibility>1</can_change_visibility>
    <can_move>0</can_move>
    <can_copy>0</can_copy>
  </permissions>
  <revision_num>2</revision_num>
  <subpages>
    ...
  </subpages>
  <revisions>
    ...
  </revisions>
</page>

5. /projects/:project_id/pages/:page_id/edit

Updates the properties and content of the page.

By setting is_minor_revision to value 1 when updating the page, the system will consider changes as minor ones and will not create a new page revision. Email notifications will not be sent to subscribers in this case.

Method: POST

Request example:

submitted = submitted
page[name] = New Name
page[is_minor_revision] = 1

Response:

<page>
  <id>21</id>
  <type>
    <![CDATA[Page]]>
  </type>
  <name>
    <![CDATA[New Name]]>
  </name>
  <body>
    <![CDATA[<p>Page content. Made a couple of changes to get a new version</p>]]>
  </body>
  <state>...</state>
  <visibility>...</visibility>
  <created_on>...</created_on>
  <created_by_id>...</created_by_id>
  <updated_on>...</updated_on>
  <updated_by_id>...</updated_by_id>
  <version>...</version>
  <permalink>...</permalink>
  <project_id>...</project_id>
  <parent_id>...</parent_id>
  <milestone_id>...</milestone_id>
  <permissions>
    <can_edit>1</can_edit>
    <can_delete>1</can_delete>
    <can_change_visibility>1</can_change_visibility>
    <can_move>0</can_move>
    <can_copy>0</can_copy>
  </permissions>
  <revision_num>3</revision_num>
</page>

6. /projects/:project_id/pages/:page_id/archive

This command will mark the selected page as archived. If successful, the system will return the updated page details.

Method: POST.

7. /projects/:project_id/pages/:page_id/unarchive

Marks a selected page as unarchived. If successful, the system will return updated page details and that page will no longer be in the Archive.

Method: POST.

Working with Status Messages

The Status module was introduced in activeCollab 1.1 and API support for this module was included in activeCollab's API a couple of months later with the release of activeCollab 1.1.4. Therefore, all commands described in this section are not available in versions of activeCollab before version 1.1.4.

1. /status

Lists the 50 most recent status messages. If you pass the user_id through the query string, you will get filtered messages posted by that specific user only.

Method: GET

Example response:

<messages>
  <message>
    <message>
      <![CDATA[It works great]]>
    </message>
    <created_on>2009-03-24 19:07:09</created_on>
    <created_by>
      <id>15</id>
      <name>
        <![CDATA[ilija.studen@gmail.com]]>
      </name>
    </created_by>
  </message>
</messages>

2. /status/add

This command will submit a new status message.

Method: POST

Example request:

submitted = submitted
status[message] = I did something interesting

Response:

<message>
  <message>
    <![CDATA[I did something interesting]]>
  </message>
  <created_on>2009-03-24 19:19:37</created_on>
  <created_by>
    <id>15</id>
    <name>
      <![CDATA[john.doe@gmail.com]]>
    </name>
  </created_by>
</message>

Working with Comments

1. Comment Fields

  1. body (string) - The comment body. A value for this field is required when a new comment is created.

2. /projects/:project_id/comments/add&parent_id=:parent_id

This command will post a new comment on the specified object in the given project.

Method: POST.

Request example:

submitted = submitted
comment[body] = My comment!

Response:

<comment>
  <id>23</id>
  <type>
    <![CDATA[Comment]]>
  </type>
  <name>
    <![CDATA[Comment on One ticket]]>
  </name>
  <body>
    <![CDATA[My comment!]]>
  </body>
  <state>...</state>
  <visibility>...</visibility>
  <created_on>...</created_on>
  <created_by_id>...</created_by_id>
  <updated_on>...</updated_on>
  <updated_by_id>...</updated_by_id>
  <version>...</version>
  <permalink>...</permalink>
  <project_id>...</project_id>
  <parent_id>...</parent_id>
  <milestone_id>...</milestone_id>
  <permissions>
    <can_edit>1</can_edit>
    <can_delete>1</can_delete>
    <can_change_visibility>1</can_change_visibility>
    <can_move>0</can_move>
    <can_copy>0</can_copy>
  </permissions>
</comment>

3. /projects/:project_id/comments/:comment_id

Displays comment details.

Method: GET

<comment>
  <id>23</id>
  <type>
    <![CDATA[Comment]]>
  </type>
  <name>
    <![CDATA[Comment on One ticket]]>
  </name>
  <body>
    <![CDATA[My comment!]]>
  </body>
  <state>...</state>
  <visibility>...</visibility>
  <created_on>...</created_on>
  <created_by_id>...</created_by_id>
  <updated_on>...</updated_on>
  <updated_by_id>...</updated_by_id>
  <version>...</version>
  <permalink>...</permalink>
  <project_id>2</project_id>
  <parent_id>10</parent_id>
  <milestone_id>
  </milestone_id>
  <permissions>
    <can_edit>1</can_edit>
    <can_delete>1</can_delete>
    <can_change_visibility>1</can_change_visibility>
    <can_move>0</can_move>
    <can_copy>0</can_copy>
  </permissions>
</comment>

4. /projects/:project_id/comments/:comment_id/edit

Updates an existing comment.

Method: POST

Request example:

submitted = submitted
comment[body] = Updating my comment!

Response:

<comment>
  <id>23</id>
  <type>
    <![CDATA[Comment]]>
  </type>
  <name>
    <![CDATA[Comment on One ticket]]>
  </name>
  <body>
    <![CDATA[Updating my comment!]]>
  </body>
  <state>...</state>
  <visibility>...</visibility>
  <created_on>...</created_on>
  <created_by_id>...</created_by_id>
  <updated_on>...</updated_on>
  <updated_by_id>...</updated_by_id>
  <version>...</version>
  <permalink>...</permalink>
  <project_id>...</project_id>
  <parent_id>...</parent_id>
  <milestone_id>...</milestone_id>
  <permissions>
    <can_edit>1</can_edit>
    <can_delete>1</can_delete>
    <can_change_visibility>1</can_change_visibility>
    <can_move>0</can_move>
    <can_copy>0</can_copy>
  </permissions>
</comment>

Working with Subtasks

1. Task Fields

  1. body (text) - The task summary. A value for this field is required when a new task is added;
  2. priority (integer) - Priority can have five integer values ranging from -2 (lowest) to 2 (highest). 0 is normal;
  3. due_on (date) - When the task is due;
  4. assignees (array) - An array of people assigned to the object. The first element of the array is a list of assignees (as an array). The second parameter is the ID of the person responsible for the task (the ID must also be in the first list).

2. /projects/:project_id/tasks/add&parent_id=:parent_id

This command will create a new subtask and attach it to the parent object.

Method: POST

Request example:

submitted = submitted
task[body] = Go shopping
task[priority] = -2

Response:

<task>
  <id>25</id>
  <type>
    <![CDATA[Task]]>
  </type>
  <name>
    <![CDATA[Go shopping]]>
  </name>
  <body>
    <![CDATA[Go shopping]]>
  </body>
  <state>...</state>
  <visibility>...</visibility>
  <created_on>...</created_on>
  <created_by_id>...</created_by_id>
  <updated_on>...</updated_on>
  <updated_by_id>...</updated_by_id>
  <version>...</version>
  <permalink>...</permalink>
  <priority>-2</priority>
  <due_on>...</due_on>
  <completed_on>...</completed_on>
  <completed_by_id>...</completed_by_id>
  <project_id>...</project_id>
  <parent_id>...</parent_id>
  <milestone_id>...</milestone_id>
  <permissions>
    <can_edit>1</can_edit>
    <can_delete>1</can_delete>
    <can_change_visibility>1</can_change_visibility>
    <can_move>0</can_move>
    <can_copy>0</can_copy>
    <can_change_complete_status>1</can_change_complete_status>
  </permissions>
</task>

3. /projects/:project_id/tasks/:task_id

Displays task details.

Method: GET.

Example response:

<task>
  <id>25</id>
  <type>
    <![CDATA[Task]]>
  </type>
  <name>
    <![CDATA[Go shopping]]>
  </name>
  <body>
    <![CDATA[Go shopping]]>
  </body>
  <state>...</state>
  <visibility>...</visibility>
  <created_on>...</created_on>
  <created_by_id>...</created_by_id>
  <updated_on>...</updated_on>
  <updated_by_id>...</updated_by_id>
  <version>...</version>
  <permalink>...</permalink>
  <priority>-2</priority>
  <due_on>...</due_on>
  <completed_on>...</completed_on>
  <completed_by_id>...</completed_by_id>
  <project_id>...</project_id>
  <parent_id>...</parent_id>
  <milestone_id>...</milestone_id>
  <permissions>
    <can_edit>1</can_edit>
    <can_delete>1</can_delete>
    <can_change_visibility>1</can_change_visibility>
    <can_move>0</can_move>
    <can_copy>0</can_copy>
    <can_change_complete_status>1</can_change_complete_status>
  </permissions>
</task>

4. /projects/:project_id/tasks/:task_id/edit

Updates task details.

Method: POST

Request example:

submitted = submitted
task[priority] = 0

Response:

<task>
  <id>25</id>
  <type>
    <![CDATA[Task]]>
  </type>
  <name>
    <![CDATA[Go shopping]]>
  </name>
  <body>
    <![CDATA[Go shopping]]>
  </body>
  <state>...</state>
  <visibility>...</visibility>
  <created_on>...</created_on>
  <created_by_id>...</created_by_id>
  <updated_on>...</updated_on>
  <updated_by_id>...</updated_by_id>
  <version>...</version>
  <permalink>...</permalink>
  <priority>...</priority>
  <due_on>...</due_on>
  <completed_on>...</completed_on>
  <completed_by_id>...</completed_by_id>
  <project_id>...</project_id>
  <parent_id>...</parent_id>
  <milestone_id>...</milestone_id>
  <permissions>
    <can_edit>1</can_edit>
    <can_delete>1</can_delete>
    <can_change_visibility>1</can_change_visibility>
    <can_move>0</can_move>
    <can_copy>0</can_copy>
    <can_change_complete_status>1</can_change_complete_status>
  </permissions>
</task>

Working with Attachments

1. /projects/:project_id/objects/:object_id/attachments

This command will lists all files attached to a specific object in the given project.

Method: GET or POST

Example response for GET request:

<attachments>
  <attachment>
    <id>...</id>
    <name>...</name>
    <mime_type>...</mime_type>
    <size>...</size>
    <created_on>...</created_on>
    <created_by_id>...</created_by_id>
    <permalink>...</permalink>
  </attachment>
</attachments>

If a POST request is submitted, the system will attach all uploaded files to the defined object. When this operation is complete, details of the last attachment will be returned.

Common Project Object Operations

1. /projects/:project_id/objects/:object_id/complete

Marks a specific object as completed. If successful, the system will return all of the object's details.

Method: POST

The types of project objects that can marked as completed are:

  1. Milestones;
  2. Checklists;
  3. Tickets;
  4. Subtasks.

2. /projects/:project_id/objects/:object_id/open

Marks specific object as open. If successful, the system will return the object's details.

Method: POST

Types of project objects that can be completed and re-opened:

  1. Milestones;
  2. Checklists;
  3. Tickets;
  4. Subtasks.

3. /projects/:project_id/objects/:object_id/star

Marks a specific project object as starred. if successful, the system will return the object's details.

Method: POST

Any project object can be starred.

4. /projects/:project_id/objects/:object_id/unstar

This command will mark a specific project object as not starred. If successful, the system will return the object's details.

Method: POST

Any project object can be un-starred.

5. /projects/:project_id/objects/:object_id/subscribe

Subscribes users to a specific object. If successful, the system will return the object's details.

Method: POST

Users can be subscribed to following project object types:

  1. Milestones;
  2. Discussions;
  3. Checklists;
  4. Files;
  5. Pages;
  6. Tickets;
  7. Subtasks.

6. /projects/:project_id/objects/:object_id/unsubscribe

Unsubscribes users from the specific project object. If successful, the system returns the object's details.

Method: POST

Users can be unsubscribed from the following project object types (if they are already subscribed to them):

  1. Milestones;
  2. Discussions;
  3. Checklists;
  4. Files;
  5. Pages;
  6. Tickets;
  7. Subtasks.

7. /projects/:project_id/objects/:object_id/move-to-trash

Moves the specific project object to Trash. If successful, the system will return the object's details.

Method: POST

Any project object type can be moved to Trash.

8. /projects/:project_id/objects/:object_id/restore-from-trash

Restores an object from the Trash. The system will return the object's details if the command is completed successfully.

Method: POST

Any project object type can be restored from the Trash.

API Wrapper

The activeCollab API Wrapper is a set of PHP classes that makes using the activeCollab API much easier, by providing an object oriented interface. Instead of making HTTP requests from your code and handling responses, the wrapper layer lets you call a simple set of methods and work with the results in a form of PHP native types, such as arrays, objects, boolean values etc.

The activeCollab API Wrapper is free software released under LGPL licenses, and you are welcome to use it in your commercial projects, in-house applications, open source projects or any other type of application that you are working on, completely free of charge. Check the LICENSE.txt file, available in the activeCollab API Wrapper folder that you can download here, for more details.

Getting Started

Using the activeCollab API wrapper in your code should be done in three steps:

<?php
  
  // Include activeCollab API wrapper
  require_once '/lib/include.php';
  
  // Authenticate
  ActiveCollab::setAPIUrl('http://localhost/corporate/public/api.php');
  ActiveCollab::setKey('4-EUASVXm3VgJXhUfIsN1uGRASO1i0gIiLrIsbuF5e');
  
  // List projects
  print '<pre>';
  
  $projects = ActiveCollab::listProjects();
  
  if($projects) {
    foreach($projects as $project) {
      print 'Project #' . $project->getId() . ': ' . htmlspecialchars($project->getName()) . '<br />';
    } // foreach
  } // if
  
  print '</pre>';

?>

To find your token key and API URL, go to API Settings page of your user profile:

After meeting those requirements you can create objects and call methods in order to read and manipulate activeCollab data.

Some of these methods can throw an exception if they receive invalid parameters. In the following example, we'll use a try/catch block to handle any error that may happen (group with ID 1 does not exist; authentication problems; insufficient permissions etc):

try {
  $group = ActiveCollab::findProjectGroupById(1);
} catch (Exception $e) {
  echo $e->getMessage();
  echo $e->getFile();
  echo $e->getLine();
}

System Information

This chapter describes the methods that can be used to get information about the activeCollab installation you are communicating with. These are contained in class ActiveCollab. Methods can be called directly (as static methods) or through an object.

1. getVersion

Description:

array getVersion( void ) - Return API Version

Return Value:

Array containing the information about API

2. listProjects

Description:

array listProjects( void ) - List all Projects

Return Value:

Array containing the objects of Projects

3. listProjectsGroups

Description:

array listProjectsGroups( void ) - List all available project groups

Return Value:

Array containing the objects of Project groups

4. listTicketCategoriesByProjectId

Description:

array listTicketCategoriesByProjectId( int $project_id ) - List ticket categories in one project

Parameters:

project_id - id value of the project

Return Value:

Array containing the objects of Ticket categories

5. listDiscussionCategoriesByProjectId

Description:

array listDiscussionCategoriesByProjectId( int $project_id ) - List discussion categories in one project

Parameters:

project_id - id value of the project

Return Value:

Array containing the objects of Discussion categories

6. listFileCategoriesByProjectId

Description:

array listFileCategoriesByProjectId( int $project_id ) - List file categories in one project

Parameters:

project_id - id value of the project

Return Value:

Array containing the objects of File categories

7. listPageCategoriesByProjectId

Description:

array listPageCategoriesByProjectId( int $project_id ) - List page categories in one project

Parameters:

project_id - id value of the project

Return Value:

Array containing the objects of Page categories

8. listTicketsByCategoryId

Description:

array listTicketsByCategoryId( int $project_id, int $category_id ) - List all tickets for a specific project and category

Parameters:

project_id - id value of the project category_id - id value of the category

Return Value:

Array of ActiveCollabTicket objects

9. listFilesByCategoryId

Description:

array listFilesByCategoryId( int $project_id, int $category_id ) - List all files for a specific project and category

Parameters:

project_id - id value of the project category_id - id value of the category

Return Value:

Array of ActiveCollabFile objects

10. listPagesByCategoryId

Description:

array listPagesByCategoryId( int $project_id, int $category_id ) - List all pages for a specific project and category

Parameters:

project_id - id value of the project category_id - id value of the category

Return Value:

Array of ActiveCollabPage objects

11. listDiscussionsByCategoryId

Description:

array listDiscussionsByCategoryId( int $project_id, int $category_id ) - List all discussions for a specific project and category

Parameters:

project_id - id value of the project category_id - id value of the category

Return Value:

Array of ActiveCollabDiscussion objects

12. listSystemRoles

Description:

array listSystemRoles( void ) - List all system roles

Return Value:

Array containing the system roles

13. listProjectRoles

Description:

array listProjectRoles( void ) - List all project roles

Return Value:

Array containing the project roles

14. findRoleDetailsById

Description:

array findRoleDetailsById( int $role_id ) - List role details

Parameters:

role_id - id of the role

Return Value:

Array containing the information about the role

15. listCompanies

Description:

array listCompanies( void ) - List all companies

Return Value:

Array of ActiveCollabCompany objects

16. listStatusMessages

Description:

array listStatusMessages( void ) - List all status messages

Return Value:

Array of ActiveCollabStatusMessage objects

17. listStatusMessagesByUserId

Description:

array listStatusMessagesByUserId( int $user_id ) - List all status messages created by specific user

Parameters:

user_id - id of a user

Return Value:

Array of ActiveCollabStatusMessage objects

18. listPeopleByProjectId

Description:

array listPeopleByProjectId( int $project_id ) - List all people involved with a project and their permissions

Parameters:

project_id - id of a project

Return Value:

Array of ActiveCollabUser objects

19. listTicketsByProjectId

Description:

array listTicketsByProjectId( int $project_id ) - List all tickets for a specific project

Parameters:

project_id - id of a project

Return Value:

Array of ActiveCollabTicket objects

20. listArchivedTicketsByProjectId

Description:

array listArchivedTicketsByProjectId( int $project_id ) - List all archived tickets for a specific project

Parameters:

project_id - id of a project

Return Value:

Array of ActiveCollabTicket objects

21. listFilesByProjectId

Description:

array listFilesByProjectId( int $project_id ) - List all files for a specific project

Parameters:

project_id - id of a project

Return Value:

Array of ActiveCollabFile objects

22. listDiscussionsByProjectId

Description:

array listDiscussionsByProjectId( int $project_id ) - List all discussions for a specific project

Parameters:

project_id - id of a project

Return Value:

Array of ActiveCollabDiscussion objects

23. listMilestonesByProjectId

Description:

array listMilestonesByProjectId( int $project_id ) - List all milestones for a specific project

Parameters:

project_id - id of a project

Return Value:

Array of ActiveCollabMilestone objects

24. listChecklistsByProjectId

Description:

array listChecklistsByProjectId( int $project_id ) - List all checklists for a specific project

Parameters:

project_id - id of a project

Return Value:

Array of ActiveCollabChecklist objects

25. listArchivedChecklistsByProjectId

Description:

array listArchivedChecklistsByProjectId( int $project_id ) - List all archived checklists for a specific project

Parameters:

project_id - id of a project

Return Value:

Array of ActiveCollabChecklists objects

26. listTimeRecordsByProjectId

Description:

array listTimeRecordsByProjectId( int $project_id ) - List all time records for a specific project

Parameters:

project_id - id of a project

Return Value:

Array of ActiveCollabTime objects

Working With Companies

In this article we will describe the methods that can allow you to manage companies in your installation of activeCollab.

1. Fetching a company

object ActiveCollab::findCompanyById( int $company_id) - Fetches the ActiveCollabCompany object

Parameters:

company_id - id of a specific company

Return value: Object instance of ActiveCollabCompany

2. Creating a new company

object $company = new ActiveCollabCompany( void ) - Creates a new ActiveCollabCompany object

Variable value: Object instance of ActiveCollabCompany

3. Editing and saving a company

These methods are called out through a company object:

•   setName(string $name)  -  Sets the name of the company
•   setOfficeAddress(string $address) - Sets the address of the company 
•   setOfficePhone(string $phone) - Sets the phone of the company 
•   setOfficeFax(string $fax) - Sets the fax of the company 
•   setOfficeHomepage(string $homepage) - Sets the homepage of the company 
•   save(void) - Saves the company object into activeCollab
•   delete(void) - Deletes the company from activeCollab

Working With Users

These methods allow you to manage users in your activeCollab setup:

1. Fetching a user

object ActiveCollab::findUserById( int $user_id) - Fetches the ActiveCollabUser object

Parameters:

user_id - id of a specific user

Return value: Object instance of ActiveCollabUser;

ActiveCollabCompany company->getCompanyUsers(void) - Gets all users in the company

Return value: Array of object instances of ActiveCollabUser

2. Creating a new user

object $user = new ActiveCollabUser( int $company_id ) - Creates a new ActiveCollabUser object

Parameters: company_id - id of a company in which the user is going to be created

Variable value: Object instance of ActiveCollabUser

3. Editing and saving a user

These methods are called out through an user object.

•   setFirstName(string $first_name)  -  Sets the first name of the user
•   setLastName(string $last_name) - Sets the last name of the user 
•   setEmail(string $email) - Sets the email of the user
•   setPassword(string $password) - Sets the password of the user
•   setPasswordA(string $password_confirm) - Sets the confirmation password of the user
•   setRoleId(int $role) - Sets the role of the user
•   setAvatarURL(string $avatar) - Sets the URL of the avatar of the user
•   save(void) - Saves the user object into activeCollab
•   delete(void) - Deletes the user from activeCollab

Working With Projects

This section covers methods used for managing projects in activeCollab.

1. Fetching a project

object ActiveCollab::findProjectById( int $project_id) - Fetches an ActiveCollabProject object

Parameters:

project_id - id of a specific project

Return value: Object instance of ActiveCollabProject

2. Creating a new project

object $project = new ActiveCollabProject(void) - Creates a new ActiveCollabProject object

Variable value: Object instance of ActiveCollabProject

3. Editing and saving a project

These methods are called out through an project object.

•   setCompanyId(int $company_id)  -  Sets the id of the company of the project
•   setStartsOn(string $starts_on)  -  Sets the start date of the project
•   setGroupID(int $group_id)  -  Sets the id of the group of the project
•   setName(string $name)  -  Sets the name of the project
•   setOverview(string $overview)  -  Sets the overview of the project
•   setLeaderId(int $user)  -  Sets the id of the leader user of the project
•   save(void) - Saves the project object into activeCollab
•   delete(void) - Deletes the project from activeCollab
•   changeStatus(int $status) - Sets the status of the project; the status parameter can be a combination of the following constants: ACTIVECOLLAB_PROJECT_STATUS_ACTIVE, ACTIVECOLLAB_PROJECT_STATUS_PAUSED,ACTIVECOLLAB_PROJECT_STATUS_COMPLETED,ACTIVECOLLAB_PROJECT_STATUS_CANCELED
•   getUserLoggedUserPermission(void) - gets permission of the logged user
•   getIconUrl(void) - gets the URL of the project icon
•   getUserTasks(void) - list all the tasks of the user (returns array of ticket objects)

4. People on project

These methods are used for adding users and their project roles to the project.

Example code:

    $project = ActiveCollab::findProjectById(5);
    $permission = array();
    $permission['milestone'] = ACTIVECOLLAB_PERMISSION_NO_ACCESS;
    $permission['discussion'] = ACTIVECOLLAB_PERMISSION_HAS_ACCESS;
    $permission['file'] = ACTIVECOLLAB_PERMISSION_NO_ACCESS;
    $permission['page'] = ACTIVECOLLAB_PERMISSION_HAS_ACCESS;
    $permission['ticket'] = ACTIVECOLLAB_PERMISSION_CAN_CREATE;
    $permission['checklist'] = ACTIVECOLLAB_PERMISSION_CAN_CREATE;
    $permission['timerecord'] = ACTIVECOLLAB_PERMISSION_CAN_MANAGE;
    $project->addUsers(array(5),$permission);
    $project->changeUserPermission(5,$permission);
    $project->removeUserFromProject(5);

Available permission constants:

•   ACTIVECOLLAB_PERMISSION_NO_ACCESS
•   ACTIVECOLLAB_PERMISSION_HAS_ACCESS
•   ACTIVECOLLAB_PERMISSION_CAN_CREATE
•   ACTIVECOLLAB_PERMISSION_CAN_MANAGE

5. Working with project group

These methods are used for managing project groups.

    $group = new ActiveCollabProjectGroup();
    $group = ActiveCollab::findProjectGroupById(1);
    $group->setName('Gavric11');
    $group->save();
    $group->delete();

Working With Discussions

In this article we will talk about the methods used for manipulating Discussions in your activeCollab.

1. Fetching a discussion

object ActiveCollab::findDiscussionById(int $project_id, int $discussion_id) - Fetches an ActiveCollabDiscussion object

Parameters:

project_id - id of a project which the Discussion is in discussion_id - id of a specific discussion

Return value: Object instance of ActiveCollabDiscussion

2. Creating a new discussion

object $discussion = new ActiveCollabDiscussion(int $project_id) - Creates a new ActiveCollabDiscussion object

Parameters:

project_id - id of a project in which the discussion is going to be created

Variable value: Object instance of ActiveCollabDiscussion

3. Editing and saving a discussion

These methods are called out through an discussion object.

•   setCreatedByEmail(string $email)  -  Sets an email of the user who created this discussion
•   setCreatedByName(string $name)  -  Sets the name of the user who created this discussion
•   setName(string $name)  -  Sets the name of this discussion
•   setBody(string $body)  -  Sets the description of this discussion
•   setTags(array of string $tagArr) - Sets tags for this discussion
•   setVisibility(int $visibility) - Sets the visibility of this discussion; the visibility parameter can be a combination of the following constants: ACTIVECOLLAB_VISIBILITY_PRIVATE, ACTIVECOLLAB_VISIBILITY_NORMAL
•   setParentId(int $parent_id) - Sets the parent for this discussion
•   setMilestoneId(int $milestone_id) - Sets the milestone for this discussion
•   addAttachments(array of file $arr_files) - Adds array of files to a discussion
•   save(void) - Saves the discussion object into activeCollab

Working With Checklists

In this article we describe the methods used to manipulate Checklists in activeCollab.

1. Fetching a checklist

object ActiveCollab::findChecklistById(int $project_id, int $checklist_id) - Fetches an ActiveCollabChecklist object

Parameters:

project_id - id of the project where the checklist is located checklist_id - id of a specific checklist

Return value: Object instance of ActiveCollabChecklist

2. Creating a new checklist

object $checklist = new ActiveCollabChecklist(int $project_id) - Creates new ActiveCollabChecklist object

Parameters:

project_id - id of the project in which the checklist is going to be created

Variable value: Object instance of ActiveCollabChecklist

3. Editing and saving a checklist

These methods are called out through an checklist object.

•   setCreatedByEmail(string $email)  -  Sets an email of the user who created this checklist
•   setCreatedByName(string $name)  -  Sets the name of the user who created this checklist
•   setName(string $name)  -  Sets the name of this checklist
•   setBody(string $body)  -  Sets the description of this checklist
•   setTags(array of string $tagArr) - Sets tags for this checklist
•   setVisibility(int $visibility) - Sets the visibility of this checklist; the visibility parameter can be a combination of the following constants: ACTIVECOLLAB_VISIBILITY_PRIVATE, ACTIVECOLLAB_VISIBILITY_NORMAL
•   setMilestoneId(int $milestone_id) - Sets the milestone for this checklist
•   save(void) - Saves the checklist object into activeCollab

Working With Files

The following methods are used for managing Files within a project.

1. Fetching a file

object ActiveCollab::findFileById(int $project_id, int $file_id) - Fetches an ActiveCollabFile object

Parameters:

project_id - d of a project which the file is in file_id - id of a specific file

Return value: Object instance of ActiveCollabFile

2. Creating a new file

object $file = new ActiveCollabFile(int $project_id) - Creates new a ActiveCollabFile object

Parameters:

project_id - id of the project where the file is going to be created

Variable value: Object instance of ActiveCollabFile

3. Editing and saving a file

These methods are called out through an file object.

•   setCreatedByEmail(string $email)  -  Sets an email of the user who created this file
•   setCreatedByName(string $name)  -  Sets the name of the user who created this file
•   setName(string $name)  -  Sets the name of this file
•   setBody(string $body)  -  Sets the description of this file
•   setTags(array of string $tagArr) - Sets tags for this file
•   setVisibility(int $visibility) - Sets the visibility of this file; the visibility parameter can be a combination of the following constants: ACTIVECOLLAB_VISIBILITY_PRIVATE, ACTIVECOLLAB_VISIBILITY_NORMAL
•   setParentId(int $parent_id) - Sets the parent for this file
•   setMilestoneId(int $milestone_id) - Sets the milestone for this file
•   addFile(file $file) - Uploads an file and bounds it to a ActiveCollabFile object
•   getRevisions(void) - Returns revisions of this file
•   save(void) - Saves the file object into activeCollab

Working With Milestones

This article covers all Milestone-related methods in activeCollab.

1. Fetching a milestone

object ActiveCollab::findMilestoneById(int $project_id, int $milestone_id) - Fetches an ActiveCollabMilestone object

Parameters:

project_id - d of a Project which contains the Milestone milestone_id - id of a specific milestone

Return value: Object instance of ActiveCollabMilestone

2. Creating a new milestone

object $milestone = new ActiveCollabMilestone(int $project_id) - Creates new a ActiveCollabMilestone object

Parameters:

project_id - the id of the Project in which the Milestone will be created

Variable value: Object instance of ActiveCollabMilestone

3. Editing and saving a milestone

These methods are called out through an milestone object.

•   setCreatedByEmail(string $email)  -  Sets an email of the user who created this milestone
•   setCreatedByName(string $name)  -  Sets the name of the user who created this milestone
•   setName(string $name)  -  Sets the name of this milestone
•   setBody(string $body)  -  Sets the description of this milestone
•   setPriority(int $priority) - Sets the priority of this milestone; the priority parameter can be a combination of the following constants: ACTIVECOLLAB_PRIORITY_LOWEST, ACTIVECOLLAB_PRIORITY_LOW, ACTIVECOLLAB_PRIORITY_NORMAL, ACTIVECOLLAB_PRIORITY_HIGH, ACTIVECOLLAB_PRIORITY_HIGHEST
•   setTags(array of string $tagArr) - Sets tags for this milestone
•   setStartOn(timestamp $date) - Sets the date when the milestone is starting
•   setDueOn(timestamp $date) - Sets the date when the milestone is due
•   setAssignees(array of int $assignees, int $responsible_person) - Sets assignees and responsible person for this milestone
•   save(void) - Saves the milestone object into activeCollab

Working With Tickets

This article covers manipulating Tickets in your activeCollab setup using the API Wrapper.

1. Fetching a ticket

object ActiveCollab::findTicketById(int $project_id, int $ticket_id) - Fetches an ActiveCollabTicket object

Parameters:

project_id - id of the Project which contains the Ticket ticket_id - id of a specific Ticket

Return value: Object instance of ActiveCollabTicket

2. Creating a new ticket

object $ticket = new ActiveCollabTicket(int $project_id) - Creates a new ActiveCollabTicket object

Parameters:

project_id - id of the Project in which the Ticket will be created

Variable value: Object instance of ActiveCollabTicket

3. Editing and saving a ticket

These methods are called out through an ticket object.

•   setCreatedByEmail(string $email)  -  Sets an email of the user who created this ticket
•   setCreatedByName(string $name)  -  Sets the name of the user who created this ticket
•   setName(string $name)  -  Sets the name of this ticket
•   setBody(string $body)  -  Sets the description of this ticket
•   setPriority(int $priority) - Sets the priority of this ticket; the priority parameter can be a combination of the following constants: ACTIVECOLLAB_PRIORITY_LOWEST, ACTIVECOLLAB_PRIORITY_LOW, ACTIVECOLLAB_PRIORITY_NORMAL, ACTIVECOLLAB_PRIORITY_HIGH, ACTIVECOLLAB_PRIORITY_HIGHEST
•   setTags(array of string $tagArr) - Sets tags for this ticket
•   setVisibility(int $visibility) - Sets the visibility of this ticket; the visibility parameter can be a combination of the following constants: ACTIVECOLLAB_VISIBILITY_PRIVATE, ACTIVECOLLAB_VISIBILITY_NORMAL
•   setDueOn(timestamp $date) - Sets the date when the ticket is due
•   setParentId(int $parent_id) - Sets the parent for this ticket
•   setMilestoneId(int $milestone_id) - Sets the milestone for this ticket
•   setAssignees(array of int $assignees, int $responsible_person) - Sets assignees and responsible person for this ticket
•   addAttachments(array of file $arr_files) - Adds array of files to a ticket
•   save(void) - Saves the ticket object into activeCollab

Working With Time Tracking

These methods are used for managing Time Tracking in activeCollab.

1. Fetching a time track

object ActiveCollab::findTimeById(int $project_id, int $time_id) - Fetches an ActiveCollabTime object

Parameters:

project_id - d of the Project where the time record comes from time_id - id of a specific time record

Return value: Object instance of ActiveCollabTime

2. Creating a new time track

object $time = new ActiveCollabTime(int $project_id) - Creates a new ActiveCollabTime object

Parameters:

project_id - id of the Project in which the Time record is going to be created

Variable value: Object instance of ActiveCollabTime

3. Editing and saving a time

These methods are called out through an time object.

•   setCreatedByEmail(string $email)  -  Sets an email of the user who created this time
•   setCreatedByName(string $name)  -  Sets the name of the user who created this time
•   setBody(string $body)  -  Sets the description of this time
•   setUserId(int $user_id) - Id of user for whom time is created
•   setBillableStatus(int $status) - Sets the billable status of this time; the status parameter can be a combination of the following constants: ACTIVECOLLAB_BILLABLE_STATUS_NOT_BILLABLE, ACTIVECOLLAB_BILLABLE_STATUS_BILLABLE, ACTIVECOLLAB_BILLABLE_STATUS_BILLABLE_AND_PENDING, ACTIVECOLLAB_BILLABLE_STATUS_BILLED
•   setValue(float $value) - Sets value for this time
•   setRecordDate(timestamp $date) - Sets the date when the time record is created
•   setParentId(int $parent_id) - Sets the parent for this time
•   save(void) - Saves the time object into activeCollab

Working With Pages

This article lists the methods for manipulating Pages in activeCollab.

1. Fetching a page

object ActiveCollab::findPageById(int $project_id, int $page_id) - Fetches an ActiveCollabPage object

Parameters:

project_id - id of the Project which contains the Page page_id - id of a specific Page

Return value: Object instance of ActiveCollabPage

2. Creating a new page:

object $page = new ActiveCollabPage(int $project_id) - Creates a new ActiveCollabPage object

Parameters:

project_id - id of the Project where the Page will be created

Variable value: Object instance of ActiveCollabPage

3. Editing and saving a page

These methods are called out through an page object.

•   setCreatedByEmail(string $email)  -  Sets an email of the user who created this page
•   setCreatedByName(string $name)  -  Sets the name of the user who created this page
•   setName(string $name)  -  Sets the name of this page
•   setBody(string $body)  -  Sets the description of this page
•   setTags(array of string $tagArr) - Sets tags for this page
•   setVisibility(int $visibility) - Sets the visibility of this page; the visibility parameter can be a combination of the following constants: ACTIVECOLLAB_VISIBILITY_PRIVATE, ACTIVECOLLAB_VISIBILITY_NORMAL
•   setParentId(int $parent_id) - Sets the parent for this page
•   setMilestoneId(int $milestone_id) - Sets the milestone for this page
•   addAttachments(array of file $arr_files) - Adds array of files to a page
•   save(void) - Saves the page object into activeCollab

Working With Status Messages

These methods are used for managing Status messages.

1. Creating a new status message

object $message = new ActiveCollabStatusMessage( void ) - Creates a new ActiveCollabStatusMessage object

Variable value: Object instance of ActiveCollabStatusMessage

2. Editing and saving a status message

These methods are called out through an status message object:

$sm = new ActiveCollabStatusMessage();
$sm->setMessage('roke');
$sm->save();

Working With Comments

This article covers managing comments in activeCollab using the API Wrapper.

1. Fetching a comment

object ActiveCollab::findCommentById(int $project_id, int $comment_id) - Fetches an ActiveCollabComment object

Parameters:

project_id - id of the Project where the comment is located comment_id - id of a specific comment

Return value: Object instance of ActiveCollabComment

2. Creating a new comment

object $comment = new ActiveCollabComment(int $project_id) - Creates a new ActiveCollabComment object

Parameters:

project_id - id of the Project where the comment will be created

Variable value: Object instance of ActiveCollabComment

3. Editing and saving a comment

These methods are called out through an comment object.

•   setCreatedByEmail(string $email)  -  Sets an email of the user who created this comment
•   setCreatedByName(string $name)  -  Sets the name of the user who created this comment
•   setBody(string $body)  -  Sets the description of this comment
•   setParentId(int $parent_id) - Sets the parent for this comment
•   addAttachments(array of file $arr_files) - Adds array of files to a comment
•   save(void) - Saves the comment object into activeCollab

Working With Subtask

The following methods allow you to manipulate Subtasks in activeCollab.

1. Fetching a subtask

object ActiveCollab::findSubTaskById(int $project_id, int $subtask_id) - Fetches an ActiveCollabSubTask object

Parameters:

project_id - iid of the Project in which the Subtask is located subtask_id - id of a specific Subtask

Return value: Object instance of ActiveCollabSubtask

2. Creating a new subtask

object $subtask = new ActiveCollabSubTask(int $project_id) - Creates a new ActiveCollabSubTask object

Parameters:

project_id - id of the Project in which the Subtask is going to be created

Variable value: Object instance of ActiveCollabSubtask

3. Editing and saving a subtask

These methods are called out through an subtask object.

•   setCreatedByEmail(string $email)  -  Sets an email of the user who created this subtask
•   setCreatedByName(string $name)  -  Sets the name of the user who created this subtask
•   setBody(string $body)  -  Sets the description of this subtask
•   setDueOn(timestamp $date) - Sets the date when the subtask is due
•   setParentId(int $parent_id) - Sets the parent for this subtask
•   setAssignees(array of int $assignees, int $responsible_person) - Sets assignees and responsible person for this subtask
•   save(void) - Saves the subtask object into activeCollab

Common Project Object Operations

The following are some common project operations that can be used with all activeCollab objects.

•   starObject(void) - object becomes starred
•   unstarObject(void) - object becomes unstarred
•   openObject(void) - opens an object
•   completeObject(void) - completes an object
•   subscribeUser(void) - subscribes an user
•   unsubscribeUser(void) - unsubscribes an user
•   moveToTrash(void) - moves an object to the trash
•   restoreFromTrash(void) - restores an object from the trash
•   addNewSubTask(void) - creates a subtask for an object
•   addNewComment(void) - creates a comment for an object
•   addAttachments(void) - creates an attachment for an object
•   getDetails(void) - return object details as array
•   getComments(void) - returns comments (array of object Comment)
•   getSubTasks(void) - returns subtasks (array of object SubTask)
•   getAttachments(void) - returns attachments (array of object Attachment)