Help Category: Orangescrum On premises

1. Help Desk Overview

The Risk Management Help Desk supports users interacting with the Risk Module inside the Orangescrum platform.

The help desk assists with:

• Risk creation and lifecycle management
• Workflow and status issues
• Mitigation tracking
• Risk linking to tasks/sprints
• Approval workflow problems
• Notifications and escalation issues
• Dashboard/reporting support
• Technical troubleshooting

The module provides a centralised risk register, automated scoring, mitigation tracking, and an approval workflow integrated into the project lifecycle.

Developer_documentation_risk_v1

2. Supported System Architecture

The module runs on the following architecture.

Frontend

• VueJS 3
• Vuetify UI

Backend

• CakePHP 4 Risk Plugin

Database

• PostgreSQL 17

API

• REST JSON APIs

Architecture flow:

VueJS UI
↓
REST API
↓
CakePHP 4 Risk Plugin
↓
CakePHP ORM
↓
PostgreSQL Database

This architecture enables scalable risk tracking and dashboard reporting.

Developer_documentation_risk_v1

3. Help Desk Support Levels

Support Level	Responsibility
L1 Support	User assistance, password/reset issues, navigation
L2 Support	Workflow, risk linking, configuration
L3 Support	Developer debugging, database fixes, performance

4. Common User Issues & Resolutions

4.1 Cannot Create Risk

Possible Causes

• Required fields missing
• User lacks permissions
• Project context missing

Mandatory Fields

• Risk Title
• Risk Description
• Risk Category
• Risk Type
• Identified By
• Risk Owner

These must be completed before moving beyond Draft status.

Risk_Management_Scope_of_Work_v1

Resolution

1. Open Risk Module
2. Click Create Risk
3. Complete mandatory fields
4. Save as Draft

4.2 Risk Score Not Calculating

Cause

Risk score depends on:

Risk Score = Probability × Impact

Range: 1 – 25

Risk_Management_Scope_of_Work_v1

Resolution

Ensure:

• Probability selected (1–5)
• Impact selected (1–5)

4.3 Cannot Close Task Due to Risk

Cause

Tasks cannot be closed when linked risks are still open.

Risk_Management_Scope_of_Work_v1

Blocking statuses include:

• Identified
• Under Assessment
• Mitigation In Progress
• Escalated
• Monitoring
• Materialised

Resolution

1. Open Linked Risk
2. Resolve mitigation
3. Move risk to:

Closed — Resolved
Closed — Accepted
Closed — Expired

4.4 Risk Not Visible in Task

Cause

Risk is not linked.

Resolution

1. Open task
2. Click Linked Risks
3. Add risk
4. Save

4.5 Cannot Change Risk Status

Cause

Invalid workflow transition.

Allowed transitions are enforced by the system.

Risk_Management_Scope_of_Work_v1

Example transitions:

From	To
Draft	Identified
Identified	Under Assessment
Under Assessment	Mitigation
Mitigation	Monitoring
Monitoring	Closed

5. Risk Lifecycle Help

The module follows a structured lifecycle.

Draft
↓
Identified
↓
Under Assessment
↓
Mitigation In Progress
↓
Monitoring
↓
Closed

Special states:

• Escalated
• Materialised

Each transition creates an audit entry.

Risk_Management_Scope_of_Work_v1

6. Mitigation Management Help

Each risk may contain multiple mitigation plans.

Example mitigation fields:

• Title
• Description
• Assigned User
• Due Date
• Status

Mitigation statuses:

• Not Started
• In Progress
• Completed
• Overdue

These are stored in the risk_mitigations table.

Developer_documentation_risk_v1

7. Notifications & Escalations

Notifications are triggered automatically.

Event	Recipients
Risk Created	Project Manager
Risk Assigned	New Owner
Status Change	Risk Owner
Escalation	Senior Management
Mitigation Overdue	Mitigation Owner

Channels:

• Email
• In-app notifications

Risk_Management_Scope_of_Work_v1

8. Dashboard & Reporting Support

The Risk Dashboard includes:

• Total risks by status
• Risk rating distribution
• Heat map
• Overdue risks
• Mitigation progress
• Recently added risks

The 5×5 Heat Map plots probability vs impact.

Risk_Management_Scope_of_Work_v1

9. Audit Log Support

Every action is tracked.

Audit log captures:

• Field change
• Old value
• New value
• User
• Timestamp

Audit logs are immutable and cannot be edited.

Risk_Management_Scope_of_Work_v1

10. Database Troubleshooting

Key tables:

Table	Purpose
risks	Main risk records
risk_mitigations	Mitigation plans
risk_entity_links	Task/sprint linking
risk_state_history	Status history
risk_audit_logs	Audit logs

These tables support risk tracking and lifecycle management.

Developer_documentation_risk_v1

11. Developer Support (CakePHP 4)

