Staff Service Integration

Digital ID can integrate with the Staff Service to use it as the sole source of truth for staff data. When enabled, Digital ID automatically syncs staff information, photos, and signatures from Staff Service, and handles ID card revocation automatically.

Overview

When Staff Service integration is enabled:

  • Staff data (name, employee reference, photo, status) syncs automatically from Staff Service
  • Staff signatures from Staff Service are displayed on digital ID cards
  • Real-time updates are received via webhooks when staff data changes
  • Digital ID employees are automatically linked to Staff Service people records
  • ID cards are automatically revoked when staff are deactivated in Staff Service

Automatic Revocation

When a staff member is deactivated in Staff Service, their Digital ID card is automatically revoked via webhook. No manual action is required in Digital ID - the revocation happens immediately when the deactivation occurs in Staff Service.

Configuration

Step 1: Create API Key in Staff Service

Before configuring Digital ID, you need to create an API key in Staff Service:

  1. Log in to Staff Service as an organisation administrator
  2. Navigate to Admin → API Keys (in the Admin dropdown menu)
  3. Click "Create API Key"
  4. Enter a descriptive name (e.g., "Digital ID Integration")
  5. Click "Create API Key"
  6. Copy the API key immediately - it will only be shown once!

Step 2: Configure Digital ID Settings

Configure Staff Service integration in Digital ID's web interface:

  1. Log in to Digital ID as an organisation administrator
  2. Navigate to Admin → Organisation → Staff Service (in the dropdown menu)
  3. Enable Staff Service Integration:
    • Check the "Enable Staff Service Integration" checkbox
    • Enter the Staff Service URL (e.g., http://localhost:8000 or https://staff.yourdomain.com)
    • Paste the API Key you copied from Staff Service
    • Set the Sync Interval (default: 3600 seconds = 1 hour)
  4. Click "Test Connection" to verify the URL and API key are correct (optional)
  5. Click "Save Settings"

Settings Storage

Settings are stored in the database and take effect immediately. No need to edit .env files or restart the server.

Data Synchronisation

Automatic Sync

When Staff Service integration is enabled, data syncs automatically in several ways:

  • On-Demand Sync: When an employee record is accessed, if it's linked to Staff Service and data is stale, it syncs automatically
  • Periodic Sync: Run the sync script via cron to sync all staff periodically
  • Webhook Sync: Real-time sync when Staff Service sends webhook events

Manual Sync

You can manually sync all staff from Staff Service:

  1. Go to Admin → Manage Employees
  2. Click "Sync from Staff Service" button
  3. The system will sync all staff members and create employee records for new staff

Sync Script

For automated periodic syncing, you can run the sync script manually or via cron:

# Sync all organisations
php scripts/sync-staff-service.php

# Sync specific organisation
php scripts/sync-staff-service.php 1

Add to crontab for automatic syncing:

# Sync every hour
0 * * * * cd /path/to/digital-id && php scripts/sync-staff-service.php >> /var/log/staff-sync.log 2>&1

Webhook Configuration

To receive real-time updates from Staff Service (including automatic ID card revocation), configure webhooks in Staff Service:

  1. In Staff Service, go to Admin → Webhooks
  2. Create a new webhook pointing to: 
    https://your-digital-id-domain.com/api/staff-service-webhook.php
  3. Select the events you want to receive:
    • person.created - New staff member created
    • person.updated - Staff member updated
    • person.deactivated - Staff member deactivated (triggers automatic ID card revocation)
    • signature.uploaded - Signature uploaded/updated
    • photo.updated - Photo updated
  4. Set the webhook secret in Digital ID's Staff Service settings (optional, for security)

Important

Webhooks are required for automatic ID card revocation. Without webhooks configured, you'll need to manually revoke ID cards when staff are deactivated in Staff Service.

Automatic ID Card Revocation

When Staff Service integration is enabled with webhooks configured:

  • When a staff member is deactivated in Staff Service, a webhook event is sent to Digital ID
  • Digital ID automatically:
    • Sets the employee's is_active flag to false
    • Revokes all active ID cards for that employee
    • Marks the revocation as system-initiated (from Staff Service)
  • The revocation takes effect immediately - revoked cards cannot be verified
  • No manual action is required in Digital ID

Benefits

  • No need to manually revoke ID cards when staff leave
  • Immediate revocation ensures security
  • Single source of truth - manage staff in Staff Service, Digital ID follows automatically
  • Complete audit trail - all revocations are logged

Employee Management

In the employee management pages (/admin/employees.php and /admin/employees-edit.php):

  • Sync Status: Shows if employee is linked to Staff Service
  • Last Sync Time: Displays when data was last synced
  • Sync Button: Manual sync button to refresh data from Staff Service
  • Bulk Sync: "Sync from Staff Service" button to sync all employees

Signature Display

When an employee is linked to Staff Service and has a signature:

  • Signature is automatically fetched from Staff Service API
  • Signature URL is cached in employees.signature_url
  • Signature is displayed on the digital ID card below the photo
  • Signature updates automatically when synced

Standalone Mode

If Staff Service integration is disabled or unavailable:

  • Digital ID operates independently
  • Employees are managed locally
  • No external API calls are made
  • All functionality works as before
  • ID cards must be revoked manually through the admin interface

Troubleshooting

Staff Service Not Available

If the connection test fails:

  • Check STAFF_SERVICE_URL is correct
  • Verify STAFF_SERVICE_API_KEY is valid
  • Ensure Staff Service is accessible from Digital ID server
  • Check firewall/network settings

Sync Failures

If syncing fails:

  • Check error logs: error_log() messages
  • Verify API key has correct permissions
  • Ensure employee reference matches between systems
  • Check database connection and table structure

Webhook Not Working

If webhooks aren't being received:

  • Verify webhook URL is accessible from Staff Service
  • Check webhook secret matches in both systems (if configured)
  • Review webhook logs in Staff Service
  • Check firewall allows incoming webhook requests
  • Ensure the webhook endpoint is publicly accessible (if Staff Service is on a different server)

Data Mapping

The following data is synced from Staff Service to Digital ID:

Staff Service Digital ID
people.id employees.staff_service_person_id
people.first_name users.first_name (via user_id)
people.last_name users.last_name (via user_id)
people.employee_reference employees.employee_reference
people.photo_path employees.photo_path
staff_profiles.signature_path employees.signature_url
people.is_active employees.is_active

Additional Resources

For detailed technical information about the Staff Service integration, see the INTEGRATION.md file in the project root.