Using a Data Warehouse with Tidsbanken Data

This guide provides step-by-step instructions for integrating Tidsbanken data into a data warehouse. It covers how to perform an initial historical data load, set up incremental updates, handle deleted records, and retrieve live attendance information — either through API polling or real-time webhooks. By following this manual, you can ensure your data warehouse remains accurate, up to date, and optimized for reporting, analytics, and operational monitoring.

1. Extracting Historical Data

Purpose: Populate your data warehouse with an initial dataset. Steps:

  1. Decide how far back in time you want to retrieve data.

  2. Use the Get Timeline endpoint: Tidsbanken API – Get Timeline

  3. Fetch all relevant records for the chosen date range.

Tip: This is typically a one-time operation to establish your historical baseline.

2. Setting Up an Integration for Registered Timelines

Purpose: Keep your warehouse updated with new or modified timeline entries. Steps:

  1. Schedule a recurring job at your preferred interval (e.g., hourly, daily).

  2. Use the Get Timeline endpoint again.

  3. Apply a filter on the EndretDato (Modified Date) field to retrieve only the most recent changes instead of the entire dataset each time.

    • Example: Set EndretDato to “current date minus 1 day” to capture the last 24 hours.

  4. Use the Timeline ID as the primary key in your warehouse to prevent duplicate entries.

Tip: This incremental load approach improves performance and reduces API calls.

3. Retrieving Deleted Timelines

Purpose: Ensure your warehouse reflects deletions from Tidsbanken. Steps:

  1. Use the Get Deleted Since endpoint: Tidsbanken API – Get Deleted Since

  2. Use the same date filter as in step 2 (EndretDato) to capture deletions within the same time window.

  3. Remove or mark these records as deleted in your warehouse.

Note: Deleted timelines are not included in the standard timeline dataset, so this step is essential for data accuracy.

4. Live Data (Currently Clocked-In Employees)

You have two main options for retrieving live attendance and activity data:

Option A – Polling the API

  • Use the Get Clocked-In endpoint: Tidsbanken API – Get Clocked-In

  • This endpoint returns:

    • Employees currently clocked in.

    • The activity they are clocked in on.

  • When an employee changes activity:

    • A new timeline entry is created (retrievable via step 2).

    • A new record appears in the clocked-in endpoint.

  • When an employee clocks out:

    • A new timeline entry is created.

    • They no longer appear in the clocked-in endpoint.

  • Best for: Dashboards or systems that can tolerate short polling intervals (e.g., every 1–5 minutes).

Option B – Using a Webhook for Real-Time Updates

  • Instead of polling, you can subscribe to the Stemplestatus webhook: Tidsbanken Webhooks

  • The webhook sends events in real time when:

    • Status 0: Employee clocks in.

    • Status 1: Employee clocks out.

    • Status 2: Employee switches activity.

  • Each event includes detailed metadata such as employee ID, department, project, activity, and timestamps.

  • Important: To ensure you have the correct starting state, fetch the current clocked-in list via the Get Clocked-In endpoint before processing webhook events.

  • Best for: Systems that require immediate updates without frequent API polling.

5. Recommended Data Flow Architecture

  1. Initial Load: Run step 1 to populate historical data.

  2. Incremental Updates: Run step 2 and step 3 on a schedule.

  3. Real-Time Monitoring: Use step 4 — either polling or webhook — for live dashboards.

  4. Data Warehouse Storage:

    • Primary Key: Timeline ID

    • Timestamps: For incremental filtering

    • Soft Delete Flag: For deleted timelines

Conclusion

By following the steps in this guide, you can establish a robust and efficient integration between Tidsbanken and your data warehouse. The outlined approach ensures that historical data, incremental updates, deletions, and live activity are all handled in a consistent and reliable way. Whether you choose scheduled API calls, real-time webhooks, or a combination of both, this setup will keep your warehouse synchronized and ready for reporting, analytics, and operational decision-making.