Plugin structure:

plugins/Risk/

config/
src/

Controller/
Model/
Table/
Entity/

Service/
RiskWorkflowService
RiskApprovalService
RiskScoringService
RiskAuditService

Responsibilities:

Service	Function
RiskWorkflowService	Status transitions
RiskApprovalService	Approval logic
RiskScoringService	Risk score calculation
RiskAuditService	Audit tracking

12. Performance Troubleshooting

Recommended optimisations:

• Index frequently queried columns
• Pagination on risk lists
• Materialized views for dashboards
• PostgreSQL autovacuum enabled

The system supports 50,000+ risks across projects.

Developer_documentation_risk_v1

13. Scheduled Jobs (Cron)

The system runs background jobs for:

• Overdue mitigation detection
• Review reminders
• Escalation alerts
• Risk rating updates

14. Security & Access Control

Roles supported:

Role	Permissions
Team Member	Create risks
Risk Owner	Manage mitigation
Approver	Approve risks
Project Manager	Escalate risks
Admin	Full control

15. Help Desk Contact Process

Issue Reporting Format

Users should provide:

• Project Name
• Risk ID
• Screenshot
• Error Message
• Steps to reproduce

Example:

Project: Insight 2.0
Risk ID: RISK-014
Issue: Unable to move risk to Monitoring
Error: Transition not allowed

16. Escalation Matrix

Level	Contact
L1	Application Support
L2	Product Support Team
L3	Development Team
L4	Architecture / DevOps

17. Knowledge Base Topics

Help desk articles should include:

• Creating a risk
• Linking risk to tasks
• Risk workflow explanation
• Mitigation tracking
• Risk dashboard usage
• Handling escalation
• Closing risks

✅ Result

This help desk document supports:

• End users
• Project managers
• Administrators
• Developers

For the CakePHP 4 Risk Management Module described in your documents.

1. Purpose of the Help Desk

The Help Desk supports users for:

• Document upload issues
• Workflow approval problems
• Version control conflicts
• Permission and access errors
• Folder/repository configuration issues
• Performance or system errors
• Audit / compliance queries

This ensures continuous availability and reliability of the DMS platform.

2. Help Desk Support Levels (Tier Model)

Support Level	Responsibility
Level 0	Self-service portal, knowledge base, FAQs
Level 1	Basic support: login issues, upload issues
Level 2	Application support: workflow errors, permissions
Level 3	Engineering team: bug fixes, system failures
Level 4	Infrastructure/DevOps: server, database, storage

3. Help Desk Organization Structure

Users (MSP / ITD / Admin)
│
▼
Self-Service Portal
│
▼
Level 1 Support Desk
(Service Desk Agents)
│
▼
Level 2 Application Support
(DMS Functional Experts)
│
▼
Level 3 Engineering Team
(Backend + Frontend Developers)
│
▼
Level 4 Infrastructure Team
(DevOps / Cloud / Database)

4. Help Desk Ticket Categories  

User & Access Issues

• Cannot login
• Permission denied
• Cannot access folder/document

Document Upload Issues

• File upload failure
• File size limit exceeded
• Metadata validation errors

Workflow Issues

• Approval not triggered
• Workflow stuck in status
• Reviewer not receiving notification

Version Control Issues

• Version conflict
• Version restore failed
• Locked document modification attempt

Repository & Folder Issues

• Folder creation failed
• Folder permission errors
• Folder archive or move issues

Search & Registry Issues

• Search not returning results
• Export errors
• Registry view performance issue

Performance & System Issues

• Slow document loading
• Upload timeout
• API failure

5. Ticket Lifecycle Workflow

User raises ticket
        │
        ▼
Ticket Created
        │
        ▼
Level 1 Support
        │
 ┌──────┴─────────┐
 │ Resolved?      │
 │ Yes            │
 │                │
 ▼                ▼
Close Ticket    Escalate
                  │
                  ▼
            Level 2 Support
                  │
            Investigate Issue
                  │
        ┌─────────┴──────────┐
        │ Config Issue?      │
        │ Yes → Fix          │
        │ No  → Escalate     │
        ▼                    ▼
    Close Ticket       Level 3 Engineering
                              │
                        Bug Fix / Patch
                              │
                        Deploy Solution
                              │
                         Close Ticket

6. SLA (Service Level Agreement)

Priority	Example Issue	Response Time	Resolution Time
Critical	System down	15 minutes	2 hours
High	Approval workflow broken	30 minutes	4 hours
Medium	Upload issue	2 hours	1 day
Low	UI issue	1 day	3 days

7. Self-Service Support Portal

The help desk should provide a self-service portal integrated with the DMS.

Features:

1. Knowledge Base

Articles such as:

• How to upload documents
• How to submit for approval
• How version control works
• How to restore versions
• Folder permission configuration

