Overview

The Staff Service is a centralised staff management system designed for organisations where data ownership is critical. It serves as your single source of truth for all staff information, allowing you to maintain complete control over your data while feeding other systems without duplication or vendor lock-in.

Key Features

• Centralised Staff Database - One central database you own and control
• API & MCP Integration - Connect with existing systems without duplication
• Complete Data Ownership - Your data stays yours, no vendor lock-in
• Bidirectional Sync - Keep all systems in sync automatically
• Staff Self-Service - Staff can update their own personal details; sensitive changes are held for line manager approval before taking effect
• Digital Signatures - Capture and store staff signatures digitally
• Compliance Alerts - Automatic monitoring of registrations and qualifications
• Persistent Learning History - Link staff records to preserve training and skills across role changes
• Microsoft Integration - Seamless integration with Microsoft Entra and 365

Getting Started

To get started with the Staff Service, your organisation needs to be registered. If you're an organisation administrator, you can request access through the Request Organisation Access page.

For Staff Members

Once your organisation has access:

1. Register for an account using your organisation email address
2. Log in and go to My Profile → My Staff Details in the top navigation
3. Update your personal details — emergency contacts save immediately; other changes (name, address, bank details) are sent to your line manager for approval
4. Upload your profile photo and signature — both require manager approval before going live
5. You will be notified by email and by an in-app badge when your manager approves or rejects a change

See the Staff Self-Service section for a full explanation of which fields you can edit and how the approval process works.

For Administrators

As an organisation administrator, you can:

• Create and manage staff profiles
• Link staff to user accounts
• Assign staff to organisational units
• Review and approve self-service profile updates via Admin → Approve Changes
• Manage job descriptions and job posts
• Export staff data for reporting

Getting Digital ID Cards for Staff Members

After creating a staff member in Staff Service, they need an employee record in Digital ID to get a digital ID card. The process depends on whether Digital ID is integrated with Staff Service.

Setting Up Staff Service Integration

Before you can sync staff from Staff Service to Digital ID, you need to configure the integration:

Step 1: Create API Key in Staff Service

Web Interface (Recommended):

1. Log in to Staff Service as an organisation administrator
2. Go 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!

Command Line (Alternative):

1. Find your User ID and Organisation ID (check your profile URL or database)
2. Run the API key creation script:

   php scripts/create-api-key.php <user_id> <organisation_id> "Digital ID Integration"

   Example: php scripts/create-api-key.php 3 1 "Digital ID Integration"
3. Save the API key that's displayed - it won't be shown again!

Step 2: Configure Digital ID Settings

Where to paste the API key: Copy the API key from Staff Service and configure it in Digital ID's web interface. Each organisation in Digital ID should use their own API key from Staff Service.

Web Interface (Recommended):

