5pm - project management on time. 5pm API.

5pm API (beta)

About this Guide:

5pm API developer's guide describes how to use 5pm API to access and manage you 5pm account data. This guide is intended for developers who want to programmatically access their 5pm account data through their own applications.

This document is still being updated and the API is presented as an beta version. Your suggestions and feedback are welcome.

About 5pm API Web Services:

Using 5pm API, you can access and manage groups, projects, tasks, activity and users in 5pm.

To access and manage your 5pm account using 5pm API you must build your client application that connects to one or more of the provided web services.

The core messaging technology of 5pm is SOAP (Simple Object Access Protocol).

The 5pm API is composed of the following web services:

AuthenticationService – lets authenticate for services and get session id – persistent key (ttl – 30 min) that will authenticate each your request without sending user/password each time.

ProjectsService – allows you to create, list, modify and remove projects;

ProjectsGroupsService – allows you to create, list, modify and remove projects groups;

TasksService – create, list, modify and remove tasks

ActivityService – create, list, modify and remove activity (messages, progress notes)

UsersService – lets you to create, list, modify and remove 5pm users

Signing Up for using 5pm API:

In order to use 5pm API you must be an registered 5pm user – that's enough for the alpha/beta versions.

Attention! Be careful with the API – you can lose your data.

Getting started with 5pm API

In order to start using 5pm API, you need:

service host: - your account host name (ex: demo.5pmweb.com)
login: - a valid user domain
password: - valid password for the provided login;

Web Service Urls:

The operations provided by web service are defined in WSDL files. Before connecting to a web service, you need to know the URL that points to its WSDL file. Each 5pm API web service has its own WSDL. The URL for each WSDL has the following form, where <version> is the service version and <service host> is your customer account host:

Authentication: http://<service host>/api/<version>/wsdl/authentication.wsdl
Projects: http://<service host>/api/<version>/wsdl/projects.wsdl
Tasks: http://<service host>/api/<version>/wsdl/tasks.wsdl
Projects: http://<service host>/api/<version>/wsdl/projects.wsdl
ProjectsGroups: http://<service host>/api/<version>/wsdl/projectsgroups.wsdl
Activity: http://<service host>/api/<version>/wsdl/activity.wsdl
Users: http://<service host>/api/<version>/wsdl/users.wsdl

example: http://demo.5pmweb.com/api/dev/wsdl/authentication.wsdl

Connecting:

The details of how your client application connects to the WSDL depends on the programming language and SOAP toolkit being used. SOAP toolkits typically provide a function for connecting to a service at a specified URL. For example, the following PHP code connects dev API version:

/** authentication service client **/
$client = new SoapClient('http://demo.5pmweb.com/api/dev/wsdl/authentication.wsdl');

Data types:

Uppercase types, such as Project and Task, shown throughout this guide's API Reference are complex data structures or enumerations defined in the XSD:

Data Types: http://<service host>/api/<version>/wsdl/schema.xsd

Logging into 5pm Web Services:

Firstly, you must provide client authentication using AuthenticationService. After you get the sessionId (using operation signIn) you must send it each request via Soap Header. If you don't do that - you will get an exception with authentication error message (you can send the authentication request without sessionId header).

Versioning:

Current version is dev - "under development". After the new API version is released, the old version will still be supported for a while.

The Shut Down of old versions will be announced via 5pm blog.

About SOAP:

The 5pm API Web Services uses rpc-style versions of the simple object access protocol (SOAP). A client program sends a SOAP request; the web service processes the request and sends a response. Both the request and the response are packaged as XML messages that have a header and a body. The header contains metadata about the message, and the body specifies the requested operation.

The requests that a web service can process are defined in a web services definition language (WSDL) file in XML. The WSDL file describes the operations that the web service can perform, the required parameters for each operation, and the response for each operation.

Other Service Bindings:

5pm also supports GET and POST bindings, that are described in the same WSDL files.

Example:

Authentication request using GET:
http://demo.5pmweb.com/api/dev/service/get/authentication/signIn?login=<login>&password=<password>

Projects list request using GET:
http://demo.5pmweb.com/api/dev/service/get/projects/getAll?sessionId=<sessionId>

Also you can authorize each request using login and password instead of sessionId as in example below:
http://demo.5pmweb.com/api/dev/service/get/projects/getAll?_login=<login>&_password=<password>

<login> - you 5pm account username
<password> - password for provided username
<sessionId> - session string retrieved from first (authentication) request.

Examples:

include('xpmClient');

Sign In:

$client = xpmClient::getModuleInstance('authentication');

if ($remoteSessionId = $client->signIn($login, $password)) {
/** authorization succeed: use this sessionId for next requests **/
}
else {
/** not authorized **/
}

Sign Out:

$client = xpmClient::getModuleInstance('authentication');
$client->signOut();

Get projects list:

$client = xpmClient::getModuleInstance('projects');
$list = $client->getAll();

Add/Edit project:

$projectId =

$projectsClient = xpmClient::getModuleInstance('projects');
if ($projectId) {
$project = new Base($projectsClient->getById($projectId));
}
else {
$project = new stdClass();
}

$project->name = 'Project name';
$project->description = 'project description';
$project->priority = 1; /** 1 - 4 **/
$project->status = 1; /** 1 - 3 **/

try {
if ($project->id) {
$res = $projectsClient->update($project);
}
else {
$res = $projectsClient->add($project);
}
}
catch (Exception $e) {
$error = $e->getMessage();
}

Remove project:

$client = xpmClient::getModuleInstance('projects');
$client->remove($id);

WSDL Examples:

Simple code example in PHP:

SimpleAPIExample.zip - simple API usage with demo Client class (PHP)

Last updated: January 11, 2010

Do you have questions?

Email us at: support@5pmweb.com

Bored in your cubicle and waiting for 5pm?
Play The Office Space game to kill some time

Bookmark:


Home \| Blog \| Newsletters \| 5pm API \| Contact \| 5pm Twitter \| Privacy Policy \| Terms of Use \| Site Map Subscribe to 5pm™ updates: © 2007-2010 QG \| Software.com