Tidsbanken Employee Data Sync Integration Guide

Tidsbanken Employee Data Sync Integration Guide

Reference General Setup

Before configuring this integration, please complete the Simployer HRM Integration – General Setup Guide. This guide covers the initial steps for setting up integrations in Simployer and ensures that you have configured the necessary base settings for successful data sync.

1. Overview

What This Integration Does

This integration automatically synchronizes employee master data from Simployer One to Tidsbanken, eliminating manual data entry and ensuring your workforce management system stays up-to-date with your HR system.

What Gets Synced

• Employee Information: Names, employee numbers, contact details (email, phone)
• Personal Details: Birth date, Norwegian national ID (personnummer), home address
• Employment Details: Job title, hire date, employment percentage, employment type
• Department Assignment: Automatically maps and creates departments in Tidsbanken
• Bank Account Information: Payroll account number

Note: This employee data integration does NOT sync salary or compensation data.

2. Terminology & Field Mapping (Simployer One → Tidsbanken)

Key Field Names

Employment Type Mapping

Simployer One Employment Type → Tidsbanken Employee Group

Important: Employment groups are only assigned when creating NEW employees. For existing employees, the employment group set in Tidsbanken will be preserved.

Additional Mapping Rules

• Email Priority: Work email is used first; if not available, private email is used
• Phone Numbers: The same work phone number is used for both mobile (Mobil) and home phone (TlfPrivat) in Tidsbanken
• Department Mapping: Departments are matched by name (case-insensitive). If a department doesn't exist in Tidsbanken, it will be created automatically
  
  

3. Before You Start (Employee / Data Requirements)

Mandatory Information

Before an employee can be synced to Tidsbanken, the following information MUST be present in Simployer One:

✅ Personal Information

• Employee Number (REQUIRED) - Must be numeric only (e.g., "12345" not "EMP12345")
• First Name (REQUIRED) - Cannot be empty
• Last Name (REQUIRED) - Cannot be empty
• Birth Date (Optional but recommended)
• Norwegian National ID - Personnummer (Optional, only Norwegian IDs are synced)
• Home Address (Optional - street, postal code, city)

✅ Contact Information

• Work Email or Private Email (Optional but recommended - at least one should be provided)
• Work Phone (Optional)

✅ Employment Details

• Job Title (Optional)
• Hire Date (Optional)
• Employment Percentage (Optional) - Enter as whole numbers: 100 for full-time, 50 for half-time, 75 for three-quarter time
• Employment Type (Optional - used only for new employees)
• Department (Recommended) - Employee will be assigned to default department "0" if not provided

✅ Bank Account

• Bank Account Number (Optional)

4. Field Rules & Formats

Validation Rules

Employees will be SKIPPED from sync if they fail these validations:

❌ Employee Number Format

• Rule: Must contain only numbers (0-9)
• Valid Examples: "12345", "001", "9999"
• Invalid Examples: "EMP12345", "A001", "12-34"
• Result if Invalid: Employee will NOT be synced to Tidsbanken

❌ Required Name Fields

• Rule: Both first name AND last name must be present
• Result if Missing: Employee will NOT be synced to Tidsbanken

Field Formatting

? Employment Percentage

• Format: Enter as whole numbers only

Examples:

• Full-time: Enter "100" (not "100%" or "1.0")
• Half-time: Enter "50"
• Three-quarter time: Enter "75"

Note: Do not use decimals like "50.5" - use whole numbers only

?? National ID (Personnummer)

• Supported: Only Norwegian national IDs (country code "NO")
• If an employee has multiple national IDs, only the Norwegian one is used

5. How Sync Logic Works

Core Concepts

New Employees vs Existing Employees

The integration automatically detects whether an employee already exists in Tidsbanken:

• Matching Logic: Employees are matched by their Employee Number.
• New Employees: If the employee number doesn't exist in Tidsbanken, a new employee record is created
• Existing Employees: If the employee number exists in Tidsbanken, the employee record is updated with new information from Simployer One

Department Management

The integration uses a smart department mapping system:

• Fetch Existing Departments: System retrieves all current departments from Tidsbanken
• Match by Name: Departments are matched using case-insensitive name comparison (e.g., "IT Department" = "it department")
• Auto-Create New Departments: If a department exists in Simployer One but not in Tidsbanken, it's automatically created

Assign Employees:

• With Department Match: Employee is assigned to the matched Tidsbanken department
• New Employee, No Match: Assigned to default department (ID: "0")
• Existing Employee, No Match: Keeps their current Tidsbanken department assignment

Employment Group Assignment

• New Employees: Employment type from Simployer One is mapped to Tidsbanken employee group (AnsattGruppeId)
• Existing Employees: Employment group is PRESERVED from Tidsbanken and NOT updated by the sync

Rationale: This allows you to manage employment groups directly in Tidsbanken for existing employees.

Examples

Example 1: New Employee Creation

Scenario: You hire a new employee "John Smith" with employee number "12345"

In Simployer One:

• Employee Number: 12345
• Name: John Smith
• Department: IT Department
• Employment Type: Permanent Employment
• Employment Rate: 100

What Happens:

• Integration checks Tidsbanken - employee 12345 doesn't exist ✓
• Checks if "IT Department" exists in Tidsbanken:
  • If YES: Uses that department ID
  • If NO: Creates "IT Department" in Tidsbanken, then uses its ID
• Maps "Permanent Employment" to Tidsbanken employee group "Permanent employment"
• Creates new employee in Tidsbanken with all information

Example 2: Existing Employee Update

