TimeMapAPI

Click here for a complete list of operations.

A_IntroductionToTimeMapAPI

Introduction to TimeMap API Webservice

The TimeMap API is a REST webservice returning data in JSON format.

Production and Test API

When developing API integration you should use our test-service. The test service have high'er fair usage limits and you will not destroy/update any production data.

The test environment is updated every night with production data. Therefore any changes made in the test environment will be overwritten daily.

When setting access up for the first time the please set same API-password in production AND test environment (please see below), as the password entered in production will be copied to test the next night.

Power Bi, Excel and other non-controlled query tools

Please note that these tools are NOT ALLOWED to call our PRODUCTION ENVIRONMENT!

Theese tools generates a lot of uncontrolled queries to our API's that can impact online performance of our system. Using these tool on production environment is a violation of our Subscription terms and access to the API will be blocked if used on production environement.

Test Addresses

Test Webservice API: https://testservice.timemap.dk/TimeMapApi.asmx

Test TimeMap Admin: https://testasp.timemap.dk/admin

Production Addresses

Production Webservice API: https://service.timemap.dk/TimeMapApi.asmx

production TimeMap Admin: https://asp.timemap.dk/admin

Authorization

To setup access the TimeMap API you'll need to have access to the TimeMap Admin UI as an administrator.

If you are a third party developer and don't have access to the customers TimeMap system then please contact the customers TimeMap Admin and get a TimeMap user as you'll need access to validate your API integration data.

To call the TimeMap API functions you'll need three things:

API Key: An GUID unique for the customer
API Password: A password of your choice. Please use a strong password to protect your customers data!
Username: The email address of a employee in TimeMap. This user must exists

The API key is found in TimeMap Admin, menu Settings->Company (https://testasp.timemap.dk/admin/companymain.aspx).

The API Password is also set here. It's not possible to retrieve the password once set. If you forget the password you'll need to enter a new password.

In TimeMap all users is an Employee and the username is the Employees e-mail address. Therefore you will have to create a Employee with a email address in the TimeMap Admin.

Remember to create the same user and api-password in Production and in the Test environment. The API key will be the same for both environments.

Overview

The API is designed to allow customers transfer data between TimeMap and their other backend systems.

If possible we encourage you to collect data outside normal load times (06:00-18:00 on workdays) if you collects large datasets or loops multiple projects/employees. This will lower the load on our systems and make your requests quicker.

It's NOT designed to be used as dataprovider for online dashboards or statistic.

TimeMap is a OLTP system (online transaction processing system). Inserts and updates (punch in/out etc) will always have priority and conflict with heavy data selects required by dashboards and statistics.

If you wish to make dashboards and statistics based on data from TimeMap you should collect new data in batch and store the data in your own backend database and then make your statistics from your own dataset.
This will enable you to present data quick and smart without interfearing our systems (this is the reson for our fair usage limits).

In general you should cache employeeid's in your own database and use this when retrieving data from TimeMap. You could then once a day retrieve and update your employeeid's from TimeMap to ensure that your id's match the data in TimeMap.

The same goes for other datasets. If you wish to collect raw time-registrations there is no need to retrieve huge date-intervals if you cache in your own database. You could collect time-registrations e.g. twice a day and then once every week make retrieve the weeks registrations and look for modifications.

Examples

Below we have made a couple of examples on how to use the functions in our API.

We have made one simple example on how you call a JSON REST webservice from C#. The other examples is more a description on how to use your functions (and which to use)

Please read the examples even if you need another dataset or push other type of data - they represent the concept of how you could/should use the API.

If you collect data in Batch you should make a Windows Service or cron job to collect data

Simple C# example

If your use Visual Studio you could add a webreference to our webservice and get access to all the functions in your code. The reference path is: https://service.timemap.dk/TimeMapAPI.asmx?WSDL

This is a simple call in c# to get a list of employees:

using (var client = new YourNameSpace.TimeMapApiSoap.TimeMapAPISoapClient("TimeMapAPISoap"))
{
   string strJson = client.getEmployeeList("YourAPIKEY", "YourAPIPassword", "ValidUserName");
   JObject json = JObject.Parse(strJson);
   JArray empls = (JArray)json["EmployeeList"];
   if (empls!= null)
   {
      foreach (JObject empl in empls)
      {
         // Do something
         string EmplName = empl["FirstName"] + " " + empl["LastName"];
      }
   }
}

Download C# Sample Project here

Simple Javascript example

This is a simple call in javascript to get a list of employees using JQuery:

$.ajax({
   type: "POST",
   url: "https://testservice.timemap.dk/TimeMapAPI.asmx/getEmployeeList",
   data: "{'apikey': '', 'apipwd: '', username: ''}"
   contentType: "application/json; charset=utf-8",
   dataType: "json",
   headers: { "cache-control": "no-cache" },
   success: function(data) { console.log('Result:', data); yourFunctionCallRecievingData(data);},
   error: function(data) { console.log('API Error', data.responseText); if (json_errorMessage) { console.log('JSON Error: ', json_errorMessage); } }; },
   timeout: 10000
});

Download Javascript Sample Project here

Get Employee registrations

This is a conceptual example showing what functions to use and how.

If you need registrations from all users within a date interval then do like this:

Call getHourregistrations with your apikey, apipwd, username.
Leave SalaryNo and TimeMapID empty as this will retrieve all users data.
Set FromDate and ToDate to the dates you wish to retrieve, eg FromDate: '2021.12.16' and ToDate: '2021.12.17'
You should always set FromDate and ToDate as this is the only way to know what date interval is retrieved.
When your get the result set loop the JArray of JObjects (one for each registration in TimeMap) and store the data to your database.