2. Guided Troubleshooting

Example:

Problem: Upload failed
Steps:

1. Check file size (<50MB)
2. Check file type (PDF/DOCX/XLSX etc.)
3. Verify folder permissions
4. Try re-upload

8. Help Desk System Architecture

Users
│
▼
Help Desk Portal
(Web / Mobile)
│
▼
Ticket Management System
│
├── Knowledge Base
├── Ticket Queue
├── SLA Monitor
├── Notification System
│
▼
Support Agents
│
▼
Integration Layer
│
├── DMS APIs
├── Workflow Engine
├── Audit Logs
├── Database
│
▼
Monitoring & Logging

9. Monitoring and Alerting

The help desk should monitor:

Metric	Tool
API success rate	Application monitoring
Workflow failures	Log analyzer
Upload errors	System logs
Queue delays	Redis monitoring
System uptime	DevOps monitoring

10. Help Desk Tools (Recommended)

Ticketing System

• Jira Service Management
• Freshservice
• Zendesk

Monitoring Tools

• Grafana
• Prometheus
• ELK Stack

Collaboration Tools

• Slack
• Microsoft Teams

11. Help Desk Dashboard

Key KPIs:

• Total tickets opened
• Average resolution time
• SLA compliance rate
• Most frequent issues
• Pending approvals issues
• System performance alerts

12. Automation in Help Desk

Automation can include:

• Auto ticket creation from system errors
• Workflow failure alerts
• Approval delay reminders
• Auto assignment based on category
• Knowledge base recommendation

Example:

Upload Error Detected
│
▼
System Creates Ticket
│
▼
Assigned to Level 1
│
▼
User receives notification

13. Security & Compliance in Help Desk

Because DMS is government/compliance-driven, help desk must ensure:

• Audit trail of support actions
• Ticket access control
• Secure attachments
• Data privacy protection
• Compliance reporting

14. Definition of a World-Class Help Desk

A world-class help desk for the DMS must deliver:

• 24×7 support capability
• Automated ticket routing
• AI-assisted troubleshooting
• Integrated monitoring and alerts
• Knowledge-driven self-service
• SLA tracking and reporting
• Full audit compliance

As your user base grows, Orangescrum can scale flexibly depending on the deployment model.

Vertical Scaling

Upgrade resources on a single host:

• Increase CPU, RAM, and disk I/O
• Move database to a dedicated instance
• Use NVMe or SSD storage for faster query response

Example: Move from 4C/8GB to 8C/32GB to handle 3x user load.

Horizontal Scaling

Distribute load across multiple servers or containers:

• Deploy multiple app nodes behind a load balancer (HAProxy or Nginx)
• Use shared storage (NFS/GlusterFS) for uploads
• Implement MySQL/PostgreSQL replication for database redundancy
• Run Redis/Memcached for session caching if needed

Scaling in Kubernetes

If using K8s, simply scale pods:

Tip: Monitor latency, concurrent sessions, and database performance as leading indicators for scaling decisions.

Summary

Maintaining Orangescrum Self-Hosted is about discipline and consistency:

• Back up your database and upload regularly.
• Restore carefully and test before going live.
• Keep your system patched and Orangescrum version current.
• Monitor logs proactively to prevent downtime.
• Scale vertically or horizontally as your teams grow.

These practices ensure that your Orangescrum environment remains secure, resilient, and high-performing — ready for long-term enterprise adoption.

Monitoring your Orangescrum instance helps detect issues early and maintain optimal performance.

Application Logs

Located at:

Or inside the Docker container:

Use these logs to troubleshoot errors related to tasks, authentication, or integrations.

Web Server Logs

Apache/Nginx logs are typically found at:

Monitoring Tools

For production-grade observability:

• Prometheus + Grafana → CPU, memory, container metrics
• Uptime Kuma / Nagios → Service uptime
• Elastic Stack (ELK) → Centralized log analytics

Recommended Practice: Configure alerts for CPU >80%, memory >75%, or disk >90% utilization.

Orangescrum frequently releases new updates for features, performance, and security. Keeping your instance up-to-date ensures you benefit from the latest improvements.

Before Upgrading

1. Take a full backup of both database and uploads.
2. Notify users and schedule downtime.
3. Note your current version (Settings → About Orangescrum).

Upgrade Steps (Docker Method)

Pull the latest image:

1. Stop existing containers:

2. Start new containers with updated image:

3. Verify the version from the web UI.

Upgrade Steps (Manual Installation)

1. Backup /config and /uploads.
2. Download the latest release from Orangescrum’s release page or your customer portal.
3. Replace application files except /config and /webroot/uploads.
4. Run database migration scripts if included.

Restart web services:

Version Compatibility: Always check the release notes for required PHP or DB version changes before upgrading.

For enterprise users, staging upgrades are highly recommended.