Scenario: Employee "Jane Doe" (employee number "54321") changes her email and phone

Changes in Simployer One:

• Work Email: jane.doe@company.com (updated)
• Work Phone: +47 12345678 (updated)

What Happens:

• Integration finds employee 54321 already exists in Tidsbanken ✓
• Updates email (Epost) and phone (Mobil, TlfPrivat) in Tidsbanken
• Preserves existing employment group in Tidsbanken (doesn't change it)
• Preserves existing department if no new department match found

6. What You Can Change in Tidsbanken

? Safe to Change (NOT overwritten by sync)

You can manually update these fields in Tidsbanken without worrying about sync overwriting them:

• Employment Group (AnsattGruppeId) - For existing employees only. Once an employee is created, their employment group won't be updated by sync
• Department Assignment - If you manually change an employee's department in Tidsbanken and there's no matching department name in Simployer One, your manual assignment will be preserved
• Any fields not listed in the field mapping table - These are never touched by the integration

⚠️ Will Be Updated by the Sync

These fields are managed by Simployer One and will be overwritten on every sync:

• First Name (Fornavn)
• Last Name (Etternavn)
• Email (Epost)
• Mobile Phone (Mobil)
• Home Phone (TlfPrivat)
• Birth Date (Født)
• Address (Adresse, Postnummer, Poststed)
• Job Title (Tittel)
• Hire Date (AnsattDato)
• Employment Percentage (Stillingsprosent)
• National ID (Personnummer)
• Bank Account (Lønnskonto)
• Department (AvdelingId) - If there's a matching department name in Simployer One
• Active Status (Aktiv)

⚠️ Important: If you manually update any of these fields in Tidsbanken, your changes will be overwritten the next time the integration runs.

Best Practice

• ✅ Make changes in Simployer One for all synced fields to ensure consistency
• ✅ Use Tidsbanken for fields that are NOT synced (like work schedules, time tracking data, and other Tidsbanken-specific features)

7. Setup Notes & Important Behaviors

Before Integration Setup

✅ Starting Fresh (No Employees in Tidsbanken)

If you're setting up Tidsbanken for the first time:

• Verify Employee Numbers: Ensure all employee numbers in Simployer One are numeric only
• Verify Required Fields: Check that all employees have first name and last name
• Review Departments: Note which departments will be created in Tidsbanken
• Set Employment Rates: Enter employment rates as whole numbers (100, 50, 75, etc.)
• Use Employee Scope: For testing, use employee scope to sync a small set of Employees first

✅ Employees Already Exist in Tidsbanken

If you have existing employees in Tidsbanken:

• Match Employee Numbers: Ensure employee numbers in Simployer One match those in Tidsbanken
• Backup Important Data: Document any custom fields or data in Tidsbanken that might be important
• Understand Update Behavior: Existing employee data will be updated with Simployer One data
• Employment Groups: Existing employment groups will be preserved (not overwritten)
• Test First: Start with a small employee scope to validate behavior

After Integration Setup

? Post-Setup Checklist

• Verify Sync Results: Check integration logs to confirm employees synced successfully
• Review Departments: Confirm departments were created correctly in Tidsbanken
• Check Employee Data: Spot-check a few employees to verify data accuracy
• Monitor Skipped Employees: Review integration response for any skipped employees and fix validation issues
• Set Up Regular Monitoring: Schedule regular checks of integration logs

Important Behaviors to Remember

? No Employee Deletion

• The integration does NOT delete employees from Tidsbanken
• If an employee is removed from Simployer One, they remain in Tidsbanken
• You must manually deactivate or delete employees in Tidsbanken if needed

? Employee Number Uniqueness

• Employee numbers must be unique in both systems
• Duplicate employee numbers will cause sync failures
• Always verify uniqueness before adding new employees

? Department Creation

• New departments are created automatically during sync
• Department names must match exactly (case-insensitive) for mapping
• For testing environments: Limit the number of departments to avoid creating too many test departments

8. Troubleshooting

Common Sync Issues

Employee Not Syncing - Troubleshooting Steps

If an employee is not appearing in Tidsbanken, follow these steps:

Step 1: Check Integration Logs

• Review the integration response for the sync run
• Look for the employee in "skipped items" or "failed items" sections
• Note the specific error message

Step 2: Validate Required Fields

In Simployer One, verify the employee has:

• ✅ Employee Number - numeric only (no letters or special characters)
• ✅ First Name - not empty
• ✅ Last Name - not empty

Step 3: Check Employee Number Format

• Open the employee record in Simployer One
• Verify employee number contains ONLY numbers: 0-9
• Remove any letters, spaces, dashes, or special characters

Example fixes:

• "EMP-123" → "123"
• "A001" → "001"
• "12 34" → "1234"

Step 4: Verify No Duplicates

• Check if another employee in Tidsbanken already has the same employee number
• Employee numbers must be unique

Step 5: Re-run the Integration

• After fixing validation issues, trigger the integration again
• Check the logs to confirm the employee synced successfully

Department Not Mapping Correctly

Issue: Employee is assigned to wrong department or default department "0"

Common Causes & Solutions:

• Department Name Mismatch:
  • Check department names in both systems
  • Names must match (case doesn't matter: "IT" = "it" = "It")
  • Check for extra spaces or special characters
• Employee Not Assigned to Department:
  • Verify employee is assigned to a department in Simployer One
  • Check the "Department" field in the employee record
• Department Not Created Yet:
  • First sync creates the department automatically
  • Second sync will then assign employees correctly
  • Run the integration twice if needed