Getting Started with the Reporting API

Use these steps to get started with fetching data from TimeLog.

Accessing the Reporting API requires a special set of Reporting API credentials and a SiteCode both available in the System Administration in TimeLog.

This guide is using the TimeLog SDK and all example are written in C#. However, the API does not require .NET for interaction, but the SDK is (as of writing) only available for .NET.

1. Get URL

Take note of your TimeLog URL. In most cases, it would follow the pattern below. [X] is replaced by a number and the [account name] is the same you use for login.

https://app[X].timelog.com/[account name]/service.asmx

2. Activate the API and get credentials

Using a user with the standard system administrator role or similar, activate the API endpoint through the system administration. Click the personal menu (top right corner), choose System Administration, then Integrations and API then API settings (SOAP).

Request the Reporting API SiteCode and store it. Enter the special Reporting API credentials to use for the API requests.

Enable all the methods you need (for testing credentials ensure that ValidateCredentials is turned on) and as a best practice we encourage all to ensure HTTPS for all API connections.

3. Test the credentials

You should test your URL and credentials in the browser by navigating to the Reporting API endpoint and finding the method ValidateCredentials to execute a request.

4. Setup your project

Create a new .NET project, download the Reporting API DLLs from GitHub.

Add the DLLs as references in your project.

Add the following keys to the appSettings-section in web.config or app.config. And fill them with appropriate values as in step 2.

<add key="TimeLogProjectUri" value="" />
<add key="TimeLogProjectReportingSiteCode" value="" />
<add key="TimeLogProjectReportingApiId" value="" />
<add key="TimeLogProjectReportingApiPassword" value="" />

If you are not using the SDK, instead find the service URLs and add the web service references to your project. You may find the full source code for the .NET SDK on GitHub and copy some of the same constructs to other languages.

5. Prepare the request

In the SDK use the ServiceHandler.Instance.TryAuthenticate-method directly.

if (ServiceHandler.Instance.TryAuthenticate())
{
    Console.WriteLine("Success");
}
else
{
    Console.WriteLine("Failed");
}

6. Execute other methods

Now you are ready to access other services. Inside the TryAuthenticate construct from step 5.

The example below will get a list of customers with key information only (to use for a drop down).

var customersRaw = ServiceHandler.Instance.Client.GetCustomersShortList(
    ServiceHandler.Instance.SiteCode,
    ServiceHandler.Instance.ApiId,
    ServiceHandler.Instance.ApiPassword,
    CustomerStatus.All,
    AccountManager.All);
if (customersRaw.OwnerDocument != null)
{
    var namespaceManager = new XmlNamespaceManager(customersRaw.OwnerDocument.NameTable);
    namespaceManager.AddNamespace("tlp", "http://www.timelog.com/XML/Schema/tlp/v4_4");
    var customers = customersRaw.SelectNodes("tlp:Customer", namespaceManager);
    if (customers != null)
    {
        foreach (XmlNode customer in customers)
        {
            var customerName = customer.SelectSingleNode("tlp:Name", namespaceManager);
            if (customerName != null)
            {
                Console.WriteLine(customerName.InnerText);
            }
        }
    }
}
else
{
    Console.WriteLine("Failed to authenticate to reporting API");
}

Note that the Reporting API SDK provides strongly typed classes for default parameters. In the example above notice CustomerStatus.All and AccountManager.All which provides the appropriate default value for getting all (in this case) customers back.

7. Get Creative

Now it is time to get creative and use the TimeLog data for analytics, synchronization etc.

Get in contact with us for recommendations on usage, and if you have ideas for new methods - or if you encounter bugs.