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 details with verification workflows
• 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 to access your profile
3. Update your personal details, contact information, and emergency contacts
4. Upload your profile photo (subject to admin approval)
5. Add your digital signature for contracts and agreements

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 staff profile updates
• 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 containing:

Personal Information

• Name, date of birth, contact details
• Emergency contacts
• Profile photo
• Digital signature

Employment Details

• Job title and job post
• Employment start date
• Line manager
• Organisational unit assignments
• Contract type and status

Financial & Identification

• National Insurance number
• Bank account details
• Address information

Compliance & Qualifications

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

Leave Management

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

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 edit their own profile
• Organisation Administrators - Can manage all staff in their organisation
• 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.