1. Log in to Digital ID as an organisation administrator
2. Go to Admin → Organisation → Staff Service
3. Check "Enable Staff Service Integration"
4. Enter the Staff Service URL (e.g., http://localhost:8000)
5. Paste the API Key you copied from Staff Service (this key is unique to your organisation)
6. Click "Save Settings"

Alternative: .env File (for server administrators only - not recommended for multi-tenant setups):

The .env file approach is only suitable if you're running a single-tenant installation. For multi-tenant setups where multiple organisations use the same Digital ID instance, each organisation should configure their API key through the web interface, which stores it in the database per organisation.

USE_STAFF_SERVICE=true
STAFF_SERVICE_URL=http://localhost:8000
STAFF_SERVICE_API_KEY=your-api-key-from-staff-service-here
STAFF_SYNC_INTERVAL=3600

Note: Settings configured via the web interface take precedence over .env file settings. For multi-tenant deployments, always use the web interface so each organisation can have their own API key.

With Staff Service Integration (Recommended)

When Digital ID is configured to use Staff Service as the source of truth:

1. Automatic Sync: Go to Digital ID admin panel → Manage Employees → Click "Sync from Staff Service" button. This will automatically create employee records for all staff members from Staff Service.
2. Manual Creation (if needed): Go to Digital ID admin panel → Manage Employees → Click "Create New Employee" → Select the user from dropdown → Enter employee number → System will automatically link to Staff Service if a matching person is found.
3. Upload Photo (optional): Staff member can upload through their profile, or admin can upload directly.
4. View ID Card: Staff member logs in and navigates to "Digital ID Card" page - card is automatically generated.

Without Staff Service Integration (Standalone)

If Digital ID is not integrated with Staff Service:

1. Create User Account (if not already created): Staff member registers at Digital ID registration page, or admin creates user account.
2. Create Employee Record: Go to Digital ID admin panel → Manage Employees → Click "Create New Employee" → Select user → Enter employee number and display reference → Click "Create Employee".
3. Upload Photo (optional): Staff member can upload through their profile, or admin can upload/approve photos.
4. View Digital ID Card: Staff member logs in and navigates to "Digital ID Card" page.

Important Notes

• Employee Number: Should match the employee reference from your HR/payroll system. It's used for integration and cannot be changed after creation.
• User Account: Staff members need a user account in Digital ID to access their digital ID card. If they don't have one, they can register or an admin can create one.
• Photo: Recommended but not required for the digital ID card to be generated.
• Signature: If Staff Service integration is enabled and the staff member has a signature in Staff Service, it will automatically appear on their Digital ID card.

For detailed step-by-step instructions, see the Digital ID Workflow Guide.

API & MCP Integration

The Staff Service provides both REST API and MCP (Model Context Protocol) integration options for connecting with your existing systems.

API Key Management

API keys are used to authenticate external systems and applications that need to access Staff Service data. Organisation administrators can create and manage API keys through the web interface.

Creating an API Key

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", "HR System API")
5. Click "Create API Key"
6. Copy the API key immediately - it will only be shown once!

Managing API Keys

From the API Keys management page, you can:

• View all API keys for your organisation (you can only see keys created by your organisation)
• See when each key was created and last used
• Activate or deactivate keys (deactivated keys cannot be used for authentication)
• Delete keys that are no longer needed

Using API Keys

Include the API key in API requests using the Authorization header:

Authorization: Bearer YOUR_API_KEY

REST API

Our REST API provides programmatic access to staff data. All API endpoints require authentication using either:

• API Key - For external systems and automated integrations
• Session Authentication - For web applications on the same domain

Base URL

https://salmon-tarsier-739827.hostingersite.com/api/

Example: Get Staff Member

GET /api/staff-data.php?id=123
Authorization: Bearer YOUR_API_KEY

MCP Integration

For applications using Model Context Protocol (MCP), the Staff Service provides MCP-compatible endpoints that allow seamless integration with MCP-enabled systems.

Webhooks

Subscribe to webhooks for real-time notifications when staff data changes. Webhooks are sent for:

• New staff member creation
• Profile updates
• Status changes (active/inactive)
• Organisational unit assignments

Staff Profiles

Each staff member has a comprehensive profile. Fields are divided between those managed by administrators (employment data) and those the staff member can update themselves (personal data). See Staff Self-Service for details on the approval workflow.

Personal Information

Staff can update these themselves via My Staff Details.

• Name and date of birth (requires manager approval)
• Phone number (saves immediately)
• Emergency contacts (saves immediately — no approval delay)
• Home address (requires manager approval)
• Profile photo (requires manager approval)
• Digital signature (requires manager approval — only the staff member can change their own signature)

Financial & Identification

Staff can update these themselves, but all changes require manager approval before taking effect.

• National Insurance number
• Bank sort code, account number, and account name

Employment Details

Managed by administrators only.

• Job title and job post
• Employment start and end dates
• Line manager
• Organisational unit assignments
• Contracted hours and place of work

Compliance & Qualifications

• Professional registrations
• Qualifications and certifications
• Learning records
• Role history

Leave Management

Managed by administrators only.

• Annual leave allocation and usage
• Time in lieu
• Leave year dates

Staff Self-Service

Staff members can update their own personal details without needing to ask an administrator. To protect the integrity of the data, most changes are held in a queue and reviewed by the staff member's line manager before they take effect.

How to update your details

1. Log in and click My Profile in the top navigation
2. Select My Staff Details from the dropdown
3. Edit the fields you want to change and click Save Changes
4. For photos and signatures, use the upload forms at the bottom of the page

Which changes need approval?

Not all changes are treated the same. Emergency contact details are applied immediately because delays could cause real harm. Everything else with personal or financial significance is held for your manager to review first.

The approval chain

Pending changes are routed to the right person automatically based on your line manager setting:

• Your changes go to your line manager for review
• If your line manager also submits changes to their own profile, those go to their line manager
• This continues up the chain — no one approves their own changes
• Staff at the top of the chain (no line manager assigned) have their changes reviewed by an organisation administrator or HR

Notifications

The system notifies both parties at each step so nothing gets missed:

• When you submit a change — your manager receives an email and sees a red badge on the Approve Changes menu item
• When your manager reviews a change — you receive an email and see a blue badge on the My Staff Details menu item
• Visiting My Staff Details clears your badge and shows the full history of approved and rejected changes with any reasons given

If your change is rejected

Your manager must provide a written reason when rejecting a change. You will see this reason in your email notification and in the change history at the bottom of your My Staff Details page. You can then correct the submission and resubmit — resubmitting a field automatically replaces the previous pending request for that field.

For managers: reviewing changes

1. Click Admin → Approve Changes in the navigation (a red badge shows how many are waiting)
2. Each pending change shows the current value alongside the proposed value so you can compare them directly
3. For photos and signatures, both images are displayed side by side
4. Click Approve to apply the change immediately, or Reject to decline it with a reason
5. You can approve and reject individual fields independently within the same submission

Learning History & Record Linking

The Staff Service includes powerful features for maintaining complete learning and skills history, even when staff change roles or return to your organisation with different employee numbers.

Linking Person Records

When a staff member changes post, leaves and rejoins, or receives a new employee number, you can link their old and new person records. This preserves their learning history, qualifications, and skills without creating duplicate data.

How to Link Records

1. Navigate to the staff member's profile in the Staff section
2. Click on "Link Staff Records" (available in both view and edit modes)
3. Use the search form to find potential matches based on:
   • Email address
   • First and last name
   • Date of birth
4. Review the search results and click "Link Records" for the correct match
5. The system will create a bidirectional relationship between the records

What Gets Linked

When person records are linked, the following data becomes accessible across both records:

• Learning Records - All training, qualifications, and certifications
• Skills History - Professional skills and competencies

Note: Annual leave records, disciplinary records, and other employment-specific data are not transferred, as they relate to specific employment periods.

Searching Learning Records by Employee Reference

You can search for learning records using an employee reference number, which is useful when:

• A staff member has changed employee numbers
• You need to find historical training records
• You're verifying qualifications from previous employment periods

How to Search

1. Go to the Staff section
2. Click on "Search Learning Records by Employee Ref"
3. Enter the employee reference number
4. Review the results, which will show all learning records associated with that employee reference

Viewing Linked Records

Linked records are visible in several places:

• Staff Profile View/Edit - Shows all linked person records with relationship types
• Learning & Qualifications Section - Displays learning records from both current and linked records, clearly marked
• My Profile - Staff members can see their complete learning history, including records from linked profiles

Best Practices

• Link records as soon as you identify a match to preserve complete history
• Use the search functionality to find potential matches before creating new records
• Review linked records periodically to ensure accuracy
• Document the reason for linking in the relationship notes field

Unlinking Records

If records were linked incorrectly, administrators can unlink them from the "Link Srtaff Records" page. This removes the relationship but does not delete any data from either record.

Data Synchronisation

The Staff Service supports bidirectional data synchronisation with external systems, ensuring all your systems stay in sync without manual duplication.

Outbound Sync (Staff Service → Other Systems)

When staff data is updated in the Staff Service, changes can be automatically pushed to:

• Microsoft Entra / Azure AD
• Microsoft 365
• HR systems
• Rota systems
• Recruitment platforms
• Finance systems
• LMS systems

Inbound Sync (Other Systems → Staff Service)

The Staff Service can receive initial data from:

• Recruitment systems (new hires)
• HR systems (employment updates)

Sync Methods

• API Polling - External systems can poll the API for updates
• Webhooks - Real-time notifications sent to subscribed endpoints
• Scheduled Sync - Automated sync jobs run at regular intervals

Microsoft Entra/365 Integration

The Staff Service can integrate with Microsoft Entra ID (formerly Azure AD) and Microsoft 365 to synchronise user accounts and staff data, making Staff Service the central hub for identity management across your Microsoft ecosystem.

Setting Up Entra Integration

Organisation administrators can configure Entra integration through the web interface:

Step 1: Register Your Application in Azure AD

1. Go to the Azure Portal
2. Navigate to Azure Active Directory → App registrations
3. Click "New registration"
4. Enter a name for your application (e.g., "Staff Service Integration")
5. Select supported account types (typically "Accounts in this organizational directory only")
6. Click "Register"

Step 2: Configure API Permissions

For staff synchronisation, you need the following permission:

• User.Read.All - Application permission (not delegated) - requires admin consent

1. In your app registration, go to "API permissions"
2. Click "Add a permission"
3. Select "Microsoft Graph"
4. Choose "Application permissions"
5. Search for and select "User.Read.All"
6. Click "Add permissions"
7. Click "Grant admin consent" (this requires an Azure AD administrator)

Step 3: Create a Client Secret

1. In your app registration, go to "Certificates & secrets"
2. Click "New client secret"
3. Enter a description and choose an expiration period
4. Click "Add"
5. Copy the secret value immediately - it won't be shown again!

Step 4: Get Your Tenant ID and Client ID

• Tenant ID: Found in the "Overview" page of your app registration, or in Azure AD → Overview
• Client ID (Application ID): Found in the "Overview" page of your app registration

Step 5: Configure in Staff Service

1. Log in to Staff Service as an organisation administrator
2. Navigate to Admin → Entra/365 Settings
3. Enter your Tenant ID and Client ID
4. Set the ENTRA_CLIENT_SECRET environment variable with the client secret you created
5. Click "Enable Entra Integration"

Synchronising Staff from Entra

Once Entra integration is enabled, you can synchronise staff from Microsoft Entra ID:

1. Go to Admin → Entra/365 Settings
2. Click "Sync Staff from Microsoft Entra ID"
3. The system will:
   • Fetch all active users from Microsoft Entra ID
   • Match users by email address
   • Create new staff records or update existing ones
   • Map employee IDs from Entra to Staff Service

Integration with Other Applications

When Entra integration is enabled in Staff Service, other applications (like Digital ID) can use Staff Service as the source of truth for Entra-synced staff data. This ensures consistent data across all applications without duplication.

Super Administrator Access

Super administrators can configure Entra integration for any organisation when requested. This is useful for organisations that need assistance with setup or troubleshooting.

Security & Privacy

The Staff Service is built with security and privacy as top priorities.

Data Ownership

You maintain complete ownership of your data. There's no vendor lock-in, and your data stays in your control. You can export all your data at any time.

Multi-Tenant Isolation

All data is isolated by organisation. Staff from one organisation cannot access data from another organisation, even administrators.

Role-Based Access Control

Access is controlled through role-based permissions:

• Staff Members - Can view and update their own personal details via My Staff Details; sensitive changes require line manager approval before taking effect
• Line Managers - Can review and approve or reject profile change requests from their direct reports via Approve Changes
• Organisation Administrators - Can manage all staff in their organisation and act as approver for staff with no line manager assigned
• Super Administrators - Can manage organisations and system-wide settings

Managing User Roles

Super administrators can manage user roles and assign organisation administrator privileges:

1. Log in as a super administrator
2. Navigate to Admin → Users
3. Select an organisation from the dropdown (optional - leave blank to see all users)
4. For each user, you can:
   • Make Admin - Assign organisation administrator role to a user
   • Remove Admin - Remove organisation administrator role from a user

Data Protection

The Staff Service is designed to comply with GDPR and UK data protection regulations:

• Secure data storage and transmission
• Access logging and audit trails
• Data export capabilities
• Right to deletion

API Security

All API endpoints require authentication. API keys can be generated and revoked by administrators, and all API access is logged for security auditing.