29/03/2011 05. Developer's Guide

29/03/2011 05.
Developer's Guide
05. Developer's Guide
activecollab.com/docs/…/developers 1/72
29/03/2011 05. Developer's Guide
Authentication
activeCollab authentication system can be extended to include other "authentication sources", such is LDAP, database of other web
application (your website's CMS or forum for example). This is achieved by using Authentication Providers.
Authentication Providers
Authentication Provider is a piece of custom code that you develop in order to check users against any authentication source you wish.
Most of the code is already prepared, you only need to add things specific to your authentication source.
Important note is that Authentication Providers are not replacement for activeCollab authentication, but a bridge that can connect it to
other applications. Provider still needs to return an instance of User class that really exists in activeCollab users table.
Here are four important methods in 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 user's credentials against authentication source. This method is called after login form is submitted and
forwards the data entered in the login form;
3. logUserIn() - Set user as logged in and do everything you need to in such situation: set session ID, save a cookie so user gets
authenticated on the next request, contact another application to let it know that user is logged in etc.
4. logUserOut() - Make sure that user is logged out. It is great to undo everything you did with logUserIn() method: destroy session and
cookie variables, contact external application that user left and so on.
Extending Authentication System

In this example we will cover the making of a provider that extends the system by trying to log user against another user database (website
CMS or forum for example). If that fails, then we will try to authenticate user against activeCollab users database.
We will start by creating CustomAuthenticationProvider.class.php within /activecollab/angie/classes/auth/providers folder. We'll use

this code for 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 for
free, without the need to implement them once again.
Let's implement the behavior now. We want to check if user exists and that password is valid in another database after users hits Submit
button on activeCollab form. For that, we will need to override 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 config/config.php and add the following line to the block with constant definitions:
define('AUTH_PROVIDER', 'CustomAuthenticationProvider');
Overriding Authentication System

In this example, we will assume that your system administrator configured the system so Apache knows you by the username you used to
log into your computer, and that it makes this information available to PHP as authenticated_user variable. In this setup, we can
completely skip the login screen and log you in directly, based on 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 don't have login process, we can skip
authentication() method and implement 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 login screen and automatically log you in every time you visit
activeCollab .
Integrating activeCollab Login with Your Website
If you wish to integrate activeCollab login into your website, system lets you do two things:
1. Define a custom login form. This form submits user credentials to activeCollab and lets user log into the system directly from your
website;
2. Define an URL that is used to redirect users back to your website when they log out.
Please read following articles in this chapter to learn more.
Custom Login Form

You can add a form that can authenticate users in activeCollab directly from your website. To do that, all you need to do is to add a form
with specific fields that submits POST request to activeCollab's login page.
Required fields are:
1. login[email]
2. login[password]
3. login[remember]
Additionally you need to include a "submitted" hidden field with "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 names of the fields are not changed and that form action points to login
form of your activeCollab installation.
Logout URL
Since activeCollab 2 you can define URL where users will be redirected when they log out.
By default, they will be redirected back to login page unless you provide other location. To do that, open Administration > General
settings page:
At the bottom of the General Settings page there is When User Logs Out switch:
1. Select Redirect him to a custom URL
2. Once you select the field, text input field will be displayed where you can insert URL that will be used. Please note that the value of
this field needs to be a valid URL. If it's not valid, system will ignore it and redirect users to login page.
When you make the changes and submit the form, try logging out to confirm that everything is working properly.
Themes
activeCollab themes let you change the look and feel of the application without changing any core files:
Themes are per user setting, meaning that every user can pick their favorite theme from Change Settings page of his profile.
Administrators can select a default theme that is automatically selected when users are created. When default theme in administration is
changed, all user specific settings are dropped and theme is reseted for everyone to default theme.
How Themes Work?

Themes use the fact that you can override existing styling with CSS files that are included later on. When loading a page activeCollab first
includes basic CSS - resets, page layout, form widgets and other basic page elements. These files make activeCollab fully usable, but with
minimum of graphic elements on the page.
To see how activeCollab looks like with just basic files included select Sandbox theme from your profile.
When files that apply basic styling are included, activeCollab includes theme files that overrides existing settings and adds colors and
other graphic elements. Default theme that ships with activeCollab is implemented as theme that extends sandbox and you can use it as
an example on how to create a theme of your own.
Creating a Theme
Creating a theme is as easy as creating a folder and placing a CSS file in it. To create a theme:
1. Navigate to /public/assets/themes.
2. Create a new folder. Folder name will be used as theme name by activeCollab in Select Theme field (as shown on the screenshot
bellow).
3. Create theme.css inside the theme folder you have just created. This file will be automatically included by activeCollab for all users
who select this theme from their profile pages.
4. Optionally create /images folder inside of the theme folder you've just created. Inside of theme.css write CSS rules that override
existing styling.
API
activeCollab API is a set of methods that can be called from other application. These methods are used to read and manipulate the data
stored by the system.
Making a Request
Methods are executed by calling specific URL-s and fetching formatted output. URL-s are in 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=v
API URL that you need to sent request to and your token are available on API Setting page of your system profile:
1. Output Formats
Currently supported output formats are XML and JSON. There are two ways of specifying output format:
1. Recommended method is to set Accept request header. To get JSON, set it to 'application/json', or or 'application/xml' to
get XML.
2. Second method, added for convenience and to make testing easier is to add 'format' variable to a query string. Set it to
'json' to get JSON or 'xml' to get XML formatted output. 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 POST method, there needs to be a variable named "submitted" with value
"submitted". If you don't provide it, then activeCollab will reject your request (most probably with BAD REQUEST error).
Authentication
In order to use activeCollab API, first you will need to authenticate yourself to the system. This is what API key is for. It is available on API
page at user profile page:
When creating a request, API key needs to be passed as "token" GET variable. Sample request URL would look like this:
http://example.com/public/api.php?path_info=projects&token=1-55lTBjCvCALC6Jksg3vo2xQeymySDqFwkReL1H8s
Note
API key can be reset by user at any time. Also, it is automatically reset when user changes a password!
Controling API Status

There are three type of states of the activeCollab API:
Disabled - All API requests are rejected. Please note that, when API is disabled, both RSS and iCalendar feeds will stop working.
Read-Only - Applications can only read data through the API, and all requests that alter or submit data are rejected. This is default
state in which activeCollab API is after installation.
Read and Write - API users can read and write data.
To change API state check for API_STATUS in your config/config.php. If that configuration directive does not exist, add the following
line to the file:
define('API_STATUS', 1);
Values this directive can have are:
0 - API is disabled
1 - API is read-only
2 - API supports both read and write requests
API Changes
This section contains information about changes to the API that significantly change the behavior and may break backward compatibility.
Note
This API documentation section was introduce when activeCollab 2.1 was launched.
1. activeCollab 2.1
activeCollab 2.0 introduce many improvements and some of them 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 root page for a given project. Instead, it lists categories for
pages section. When category_id is provided in the request, pages posted in that category will be listed
4. Page versions are prepresented 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 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 task root element instead of the items
10. /projects/:project_id/tasks/:task_id/edit returns task root element instead of the items
System Information
This chapter lists commands that can be used to get information about activeCollab installation you are communicating with.
1. /info
Return system information about the installation you are working with. This information includes system versions, info about
logged user, mode in which API is, etc.
Method: GET
Informations that this request returns are:
api_version - Version of activeCollab API

system_version - 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 user (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 exposes several methods for listing user roles and reading permissions of 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 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
Example Response:
<project_roles>
<project_role>
<id>...</id>
<name>...</name>
<permissions>
<discussion>1</discussion>
...
</permissions>
</project_role>
</project_roles>
3. /roles/:role_id
Displays details of 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. Each user will be able to read details of each role.
Method: GET
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>
...
</permissions>
</project_role>
Working with Companies and Users
activeCollab offers several commands that let other applications create and manage company and 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) - User's email address. Value of this field is required when user account is created, it needs to be properly
formatted and there can be only one user with a given email address in the system.
2. password (string) - User's password. Value of this field is required when user account is created and minimal length is 3
characters.
3. first_name (string) -First name
4. last_name (string) - Last name
5. role_id (integer) - ID of the user's system role. Only administrators or people managers are able to change value of this
field.
Note
When new user account is created, user can set role_id to custom value only if he is Administrator or People Manager. If user
who creates an account is not Administrator or People manager, users role will be set to default role configured on
Administration > Roles page.
3. /people
Lists all companies defined in the system (both, active and archived companies).
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. On success, details of newly created company will be returned
Method: POST
Request example:
submitted=submitted
company[name]=New Company
Example response:
<company>
<id>...</id>
<name>...</name>
<office_address></office_address>
<office_phone></office_phone>
<office_fax></office_fax>
<office_homepage></office_homepage>
</company>
5. /people/:company_id
Shows properties of a specific company.
Method: GET.
Example response:
<company>
<id>...</id>
<name>...</name>
<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>
</company>
7. /people/:company_id/delete
Delete a company and all of its users. Projects this company and its users are related to will not be deleted! On success, system
returns HTTP status 200 OK.
Note
Owner company can't be deleted
Method: POST.
Request example:
submitted=submitted
8. /people/:company_id/add-user
Creates a user account in the selected company. On success, function displays details of newly created user account.
Note
Only Administrators and People Managers can set role_id value. If user who creates new account is not Administrator or
People Manager, 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>
<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>
<email>...</email>
<token>...</token>
<company>
<id>...</id>
<name>...</name>
</company>
<avatar_url>...</avatar_url>
</user>
10. /people/:company_id/users/:user_id/edit
Updates details of existing user.
Method: POST.
Request example:
user[first_name] = John
user[last_name] = Doe
Example response:
<user>
<id>...</id>
<email>...</email>
<token>...</token>
<company>
<id>...</id>
<name>...</name>
</company>
<avatar_url>...</avatar_url>
</user>
11. /people/:company_id/users/:user_id/delete
Delete specific user account. On success, HTTP 200 OK status is returned.
Note
Data created by this user - project, tickets, discussions, comments, etc. will not be deleted.
Method: POST.
Request example:
Working with Projects

Commands listed in this section are used for management of projects.
1. Project Fields
1. name (string) - Project name

2. overview (text) - Project overview
3. default_visibility (integer) - Default visibility preselected 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 a project leader
8. status (string) - Project status. This field is available only for edit-status action and has four possible values: active,
paused, completed and canceled
2. /projects
Shows all projects that the authenticated user has access to. This function will show 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>
<leader_id>...</leader_id>
<group_id>...</group_id>
</project>
</projects>
3. /projects/add
Creates a new project.
Method: POST.
Additionally you can include project_template_id variable. It needs to be a valid project ID. If this variable is present, new
project will be created based on that project 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>
<leader_id>...</leader_id>
<group_id>...</group_id>
</project>
4. /projects/:project_id
Shows the properties of the specific project. In addition to project properties, this request also returns:
1. Brief information about the leader

2. Brief information about the client
3. Permissions that logged in user has in project sections
Method: GET
Example response:
<project>
<id>2</id>
<name>
<![CDATA[Created through API]]>
</name>
<status>
<![CDATA[active]]>
</status>
<leader>...</leader>
<company_id>0</company_id>
<group_id>0</group_id>
<logged_user_permissions>
<role>
<![CDATA[administrator]]>
</role>
<permissions>
<milestone>3</milestone>
<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:
project[name] = New name
project[company_id] = 16
<project>
<id>2</id>
<name>
<![CDATA[New name]]>
</name>
<status>
<![CDATA[active]]>
</status>
<leader_id>15</leader_id>
</project>
6. /projects/:project_id/edit-status
Updates project status. Status can have four different values:
1. active
2. paused
3. completed
4. canceled
Method: POST.
Request example:
project[status] = completed
Response:
<project>
<id>2</id>
<name>
<![CDATA[Project Name]]>
</name>
<status>
<![CDATA[completed]]>
</status>
</project>
7. /projects/:project_id/delete
Delete selected project. On success, system returns HTTP status 200 OK.
Note
This operation is final and when executed there is no Undo!
Method: POST.
Request example:
submitted=submitted
8. /projects/:project_id/user-tasks
Returns all tasks that are assigned to the logged in user in a particular project.
Method: GET
<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>
<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
Returns the list of people involved with a project and their permissions. Permissions are per module and have 4 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
Response:
<project_users>
<project_user>
<user_id>15</user_id>
<role>
<![CDATA[administrator]]>
</role>
<permissions>
<file>3</file>
<page>3</page>
<ticket>3</ticket>
</permissions>
</project_user>
<project_user>
<role>
<![CDATA[custom]]>
</role>
<permissions>
<file>1</file>
<page>2</page>
<ticket>2</ticket>
</permissions>
</project_user>
</project_users>
2. /projects/:project_id/people/add
Using this command, you can add one or more users to the project and set their 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 project role users will have in the project. This parameter is optional. If value is
not present, system will use project_permissions[permissions].
2. project_permissions[permissions] - Array of permissions for different sections users will have in the project. This
parameter is ignored when project_permissions[role_id] is present.
Method: POST
This request will add users with ID-s 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 request will add users with ID-s 15 and 72 to the project, and set their permissions of tickets and discussions module to
Has access. All other sections will be set to No access:
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 to change permissions of selected user in a given project.
Change permissions command accepts one parameter (project_permissions) with two fields:
This command accepts two parameters:
1. project_permissions[role_id] - ID of the project role users will have in the project. This parameter is optional. If value is
not present, system will use project_permissions[permissions].
2. project_permissions[permissions] - Array of permissions for different sections users will have in the project. This
parameter is ignored when project_permissions[role_id] is present.
This request will change user permissions and his project role to role #10:
submitted=submitted
project_permissions[role_id]=10
This request will change user's permission so he has access to tickets and discussions module. All other sections will be set to
No access:
project_permissions[permissions][discussion] = 1
project_permissions[permissions][ticket] = 1
4. /projects/:project_id/people/:user_id/remove-from-project
Removes specific user from the project. On success, this function returns HTTP 200 OK status.
Method: POST
Working with Project Groups

Project group commands let you grammatically manage project groups from external application.
Note
Work with project groups through API is added to 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.
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. 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 projects that belong to that 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>
</project>
</projects>
</project_group>
5. projects/groups/:project_group_id/edit
Updates existing 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 project group from database. On success, system will return HTTP status 200, OK.
Method: POST.
Note
Only empty project groups can be deleted.
Request example:
submitted=submitted
Working with Discussions

Discussions are project section where people can discuss various aspects of the project in environment similar to online forums. Each
project has a separate discussions 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
Lists 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_by_id>...</created_by_id>
<updated_on>...</updated_on>
<updated_by_id>...</updated_by_id>
<version>...</version>
<project_id>...</project_id>
<parent_id>...</parent_id>
<milestone_id>...</milestone_id>
<permissions>
</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>
</type>
<name>
<![CDATA[New Discussion]]>
</name>
<body>
</body>
<state>...</state>
<created_by_id>15</created_by_id>
<permissions>
</permissions>
</discussion>
4. /projects/:project_id/discussions/:discussion_id
Displays discussion details.
In addition to discussion details, this command also returns all comments people posted here as part of the comments
property.
Method: GET
Response:
<discussion>
<id>11</id>
<type>
</type>
<name>
<![CDATA[New Discussion]]>
</name>
<body>
</body>
<state>...</state>
<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>
<permissions>
</permissions>
</comment>
</comments>
<permissions>
</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>
</type>
<name>
<![CDATA[Updated Name]]>
</name>
<body>
</body>
<state>...</state>
<permissions>
</permissions>
</discussion>
Working with Checklists

Commands in this section lets you manage checklists in projects. Each project has its own set of checklists.
Note
By default, Checklists module is not installed in activeCollab Corporate and these commands are not available. To install it, go to
Administration > Modules page and install it from the list of Available Modules.
1. Checklist Fields
1. name (string) - Object name or short, one line summary. Value of this field is required when 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
Shows 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>
<priority>...</priority>
<completed_by_id>...</completed_by_id>
<permissions>
</permissions>
</checklist>
</checklists>
3. /projects/#project_id/checklists/archive
Shows all completed checklists in a project.
Method: GET.
Example response:
<checklists>
<checklist>
<id>13</id>
<type>
</type>
<name>
</name>
<body>
</body>
<state>...</state>
<permissions>
</permissions>
</checklist>
</checklists>
4. /projects/:project_id/checklists/add
Creates 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>
</type>
<name>
<![CDATA[New checklist]]>
</name>
<body>
</body>
<state>...</state>
<permissions>
</permissions>
</checklist>
5. /projects/:project_id/checklists/:checklist_id
Shows 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>
</type>
<name>
<![CDATA[New checklist]]>
</name>
<body>
</body>
<state>...</state>
<tasks>
...
</tasks>
<permissions>
</permissions>
</checklist>
6. /projects/:project_id/checklists/:checklist_id/edit
Updates properties of existing checklist.
Method: POST.
Request example:
submitted=submitted
checklist[name] = Updated name
Response:
<checklist>
<id>13</id>
<type>
</type>
<name>
</name>
<body>
</body>
<state>...</state>
<permissions>
</permissions>
</checklist>
Working with Files

Each project has a section where files can be uploaded, discussed and file versions can be tracked. Commands in this section allows you to
manage all of these files.
1. File Fields
1. name (string) - File name.

2. body (text) - File description.
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 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>
<permissions>
</permissions>
</file>
</files>
3. /projects/:project_id/files/upload-single
Uploads a single file
If name property is not provided, system will use original file name.
Method: POST.
Additional requirement is a file to be uploaded (any name will work, but we recommend that you name file field 'attachment').
Request example:
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>
</body>
<state>...</state>
<permissions>
</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 value of revisions property.
Method: GET.
<file>
<id>17</id>
<type>
<![CDATA[File]]>
</type>
<name>
<![CDATA[new_file.png]]>
</name>
<body>
</body>
<state>...</state>
<permissions>
</permissions>
<revisions>
...
</revisions>
</file>
5. /projects/:project_id/files/:file_id/edit
Updates file details.
Method: POST.
Example request:
file[name] = New-Name.png
Response:
<file>
<id>17</id>
<type>
<![CDATA[File]]>
</type>
<name>
<![CDATA[New-Name.png]]>
</name>
<body>
</body>
<state>...</state>
<permissions>
</permissions>
</file>
Working with Milestones
1. Milestone Fields
1. name (string) - Milestone summary. Value of this field is required when milestone is created.
2. body (text) - File Description.
3. start_on (date) - Date when the milestone starts. Value of this field is required when milestone is created.
4. due_on (date) - Date when the milestone is due. Value of this field is required when 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 element of array is list of assignees (as 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.
2. /projects/:project_id/milestones
Lists 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>
<permissions>
</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:
milestone[name] = Test milestone
milestone[start_on] = 2008-05-05
milestone[due_on] = 2008-05-08
Response:
<milestone>
<id>18</id>
<type>
</type>
<name>
<![CDATA[Test milestone]]>
</name>
<body>
</body>
<state>...</state>
<permissions>
</permissions>
<due_on>2008-05-08</due_on>
</milestone>
4. /projects/:project_id/milestones/:milestone_id
Shows milestone details.
Method: GET
Example response:
<milestone>
<id>18</id>
<type>
</type>
<name>
<![CDATA[Test milestone]]>
</name>
<body>...</body>
<state>...</state>
<assignees>...</assignees>
<permissions>
</permissions>
<due_on>2008-05-08</due_on>
</milestone>
5. /projects/:project_id/milestones/:milestone_id/edit
Updates milestone details
Method: POST.
Request example:
milestone[name] = Update name
Response:
milestone>
<id>18</id>
<type>
</type>
<name>
<![CDATA[Update name]]>
</name>
<body>...</body>
<state>...</state>
<permissions>
</permissions>
<due_on>2008-05-08</due_on>
</milestone>
Working with Tickets
1. Ticket Fields
1. name (string) - Ticket summary. Value of this field is required when ticket is created.
2. body (text) - Full ticket description.
5. priority (integer) - Priority can have one of the 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. First element of array is list of assignees (as array). Second
parameter is an ID of the person responsible for the ticket (ID must be in the first list).
9. parent_id (integer) - ID of the parent object (category, ticket for tasks, and so on).
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>
<permissions>
</permissions>
</ticket>
</tickets>
3. /projects/:project_id/tickets/archive
Shows all completed tickets in a project.
Method: GET
<tickets>
<ticket>
<id>9</id>
<type>
<![CDATA[Ticket]]>
</type>
<name>
</name>
<body>...</body>
<state>...</state>
<permissions>
</permissions>
</ticket>
</tickets>
4. /projects/:project_id/tickets/add
Creates a new ticket
Method: POST.
Request example:
ticket[name] = This is summary
Response:
<ticket>
<id>19</id>
<type>
<![CDATA[Ticket]]>
</type>
<name>
<![CDATA[This is summary]]>
</name>
<body>...</body>
<state>...</state>
<permissions>
</permissions>
</ticket>
5. /projects/:project_id/tickets/:ticket_id
Displays ticket details.
Method: GET
Note
When making a request, please use ticket ID for that particular project, not project object ID.
<ticket>
<id>9</id>
<type>
<![CDATA[Ticket]]>
</type>
<name>
<![CDATA[My ticket]]>
</name>
<body>...</body>
<state>...</state>
<comments>
...
</comments>
<tasks>
...
</tasks>
<attachments>
...
</attachments>
<assignees>
...
</assignees>
<permissions>
</permissions>
</ticket>
6. /projects/:project_id/tickets/:ticket_id/edit
Updates properties of existing ticket
Method: POST.
Note
When making a request, please use the ticket ID for that particular project, not project object ID.
Reqest example:
ticket[name] = Updated summary
Response:
<ticket>
<id>9</id>
<type>
<![CDATA[Ticket]]>
</type>
<name>
</name>
<body>...</body>
<state>...</state>
<permalink>
<![CDATA[http://localhost/corporate_12/public/index.php?path_info=projects%2F1%2Ftickets%2F1]]
</permalink>
<permissions>
</permissions>
</ticket>
Working with Time
1. Time Fields
1. body (text) - Full description.

2. user_id (integer) - ID of the user whose time is logged. Value of this field is required when time record is added.
3. value (float) - Number of hours logged. Two formats are allowed: 5:30 (5h and 30 minutes) and 5.5. (5 and a half hours).
Value of this field is required when time record is added.
4. record_date (date) - Date when the time was spent. Value of this field is required when the time record is added.
5. billable_status (integer) - Represents record status. This field was added in activeCollab 1.1.5 to replace 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 billable_status field. These two fields are still available
for compatibility reasons:
1. is_billable (boolean) - Is this record billable or not.

2. is_billed (boolean) - Has this time already been billed or not (ignored if is_billable is set to FALSE)
2. /projects/:project_id/time
Lists 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>
<permissions>
</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>
</time_record>
</time_records>
3. /projects/:project_id/time/add
Add a new time record to the time log
Method: POST
Request example:
time[user_id] = 1
time[value] = 3:30
time[record_date] = 2008-05-01
Response:
<time_record>
<id>20</id>
<type>
</type>
<name>
</name>
<body>...</body>
<state>...</state>
<permissions>
</permissions>
<value>3.5</value>
<is_billable>...</is_billable>
<is_billed>...</is_billed>
</time_record>
4. /projects/:project_id/time/:record_id
Displays record details.
Method: GET
Example response:
<time_record>
<id>20</id>
<type>
</type>
<name>
</name>
<body>...</body>
<state>...</state>
<permissions>
</permissions>
<value>3.5</value>
</time_record>
5. /projects/:project_id/time/:record_id/edit
Updates record properties.
Method: POST
Request example:
time[value] = 3:45
Response:
<time_record>
<id>20</id>
<type>
</type>
<name>
</name>
<body>...</body>
<state>...</state>
<permissions>
</permissions>
<billable_status>...</billable_status>
<value>3.75</value>
</time_record>
Working with Pages
1. Page Fields
1. name (string) - Page title. Value of this field is required when page is created.
2. body (text) - Page body. Value of this field is required when page is created.
3. tags (string) - List of comma-separated tags.
6. parent_id (integer) - ID of the parent object (category, ticket for tasks so on). Value of this field is required when page is
created.
2. /projects/:project_id/pages
Lists page categories.
Method: GET
<categories>
<category>
<id>3</id>
<type>
<![CDATA[Category]]>
</type>
<name>
<![CDATA[General]]>
</name>
<body>...</body>
<state>...</state>
<version>1</version>
<permissions>
</permissions>
</category>
</categories>
3. /projects/:project_id/pages/add
Creates a new page.
Method: POST.
Request example:
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>
<permissions>
</permissions>
<revision_num>1</revision_num>
</page>
4. /projects/:project_id/pages/:page_id
Displays page details with list of 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>
<comments>
...
</comments>
<tasks>
...
</tasks>
<attachments>
...
</attachments>
<permissions>
</permissions>
<subpages>
...
</subpages>
<revisions>
...
</revisions>
</page>
5. /projects/:project_id/pages/:page_id/edit
Updates properties and content of the page.
By setting is_minor_revision to 1 when updating the page, system will consider changes to be a minor change and will not
create a new page revision. Email notification will not be sent to subscribers in this case.
Method: POST
Request example:
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>
<permissions>
</permissions>
</page>
6. /projects/:project_id/pages/:page_id/archive
Marks selected page as archived. On success, system will return updated page details.
Method: POST.
7. /projects/:project_id/pages/:page_id/unarchive
Marks selected page as archived. On success, system will return updated page details.
Method: POST.
Working with Status Messages

Status Updates module was added in activeCollab 1.1, but API support for it was added a couple of months later, in activeCollab 1.1.4.
Commands listed in this section are not available in older versions.
1. /status
Lists 50 recent status messages. Pass user_id through query string to filter only messages posted by the specific user.
Method: GET
Example response:
<messages>
<message>
<message>
<![CDATA[It works great]]>
</message>
<created_by>
<id>15</id>
<name>
<![CDATA[ilija.studen@gmail.com]]>
</name>
</created_by>
</message>
</messages>
2. /status/add
Submits new status message.
Method: POST
Example request:
status[message] = I did something interesting
Response:
<message>
<message>
<![CDATA[I did something interesting]]>
</message>
<created_by>
<id>15</id>
<name>
<![CDATA[john.doe@gmail.com]]>
</name>
</created_by>
</message>
Working with Comments
1. Comment Fields
1. body (string) - Comment body. Value of this field is required when new comment is created.
2. /projects/:project_id/comments/add&parent_id=:parent_id
Posts a new comment on the specific object.
Method: POST.
Request example:
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>
<permissions>
</permissions>
</comment>
3. /projects/:project_id/comments/:comment_id
Displays comment details.
Method: GET
<comment>
<id>23</id>
<type>
<![CDATA[Comment]]>
</type>
<name>
</name>
<body>
<![CDATA[My comment!]]>
</body>
<state>...</state>
<milestone_id>
</milestone_id>
<permissions>
</permissions>
</comment>
4. /projects/:project_id/comments/:comment_id/edit
Updates existing comment.
Method: POST
Request example:
comment[body] = Updating my comment!
Response:
<comment>
<id>23</id>
<type>
<![CDATA[Comment]]>
</type>
<name>
</name>
<body>
<![CDATA[Updating my comment!]]>
</body>
<state>...</state>
<permissions>
</permissions>
</comment>
Working with Subtasks
1. Task Fields
1. body (text) - Task summary. Value of this field is required when 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 task is due.
4. assignees (array) - Array of people assigned to the object. First element of array is list of assignees (as array). Second
parameter is an ID of a person responsible for a task (ID must be in the first list).
2. /projects/:project_id/tasks/add&parent_id=:parent_id
Creates a new subtask and attach it to a parent object.
Method: POST
Request example:
task[body] = Go shopping
task[priority] = -2
Response:
<task>
<id>25</id>
<type>
<![CDATA[Task]]>
</type>
<name>
<![CDATA[Go shopping]]>
</name>
<body>
</body>
<state>...</state>
<priority>-2</priority>
<permissions>
</permissions>
</task>
3. /projects/:project_id/tasks/:task_id
Shows task details.
Method: GET.
Example response:
<task>
<id>25</id>
<type>
<![CDATA[Task]]>
</type>
<name>
</name>
<body>
</body>
<state>...</state>
<priority>-2</priority>
<permissions>
</permissions>
</task>
4. /projects/:project_id/tasks/:task_id/edit
Updates task details.
Method: POST
Request example:
task[priority] = 0
Response:
<task>
<id>25</id>
<type>
<![CDATA[Task]]>
</type>
<name>
</name>
<body>
</body>
<state>...</state>
<permissions>
</permissions>
</task>
Working with Attachments
1. /projects/:project_id/objects/:object_id/attachments
Lists all files attached to a specific object.
Method: GET or POST
Example response for GET request:
<attachments>
<attachment>
<id>...</id>
<name>...</name>
<mime_type>...</mime_type>
<size>...</size>
</attachment>
</attachments>
If POST request is submitted, system will attach all the uploaded files and attach them to the object. When done, last
attachment details are returned.
Common Project Object Operations
1. /projects/:project_id/objects/:object_id/complete
Marks specific object as completed. On success system returns object details.
Method: POST
Types that can be completed:
1. Milestones
2. Checklists
3. Tickets
4. Subtasks
2. /projects/:project_id/objects/:object_id/open
Marks specific object as open. On success system returns object details.
Method: POST
Types that can be completed and reopened:
1. Milestones
2. Checklists
3. Tickets
4. Subtasks
3. /projects/:project_id/objects/:object_id/star
Marks specific object as starred. On success object system returns object details.
Method: POST
Any project object can be starred.
4. /projects/:project_id/objects/:object_id/unstar
Marks specific object as not starred. On success, system returns object details.
Method: POST
Any project object can be unstarred.
5. /projects/:project_id/objects/:object_id/subscribe
Subscribes users to a specific object. On success system returns object details.
Method: POST
Users can be subscribed to following 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 object. On success system returns object details.
Method: POST
Users can be unsubscribed from following 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 specific object into Trash. On success system will return object details.
Method: POST
Any project object type can be moved to Trash.
8. /projects/:project_id/objects/:object_id/restore-from-trash
Restores object from Trash. System will return object details on success.
Method: POST
Any project object type can be restored from Trash.
API Wrapper
activeCollab API Wrapper is a set of PHP classes that make use of activeCollab API much easier, by providing object oriented interface to
it. Instead of making HTTP requests from your code and handling responses, wrapper layer lets you call simple set of methods and work
with the result in form of PHP native types, such are arrays, objects, boolean values etc.
activeCollab API Wrapper is Free Software released under LGPL licenses, and you are free 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 LICENSE.txt
for details.
Getting Started
Usage of activeCollab API in your code goes in three steps: load API wrapper code (files located in /lib folder), provide authentication
parameters and finally execute one or more commands against the API:
<?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 the methods can throw an exception if they receive invalid parameters. In the following example, we'll use try / catch block to
handle any error that might 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 lists methods that can be used to get information about activeCollab installation you are communicating with. They 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:
Return Value:
Array containing the objects of Discussion categories
6. listFileCategoriesByProjectId
Description:
array listFileCategoriesByProjectId( int $project_id ) - List file categories in one project
Parameters:
Return Value:
Array containing the objects of File categories
7. listPageCategoriesByProjectId
Description:
array listPageCategoriesByProjectId( int $project_id ) - List page categories in one project
Parameters:
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:
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:
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:
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:
Return Value:
20. listArchivedTicketsByProjectId
Description:
array listArchivedTicketsByProjectId( int $project_id ) - List all archived tickets for a specific project
Parameters:
Return Value:
21. listFilesByProjectId
Description:
array listFilesByProjectId( int $project_id ) - List all files for a specific project
Parameters:
Return Value:
Array of ActiveCollabFile objects
22. listDiscussionsByProjectId
Description:
array listDiscussionsByProjectId( int $project_id ) - List all discussions for a specific project
Parameters:
Return Value:
Array of ActiveCollabDiscussion objects
23. listMilestonesByProjectId
Description:
array listMilestonesByProjectId( int $project_id ) - List all milestones for a specific project
Parameters:
Return Value:
Array of ActiveCollabMilestone objects
24. listChecklistsByProjectId
Description:
array listChecklistsByProjectId( int $project_id ) - List all checklists for a specific project
Parameters:
Return Value:
Array of ActiveCollabChecklist objects
25. listArchivedChecklistsByProjectId
Description:
array listArchivedChecklistsByProjectId( int $project_id ) - List all archived checklists for a specific project
Parameters:
Return Value:
Array of ActiveCollabChecklists objects
26. listTimeRecordsByProjectId
Description:
array listTimeRecordsByProjectId( int $project_id ) - List all time records for a specific project
Parameters:
Return Value:
Array of ActiveCollabTime objects
Working With Companies

Methods that allow you to manage companies in activeCollab.
1. Fetching a company
object ActiveCollab::findCompanyById( int $company_id) - Fetches 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 new ActiveCollabCompany object
Variable value: Object instance of ActiveCollabCompany
3. Editing and saving a company
These methods are callout through an 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 managing users in activeCollab.
1. Fetching a user
object ActiveCollab::findUserById( int $user_id) - Fetches 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 new ActiveCollabUser object
Parameters: company_id - id of a company in which user is going to be created
Variable value: Object instance of ActiveCollabUser
3. Editing and saving a user
These methods are callout 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 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 new ActiveCollabProject object
Variable value: Object instance of ActiveCollabProject
3. Editing and saving a project
These methods are callout 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 comb
• 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

This are the methods used for manipulating discussions in activeCollab.
1. Fetching a discussion
object ActiveCollab::findDiscussionById(int $project_id, int $discussion_id) - Fetches ActiveCollabDiscussion object
Parameters:
project_id - id of a project in which is discussion 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 new ActiveCollabDiscussion object
Parameters:
project_id - id of a project in which discussion is going to be created
Variable value: Object instance of ActiveCollabDiscussion
3. Editing and saving a discussion
These methods are callout 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 parame
• 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

This is a section with methods that are used to manipulate checklists in activeCollab.
1. Fetching a checklist
object ActiveCollab::findChecklistById(int $project_id, int $checklist_id) - Fetches ActiveCollabChecklist object
Parameters:
project_id - id of a project in which is checklist 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 a project in which checklist is going to be created
Variable value: Object instance of ActiveCollabChecklist
3. Editing and saving a checklist
These methods are callout 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 paramet
• setMilestoneId(int $milestone_id) - Sets the milestone for this checklist
• save(void) - Saves the checklist object into activeCollab
Working With Files

Methods that are used for managing files.
1. Fetching a file
object ActiveCollab::findFileById(int $project_id, int $file_id) - Fetches ActiveCollabFile object
Parameters:
project_id - id of a project in which is file 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 ActiveCollabFile object
Parameters:
project_id - id of a project in which file is going to be created
Variable value: Object instance of ActiveCollabFile
3. Editing and saving a file
These methods are callout 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 ca
• 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 section covers milestones in activeCollab
1. Fetching a milestone
object ActiveCollab::findMilestoneById(int $project_id, int $milestone_id) - Fetches ActiveCollabMilestone object
Parameters:
project_id - id of a project in which is 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 ActiveCollabMilestone object
Parameters:
project_id - id of a project in which milestone is going to be created
Variable value: Object instance of ActiveCollabMilestone
3. Editing and saving a milestone
These methods are callout 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 b
• 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 responsibl
• save(void) - Saves the milestone object into activeCollab
Working With Tickets

This section covers manipulating tickets.
1. Fetching a ticket
object ActiveCollab::findTicketById(int $project_id, int $ticket_id) - Fetches ActiveCollabTicket object
Parameters:
project_id - id of a project in which is 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 new ActiveCollabTicket object
Parameters:
project_id - id of a project in which ticket is going to be created
Variable value: Object instance of ActiveCollabTicket
3. Editing and saving a ticket
These methods are callout 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
• setTags(array of string $tagArr) - Sets tags for this ticket
• setVisibility(int $visibility) - Sets the visibility of this ticket; the visibility parameter
• 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
• 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 to manage time tracking.
1. Fetching a time track
object ActiveCollab::findTimeById(int $project_id, int $time_id) - Fetches ActiveCollabTime object
Parameters:
project_id - id of a project in which is time time_id - id of a specific time
Return value: Object instance of ActiveCollabTime
2. Creating a new time track
object $time = new ActiveCollabTime(int $project_id) - Creates new ActiveCollabTime object
Parameters:
project_id - id of a project in which time is going to be created
Variable value: Object instance of ActiveCollabTime
3. Editing and saving a time
These methods are callout 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 c
• 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 section contains methods for manipulating pages in activeCollab.
1. Fetching a page
object ActiveCollab::findPageById(int $project_id, int $page_id) - Fetches ActiveCollabPage object
Parameters:
project_id - id of a project in which is 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 new ActiveCollabPage object
Parameters:
project_id - id of a project in which page is going to be created
Variable value: Object instance of ActiveCollabPage
3. Editing and saving a page
These methods are callout 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 ca
• 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 new ActiveCollabStatusMessage object
Variable value: Object instance of ActiveCollabStatusMessage
2. Editing and saving a status message
These methods are callout through an status message object:
$sm = new ActiveCollabStatusMessage();

$sm->setMessage('roke');
$sm->save();
Working With Comments

This section covers the managing of the comments in activeCollab.
1. Fetching a comment
object ActiveCollab::findCommentById(int $project_id, int $comment_id) - Fetches ActiveCollabComment object
Parameters:
project_id - id of a project in which is comment 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 new ActiveCollabComment object
Parameters:
project_id - id of a project in which comment is going to be created
Variable value: Object instance of ActiveCollabComment
3. Editing and saving a comment
These methods are callout 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

These methods allow manipulating subtasks in activeCollab.
1. Fetching a subtask
object ActiveCollab::findSubTaskById(int $project_id, int $subtask_id) - Fetches ActiveCollabSubTask object
Parameters:
project_id - id of a project in which is subtask 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 new ActiveCollabSubTask object
Parameters:
project_id - id of a project in which subtask is going to be created
Variable value: Object instance of ActiveCollabSubtask
3. Editing and saving a subtask
These methods are callout 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
• save(void) - Saves the subtask object into activeCollab
Common Project Object Operations

These are common project operations for 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)

29/03/2011 05. Developer's Guide

Enviado por

Dados do documento

Descrição original:

Título original

Direitos autorais

Formatos disponíveis

Compartilhar este documento

Compartilhar ou incorporar documento

Opções de compartilhamento

Você considera este documento útil?

Este conteúdo é inapropriado?

Direitos autorais:

Formatos disponíveis

29/03/2011 05. Developer's Guide

Enviado por

Direitos autorais:

Formatos disponíveis

29/03/2011 05.

05. Developer's Guide

Here are four important methods in Authentication Provider:

Extending Authentication System

We will start by creating CustomAuthenticationProvider.class.php within /activecollab/angie/classes/auth/providers folder. We'll use

Overriding Authentication System

We will call this authentication provider ApacheAuthenticationProvider and we'll define it in

class ServerAuthenticationProvider extends AuthenticationProvider {

Integrating activeCollab Login with Your Website

Please read following articles in this chapter to learn more.

Custom Login Form

Required fields are:

Here is the example form markup:

<form method="post" action="http://www.activecollab.com/my/ac/public/index.php?path_info=login">

1. Select Redirect him to a custom URL

How Themes Work?

Controling API Status

Values this directive can have are:

1. /project/:project_id/checklists/:checklist_id/edit returns checklist root element instead of the item

Informations that this request returns are:

api_version - Version of activeCollab API

Working with Roles

Since: activeCollab 1.1.4

Lists all project roles and displays their permissions.

Since: activeCollab 1.1.4

Since: activeCollab 1.1.4

Example of the system role response:

Example of the project role Response:

Shows properties of a specific company.

Owner company can't be deleted

Shows details of a specific user.

Updates details of existing user.

Delete specific user account. On success, HTTP 200 OK status is returned.

Working with Projects

1. name (string) - Project name

1. Brief information about the leader

Updates project properties.

Updates project status. Status can have four different values:

This operation is final and when executed there is no Undo!

Since: activeCollab 1.1.2

Working with Project People

Since: activeCollab 1.1.4

1. users - An array of users that you want to add to the project.

Since: activeCollab 2.0.3

This command is used to change permissions of selected user in a given project.

This command accepts two parameters:

Since: activeCollab 2.0.3

Working with Project Groups

1. Project Group Fields

Lists all available project groups.

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

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

Updates existing group name.

Working with Discussions

Lists all discussions in a project.

Creates a new discussion in the specified project

Displays discussion details.

Updates existing discussion details.

Working with Checklists

Shows all active checklists for a given project.

Shows all completed checklists in a project.

Creates a new checklist.