onepoint API

Introduction to our REST/Web Services API

onepoint REST/Web Services API

The preferred way to integrate onepoint PROJECTS with other systems is the REST/SOAP API. All Web Service methods are available both as REST and SOAP calls. The functionality of the current version of this new API is limited to accessing business objects of types user, project status (pipeline stage), project and task (activity). However, the API will be extended step by step to provide additional functionality.

Introduction

The onepoint REST/SOAP API is a session-oriented API that lets you access data stored in a onepoint Project repository via web service calls. Both the REST and the SOAP protocols are based on HTTP and work over http and secure https endpoints. Please note that the onepoint REST/SOAP API is session-oriented. Therefore, your HTTP client will have to be able to handle HTTP set-cookie responses.

The following description of services and calls is based on the REST version of the API. Each call description includes input parameters, an example request URL and a sample response. All calls are available in both the REST and the SOAP version. You can map the naming of the request parameters and response objects 1:1 to the SOAP version.

The REST and SOAP endpoints are made up of the base URL the onepoint server is running on (http://:/) plus the name of the respective API protocol ("rest" or "soap"). If the onepoint server is running on the local computer on port 8080 and the WAR package is named "opproject" then the SOAP and REST end points would be like in the following two examples:

  • REST: http://localhost:8080/opproject/rest
  • SOAP: http://localhost:8080/opproject/soap

In order to call a REST method all you need to do is to append the service name and the method name both with prefixed slashes ("/") - followed by the method parameters as outlined in the example request URLs. If you get an application-level error from a REST call you will get a special error response that will always have the same format which is not related to the type of request you made:

<errorResponse>
   <error code="main.error.NotSignedOn">
      <message>You are not signed on</message>
   </error>
</errorResponse>

A table of common errors will be made available at a later point in time.

Service Overview

Starting with onepoint Project 10 Update 1 the onepoint REST/SOAP API provides the following public services and methods. The public API will be extended in each release of onepoint Project based on the feedback of our customers and partners.

users

projects

tasks

Service: users

Method: signOn

The signOn method signs on a specific user using the specified password. On success, it returns the object for the signed-on user.

Request parameters:
  • login: The user name or login of the user
  • password: The password of the user. If you do not specify a valid encryption via a password prefix {encryption} the password is interpreted as a plain text password. Valid names for encryption are: plain, sha1
Example request:

http://localhost:8080/opproject/rest/users/signOn?
   login=cs&password={plain}test

Example response:

<signOnResponse>
   <user id="2">
      <name>cs</name>
      <displayName>Claudia Schulz</displayName>
      <description></description>
      <source>0</source>
      <level>2</level>
      <active>true</active>
      <contact id="229377">
         <lastName>Schulz</lastName>
         <firstName>Claudia</firstName>
         <eMail></eMail>
         <phone></phone>
         <mobile></mobile>
         <fax></fax>
      </contact>
   </user>
</signOnResponse>

Method: signOff

The signOff method signs off the current user.

Request parameters:

None

Example request:

http://localhost:8080/opproject/rest/users/signOff

Example response:

<signOffResponse/>

Method: currentUser

The currentUser method returns the user object of the currently signed-on user.

Request parameters:

None

Example request:

http://localhost:8080/opproject/rest/users/currentUser

Example response:

<currentUserResponse>
   <user id="2">
      <name>cs</name>
      <displayName>Claudia Schulz</displayName>
      <description></description>
      <source>0</source>
      <level>2</level>
      <active>true</active>
      <contact id="229377">
         <lastName>Schulz</lastName>
         <firstName>Claudia</firstName>
         <eMail></eMail>
         <phone></phone>
         <mobile></mobile>
         <fax></fax>
      </contact>
   </user>
</currentUserResponse>

Service: projects

Method: listProjectStatuses

The listProjectStatuses method returns a list of all configured project statuses.

Request parameters:

None

Example request:

http://localhost:8080/opproject/rest/projects/listProjectStatuses

Example response:

<listProjectStatusesResponse>
   <projectStatuses>
      <projectStatus id="688128">
         <sequence>0</sequence>
         <name>red</name>
         <color>0</color>
         <active>true</active>
         <rgbColor>#bf0000</rgbColor>
      </projectStatus>
      ...
   </projectStatuses>
</listProjectStatusesResponse>

Method: listMyProjects

The listMyProjects method returns a list of all active projects the current users has access to (comparable to the MY WORK/Projects tool if you select "Observer" for the role filter).

Request parameters:

None

Example request:

http://localhost:8080/opproject/rest/projects/listMyProjects

Example response:

<listMyProjectsResponse>
   <projects>
      <project id="425993">
         <name>ALS v5</name>
         <type>3</type>
         <description>Automatic Landing System</description>
         <start>2009-09-07Z</start>
         <finish>2009-11-26Z</finish>
         <budget>0.0</budget>
         <savingsPotential>0.0</savingsPotential>
         <probability>100</probability>
         <archived>false</archived>
         <priority>3</priority>
         <projectPlan id="589826">
            <start>2009-09-07Z</start>
            <finish>2009-11-26Z</finish>
            <duration>472.0</duration>
            <complete>0.0</complete>
            <baseEffort>0.0</baseEffort>
            <actualEffort>0.0</actualEffort>
            <remainingEffort>0.0</remainingEffort>
            ...
         </projectPlan>
         <projectStatus>32770</projectStatus>
         <accessLevel>64</accessLevel>
         <costsTrafficLight>0</costsTrafficLight>
         <customersTrafficLight>-1</customersTrafficLight>
         <datesTrafficLight>0</datesTrafficLight>
         <displayName>ALS v5</displayName>
         <managerTrafficLight>-1</managerTrafficLight>
         <qualityTrafficLight>-1</qualityTrafficLight>
         <resourcesTrafficLight>0</resourcesTrafficLight>
         <trafficLight>0</trafficLight>
      </project>
      ...
   </projects>
</listMyProjectsResponse>

Service: tasks

Method: listMyTasks

The listMyTasks method returns a list of all tasks the current user is currently assigned to (comparable to the MY WORK/Tasks tool).

Request parameters:

None

Example request:

http://localhost:8080/opproject/rest/tasks/listMyTasks

Example response:

<listMyTasksResponse>
   <activities>
      <activity id="655363">
         <name>Project start</name>
         <description/>
         <type>0</type>
         <attributes>0</attributes>
         <sequence>1</sequence>
         <outlineLevel>1</outlineLevel>
         <start>2009-12-07Z</start>
         <finish>2009-12-18Z</finish>
         <duration>80.0</duration>
         <leadTime>0.0</leadTime>
         <followUpTime>0.0</followUpTime>
         <complete>50.0</complete>
         <priority>3</priority>
         <status>0</status>
         <baseEffort>80.0</baseEffort>
         <unassignedEffort>0.0</unassignedEffort>
         <actualEffort>40.0</actualEffort>
         <remainingEffort>40.0</remainingEffort>
         <payment>0.0</payment>
         <deleted>false</deleted>
         <expanded>false</expanded>
         <template>false</template>
         <effortBillable>100.0</effortBillable>
         <wbsCode>1.1</wbsCode>
         ...
      </activity>
      ...
   </activities>
</listMyTasksResponse>

Ready for the next step?

onepoint PROJECTS is the first 100% web-based, fully-integrated project and portfolio management solution that does not force you to compromise between usability and deploying a "real" PPM solution. Interested?

Watch Tutorial Videos Get Free Trial