In TimeMap you could have MANY registrations on one date. If you don't need all the details you could sum the records on project/task/absence for every date/employee to avoid to many rows in your database.

If you for some reson need to get only one employees data you should make sure you have a table containing the employee salaryno or TimeMapID.
You could make a field in your system to hold the salaryno/timemapid that the customer can update or you could call getEmployee and store all employees from TimeMap in your database.

When your have the salaryno/timemapid then make the same call as above, but specify the salaryno or timemapid

Please do not loop your Employee Table and make one call to getHourregistrations for every employee. This will be mush slower and cause more load on your system and on TimeMap.

Please Note: In TimeMap absence is stored as a registration in the same way as a work registration. The only difference is that the registration holds a absenceid/absencename. The AbsenceType specify if the records time-interval is to be included in the employees worktime and/or salary (Please see and store info about absence types with the function getAbsencetypes).

Get Futhure Absence

This is a conceptual example showing what functions to use and how.

If you need absence you'll need to retrieve hourregistrations as in TimeMap absence is stored as a registration in the same way as a work registration.
The only difference is that the registration holds a absenceid/absencename.
The AbsenceType specify if the records time-interval is to be included in the employees worktime and/or salary (Please see and store info about absence types with the function getAbsencetypes).

Therefore you could call getHourregistrations with your apikey, apipwd, username.
Leave SalaryNo and TimeMapID empty as this will retrieve all users data.
Set FromDate and ToDate to the dates you wish to retrieve, eg from today and one year ahead: FromDate: '2021.12.16' and ToDate: '2022.12.16'
When your get the result set loop the JArray of JObjects (one for each registration in TimeMap) and store the data to your database.

Please do not loop your Employee Table and make one call to getHourregistrations for every employee. This will be much slower and cause more load on your system and on TimeMap. Instead do a getHourregistrations call without employeeid/salaryno to get all employee registrations in the period.

Push projects/orders to TimeMap

This is a conceptual example showing what functions to use and how.

If you need transfor e new order from your ERP system you will need to create a new Project i TimeMap

In TimeMap employees can punch in/out from projects and change projects or task during the day.
A project is unique and only lives while the employees need to register time on that project. Therefore a order will be a project in TimeMap.

TimeMap also have tasks, but a task is a type of job-function that can be done be a employee on a project/order. A task could be "Meeting" or "Welding" and can be used on multiple projects.

Projects can be ordered in a hierarchy that is multiple levels (no limts). Some customers create thair customer as a project and then creates all this customers orders as subprojects for the customer-project.
This makes it easy for the employee to find the order by first selecting the customer (customer-project) ans the get a list of open projects/orders for that customer.

Use the function createProject with your apikey, apipwd, username to create or update a project.
The projectNo is the key between TimeMap and your backend system and should always be specified.
If the projectNo already exists in TimeMap we will update the project and if not we will create a new project.
Please see https://testservice.timemap.dk/TimeMapAPI.asmx?op=createProject for more parameters and description.

Please do not loop all your projects to update data in TimeMap. Call createProject when a new project is created or you need to update an existing project.

You should always specify a validFrom date when creating a project. The project will be visible for the employees from that date. If not specified the project will be visible imedially.

When the project is complete set the "validTo" date or set "competed" to 1.

When your need to get registrations for the project please call getProjectregistrations with the projectno parameter.

Support

If you need help with your integration the please contact our support by email on this address. Within office hours we will responde quickly:

support@timemap.dk

Function Descriptions

Test

The test form is only available for requests from the local machine.

SOAP 1.1

The following is a sample SOAP 1.1 request and response. The placeholders shown need to be replaced with actual values.

POST /TimeMapApi.asmx HTTP/1.1
Host: testservice.timemap.dk
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction: "http://tempuri.org/A_IntroductionToTimeMapAPI"

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <A_IntroductionToTimeMapAPI xmlns="http://tempuri.org/" />
  </soap:Body>
</soap:Envelope>

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <A_IntroductionToTimeMapAPIResponse xmlns="http://tempuri.org/">
      <A_IntroductionToTimeMapAPIResult>string</A_IntroductionToTimeMapAPIResult>
    </A_IntroductionToTimeMapAPIResponse>
  </soap:Body>
</soap:Envelope>

SOAP 1.2

The following is a sample SOAP 1.2 request and response. The placeholders shown need to be replaced with actual values.

POST /TimeMapApi.asmx HTTP/1.1
Host: testservice.timemap.dk
Content-Type: application/soap+xml; charset=utf-8
Content-Length: length

<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
  <soap12:Body>
    <A_IntroductionToTimeMapAPI xmlns="http://tempuri.org/" />
  </soap12:Body>
</soap12:Envelope>

HTTP/1.1 200 OK
Content-Type: application/soap+xml; charset=utf-8
Content-Length: length

<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
  <soap12:Body>
    <A_IntroductionToTimeMapAPIResponse xmlns="http://tempuri.org/">
      <A_IntroductionToTimeMapAPIResult>string</A_IntroductionToTimeMapAPIResult>
    </A_IntroductionToTimeMapAPIResponse>
  </soap12:Body>
</soap12:Envelope>

HTTP GET

The following is a sample HTTP GET request and response. The placeholders shown need to be replaced with actual values.

GET /TimeMapApi.asmx/A_IntroductionToTimeMapAPI? HTTP/1.1
Host: testservice.timemap.dk

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length

<?xml version="1.0" encoding="utf-8"?>
<string xmlns="http://tempuri.org/">string</string>