Application Programming Interface (API)

This document describes how to use the AceProject API to develop your own tools to retrieve and manage your data. This guide is intended for developers and includes information about using the API as well as access to the API Explorer with code samples. Do not hesitate to contact us should you require additional information or technical support.

The API is always under development. Changes to the data model and to functions often occur, but we do our best to minimize the impact of such modifications. We can’t guarantee that external tools developed using this API won’t need extra development after a new version of the API is released.

Examples

Click here to download an example using a Winform. Here is another example to create a project, create a task, and upload a document to a task.

Video Example

The following video shows how a novice user can access and retrieve information from AceProject into Microsoft Excel (no programming required):

Watch Video (7:26)

Table of contents

Getting started

To start using the AceProject API, you need:

  • Your Account Name: Your account name (AccountId) is the subdomain found in the URL (http://account.aceproject.com). If you do not have an account, you can create one for free here.
  • A Login name: A Username: a valid username associated to an active user within the account.
  • A Password: a valid password associated to the provided username.

First Steps

Getting Public Settings

  1. The GetPublicSettings function returns various public fields with information about the account.

Getting a GUID

  1. The Login function requires a valid username and password for an active user within the account.
  2. The function returns a GUID with various user related information. The GUID necessary for all other calls to the API. It is valid for a predetermined period of time and will then automatically expire after 8 hours of inactivity.

Parameters: Data types and formats

The API uses various data types and formats. Here are a few important details when calling and using the API

Dates

  1. Dates must always be provided using the following format: YYYY-MM-DD. For example, 23 Febuary 2011 would be 2011-02-23.

Time

  1. Hours use 0 through 24 standard.
  2. Time must always be provided using the following format: HH:MI:SS. For example, 13:20:55
  3. When used with dates, hours will be provided in this format: YYYY-MM-DD HH:MI:SS

Numbers

  1. Decimal values must always be sent with a period (.) as the decimal separator and do not require hundred separators. Do not use comma, space or any other character.

Non mandatory parameters vs. empty values

  1. When a parameter is non mandatory and you do not wish to provide or change a value for the parameter, do not mention it within the querystring when calling the API.
  2. If you want to pass an empty value for the parameter, you must use parameter=NULL.

Default values

  1. Some parameters have predefined default values. Default values can be specific settings or NULL when a parameter is non mandatory.
  2. When retrieving the function examples through the API Explorer, default values are automatically set in the HTTP Get example code. You can change theses values to any valid input when needed.

Return formats

You can provide, for each call, a desired format.

  1. Dataset: format=ds
  2. RecordSet: format=rs
  3. JSON: format=json – Still BETA, no support provided

Error Messages

When the API returns an error, different message types are predefined. Check the MESSAGE_TYPE column for one of these types.

  • MSG_FUNCTIONAL: Returned when a user inputs invalid data.
  • MSG_LOGOUT: Returned when the provided GUID is expired or invalid.
  • MSG_PERMISSION: Returned when the user doesn’t have sufficient privileges to access the function or related data.
  • MSG_TECHNICAL: Returned when a technical problem occurs within the API. This can happen if the database is unavailable or an unexpected behaviour occurs within the API code. For hosted accounts, an email with detailed error information is sent to the AceProject technical staff. For Intranet versions, error messages are logged either in the Windows Event Log or in a log file located in the files folder of the Intranet installation.
  • MSG_MESSAGE: This message type is used to send feedback to the calling application. It is typically used for information purposes and does not mean an error has occured.

Timezones

Timezones are now automatically managed in AceProject through the API. Each account has a defined timezone and each user can either use the account default timezone or specifies its own. Upon login, the GUID is linked to the user, thus the API knows what timezone is currently in use by the user for each call. When providing date and time values, the API will convert time to UTC and save that value in the database. When retrieving information from the database, the API will convert the UTC time to the user’s timezone. There is no need for any conversions on the client end as long as the appropriate GUID is being used.

Functions

Here is a list of available API functions to access and manage data within your AceProject account. Click on the function name to access the API Explorer which provides detailed information about the parameters and sample .Net code.

Authentication

  1. GetPublicSettings
  2. Login
  3. Logout
  4. SetLanguage

Account Configuration

  1. GetAccount
  2. SaveAccount
  3. GetTimeZonesList
  4. GetUserGroups
  5. SaveUserGroup
  6. DeleteUserGroup
  7. GetProjectTypes
  8. SaveProjectType
  9. DeleteProjectType
  10. GetProjectPriorities
  11. SaveProjectPriority
  12. DeleteProjectPriority
  13. GetProjectStatuses
  14. SaveProjectStatus
  15. DeleteProjectStatus
  16. GetClients
  17. SaveClient
  18. DeleteClient
  19. GetTimeTypes
  20. SaveTimeType
  21. DeleteTimeType
  22. GetExpenseTypes
  23. SaveExpenseType
  24. DeleteExpenseType

Users

  1. GetUsers
  2. SaveUser
  3. GetUserNotepad
  4. SaveUserNotepad
  5. DeleteUserItems
  6. DeleteUser
  7. GetTotals

Projects

  1. GetProjectAccess
  2. GetProjects
  3. CreateOrCopyProject
  4. UpdateProject
  5. DeleteProject
  6. AssignUserProject
  7. UnAssignUserProject

Project Configuration

  1. GetTaskTypes
  2. SaveTaskType
  3. DeleteTaskType
  4. GetTaskPriorities
  5. SaveTaskPriority
  6. DeleteTaskPriority
  7. GetTaskStatuses
  8. SaveTaskStatus
  9. DeleteTaskStatus
  10. GetTaskGroups
  11. SaveTaskGroup
  12. DeleteTaskGroup

Tasks

  1. GetTasks
  2. GetTaskComments
  3. GetTaskDependencies
  4. GetTaskHistory
  5. GetNewTaskSettings
  6. SaveTask
  7. MoveOrCopyTask
  8. DeleteTask
  9. DeleteTaskComment
  10. GetAssignedUserList
  11. AssignUserTask

Time Sheets

  1. GetMyWeeks
  2. GetMyWorkItems
  3. CreateWeek
  4. GetNewTimeSettings
  5. SaveWorkItem
  6. DeleteWorkItem
  7. GetClock
  8. OpenClock
  9. CloseClock
  10. DeleteClock
  11. GetTimeReport

Expenses

  1. GetMyExpenses
  2. SaveExpense
  3. DeleteExpense
  4. GetExpenseReport

Messages

  1. GetMessages
  2. SaveMessage
  3. DeleteMessage

Discussion Forum

  1. GetDiscussionSubject
  2. SaveDiscussionSubject
  3. DeleteDiscussionSubject
  4. GetDiscussionMessage
  5. SaveDiscussionMessage
  6. DeleteDiscussionMessage

Leave a Reply