Setup

Setting up TimeLog API is easily done. First, you need to activate TimeLog API and create an API Login. Then you need to request your Site Code and finally enable the methods you are going to use.

Follow the instructions below to set up TimeLog API.

Activation

Before you can begin using the TimeLog API it must be activated in your TimeLog Project account. Activation is swift and easy, but since it is located in the System Administration you must have the permission level of a system administrator to perform the activitation.

Activating TimeLog API

Go to the System Administration in your TimeLog Project – press F10 after you have logged in – and locate and click on "TimeLog API – Settings" in the menu.

In the "Settings" tab select "Enable TimeLog API" and then click "Update".

Screenshot explaining activation.

Authentication

TimeLog API relies on a combination of an API Login and a Site Code for authentication to ensure only you can access your own data.

Create an API Login

You need to create an API Login for TimeLog API. The API Login is passed when requesting API methods.

Your API Login consists of an API ID and an API Password. Both are entered in the "API Login" panel in the "Settings" tab. You will be asked to repeat the password to avoid misspellings and typos. Click on "Update" to save your API Login.

Screenshot explaining API Login.

You can change your API Login later if necessary. However, if you build applications with a hard coded API Login, you will have to change the login information in these aswell, or they will break.

This is why TimeLog API is prepared for two different security models. The first is based on the API Login, while the second is based on the ApiUserAuthentication method explained below in "ApiUserAuthentication Method".

Changes to the API Login are logged. View the log from the "Log" tab in "TimeLog API – Settings".

Request your Site Code

Each TimeLog Project account has a unique ID known in TimeLog API as the Site Code.

To get your Site Code click "Request Site Code". The Site Code will be sent to the email address you have specified as yours in "Personal Profile". Site Code requests are handled manually by TimeLog's support and some time for delivery may be expected (typically one working day).

Since there can be more system administrators for one TimeLog Project account, you can see when and by who the Site Code was requested in the log located in the "Log" tab.

Screenshot explaining requesting a Site Code.

Secure communication (SSL)

To keep "foul players" from listening in on your communication make sure "Access only allowed via a secure http-connection (https)" is turned on. By doing so all communication is encrypted, and you should only consider disabling this if you use TimeLog API inside a secure network.

Web Services Methods

Once TimeLog API is activated and authentication is in place you can proceed and enable the web services methods. You can do so in the "Output Methods" tab. Right now only output methods are available, but methods for input are planned.

Enabling Output Methods

The output methods are organised in groups of methods. Check the methods you want to use. As an extra precaution it is only recommended to enable the methods you are actually going to use. Click "Update" to enable the selected methods.

Screenshot explaining enabling methods.

See here for detail documentation for each web services method.

Locating hostName and companyShortName

To locate your TimeLog Project account, each method needs to know your company's specific address, which consists of the hostName and companyShortName followed by "service.asmx".

An example: https://tl.timelog.com/yourcompany/service.asmx?wsdl
"tl.timelog.com" is the hostName, and "yourcompany" is the companyShortName.

Screenshot explaining hostName and companyShortName.

ApiUserAuthentication Method

As mentioned in the section "Authentication" above there are two different models for authentication with TimeLog API.

Screenshot explaining ApiUserAuthentication.

Security Model 1

Visual explanation of Security Model 1.

The first security model is based solely on the API Login and Site Code for authentication. The application makes a web service method call to TimeLog API passing the Site Code and API Login. TimeLog API then retrieves the data from the database and returns the result as data in XML-format to the application.

This model is useful for solutions like intranets and extranets, where the user is already logged in, and where access is controlled by the login from that solution. However, it is not possible to differentiate data access based on permission levels in TimeLog Project.

Security Model 2

Visual explanation of Security Model 2.

The second security model uses the ApiUserAuthentication method. This is a special method which makes it possible to differentiate applications based on the user login and permission level in TimeLog Project.

Create a login function in your application, which passes the Site Code and TimeLog Project login to the ApiUserAuthentication method. TimeLog API validates the Site Code and login against the database. If successful the ApiUserAuthentication method returns user information and permission level from TimeLog Project along with the API Login.

You can now differentiate your application based on the user's permission level in TimeLog Project. Use the returned API Login along with the Site Code when making calls to other web services methods.