Azure DevOps Powered Support Ticketing

Production • Quick Start • Features • Documentation

---

DevDesk is a Zendesk-style support ticketing portal that uses Azure DevOps as its backend. Built by KnowAll.

Features

• Microsoft Authentication - Sign in with Azure AD/Microsoft accounts
• Azure DevOps Integration - Work items tagged as "ticket" appear as support tickets
• Multi-tenant Support - Different clients have different DevOps projects (e.g., Medite, Cairn Homes)
• Permission-based Access - Users only see tickets from projects they have access to
• Email-to-Ticket - Send emails to [email protected] to create tickets automatically
• Email Responses - Replies to tickets email the requester via Exchange Online
• Zendesk-like UI - Familiar interface with views, filters, and ticket management

Quick Start

Prerequisites

• Node.js 18+
• npm or yarn
• Azure DevOps organization
• Azure AD application for authentication
• Exchange Online mailbox (for email integration)

Installation

1. Clone the repository

   git clone https://github.com/knowall-ai/devdesk.git
   cd devdesk

2. Install dependencies

   npm install

3. Configure environment variables

   cp .env.example .env

   Edit .env with your values (see .env.example)

4. Run the development server

   npm run dev

5. Open the application Navigate to http://localhost:3000

Azure AD Setup

1. Register a new application in Azure AD
2. Add redirect URIs:
   • Development: http://localhost:3000/api/auth/callback/azure-ad
   • Production: https://devdesk.knowall.ai/api/auth/callback/azure-ad
3. Configure API permissions for Azure DevOps:
   • 499b84ac-1321-427f-aa17-267ca6975798/.default (Azure DevOps)
4. Create a client secret and note it down

How It Works

Ticket Tagging

Only Azure DevOps work items with the "ticket" tag will appear in DevDesk. To convert any work item into a support ticket:

1. Open the work item in Azure DevOps
2. Add the tag "ticket"
3. The item will now appear in DevDesk

Project Mapping

DevDesk maps Azure DevOps projects to organizations/clients:

Project	Domain	Description
Medite	medite.com	Medite client project
Cairn Homes	cairnhomes.com	Cairn Homes client project
KnowAll	knowall.ai	Internal KnowAll project

Email Integration

Inbound Email (Creating Tickets)

Customers send emails to [email protected] to create tickets:

1. Set up Exchange Online mailbox for [email protected]
2. Configure mail flow rule to forward to webhook
3. Or use Power Automate to POST to /api/email/webhook

Outbound Email (Responses)

When agents reply to tickets, the requester receives an email:

1. Configure Exchange Online SMTP settings
2. Set SMTP_* environment variables
3. Replies include ticket reference for threading

Exchange Online Setup

1. Create shared mailbox: [email protected]
2. Enable SMTP AUTH for the mailbox
3. Create app password or configure OAuth
4. Set up mail flow rules for inbound processing

See docs/EMAIL_SETUP.adoc for detailed instructions.

Tech Stack

• Framework: Next.js 15 (App Router)
• Language: TypeScript
• Styling: Tailwind CSS
• Authentication: NextAuth.js with Azure AD
• Backend: Azure DevOps REST API
• Icons: Lucide React
• Deployment: Azure App Service

Project Structure

devdesk/
├── src/
│   ├── app/                    # Next.js app router pages
│   │   ├── api/               # API routes
│   │   │   ├── auth/          # NextAuth endpoints
│   │   │   ├── devops/        # DevOps API proxy
│   │   │   └── email/         # Email webhook
│   │   ├── tickets/           # Ticket pages
│   │   ├── customers/         # Customer pages
│   │   ├── organizations/     # Organization pages
│   │   └── login/             # Login page
│   ├── components/            # React components
│   ├── lib/                   # Utility functions
│   └── types/                 # TypeScript types
├── docs/                      # Documentation
├── tests/                     # Playwright tests
└── public/                    # Static assets

Documentation

• Solution Design
• Deployment Guide
• Testing Guide
• Troubleshooting

Development

# Run development server
npm run dev

# Build for production
npm run build

# Run production server
npm start

Code Quality Checks

The following checks run automatically on every pull request via GitHub Actions:

# Run all checks (recommended before pushing)
npm run check

# Individual checks
npm run typecheck      # TypeScript type checking
npm run lint           # ESLint
npm run lint:fix       # ESLint with auto-fix
npm run format:check   # Prettier format check
npm run format         # Prettier auto-format

# Run tests
npm run test

All checks must pass before a PR can be merged.

License

Proprietary - KnowAll AI Ltd.

Support

For support, email [email protected] or visit knowall.ai.