# Welcome to Harmony Your guide to Harmony's AI-powered IT service management platform Welcome to Harmony! This documentation covers everything you need to deploy, configure, and operate your autonomous IT help desk. {% hint style="info" %} New to Harmony? Start with our [Integrations](https://github.com/harmonyso/public-docs/blob/main/integrations/slack.md) to connect your collaboration tools and get operational quickly. {% endhint %} ### IT Service Desk & Ticketing Employees submit requests through Slack, Microsoft Teams, email, or web portal. Harmony's AI help desk agent handles each request intelligently: * **Smart Routing** - Tickets are classified and routed to the right team based on request content and context * **Knowledge-Powered** - References knowledge bases to answer questions with accurate, sourced information * **Autonomous Resolution** - Executes automations to resolve common requests without human intervention * **Seamless Escalation** - Hands off to human agents when needed, with full context and transparency
SlackConnect Harmony to Slack for instant IT supporthttps://github.com/harmonyso/public-docs/blob/main/integrations/slack.md
Microsoft TeamsIntegrate with Teams for seamless ticket managementhttps://github.com/harmonyso/public-docs/blob/main/integrations/teams.md
OktaAutomate identity and application managementhttps://github.com/harmonyso/public-docs/blob/main/integrations/okta.md
Microsoft Entra IDCentralize identity and user provisioninghttps://github.com/harmonyso/public-docs/blob/main/integrations/microsoft-entra.md
### API & Developer Tools Build custom integrations and automate your IT workflows programmatically.
API ReferenceExplore our REST API for tickets, users, and workflowshttps://docs.harmony.io/api-references
### Integrations Connect Harmony to 40+ tools including Slack, Okta, Google Workspace, Jira, ServiceNow, and more. Our integrations enable automated workflows, centralized user management, and unified visibility across your IT ecosystem.
Browse All IntegrationsExplore our complete integration catalog organized by categoryhttps://github.com/harmonyso/public-docs/blob/main/integrations/overview.md
### Need Help? Reach out to our team at # Getting Started Learn the basics of Harmony Dashboard, including key features, system requirements, and how to access and navigate the platform for the first time. {% hint style="info" %} **Path:** `/dashboard` {% endhint %} ### Welcome to Harmony Dashboard Harmony Dashboard is your central command center for IT operations. The platform combines service desk ticketing, asset management, software inventory, AI agents, and agent automation in one interface. {% hint style="info" %} **First time here?** This guide covers everything from what Harmony does to how to use the dashboard home screen. Navigation and advanced features are covered in separate guides. {% endhint %} ### What is Harmony Dashboard? Harmony Dashboard is an IT operations platform that unifies: * **Service Desk** - Manage tickets across multiple desks with team-based routing * **Asset Management** - Track hardware inventory, software licenses, and compliance * **AI Agents** - Automate tasks like password resets, compliance checks, and onboarding * **Agents** - Build and run automation with the visual agent builder * **Analytics** - Custom dashboards with metrics on tickets, SLA, assets, and agents Your experience depends on your role. Platform users (Admin, Agent, Observer) see the full dashboard. Desk-only users land on their tickets. Other users are directed to the Portal for self-service. ### Key Features Overview The main sidebar gives access to core areas (based on your permissions): | Section | Description | | ------------- | ------------------------------------------------------------------- | | **Dashboard** | Metrics and widgets for service desk, assets, AI agents, and agents | | **Tickets** | Service desk with desks, ticket lists, and conversations | | **Agents** | AI agents for compliance, acknowledgments, and automation | | **Agents** | Visual agent builder (when enabled) | | **Assets** | Hardware inventory and details | | **Software** | Software applications and licenses | | **People** | Employee directory | | **Settings** | Configuration for desks, integrations, and preferences | The sidebar is collapsible. Use the search icon or **Cmd+K** / **Ctrl+K** to open the command palette for quick navigation. ![Main sidebar with core sections](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-f01d36156d4b2ec44b52edb47be95830e8635dc0%2Fsidebar-sections.png?alt=media) ### System Requirements Harmony runs in a web browser. Supported: * Modern browsers (Chrome, Firefox, Safari, Edge) * JavaScript enabled * Network access to your Harmony tenant The app uses React, TanStack Router, and Descope for authentication. Data is cached in the browser (IndexedDB) for offline resilience. ### Accessing the Dashboard 1. **Log in** at your tenant URL (e.g. `https://demo.harmony.io`). 2. **After login**, you're redirected by role: * **Platform roles** (Admin, Agent, Observer) → `/dashboard` * **Desk-only users** → first accessible ticket desk * **Other users** → `/portal` 3. **Dashboard URL**: `/dashboard` shows your default or system dashboard. Admins can create custom dashboards; the system dashboard is read-only and serves as the default view. #### Try Harmony with a demo account Not ready to set up your own workspace? You can explore Harmony using a demo tenant account. A dedicated demo login flow lets you experience the full platform - tickets, assets, AI agents, agents, and more - right away, without any setup required. ### First Login Experience Authentication is handled by Descope. On first visit: 1. You're redirected to the login flow if not authenticated. 2. After login, the app loads with ThemeProvider, feature flags, and analytics. 3. Your tenant name appears in the sidebar header. 4. Permissions are checked to show the correct sidebar items. If you land on `/portal` instead of `/dashboard`, your role may not include platform access. ### Install Harmony on Your Device You can install Harmony so it feels and behaves like a native app, without being tied to a browser tab. #### Progressive Web App (PWA) Harmony supports installation as a Progressive Web App on desktop and mobile. Once installed, you can launch it directly from your home screen or app launcher. Key benefits include: * **Faster load times** - A service worker keeps assets up to date with immediate cache invalidation whenever a new version ships, so you are never running stale code. * **Push notifications** - Harmony can deliver timely alerts even when it is not your active browser tab. * **Offline resilience** - Core assets are cached for improved reliability. To install, look for the install prompt in your browser's address bar or menu, and follow the on-screen steps. #### Android app (Google Play Store) Harmony is also available as a native Android app on the Google Play Store. The app is built using a Trusted Web Activity (TWA), delivering the full Harmony web experience in a native Android wrapper. You can add it to your home screen, launch it like any other app, and enjoy a more integrated mobile experience. Search for **Harmony** on the Google Play Store to download and install it on your Android device. ### Dashboard Home Screen ![Default dashboard home view with widgets](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-c628e0c3a23beade640481af122e313695703bf6%2Fdashboard-home.png?alt=media) The dashboard shows a grid of widgets. You can change the date range, refresh data, and-for custom dashboards-edit the layout. New workspaces start with an improved default layout, giving you a useful, well-organised view of your IT operations right from the start. #### Default metrics (system dashboard) The system dashboard includes: **Number widgets:** * Average Response Time * Average Resolution Time * SLA Compliance * Total Tickets **Chart widgets:** * Ticket breakdown * Software breakdown * Asset breakdown by compliance * Tickets resolved by employee * Tickets solved by AI * AI resolved vs escalated * Tickets created by employee / AI * Opened vs resolved * SLA compliance * Response vs resolution * Ticket priority * Agent ended by status * Agent started by name / category #### Date range Use the date range selector for 1d, 7d, 30d, or 90d. All widgets use this range. #### Custom dashboards When you can edit: * **Edit** - Enter edit mode to add, remove, or reposition widgets * **Add widgets** - Open the widget library * **Save & Exit** - Save layout changes * **Cancel** - Discard edits Widget types include line, bar, and donut charts plus number widgets. ### Harmony Copilot Harmony Copilot is the AI assistant built into the platform, helping agents work faster and automating routine tasks. Copilot uses a curated, tagged set of platform APIs specifically optimised for AI-assisted interactions, so it consistently reaches for the right tools when helping you. Recent improvements include: * **More accurate API selection** - Copilot now uses path template matching in its API explorer, making it more reliable at locating and acting on the correct endpoints. * **Better structured outputs** - Copilot's prompts include improved guidance for entity link formatting and auto-tagging, resulting in more consistent and readable responses. ### Getting Help and Support Use the **Help** button in the sidebar (message circle icon) to open Intercom support. You can also use the command palette (**Cmd+K** / **Ctrl+K**) to search for navigation and actions across the app. ![Command palette with search](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-782ff923b00f975d80748713c0c0eb9ee2225513%2Fcommand-palette.png?alt=media) *** ### Related Resources
Navigating the InterfaceMaster the sidebar, command palette, and keyboard shortcutshttps://github.com/harmonyso/public-docs/tree/main/guides/navigating-the-interface/README.md
Understanding IntegrationsConnect Slack, Okta, and other toolshttps://github.com/harmonyso/public-docs/tree/main/guides/understanding-integrations/README.md
Managing Your ProfileUpdate your profile settings and preferenceshttps://github.com/harmonyso/public-docs/tree/main/guides/managing-your-profile-and-preferences/README.md
Harmony PortalEnd-user portal for chat, tickets, and approvalshttps://github.com/harmonyso/public-docs/tree/main/guides/using-the-harmony-portal/README.md
# Navigating the Interface Master the Harmony Dashboard interface with the sidebar, command palette, keyboard shortcuts, and navigation features. {% hint style="info" %} **Key routes:** `/dashboard` · `/tickets` · `/agents` · `/assets` · `/software` · `/people` · `/settings` · `/portal` {% endhint %} ### Understanding the Dashboard Layout The Harmony layout uses a collapsible sidebar on the left, a top navigation bar, main content in the center, and a user menu in the sidebar footer. The layout adapts for mobile. When you're on the Portal, the sidebar is hidden and a different layout is shown. The **top navigation bar** appears on every page and houses the Copilot button and global search in a compact, unified toolbar. All components in the bar are capped at 32px height for a consistent, polished look. Spacing and borders across pages have been refined, with reduced padding and visible container borders that render correctly in both light and dark mode. ![Full layout with sidebar expanded](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-fe7bd0d6905a6371dd3c7ee33c02dd4a48e600c4%2Flayout-full.png?alt=media) ### Using the Main Sidebar The main sidebar is the primary way to move between sections of Harmony. #### Collapsing and Expanding the Sidebar * **Toggle button** - A circular button appears on the right edge of the sidebar on hover. Click it to collapse or expand. * **Keyboard shortcut** - Press `Cmd+S` (Mac) or `Ctrl+S` (Windows/Linux) to toggle the sidebar. * **Collapsed mode** - When collapsed, the sidebar shows only icons. Click the logo or any icon to expand it again. The sidebar state is stored so it stays the same across sessions. The sidebar menu area now scrolls independently when the navigation list is long. The header and footer remain fixed, so important controls like your user menu are never pushed out of view. Collapsible menu sections display a chevron arrow so you can tell at a glance when there are nested items to expand. Menu items and sub-items share a consistent height for a uniform appearance. Your **tenant information** is visible in the sidebar footer, making it easy to confirm which workspace you are operating in without navigating away. #### Understanding Sidebar Sections The sidebar shows different sections based on your permissions: | Section | Route | Who sees it | | ------------ | ------------------- | --------------------------------------- | | Dashboard | `/dashboard` | Platform roles (Admin, Agent, Observer) | | Tickets | `/tickets/desk/...` | Users with ticket access | | Agents | `/agents` | Platform roles | | Assets | `/assets` | Platform roles | | Applications | `/software` | Platform roles | | People | `/people` | Platform roles | | Settings | `/settings` | Users with settings access | | Help | - | Opens Intercom | {% hint style="info" %} The **Software** tab has been renamed to **Applications** across the platform to align with common industry terminology. {% endhint %} #### Desk Navigation in Sidebar Under **Tickets**, you can switch between desks: * **All** - View tickets across all desks you can access. * **Individual desks** - Each desk appears as a sub-item. Click to open that desk's ticket list. * **Subdesks and teams** - Desks with associated teams appear as collapsible menu items. Expand a desk to reveal its teams and navigate directly to a team's filtered view. * **Other** - Shown when the "disabled desks" feature is on, for desks you don't normally access. The Tickets item is a collapsible menu. Expand it to see the list of desks. #### Desk Hover Previews When the sidebar is collapsed (icon-only mode), hover over a desk item to see a preview card. The card shows the desk name, its teams, and quick links to navigate directly to each team. Desks with teams show a chevron. Use this to switch context between teams without leaving your current agent. ![Sidebar collapsed with desk hover card](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-9d7e6e9e3673c1f50b6909d46ad8427cf7db9dd0%2Fdesk-hover-preview.png?alt=media) #### Understanding Desk Hierarchy Desks are top-level units; each can have teams. In the sidebar, desks appear under Tickets. Teams are shown both in the collapsible desk menu and in the hover preview card when the sidebar is collapsed. ### Using the Command Palette (Cmd+K / Ctrl+K) The command palette gives quick access to navigation, search, and actions. #### Opening the Command Palette * **Keyboard** - Press `Cmd+K` (Mac) or `Ctrl+K` (Windows/Linux). * **Sidebar** - Click the search icon in the sidebar header. #### Searching for Actions With the palette open, type to search. It shows: * **Navigation** - Go to Dashboard, Tickets, Agents, Agents, Assets, Applications, People, Settings * **Employees** - Jump to employee profiles by name (type 2+ characters); employee avatars appear alongside results for easier identification * **Tickets** - Find and open tickets by title (type 2+ characters) * **Assets** - Find and open assets (type 2+ characters) * **Applications** - Find and open software applications by name (type 2+ characters); application logos appear where available * **Utility** - Reload page, copy URL, toggle theme, toggle sidebar, open help Live search results (employees, assets, tickets, applications) appear after you type at least 2 characters. Results are grouped by category. Select an item and press Enter to open it. ![Command palette with search results](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-f5597849cfb099b32506f633059e200fdab16118%2Fcommand-palette.png?alt=media) #### Understanding Command Categories Categories include Navigation, search results (Employees, Tickets, Assets, Applications), and Utility. Use the search field to filter. #### Quick Navigation with Commands Select a command with the mouse or arrow keys, then press Enter to run it. The palette closes after you run a command. ### Using the Copilot Button The Copilot button is available from the top navigation bar on every page. You can reposition it anywhere on your screen by dragging it, so it stays out of the way while you work. The Copilot panel and welcome screen display correctly on mobile devices and smaller screens. The button supports mouse, touchscreen, and keyboard navigation reliably. ### Keyboard Shortcuts Harmony provides an expanded set of keyboard shortcuts to help you move faster through the platform without reaching for your mouse. Modifier keys: `Cmd` on Mac, `Ctrl` on Windows/Linux. #### Global Shortcuts | Shortcut | Action | | ------------------ | ------------------------- | | `Cmd+K` / `Ctrl+K` | Open command palette | | `Cmd+S` / `Ctrl+S` | Toggle sidebar | | `Cmd+H` / `Ctrl+H` | Toggle Intercom (Help) | | `Cmd+M` / `Ctrl+M` | Toggle theme (light/dark) | #### Navigation Shortcuts (g then key) Type `g`, then a letter: | Sequence | Destination | | --------------------- | --------------------------- | | `g` then `d` | Dashboard | | `g` then `t` | Tickets | | `g` then `i` | Agents | | `g` then `w` | Agents | | `g` then `a` | Assets | | `g` then `s` | Applications | | `g` then `p` | People | | `g` then `c` | Settings | | `g` then `g` then `a` | Admin (Harmony admins only) | #### Settings Tab Shortcuts (t then key) When you're in Settings, type `t`, then a letter: | Sequence | Tab | | ------------ | ---------------- | | `t` then `g` | General | | `t` then `i` | Integrations | | `t` then `k` | Knowledge Base | | `t` then `a` | Asset Management | | `t` then `d` | Desks | | `t` then `b` | Branding | | `t` then `p` | Preferences | #### Table Navigation Shortcuts In data tables (e.g. tickets, assets, people), these shortcuts work when the table has focus: | Shortcut | Action | | --------- | ------------------------------------- | | `/` | Focus search | | `Escape` | Clear search | | `↑` / `↓` | Move between rows | | `←` / `→` | Previous / next page (when available) | | `Shift+R` | Refresh table | | `Shift+X` | Reset filters | You can also navigate between pages, open items with the Enter key, and switch between tabs entirely from the keyboard across all major surfaces including tickets, assets, people, and settings. #### Theme Toggle (Cmd+M / Ctrl+M) Press `Cmd+M` or `Ctrl+M` anywhere to switch between light and dark theme. ### Using Breadcrumbs for Navigation Breadcrumb navigation appears across Harmony, giving you clear context about where you are in the platform. Breadcrumbs replace the previous back arrow on most pages. Breadcrumbs appear on pages with nested structure, such as: * **Settings → Desks → \[Desk name]** - When viewing a desk * **Settings → Desks → \[Desk] → Teams → \[Team]** - When viewing a team * **Settings → User Management → \[User]** - When viewing a user * **Settings → User Management → \[Group]** - When viewing a group Breadcrumb segments are links; click them to go back to that level. ![Breadcrumbs on Settings desk page](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-cfc510203a0873c45ee03bb1cd73c2399a1dbb22%2Fbreadcrumbs.png?alt=media) #### Navigating Back Through Breadcrumbs Click any breadcrumb segment to return to that page. For example, from **Settings → Desks → IT** → Teams → Support, click **Desks** to go back to the desks list, or **Settings** to go to settings home. On some detail pages (e.g., tickets, software), a back arrow uses browser history or falls back to the parent route. ### Working with Employee Selectors Employee selectors appear in forms when you need to assign someone, add a participant, or select a user (e.g., ticket assignee, approval steps). #### Using Employee Selector Fields Employee selector fields use a combobox: click to open a dropdown, or type to search. The field shows the selected employee's avatar and name. Use **Clear** or the X to remove the selection. #### Searching for Employees Type in the employee selector to search by display name, first/last name, email, job title, department, or location. Results appear as you type. By default, only active employees are shown (depending on the field configuration). When adding approvers, the dropdown opens instantly and stays responsive while typing, even in large organisations. Results are capped at 50 visible matches. If there are more matches, a **"Type to narrow results..."** hint guides you to filter further. #### Selecting Multiple Employees When a field supports multiple employees (e.g., approval approvers), use the multi-select variant. Selected employees appear as stacked avatars with a "+N" for overflow. Use the dropdown to add or remove people. Some selectors support partial selection (e.g., for approval fallback). #### Understanding Employee Avatars Avatars show the employee's photo or initials. Size varies by context (sm, md, lg). VIP employees may have a badge. The Harmony AI agent has a special avatar treatment. #### Viewing Employee Hover Cards Hover over an employee avatar (in selectors, tables, or profiles) to see a hover card. The card shows: name, job title, department, messaging options (Slack, Teams, email), local time, location, office, and phone numbers. VIP badge appears when applicable. Click the profile link to open the employee in People. #### Understanding Employee Status Employee selectors typically filter to **active** employees only. Inactive or terminated employees may be excluded from search results. The `activeOnly` behavior depends on the field (e.g., ticket assignee vs. approval approvers). ### Using the User Menu The user menu is in the sidebar footer. It shows your avatar, name, and email. #### Menu Options * **Admin** - Go to admin (only for Harmony admins) * **Self-service portal** - Open the portal in a new tab * **Documentation** - Open docs.harmony.io * **Theme** - Switch between light and dark * **Log out** - Sign out ![User menu dropdown in sidebar footer](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-fa933e9f43ba6c016db22e22459e76c69e532211%2Fuser-menu.png?alt=media) ### Dynamic Browser Tab Titles Each page in Harmony now displays a meaningful, context-aware title in your browser tab instead of a static label. This makes it easier to identify open tabs at a glance, switch between multiple Harmony pages, and navigate your browser history more effectively. Page titles follow a consistent format, for example: * **Tickets - All Desks | Harmony** * **Ticket - INC-637 (Desk-name) | Harmony** * **Assets - Asset-name | Harmony** * **Employees - Employee-name | Harmony** * **Applications - App-name | Harmony** * **Settings - Integrations | Harmony** * **Settings - Desk-name: Members | Harmony** ### Accessibility and Assistive Technology Harmony has improved accessibility compliance across all surfaces, including the service desk, settings, assets, applications, people, portal, and dashboard. Key improvements include: * **Keyboard navigation** - Move between pages, navigate tables and dropdown menus, open items with the Enter key, and switch between tabs without a mouse. * **Screen reader support** - Buttons, form inputs, links, and interactive elements include proper labels and roles for use with screen readers. * **Right-to-left language support** - Chat messages and saved views display correctly when using RTL languages such as Hebrew or Arabic, with proper text alignment and layout direction throughout the interface. ### Performance and Responsiveness Harmony is faster and more responsive across the board, particularly for users on older or less powerful hardware: * **Near-instant page navigation** - Blocking loaders during route transitions have been removed, so switching between pages feels immediate. * **Faster tables and filters** - Tables and filter dropdowns use optimised rendering and deferred data loading. * **Snappier forms** - Typing in fields like name, description, and category is smooth, with fewer unnecessary UI updates as you fill out forms. Complex forms no longer trigger full re-renders on every keystroke. * **Dashboard widgets** - Chart animations have been tuned to reduce unnecessary processing. {% hint style="info" %} Use the command palette (`Cmd+K`) to reach most areas without using the sidebar. {% endhint %} {% hint style="info" %} Shortcuts like `g>d` mean: press `g`, then press `d`. No need to hold both at the same time. {% endhint %} *** ### Related Resources
Getting StartedLearn the basics of Harmony Dashboard and key featureshttps://github.com/harmonyso/public-docs/tree/main/guides/getting-started-with-harmony-dashboard/README.md
Managing Your ProfileUpdate your profile settings and preferenceshttps://github.com/harmonyso/public-docs/tree/main/guides/managing-your-profile-and-preferences/README.md
Managing PeopleEmployee directory and profileshttps://github.com/harmonyso/public-docs/tree/main/guides/managing-people/README.md
# Managing Your Profile and Preferences Customize your Harmony Dashboard experience by managing your profile, preferences, theme, and desk visibility. {% hint style="info" %} **Path:** `/settings/preferences` {% endhint %} ### Viewing Your Profile Information Your profile information appears in the **user menu** in the sidebar footer. Click your avatar to open it. The menu shows: * **Name** - Display name from your employee record or account * **Email** - Work email * **Avatar** - Profile photo from your linked employee record, or initials if no photo is set {% hint style="info" %} Profile data (name, email, photo) is synced from your identity provider or HRIS. To change it, update your record in the source system; Harmony will reflect the changes on the next sync. {% endhint %} {% hint style="info" %} To update your profile details or avatar, use your organization's identity provider or HRIS. Harmony displays synced data and doesn't support editing it in the dashboard. {% endhint %} ![User menu in sidebar footer](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-fa933e9f43ba6c016db22e22459e76c69e532211%2Fuser-menu.png?alt=media) ### Setting Your Availability and Out-of-Office Status You can manually set your availability status directly from your user profile in Harmony. This lets your team and the platform know when you are unavailable, either immediately or planned in advance. To set your availability: 1. Click your avatar in the sidebar footer to open the user menu. 2. Select **Availability** or **Out of Office**. 3. Choose a start and end date and time for the unavailable period. 4. Save the entry. You can also: * **Schedule future unavailability** - Select a date range in advance so your status updates automatically when the time arrives. * **View upcoming scheduled periods** - See all manually configured availability windows in one place from your profile. * **Edit or remove entries** - Any availability period you have set manually can be updated or deleted at any time. {% hint style="info" %} Availability status set here applies to your account across Harmony and is visible to others on your team. {% endhint %} ### Setting Personal Preferences Go to **Settings → Preferences** to adjust personal behavior and appearance. Preferences are stored in your browser and apply only to your account. #### Theme Selection (Light/Dark) Choose a theme for the interface: 1. Go to **Settings → Preferences**. 2. Under **Appearance → Theme**, select: * **Light** - Light backgrounds * **Dark** - Dark backgrounds ![Preferences page with Theme and other settings](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-dd35557c6f6e1b320d0fc07846e3ee4f83d7d348%2Fpreferences-theme.png?alt=media) You can also use **Cmd+M** (Mac) or **Ctrl+M** (Windows/Linux) anywhere to toggle the theme, or use the **Theme** option in the user menu. Dark mode can also be toggled from the command menu (**Cmd+K** / **Ctrl+K**). Your dark mode preference is now saved between sessions, so you no longer need to re-enable it each time you log in. Dark mode is also applied consistently to the login screen and admin or impersonation flows. #### Enter Key Behavior for Messages Control how Enter works in ticket message fields: 1. Go to **Settings → Preferences**. 2. Under **Ticket Messages → Enter key behavior**, choose: * **Send message (default)** - Enter sends, Shift+Enter adds a new line * **New line** - Enter adds a new line, Shift+Enter sends This affects the ticket chat panel and other message inputs. #### Desk Visibility Preferences Control which desks appear in the Tickets sidebar: 1. Go to **Settings → Preferences**. 2. Under **Desk Visibility**, use the checkboxes to show or hide desks. 3. Click **Save Changes** to apply. Hidden desks disappear from the sidebar. You can still reach them by URL if needed. ![Settings > Preferences with desk visibility checkboxes](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-dd35557c6f6e1b320d0fc07846e3ee4f83d7d348%2Fdesk-visibility-preferences.png?alt=media) #### Desk Ordering Preferences Set the order of desks in the Tickets sidebar: 1. Go to **Settings → Preferences**. 2. Under **Desk Visibility**, drag desks using the grip handle to reorder. 3. Click **Save Changes** to apply. Visibility and order are saved together. Use **Reset** to revert before saving. {% hint style="info" %} Preferences are stored per browser. If you use multiple devices or browsers, set your preferences on each one. {% endhint %} ### Custom Logo for Your Workspace You can upload and manage a custom logo for your Harmony workspace, allowing you to brand your support experience with your own visual identity and make the platform feel native to your product. To add or update your workspace logo: 1. Go to your workspace management settings. 2. Locate the **Logo** section. 3. Upload your logo file and save. Your logo will appear across the Harmony interface for your workspace. *** ### Related Resources
Knowledge BaseKnowledge Base sources and articleshttps://github.com/harmonyso/public-docs/tree/main/guides/managing-knowledge-base/README.md
Navigating the InterfaceMaster the sidebar, command palette, and keyboard shortcutshttps://github.com/harmonyso/public-docs/tree/main/guides/navigating-the-interface/README.md
User Roles and PermissionsUnderstand access control and permissionshttps://github.com/harmonyso/public-docs/tree/main/guides/understanding-user-roles-and-permissions/README.md
# Understanding User Roles and Permissions Understand the different user roles and permissions in Harmony Dashboard, including platform roles, desk roles, and how they affect feature access. {% hint style="info" %} **Path:** View user roles at `/settings/user-management` {% endhint %} ### Overview of User Roles Harmony uses role-based access control (RBAC) to ensure that every team member only sees and interacts with what is relevant to their responsibilities. Roles are split into two types: 1. **Platform roles** - Apply across the whole tenant (Admin, Agent, Observer) 2. **Desk roles** - Apply per service desk (Manager, Agent, Observer) Your effective access depends on the combination of these roles. Navigation, actions, and visible content all adapt to your assigned role automatically. ### Platform Roles Platform roles are tenant-wide and control access to the main dashboard areas. | Role | Access | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Platform Admin** | Full access: Dashboard, Tickets, Agents, Workflows, Assets, Software, People, Settings. Implicit access to all desks. Cannot be assigned to tickets unless also a Desk member. | | **Platform Agent** | All modules except Settings. The Tickets section is only visible if the user is also a Desk member. | | **Platform Observer** | Read-only access to the same areas as Agent. The Tickets section is only visible if the user is also a Desk member. | Platform roles are assigned through your identity provider (e.g., Okta, Entra ID). Harmony reads them from your JWT on login. {% hint style="info" %} The Employee role has been removed from Harmony. Role assignment is now simplified to the platform roles listed above plus desk roles, reducing confusion when configuring access for your team. {% endhint %} ### Desk Roles Desk roles are per-desk and control what you can do on each service desk. | Role | Access | | ----------------- | ----------------------------------------------------------------------------- | | **Desk manager** | Manages the desk, its teams, and settings. Can access Settings for that desk. | | **Desk agent** | Works tickets on the desk. | | **Desk observer** | Read-only access to the desk. | You can have different desk roles on different desks. Platform Admins have implicit manager-level access to all desks. ### Understanding Role Permissions Access is derived as follows: * **Dashboard, Agents, Workflows, Assets, Software, People** - Visible only with a platform role. * **Tickets** - Visible with a platform role combined with Desk membership, or any desk-level access. * **Settings** - Visible to Platform Admins and desk managers (for their desks). * **Landing page** - Platform role → Dashboard; desk-only → first desk; otherwise → Portal. * **Assets** - Access to asset listings is governed by your role. Agents and users can only view the assets they are permitted to see, in line with Harmony's broader authorization model. Desk access comes from your identity provider via groups. Your employee record is linked to desk resources with a `manager`, `agent`, or `observer` relation. Permissions are applied uniformly across all Service Desk operations, so access control behaviour is consistent and predictable regardless of which service calls are made. ### Copilot Chat Access by Role Harmony's Copilot chat is available to users with the following platform roles: | Role | Copilot Access | | --------------------- | -------------- | | **Platform Admin** | ✓ | | **Platform Agent** | ✓ | | **Platform Observer** | ✓ | Copilot is not available to users without a platform role (i.e., desk-only access). This means your support agents and observers can take advantage of AI-assisted guidance directly within their existing accounts, without requiring Admin-level access. ### API Access Keys and Role-Based Permissions API Access Keys are subject to the same role-based permission boundaries as your human users. Each key is mapped to an equivalent platform role based on its permission level: | Key Type | Equivalent Role | Capabilities | | ---------------- | ----------------- | -------------------------- | | **Read + Write** | Platform Admin | Full read and write access | | **Read-only** | Platform Observer | View-only access | This reduces the risk of over-privileged API access and makes it easier to enforce consistent security boundaries across both human users and automated integrations. ### Custom Display Names for Roles You can rename roles in your workspace to better reflect how your team is structured. Instead of being limited to default role names, you can set a custom display name for any role - making it easier to align Harmony's access management with your organization's own terminology and hierarchy. Role display names are also kept clear and consistent across Access Management, so permissions are easy to understand at a glance when assigning access to team members. No changes to underlying permissions occur when display names are updated. ### Viewing Your Assigned Roles To see another user's roles, go to **Settings → User Management → Users**, then open the user. The detail view shows: * **Groups** - IdP groups with role badges * **Desks** - Desks with Desk manager / Desk agent / Desk observer badges ![User detail pane with Groups, Desks, and role badges](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-92dfdc92a5307d1cc66c380adbefd406e35af3af%2Fuser-roles-badges.png?alt=media) Your own roles control what you see in the sidebar and where you land after login. There is no self-service "view my roles" page; admins manage roles in the identity provider. ### Understanding Role Badges Role badges appear in: * **Users table** - Under the Role column, showing platform and group-derived roles * **User detail** - Next to each group and desk Badges use outline style and show role names such as "Platform Admin", "Desk manager", "Desk agent", "Desk observer". If a custom display name has been set for a role, the custom name appears in place of the default. ![Users table with Role column badges](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-99ecc2ca7b448b135d1607e1bff6c3d8f8e37bac%2Fusers-table-role-column.png?alt=media) ### How Roles Affect Access to Features | Feature | Platform Admin | Platform Agent | Platform Observer | Desk-only | | --------- | ----------------------------- | ------------------- | ------------------ | ------------------ | | Dashboard | ✓ | ✓ | ✓ | ✗ | | Tickets | ✓ (all desks, if Desk member) | ✓ (if Desk member) | ✓ (if Desk member) | ✓ (assigned desks) | | Agents | ✓ | ✓ | ✓ | ✗ | | Workflows | ✓ | ✓ | ✓ | ✗ | | Assets | ✓ | ✓ | ✓ (read-only) | ✗ | | Software | ✓ | ✓ | ✓ (read-only) | ✗ | | People | ✓ | ✓ | ✓ (read-only) | ✗ | | Settings | ✓ | ✓ (if desk manager) | ✗ | ✗ | | Portal | ✓ | ✓ | ✓ | ✓ | | Copilot | ✓ | ✓ | ✓ | ✗ | ### Group-Based Role Assignments Roles are assigned through **groups** in your identity provider. Harmony does not edit roles directly; it consumes group membership and maps groups to platform and desk roles. Admins configure role mappings in the identity provider. Changes there sync to Harmony and determine what users can see and do. You can also set custom display names for roles directly within Harmony's Access Management settings to match your organization's terminology. {% hint style="info" %} User and group management happens in your identity provider. Harmony reflects those assignments; it does not let you add or remove users or change their roles in the app. {% endhint %} *** ### Related Resources
User ManagementManage users, groups, and roleshttps://github.com/harmonyso/public-docs/tree/main/guides/managing-user-management/README.md
Managing PeopleEmployee directory and profileshttps://github.com/harmonyso/public-docs/tree/main/guides/managing-people/README.md
Managing Your ProfileUpdate your profile settings and preferenceshttps://github.com/harmonyso/public-docs/tree/main/guides/managing-your-profile-and-preferences/README.md
Navigating the InterfaceMaster the sidebar, command palette, and keyboard shortcutshttps://github.com/harmonyso/public-docs/tree/main/guides/navigating-the-interface/README.md
# Using Harmony Copilot Harmony Copilot is an AI-powered assistant built directly into the Harmony platform. It lets you manage IT support tasks through natural conversation without leaving the page you are on, navigating complex menus, or switching between tools. Copilot understands your organization's data and can take action on your behalf, so you can focus on resolving issues rather than finding where to start. ### Accessing Copilot Copilot is available from every page in the product. To open it, select the **Copilot** button in the interface. A chat panel slides open and is ready to use immediately. When you first open the panel, Copilot displays a set of quick-start prompts to help guide your initial steps. If you already know what you need, you can skip the prompts and type a request directly into the free-text input field. ### What You Can Do with Copilot #### Create tickets through conversation Instead of filling out a form, you can describe an issue in plain language and Copilot will create a support ticket on your behalf. Copilot extracts the relevant details from your description, maps them to the appropriate fields, and confirms the result so you always know what was submitted. #### Take action without switching context Copilot can act on your behalf across IT support workflows. Because it understands your organization's data, it can surface the right information and perform tasks in response to a single conversational request, keeping you on the page you are already working from. ### Tips for Getting the Best Results * **Be specific** - Include details such as the affected user, device, or service when describing an issue. The more context you provide, the more accurately Copilot can act. * **Use the quick-start prompts** - If you are unsure how to phrase a request, the suggested prompts are a good starting point and show you the kinds of tasks Copilot can handle. * **Review before confirming** - Copilot summarizes the action it is about to take before executing it. Read the summary and confirm or adjust as needed. * **Iterate naturally** - If the first response is not quite right, follow up in the same conversation. Copilot maintains context across the messages in a session. ### Availability Harmony Copilot is available to all users directly within the platform. No additional installation or configuration is required to start using it - simply open the chat panel from any page and begin. # Installing the Harmony App on MDM Deploy the Harmony app to managed Windows, macOS and iOS devices automatically using Intune, Jamf Pro, JumpCloud, Workspace ONE, Ivanti or Kandji. Harmony is available as an installable app, so your employees can open it from the Start menu or the Dock instead of finding a browser tab. If your organization manages devices with an MDM, you can install it on every device automatically, with no installer to package, no administrator rights, and nothing for your users to do. This guide explains how the deployment works, what to check before you start, and the exact steps for the most common MDM platforms. {% hint style="info" %} This guide is about deploying the Harmony app **to** your devices. It is not about connecting your MDM as an integration so that Harmony can read your device inventory. For that, see [Unified MDM Device Management](https://github.com/harmonyso/public-docs/tree/main/guides/unified-mdm-device-management/README.md). {% endhint %} ### How it works Your MDM does not install the app itself. It delivers a single browser policy called `WebAppInstallForceList` to the device, and Chrome or Edge installs the Harmony app the next time it starts. Because the browser is already running in the user's session, nothing needs elevation and nothing interrupts them. Two things follow from this. The policy value is identical on every platform, so the only real difference between MDM platforms is how you deliver it. And because the browser performs the install, your Harmony address must be reachable from the device at that moment. ### Supported Platforms | Platform | How the app is delivered | Silent install | | ----------------- | ----------------------------------------------- | -------------------- | | Windows 10 and 11 | Browser policy, through Chrome or Edge | Yes | | macOS | Browser policy, through a configuration profile | Yes | | iPhone and iPad | Managed Web Clip | Icon only, see below | | Linux | Browser policy, through a managed policy file | Yes | ### Choose your platform Read the two short sections below, then jump straight to your own MDM. | Your MDM | Go to | | ---------------------- | ------------------------------------------------------------------------- | | Microsoft Intune | [Configuring Microsoft Intune](#configuring-microsoft-intune) | | Jamf Pro | [Configuring Jamf Pro](#configuring-jamf-pro) | | JumpCloud | [Configuring JumpCloud](#configuring-jumpcloud) | | Workspace ONE UEM | [Configuring Workspace ONE UEM](#configuring-workspace-one-uem) | | Ivanti Neurons for UEM | [Configuring Ivanti Neurons for UEM](#configuring-ivanti-neurons-for-uem) | | Kandji | [Configuring Kandji](#configuring-kandji) | | Something else | [Configuring any other MDM](#configuring-any-other-mdm) | | iPhone or iPad | [Setting up iPhone and iPad](#setting-up-iphone-and-ipad) | ### What you need before you start 1. **Find your Harmony address.** In Harmony, go to **Settings** and open **General**. The **Domain** field shows your address, in the form `yourcompany.harmony.io`. Every example below uses `yourcompany`, so replace it with your own. 2. **Confirm the app is installable.** Open `https://yourcompany.harmony.io/` in Microsoft Edge on a test machine and check that the **Install** icon appears in the address bar. If you cannot install it by hand, no policy will install it either. 3. **Allow Harmony through your proxy and SSL inspection.** Allowing `*.harmony.io` covers the application, its API and its realtime endpoint. 4. **Check that your target users have Harmony accounts.** The app opens to your organization's sign-in on first launch. Pushing it to a group without Harmony access gives those users an icon that leads to a login wall. {% hint style="warning" %} If `https://yourcompany.harmony.io/` does not load at all, the DNS record for your address may not be provisioned yet. Contact Harmony support before you build any policy. {% endhint %} {% hint style="info" %} If your network policy requires exact hostnames rather than a wildcard, or blocks outbound websockets by default, contact Harmony support for the precise list for your instance. A blocked websocket stops live ticket updates without showing an error. {% endhint %} ### What lands on the device | | | | -------------- | --------------------------------------------------------- | | **Appears as** | Harmony, in the Start menu, search and Launchpad | | **Window** | Standalone, with no address bar and its own taskbar entry | | **Opens at** | Your Harmony workspace root | The app updates itself from the web, so there is nothing for your MDM to maintain after the initial deployment. Harmony asks the user before applying a new version rather than reloading underneath them, so users occasionally see an update prompt in the app window. This is deliberate, to avoid losing a half-written ticket. {% hint style="info" %} The Harmony app always opens at your workspace root. Pointing the policy at a deeper path, such as `/portal`, does not produce an app that opens there. {% endhint %} ### Understanding the policy value Every platform below uses the same setting, `WebAppInstallForceList`, but the format differs by operating system. Pick your platform: {% tabs %} {% tab title="Windows" %} A JSON array, written as a single string value. ```json [ { "url": "https://yourcompany.harmony.io/", "default_launch_container": "window", "create_desktop_shortcut": true, "fallback_app_name": "Harmony" } ] ``` {% endtab %} {% tab title="macOS" %} A property list array of dictionaries, not a JSON string. ```xml WebAppInstallForceList url https://yourcompany.harmony.io/ default_launch_container window fallback_app_name Harmony ``` {% endtab %} {% tab title="Linux" %} A JSON file, with the setting name as a key. ```json { "WebAppInstallForceList": [ { "url": "https://yourcompany.harmony.io/", "default_launch_container": "window", "fallback_app_name": "Harmony" } ] } ``` {% endtab %} {% endtabs %} Whichever format you use, the fields mean the same thing. | Field | What it does | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `url` | Required. Your Harmony address, including the trailing slash. | | `default_launch_container` | `window` opens Harmony standalone, with no address bar and its own taskbar button. `tab` opens it as an ordinary browser tab. | | `create_desktop_shortcut` | Adds a desktop icon. A Start menu entry is created either way. Ignored on macOS, where the app goes to the Applications folder. | | `fallback_app_name` | The name used if Harmony cannot be reached at install time, for example on a laptop that first starts up off the network. Prevents a raw URL appearing in the Start menu. | {% hint style="warning" %} Write this value in a plain text editor. Curly quotes from a word processor or a rich text ticket field are the most common reason a policy is silently rejected. {% endhint %} ### Configuring Microsoft Intune Microsoft Edge policies ship with Intune, so Edge is the shortest path. Google Chrome requires importing Google's policy templates first. #### Microsoft Edge 1. Sign in to `intune.microsoft.com` as **Intune Administrator** or **Policy and Profile Manager**. 2. Go to **Devices**, then **Configuration**, then select **Create** and **New Policy**. 3. Set **Platform** to `Windows 10 and later` and **Profile type** to `Settings catalog`, then select **Create**. 4. On **Basics**, name the profile, for example `WIN-Edge-Harmony-App`, and record your Harmony address in the description. Select **Next**. 5. Select **Add settings** and search for `WebAppInstallForceList`. 6. Under the category **Microsoft Edge**, select **Configure list of force-installed Web Apps**, then close the picker. The policy is published for both device and user scope, so two copies appear. Choose the one that matches what you will assign to. Device scope installs Harmony for every user of a shared machine. 7. Set the toggle to **Enabled**. The value box is a single free-text field, so paste the whole JSON array into it. 8. Select **Next** through **Scope tags**. 9. On **Assignments**, select **Add groups** and choose a pilot group of five to ten devices. Select **Next**. 10. Review the summary and select **Create**. Widen the assignment once the pilot confirms Harmony installs and signs in. #### Google Chrome Chrome's settings are not in the Intune settings catalog by default, so you must import Google's policy templates first. 1. Download `policy_templates.zip` from [chromeenterprise.google/browser/download](https://chromeenterprise.google/browser/download/). From `windows/admx/`, take `google.admx`, `chrome.admx`, and the `en-US` copies of `google.adml` and `chrome.adml`. 2. Go to **Devices**, then **Configuration**, then the **Import ADMX** tab, then select **Import**. 3. Import `google.admx` first, paired with `google.adml`. This file defines the namespace that Chrome's template depends on, so importing Chrome first fails validation. 4. Import `chrome.admx` paired with `chrome.adml`. Wait until both rows show status **Available**. 5. Create a settings catalog profile as in steps 2 to 4 above, named for example `WIN-Chrome-Harmony-App`. 6. Search for `WebAppInstallForceList`. The imported settings appear under **Google**, then **Google Chrome**. Enable the setting, paste the same JSON array, assign the profile and create it. #### Using a script instead If ADMX import is unavailable in your tenant, write the value directly with a script. This covers Chrome and Edge together. Go to **Devices**, then **Scripts and remediations**, then **Platform scripts**, then **Add**, and select `Windows 10 and later`. Set **Run this script using the logged-on credentials** to `No`, **Enforce script signature check** to `No`, and **Run script in 64-bit PowerShell host** to `Yes`. ```powershell $json = @' [{"url":"https://yourcompany.harmony.io/","default_launch_container":"window","create_desktop_shortcut":true,"fallback_app_name":"Harmony"}] '@ $targets = @( 'HKLM:\SOFTWARE\Policies\Google\Chrome', 'HKLM:\SOFTWARE\Policies\Microsoft\Edge' ) foreach ($key in $targets) { if (-not (Test-Path $key)) { New-Item -Path $key -Force | Out-Null } New-ItemProperty -Path $key -Name 'WebAppInstallForceList' ` -Value $json -PropertyType String -Force | Out-Null } ``` #### Opening Harmony at sign-in On service desk workstations where Harmony is the primary tool for the shift, you can have it open automatically. Add the `WebAppSettings` policy in the same category, with this value: ```json [ { "manifest_id": "https://yourcompany.harmony.io/", "run_on_os_login": "run_windowed" } ] ``` Confirm the identifier at `chrome://web-app-internals` on a machine that already has Harmony installed before rolling this out widely. ### Configuring Jamf Pro Jamf manages Apple platforms. If you also have Windows devices, pair this with Intune or JumpCloud. 1. Go to **Computers**, then **Configuration Profiles**, then select **New**. 2. On the **General** payload, name the profile, for example `MAC-Harmony-App`, set **Level** to `Computer Level`, and set **Distribution Method** to `Install Automatically`. Computer Level matters, because a user-level profile installs Harmony for one account only. 3. Select the **Application & Custom Settings** payload, then **External Applications**, then **Add**. 4. Set **Source** to `Upload File (plist)` and **Preference Domain** to `com.google.Chrome`. For Microsoft Edge, use `com.microsoft.Edge` in a second payload. 5. Upload or paste the property list below. If your Jamf Pro version offers a **Google Chrome** manifest under the **Jamf Repository** source, you can use that instead and fill the field in a typed form. 6. On the **Scope** tab, target a smart computer group. Start with a test group. 7. Select **Save**. The profile installs at the next check-in, and Harmony appears the next time Chrome starts. ```xml WebAppInstallForceList url https://yourcompany.harmony.io/ default_launch_container window fallback_app_name Harmony ``` {% hint style="warning" %} On macOS this value must be a real property list array of dictionaries, as shown above. Pasting the Windows JSON string into a Mac profile does not work, and fails without an error message. {% endhint %} On macOS, Harmony installs to `~/Applications/Chrome Apps.localized/` and appears in Launchpad and Spotlight. ### Configuring JumpCloud JumpCloud covers Windows and macOS through two different mechanisms, so build one policy per platform and bind both to the same device group. Windows devices need the JumpCloud agent, and Macs must be enrolled in JumpCloud MDM. #### Windows 1. Go to **Device Management**, then **Policy Management**, then **New Policy**, and select the **Windows** tab. 2. Choose the **Advanced: Windows Registry** template. 3. Name the policy, then add a registry value with **Registry Hive** `HKEY_LOCAL_MACHINE`, **Path** `SOFTWARE\Policies\Google\Chrome`, **Name** `WebAppInstallForceList`, and **Type** `String (REG_SZ)`. Paste the JSON array as the value, on a single line. 4. Add a second registry value, identical except for the path, using `SOFTWARE\Policies\Microsoft\Edge`. 5. On the **Device Groups** tab, bind the policy and save. If the registry template is not available in your tenant, use **Commands** with the PowerShell script from the Intune section, run as `System` on a repeating schedule so it reapplies itself. #### macOS Save a configuration profile containing the `com.google.Chrome` payload shown in the Jamf Pro section, then go to **Policy Management**, **New Policy**, **Mac**, and choose the **Custom MDM Configuration Profile** template. Upload the profile and bind it to your Mac device group. ### Configuring Workspace ONE UEM #### Windows A script is the lower-friction route, because it needs no template import and covers both browsers at once. Go to **Resources**, then **Scripts**, then **Add**, and select Windows. Set the language to **PowerShell**, the execution context to **System**, and the architecture to **64-bit**, then paste the script from the Intune section. Assign it to a smart group with a periodic trigger, so the value is restored if it is changed locally. #### macOS Go to **Resources**, then **Profiles**, then **Add**, then **Apple macOS**, then **Device Profile**. Select the **Custom Settings** payload and paste the property list from the Jamf Pro section, with the target domain `com.google.Chrome`. Assign to a smart group and select **Save & Publish**. ### Configuring Ivanti Neurons for UEM This applies to Ivanti Neurons for UEM and to older MobileIron Core builds. Console labels differ slightly between the two, but the mechanism is the same. #### Windows Go to **Configurations**, then **Add**, then Windows, then **Custom Settings**, and add an OMA-URI setting. For Microsoft Edge, no template import is needed. For Chrome, ingest Google's templates through the same mechanism first, then reference the Chrome node at: ``` ./Device/Vendor/MSFT/Policy/Config/Chrome~Policy~googlechrome/WebAppInstallForceList ``` Set the value using ADMX policy syntax, with the quotes in the JSON escaped for XML: ``` ``` {% hint style="info" %} The escaping makes this route easy to get wrong. If Ivanti can run PowerShell against your Windows devices, the script from the Intune section does the same job with no escaping and is easier to audit. {% endhint %} #### macOS Go to **Configurations**, then **Add**, then macOS, then **Custom Configuration**, and upload the same configuration profile you would use with Jamf Pro or JumpCloud. ### Configuring Kandji 1. Save a configuration profile containing the `com.google.Chrome` payload from the Jamf Pro section. 2. Go to **Library**, then **Add New**, then **Custom Profile**. 3. Upload the profile, name the library item, for example `Harmony app`, and assign it to the Blueprints that should receive it. 4. Select **Save**. Kandji applies the profile at the next agent check-in, and Harmony appears at the next Chrome launch. ### Configuring any other MDM There is no Harmony-specific integration involved. If your management tool can do any one of the following, it can deploy the Harmony app. **Write a Windows registry value.** Set `WebAppInstallForceList` as a `REG_SZ` value containing the JSON array, under `HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Google\Chrome` for Chrome, or `HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\Edge` for Edge. **Deliver a macOS configuration profile.** Use the `com.google.Chrome` property list payload from the Jamf Pro section. It is portable across every Apple MDM. **Manage Chrome from the Google Admin console.** If your browsers or ChromeOS devices are enrolled in Chrome Browser Cloud Management, go to `admin.google.com`, then **Devices**, then **Chrome**, then **Settings**, then **Users & browsers**. Select the target organizational unit, find **Force-installed web apps**, and paste the same JSON array. On Windows, note that registry policies take precedence over cloud policies by default. **Place a file on Linux.** Write a JSON file with `WebAppInstallForceList` as a key to `/etc/opt/chrome/policies/managed/harmony.json` for Chrome, or `/etc/opt/edge/policies/managed/harmony.json` for Edge, owned by root with mode 0644. ### Setting up iPhone and iPad Apple provides no equivalent of `WebAppInstallForceList`, so the Harmony app cannot be installed silently on iOS or iPadOS the way it can on Windows and macOS. What you can do instead is push a managed **Web Clip**: a Harmony icon on the home screen that opens the app full screen, without Safari's browser controls. Harmony supports this, so the icon uses the Harmony name and opens without a browser bar. Most MDM platforms offer a Web Clip payload directly. In Intune it is under **Apps**, then **iOS/iPadOS**, as the **Web clip** app type. In Jamf Pro it is the **Web Clip** payload. Set the URL to `https://yourcompany.harmony.io/` and enable full screen. {% hint style="info" %} Most Web Clip payloads let you prevent users removing the icon. On corporate-owned devices this is usually fine. On personally-owned devices enrolled in your MDM, an icon that cannot be removed tends to generate complaints, so consider leaving it removable. {% endhint %} ### What your users see Installation is invisible. There is no prompt, no progress bar, no restart, and no administrator rights required. Afterwards your users find a **Harmony** entry in the Start menu, or in Launchpad on macOS, with the Harmony icon and searchable from the taskbar. They also get a desktop shortcut if you enabled it. Opening it gives a clean standalone window with no address bar and its own taskbar button, which can be pinned like any other application. While the policy is assigned, the app cannot be removed and shows as managed by your organization. Allow up to eight hours for the policy to reach a device, then a browser restart for the app to appear. To test immediately, force an MDM sync on the device and fully close and reopen the browser. ### Verifying the installation 1. On a target device, open `chrome://policy` or `edge://policy` and select **Reload policies**. 2. Find `WebAppInstallForceList`. The status should read **OK**. Anything else, or the policy missing entirely, tells you where the problem is. 3. Check `chrome://apps` for the Harmony app. A successful result in your MDM console confirms only that the policy value was written, not that the app installed. That evidence is in the browser. ### Troubleshooting | Symptom | Likely cause | What to do | | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | The policy does not appear at `chrome://policy` | For Chrome, the policy templates were never imported. Otherwise the value was written to the wrong registry hive. | Confirm the ADMX import status is **Available**, or check the value under `HKEY_LOCAL_MACHINE`. | | The policy appears with status **Error** | The JSON is malformed, usually curly quotes or a trailing comma. | Re-paste the value from a plain text editor. | | The policy reads **OK** but no app appears | Harmony or its icons could not be reached at install time, usually a proxy or SSL inspection rule. | Allow `*.harmony.io`, then open `chrome://web-app-internals` for the exact reason. | | Harmony opens in a browser tab | `default_launch_container` is missing or set to `tab`. | Set it to `window`. The change applies to new installations. | | It works in Edge but not Chrome | Only one browser's policy was deployed. | The two browsers read separate settings, so deploy both. | ### Removing the app Remove the group from the policy assignment, or set the value to an empty array `[]`. Enforcement stops at the next browser launch. The app itself stays installed and simply becomes removable by the user. This is deliberate, so that a policy change does not delete an app someone is working in. Neither browser offers a supported silent uninstall for web apps, so plan removal as a message to your users rather than a command. ### Related Resources
Using the Harmony PortalWhat your employees see in the apphttps://github.com/harmonyso/public-docs/tree/main/guides/using-the-harmony-portal/README.md
User Roles and PermissionsMake sure your users have access firsthttps://github.com/harmonyso/public-docs/tree/main/guides/understanding-user-roles-and-permissions/README.md
Unified MDM Device ManagementConnect your MDM so Harmony can read deviceshttps://github.com/harmonyso/public-docs/tree/main/guides/unified-mdm-device-management/README.md
Navigating the InterfaceFind your way around Harmonyhttps://github.com/harmonyso/public-docs/tree/main/guides/navigating-the-interface/README.md
# Creating and Managing Custom Dashboards Learn how to create, navigate, duplicate, rename, and manage custom dashboards in Harmony. {% hint style="info" %} **Path:** `/dashboard` {% endhint %} ### Understanding the Dashboard Overview The Dashboard is your central view for IT operations metrics. Harmony shows one dashboard at a time. When you open **Dashboard** from the sidebar, you see either your default dashboard or the built-in system dashboard. The main area displays widgets in a responsive grid: drag to reorder, resize by dragging corners (in edit mode), and add or remove widgets as needed. Dashboards now support a significantly expanded metrics engine, giving you deeper visibility into your support operations. You can apply advanced filtering, control sort order, hide empty data groups, and view interactive charts - including time-series trends and application distribution breakdowns - directly within your dashboards. ### Understanding the System Dashboard The **system dashboard** is a built-in dashboard named "Dashboard" that includes a predefined set of metrics: response time, resolution time, SLA compliance, ticket breakdowns, software and asset metrics, and more. It is always available and appears first in the dashboard list. The system dashboard \*\*cannot be edited\*\*, duplicated, or deleted. To customize your view, create a new dashboard or duplicate an existing one. Platform admins retain exclusive control over the system dashboard - desk admins cannot edit or delete it. ### Understanding Dashboard Permissions Harmony supports two levels of dashboard management access: * **Platform admins** have full control over all dashboards, including the system dashboard. Only platform admins can manage the default overview dashboard. * **Desk admins** can create new dashboards and edit or delete any dashboard they have created or been assigned ownership of. Desk admins can view all dashboards but can only modify those they own. This allows teams to manage their own reporting views without requiring platform-level admin access. ### Creating Your First Dashboard 1. Click the dashboard title (or the chevron next to it) to open the dashboard dropdown. 2. Click **Create dashboard** at the bottom. A new empty dashboard is created and opened. The backend assigns a name such as "Untitled Dashboard" or "Untitled Dashboard 2". You can rename it in edit mode and add widgets. Both platform admins and desk admins can create dashboards. Once created, the dashboard owner can edit or delete it. ![Dashboard dropdown with Create dashboard, star, and copy icons](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-68fb67a28f543db2b365bd84422b7de21d9bbfb5%2Fdashboard-dropdown.png?alt=media) ### Navigating Between Multiple Dashboards * Click the dashboard title in the header to open a dropdown of all dashboards. * Use the search field to filter by name. * Click a dashboard to switch to it. The list shows "All dashboards" with each dashboard's name and creator. When you visit **/dashboard** (without an ID), Harmony shows your default dashboard, or the system dashboard if no default is set. ### Setting a Default Dashboard The default dashboard is the one that opens when you go to **/dashboard**. 1. Open the dashboard dropdown (click the title). 2. Find the dashboard you want as default. 3. Click the **star** icon. A filled star indicates the current default. You can set the system dashboard as default by starring it when no other dashboard is starred. ### Duplicating Dashboards 1. Open the dashboard dropdown. 2. Hover a dashboard and click the **copy** icon. 3. A duplicate is created and opened. Custom dashboards copy their layout; the system dashboard is copied with the default layout and named "Dashboard Copy". ### Renaming Dashboards 1. Click **Edit** to enter edit mode. 2. Click the dashboard title or the **Edit** icon next to it. 3. Type the new name (up to 32 characters). 4. Press Enter or click away to commit, then click **Save & Exit**. Names are saved when you exit edit mode. ### Deleting Custom Dashboards 1. Click **Edit** to enter edit mode. 2. Click **Delete** in the header. 3. Confirm in the dialog. The system dashboard cannot be deleted. You must keep at least one dashboard; the Delete button appears only when more than one dashboard exists. Desk admins can delete dashboards they own. Platform admins can delete any custom dashboard. ![Edit mode with Delete button in header](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-61d6bee101ed0fa56a142cce7a2c0386b9e8d905%2Fdashboard-edit-delete.png?alt=media) ### Using Advanced Metric Filtering and Controls When configuring widgets and reports on your dashboards, you have access to a richer set of controls for shaping the data you see: #### Filter Operators Apply precise filters to metric queries using the following operators: * **Equals** - match an exact value * **Not-equals** - exclude a specific value * **Regex match** - include results that match a regular expression pattern * **Regex non-match** - exclude results that match a regular expression pattern #### Sort Control Choose how metric results are ordered: * **Ascending** or **descending** sort order for standard ordering of results * **No sorting** to preserve the natural query order when sequence matters #### Hide Empty Groups When a metric query returns groups with no data, you can enable **hide empty groups** to suppress those rows or segments from the display. This keeps your charts and tables focused on the data that is actually present. ### Viewing Charts and Analytics Breakdowns Dashboards include interactive chart types and structured analytics views to help you understand trends and distributions in your support data: * **Application breakdown chart**: See how your support activity is distributed across different applications at a glance. This software/application distribution breakdown shows volume spread across the apps your team supports. * **Time-series and interval reporting**: View trends over time by selecting reporting intervals. This lets you track how metrics change day over day, week over week, or across any custom period. These visualizations are available when adding or configuring widgets on any custom dashboard. ### Related Resources
Dashboard WidgetsAdd, configure, and arrange dashboard widgetshttps://github.com/harmonyso/public-docs/tree/main/guides/working-with-dashboard-widgets/README.md
Getting StartedLearn the basics of Harmony Dashboard and key featureshttps://github.com/harmonyso/public-docs/tree/main/guides/getting-started-with-harmony-dashboard/README.md
# Working with Dashboard Widgets Learn how to add, configure, arrange, and customize dashboard widgets in Harmony. {% hint style="info" %} **Path:** `/dashboard` {% endhint %} ### Understanding Widget Types Dashboard widgets fall into two categories: **number widgets** and **chart widgets**. #### Number Widgets Number widgets display a single metric, such as: * Average Response Time * Average Resolution Time * SLA Compliance * Total Tickets They use a fixed height and can span 3-12 columns wide. Spacing around number widgets has been improved for a cleaner layout. Number widgets are interactive - clicking a single number widget (e.g. total ticket count) navigates to the corresponding page with the widget's filters automatically applied. For number-group widgets (e.g. tickets broken down by status), click any individual entry to navigate to that page filtered by that specific value. Clickable widgets display a subtle highlight on hover so it is clear they are interactive. #### Chart Widgets Chart widgets visualize data as line charts, bar charts, or donut charts. Examples include: * Ticket breakdown, software breakdown, asset breakdown * Tickets resolved by employee, tickets solved by AI * SLA compliance, response vs resolution, ticket priority * Agent metrics Each chart widget is predefined to support one or more chart types (line, bar, donut). When multiple types are available, you can switch between them using the chart-type toggle in the widget header. You can also click directly on chart elements - such as bar chart segments, donut chart slices, and bar-gauge visualizations - to navigate to a filtered view of the underlying data. Relevant filters (including team and desk) are automatically applied so the resulting view matches exactly what the widget was showing. #### Widget Descriptions and Tooltips All default dashboard widgets include a plain-language description of what they measure. An info tooltip icon appears on each widget - hover over it to read the explanation without leaving your dashboard. This helps your team interpret data at a glance without needing additional context. ### Available Widgets The widget library spans several data source categories. Below is an overview of what is available. #### Tickets Ticket widgets cover the full range of support metrics, including: * Priority breakdown, unassigned ticket count, average satisfaction score * Top service catalog items, top categories, top symptoms * SLA metrics and resolution trends * Status-based counts, assignee breakdowns, workflow and knowledge base links #### Requests Six request-based widgets capture Harmony's complete impact on support operations, including conversations resolved autonomously before a ticket was created: * **Deflection Rate** - a KPI tile showing the percentage of requests resolved by Harmony out of all conversations * **Total Requests by Resolution** - a donut chart breaking down requests into "Resolved by Harmony" vs. "Escalated to Human" * **Request Resolution Trend** and additional request-focused metrics These widgets are available in the widget library under the **Requests** section. #### Assets Asset widgets give you richer visibility into your asset inventory at a glance: * **Asset breakdown by age** - assets categorized into age ranges (0-1 year, 2-3 years, 4-5 years, 6+ years) based on purchase date, with manufacturing year used as a fallback * **Asset breakdown by EOL status** - see how many assets are End of Life, EOL Planned, or Supported; click any segment to navigate to the Assets page filtered by that EOL status * **Asset breakdown by vendor** - distributed view of assets by vendor * **Asset by Age** - click any age bucket to open the assets table pre-filtered by that age range #### Applications Five pre-built application insight stat widgets are available under the **Applications** section in the widget library: * **Ghost** - applications with no recent activity * **Inactive** - applications that have gone dormant * **Shadow** - untracked or undiscovered applications * **Orphaned** - applications with no assigned owner * **Impaired** - applications experiencing issues Each widget displays a live snapshot count. Clicking any widget takes you directly to the Applications page with the matching filter applied. Application insight widgets show counts that match what you see on the main applications page, filtered by the same default statuses - Approved and Discovered - so numbers are always aligned and reliable. #### Employee Adoption The **Employee Adoption Rate** widget shows the percentage of employees who submitted at least one request via the Service Desk Agent, visualized week over week so you can spot trends at a glance. Features include: * **Week-over-week chart** - see how adoption changes over time * **Time-frame filtering** - narrow the view to specific date ranges * **Per-tenant data** - each organization sees its own adoption figures #### Live Queue Widgets Three real-time widgets give your team instant visibility into the current state of your support queue: * **Open tickets now** - displays the current count of all tickets in an open or pending state * **Unassigned tickets now** - shows how many tickets are currently waiting to be assigned to an agent * **Tickets crossed SLA threshold now** - highlights the number of tickets that have breached their SLA ### Adding Widgets to Your Dashboard #### Using the Widget Library 1. Click **Add widgets** (with the plus icon) in the dashboard header. 2. The **Widget library** opens as a side panel with all available widgets, organized by category (Tickets, Requests, Assets, Applications, and more). 3. Click a widget to add it. Widgets are sorted by category (number first, then chart) and by type. Hover over a widget in the library to see a preview before adding. You can also access the library directly from a new dashboard's empty state to get started immediately. ![Widget library side panel](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-4ed177f28f5d89297f9baf199a2551d4d7c6e892%2Fwidget-library.png?alt=media) #### Quick Add in View Mode On a custom dashboard (not the system dashboard), you can add widgets without entering edit mode. Click **Add widgets**, choose a widget, and it is added and saved automatically. #### Add in Edit Mode For finer control, enter edit mode first: 1. Click **Edit** in the header. 2. Click **Add widgets** and select from the library. 3. Arrange and resize as needed. 4. Click **Save & Exit** to persist your changes. In edit mode, new widgets are not saved until you click **Save & Exit**. ### Configuring Widget Settings #### Switching Chart Types Chart widgets that support multiple types (line, bar, donut) show a chart-type button in the header. Click it to cycle to the next available type. The button shows the icon of the type you will switch to. Not all chart widgets support all types; availability depends on the widget. #### Widget Units You can configure units for widget metric values so they are displayed in a clear, human-readable format. When setting up or editing a widget, choose from: * **Time** - values are automatically formatted into a readable time display (e.g. hours, minutes, seconds) based on the magnitude of the data * **Currency** - values are displayed as monetary amounts, with the option to select your preferred currency #### Widget Titles and Data Sources Widget titles and data sources are predefined. Each widget is configured to show a specific metric from Harmony (tickets, assets, software, AI performance, etc.). You cannot rename widgets or change their data sources in the UI. ### Clicking Widgets to Explore Data Many widgets act as deep links to filtered views of the underlying data. When you click a widget element, Harmony automatically applies the relevant filters - including team and desk - so the resulting view matches exactly what the widget was showing. This works across: * **Status-based widgets** - click a status (e.g. Pending Approvals) to see all tickets in that state * **Assignee widgets** - click an agent or assignee to view their associated tickets * **Workflow, knowledge base, and service catalog item widgets** - each links through to the corresponding filtered page * **Number widgets** - single values navigate directly to the filtered page; group entries navigate filtered by that specific value * **Asset by Age widget** - click an age bucket to open the assets table filtered to that age range * **Application insight widgets** - click to open the Applications page filtered by the matching status * **Bar charts, donut charts, and bar-gauge visualizations** - click any segment or bar to drill into the matching records Clickable widgets display a subtle highlight on hover so it is clear they are interactive. ### Metric Calculation Accuracy #### Median-Based Averages Average metrics - such as Average Ticket Response Time - now use the statistical median rather than the mean. This gives you a more representative view of typical performance that is less skewed by outliers. #### SLA Score Denominators SLA score widgets now display the denominator alongside the score, so you can see the full picture of how your SLA score is being calculated, not just the resulting percentage. #### CSAT Response Count The Average Satisfaction Score widget displays the number of survey responses the score is based on, giving you instant confidence in how representative the result is. A tooltip explains the score's meaning directly in context. The response count appears consistently alongside the score across all widget and graph types - including bar, pie, line, and table views. When viewing satisfaction scores over time, the response count is shown on hover via a tooltip. ### Removing Widgets 1. Click **Edit** to enter edit mode. 2. Hover a widget and click the **trash** icon in its header. 3. Click **Save & Exit** to persist the change. ### Rearranging Widgets (Drag & Drop) 1. Click **Edit** to enter edit mode. 2. Grab the **drag handle** (grip icon) on the left side of a widget header. 3. Drag the widget to a new position. It snaps to the grid. {/\* IMAGE: Edit mode with drag handle on widget header → /guides/working-with-dashboard-widgets/screenshots/widget-drag-handle.png | UI: frontend-app/src/features/dashboard/components/layout/dashboard-grid.tsx, widgets/chart-widget.tsx | Route: /dashboard \*/} 4. Click **Save & Exit** to save the layout. ### Resizing Widgets 1. Click **Edit** to enter edit mode. 2. Drag the **resize handle** at the bottom-right corner of a widget. **Number widgets:** Width only, 3-12 columns. Height is fixed. **Chart widgets:** Width (3-12 columns) and height (3, 6, or 9 rows). Width snaps to 3, 4, 6, 8, 9, or 12 columns; height snaps to 3, 6, or 9 rows. ### Understanding the Widget Layout Grid The dashboard uses a 12-column grid: * **Desktop:** Widgets use their assigned positions and sizes. * **Tablet:** Layout may show 2 widgets per row where applicable. * **Mobile:** Widgets stack in a single column. Row height is fixed at 99px per row. Margins between widgets are 16px. ### Using Dashboard Date Ranges and Filters The date range selector and desk selector in the dashboard header apply to all supported widgets. #### Filtering by Service Desk A desk selector in the dashboard header lets you choose a particular service desk or view data across all desks at once. The following widgets support desk-based filtering: * **Average Response Time** and **Average Resolution Time** * **SLA Compliance** (number and chart views) * **Total Tickets**, **Opened vs. Resolved**, and **Ticket Breakdown** * **User Satisfaction** and **AI Resolved vs. Escalated** * **Open Tickets Now**, **Unassigned Tickets Now**, and **SLA Breached Now** #### Setting Date Range Presets ![Dashboard with date range selector](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-3dd6213a132664e589dd08ea189ffd48486a2441%2Fdate-range-selector.png?alt=media) Click the date range button to open the selector. Choose a preset: * **Last 24 hours** (1d) * **Last 7 days** (7d) * **Last 30 days** (30d) - default * **Last 90 days** (90d) #### Using Custom Date Ranges 1. Open the date range selector. 2. Enter **From** and **To** dates (YYYY-MM-DD), or use the interactive calendar to pick any start and end date. 3. Click **Apply time range**. Custom ranges are limited to 90 days. The "From" date must be before the "To" date. When a single day is selected, charts automatically switch to hourly buckets for finer resolution. Date ranges are handled with timezone awareness so results stay accurate regardless of your location. #### How Date Ranges Affect All Widgets The selected date range applies to every widget on the dashboard. Data granularity adjusts automatically: shorter ranges (e.g. 24h) use finer intervals; longer ranges (e.g. 90d) may aggregate by week. Use the refresh button to reload data with the current range. ### Related Resources
Managing Custom DashboardsCreate, navigate, and manage custom dashboardshttps://github.com/harmonyso/public-docs/tree/main/guides/creating-and-managing-custom-dashboards/README.md
Getting StartedLearn the basics of Harmony Dashboard and key featureshttps://github.com/harmonyso/public-docs/tree/main/guides/getting-started-with-harmony-dashboard/README.md
# Analyzing Service Desk Metrics Understand and interpret service desk metrics in the Harmony Dashboard: ticket volume, response and resolution times, SLA compliance, and ticket breakdowns. {% hint style="info" %} **Path:** `/dashboard` {% endhint %} ### Tracking Service Desk Overview The dashboard surface key service desk metrics at a glance. Add these widgets to monitor current state: | Widget | What it shows | | ---------------------- | ------------------------------------------------------------------------------ | | **Tickets Opened** | Number of tickets created in the selected date range | | **Open Tickets** | Current count of tickets in open or active states (Open, In Progress, Pending) | | **Unassigned Tickets** | Current count of tickets without an assignee | | **SLA Breached** | Current count of open tickets that have exceeded their resolution SLA deadline | These metrics use live data from your service desk and update when you refresh. ![Dashboard with Tickets Opened, Open Tickets, SLA Breached widgets](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-372cd701d31697950dab122112bdf1ac1808c12c%2Foverview-widgets.png?alt=media) ### Understanding Ticket Volume Trends #### Total Tickets The **Tickets Opened** widget shows how many tickets were created during the selected time range. It counts unique tickets by `ticket-created` events and is useful for tracking support demand over time. #### Opened vs Resolved Tickets The **Opened vs Resolved Tickets** chart compares ticket creation and resolution over time. It shows: * **Open** - Tickets created each day * **Resolved** - Tickets resolved each day Use it to see whether backlog is growing or shrinking. Available as line or bar chart. ![Opened vs Resolved Tickets chart](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-74f1b1b1943c9eff2c81226025a0c885001df5c7%2Fopened-vs-resolved.png?alt=media) ### Monitoring Response and Resolution Time #### Average Response Time Time from ticket creation to the first non-internal reply. Displayed as a single number (e.g. `45m`, `2h 15m`) for the selected range. #### Average Resolution Time Time from ticket creation to resolution. Also shown as a single number for the selected range. A resolution timestamp is now recorded for every request, giving you a precise record of when each request reached its final state. The timestamp is calculated based on request type and outcome: * **Pending requests** - timestamped at the moment the request was first created * **Requests resolved by Harmony or escalated with a linked ticket** - uses the ticket's SLA completion time, falling back to the ticket event log time, then the last message timestamp * **Requests resolved or escalated without a linked ticket** - uses the last message timestamp as the resolution point This ensures that response time, resolution time, and SLA compliance calculations are as accurate as possible across all request types. #### Response vs Resolution Time Trends The **Response vs Resolution Time** chart shows daily averages for both metrics over time. Helps spot trends and correlate response speed with resolution speed. ![Response vs Resolution Time chart](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-8845ac3389c4a5d0d5f516cac6e7a5c45b2a130a%2Fresponse-vs-resolution.png?alt=media) ### Tracking SLA Compliance #### SLA Compliance Percentage The **SLA Compliance** number widget shows the percentage of tickets that met their SLA (no breach) within the selected range. Computed as `tickets without breach / (tickets + breaches) × 100`. You can now filter and group SLA compliance by **service catalog item**, so you can track SLA performance across the different catalog item types your team has configured. This makes it easier to identify which services are most at risk of breaching their targets. #### SLA Compliance Trends The **SLA Compliance Trend** chart shows how SLA compliance changes over time. It stacks "SLA met" and "SLA breached" so you can see the proportion of each by day. ![SLA Compliance Trend stacked chart](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-e1e2421d09917cfca0053a41ab725ef330e59841%2Fsla-compliance-chart.png?alt=media) #### SLA Breaches The **SLA Breached** widget shows how many open tickets have passed their resolution deadline without being completed. This is a point-in-time count, not a trend. ### Analyzing Ticket Breakdowns #### Breakdown by Status **Ticket Breakdown by Status** shows tickets grouped by status: Open, In Progress, Pending (split into sub-states - see below), Resolved, Closed. Use donut or bar view. Statuses use consistent colors (e.g. green for Open, orange for Pending). Resolution labels now use clearer, more consistent display names across all status breakdowns and reports, making it easier to interpret ticket data at a glance. Internal identifiers such as desk IDs are automatically translated into human-readable names wherever they appear in your reports. A dedicated status breakdown view is also available in the Service Desk, with filtering support so you can narrow the breakdown by criteria relevant to your team's workflow. Use this to quickly identify bottlenecks and track open versus resolved volumes. ![Ticket status donut/bar chart](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-44f4871a74e463796d711ceab5cfd1c9688e9f2c%2Fbreakdown-status.png?alt=media) #### Understanding Pending States The pending status now distinguishes between two specific states, giving you better visibility into where work is queued: * **Pending Harmony** - the request is open and assigned to Harmony (AI is handling it) * **Pending Human** - the request is open and assigned to a human agent This makes it easier to identify bottlenecks, whether the queue is building on the AI side or the human agent side. #### Breakdown by Priority **Ticket Breakdown by Priority** shows ticket volume by priority over time: Low, Medium, High, Urgent. Available as bar or line chart. Clicking a bar can navigate to filtered tickets. ![Ticket Breakdown by Priority chart](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-f15f7f9b4df1936ae95a9bf894aab83c97384095%2Fbreakdown-priority.png?alt=media) #### Breakdown by Assignee You can now filter and group key ticket metrics by assignee, giving you a more granular view of support performance across your team. The following metrics support assignee-level breakdowns: * **Tickets created** - see volume broken down by assignee * **Open ticket age** - understand how long tickets have been open per assignee * **Closed ticket age** - analyse resolution time per agent Assignees are displayed by their human-readable display name rather than internal identifiers. #### Breakdown by Service Catalog Item Ticket metrics can also be filtered and grouped by service catalog item. This gives you a clearer picture of which catalog items are driving the most support volume and how your service catalog is being used in practice. The following metrics support this dimension: * **Tickets created** - see volume per catalog item * **Open ticket age** - understand how long tickets remain open per service * **Closed ticket age** - analyse resolution time across catalog items * **SLA compliance** - track SLA performance by service catalog item #### Breakdown by Tag You can now view aggregated data by tag across your service desk tickets. Tag aggregations make it easier to identify trends, spot recurring issues, and understand which topics are driving the most support volume at a glance. #### Breakdown by Employee (Created/Resolved) * **Tickets Resolved by Employee** - Resolution count by employee over time (top contributors by resolver). * **Tickets Created by Employee** - Creation count by employee over time (requesters or internal creators). Both use the reports API with `groupBy` on the actor. Useful for workload and contribution analysis. ### Measuring User Satisfaction Scores The **User Satisfaction** widget shows an average satisfaction score from survey responses. Scores are shown with a label (e.g. excellent, very good, good, fair, needs improvement) based on the average rating. Add this widget from the Widget Library to include it on your dashboard. ![User Satisfaction widget](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-91cd557c2df840dec8b56b88c88a67a42ece580a%2Fuser-satisfaction.png?alt=media) ### Tracking AI Deflection and Autonomous Resolution Harmony tracks how effectively it handles employee requests without human intervention. These metrics give you a clear picture of your support operation's AI performance over time. #### Autonomous vs. Escalated Requests The deflection metrics show how many employee requests Harmony resolved autonomously versus how many were escalated to a human agent. You can track whether your autonomous resolution rate is improving, declining, or holding steady over any selected time range. Every support conversation is classified into one of the following resolution states: * **Resolved by Harmony** - the AI determined the request was fully answered without human intervention * **Escalated** - a human agent was assigned to the ticket; no AI classification is needed for these requests * **Pending Harmony** - the request is open and Harmony (AI) is handling it * **Pending Human** - the request is open and assigned to a human agent * **Unresolved** - the request could not be conclusively classified Resolution detection uses a layered approach: ticket assignment signals are checked first (escalated tickets are flagged immediately without further AI analysis), followed by AI-powered conversation analysis for the remaining cases. This makes resolution signals more accurate and decisions faster. #### Requests by Category The **Requests by Category** report now lets you slice data by resolution status, giving you a clearer picture of how support volume breaks down across both topic and outcome. Each category can be segmented across three resolution states: * **Resolved by Harmony** - requests handled automatically by the AI * **Escalated** - requests passed on to a human agent * **Pending** - requests still in progress Use this breakdown to spot which request categories drive the most escalations or remain unresolved, so you can tune your automations more precisely. #### Conversation Analytics Conversation data can be broken down by category and resolution type, making it easier to spot trends across different ticket types and outcomes. Resolution metrics are accurately zero-filled for terminal states, ensuring your charts and trend lines reflect complete, consistent data even when there is no activity in a given period. *** ### Related Resources
Automation & SLAConfigure SLA policies and automation ruleshttps://github.com/harmonyso/public-docs/tree/main/guides/configuring-automation-and-sla/README.md
Service Desks & TeamsDesk structure and team configurationhttps://github.com/harmonyso/public-docs/tree/main/guides/managing-service-desks-and-teams/README.md
Working with WidgetsAdd and configure dashboard widgetshttps://github.com/harmonyso/public-docs/tree/main/guides/working-with-dashboard-widgets/README.md
Managing Custom DashboardsCreate and navigate custom dashboardshttps://github.com/harmonyso/public-docs/tree/main/guides/creating-and-managing-custom-dashboards/README.md
# Analyzing Asset and Automation Metrics Understand asset compliance, software status, AI resolution, agent runs, and workflow metrics in the Harmony Dashboard. {% hint style="info" %} **Path:** `/dashboard` {% endhint %} ## Asset Metrics ### Understanding Asset Compliance Status **Asset Breakdown by Compliance** shows how many assets are compliant vs non-compliant (e.g. with MDM or security policies). Use it to monitor compliance across hardware. Click a segment to filter the Assets page by that compliance status. ![Dashboard widget with compliance segments](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-82abdff3ec0211697e89229d381bef668e963211%2Fasset-compliance-widget.png?alt=media) ### Viewing Asset Distribution These widgets show asset distribution on the default dashboard: | Widget | What it shows | | ------------------- | -------------------------------------------------------------------------------------- | | **By Vendor** | Assets grouped by manufacturer. Top 9 vendors shown; the rest are grouped as "Others". | | **By Model Family** | Assets grouped by device model family (e.g. MacBook Pro, iPhone 14). | Clicking a segment opens the Assets page filtered by that dimension. ![Asset distribution widgets (By Vendor, By Model Family)](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-3fcad3320db8a3071b13c4ac80b3bc3125d0c2d4%2Fasset-distribution-widgets.png?alt=media) ### Tracking Asset Lifecycle Status **Asset Breakdown by Status** shows assets by lifecycle status: * **In stock** - Available, not assigned * **Active** - In use * **In repair** * **EOL planned** - End-of-life planned * **EOL grace period** - Past planned EOL, in grace * **EOL reached** - Expired * **Retired** ![Asset Breakdown by Status widget (lifecycle)](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-8d01ad9b5ec5b10f601868d597ba804e41cdc238%2Fasset-status-widget.png?alt=media) ### Understanding Asset Age Breakdown **Asset Breakdown by Age** groups assets by purchase date into buckets: * 0-1 year * 2-3 years * 4-5 years * 6+ years * N/A (no purchase date) Color coding highlights older assets (e.g. orange for 4-5 years, red for 6+). Use it for refresh planning and lifecycle management. ![Asset age breakdown chart](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-e050420d4777117b8aeaaea252c21a267d253187%2Fasset-age-chart.png?alt=media) ### Viewing Asset Breakdown by OS Version **Asset Breakdown by OS Version** lets you view your assets grouped by specific operating system version, giving you a more granular view of your environment than the existing OS type grouping (Linux, Windows, etc.). Use this widget to: * Identify assets running outdated OS versions * Assess coverage gaps across your device fleet * Prioritize remediation efforts for vulnerable or unsupported versions This metric is available alongside existing device and asset reports in the Widget Library. *** ## Software Metrics ### Monitoring Software Status **Software Breakdown by Status** shows the distribution of applications by status: * **Approved** - Authorized for use * **Discovered** - Detected but not yet approved * **Ignored** - Explicitly excluded Click a segment to filter the Software page by that status. ![Software status donut chart](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-bf903457ad95bb9c17bb35881de8eea7b3040a7d%2Fsoftware-status-chart.png?alt=media) *** ## Integration Metrics ### Monitoring Integration Usage **Integration Usage by Category and Product** shows how many integration instances are configured in your tenant, broken down by category and specific product. Use it to understand how integrations are being used across your environment and confirm coverage across key systems. Categories tracked include: * **IdP** - Identity providers (e.g. Okta) * **MDM** - Mobile device management (e.g. Kandji) * **HRIS** - HR information systems (e.g. HiBob) * **EDR** - Endpoint detection and response * And other major integration categories This metric is available in the Widget Library alongside other asset and automation reports. *** ## AI and Automation Metrics ### Tracking AI-Resolved Tickets **Tickets Resolved by AI** shows how many tickets Harmony AI resolved each day. Counts tickets where the resolver was `harmony_ai` and excludes imported tickets. ### Tracking AI-Created Tickets **Tickets Created by AI** shows tickets created by AI agents (e.g. auto-created from triage or enrichment). Filters on `created_by_agent: true` and excludes imported tickets. ### Understanding AI Resolution vs Escalation Rates **AI vs Human Resolution** compares three metrics over time: * **Resolved by AI** - Tickets resolved by Harmony AI * **Escalated to Human** - Tickets escalated to human agents * **Deflected by AI** - Conversations resolved without a ticket Use it to measure deflection and escalation rates. ![AI vs Human Resolution chart (deflection/escalation)](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-df2da1457a7ad7377c491839e48e1a10107f0fac%2Fai-vs-human-resolution.png?alt=media) ### Tracking AI Deflection and Request Volume The reports dashboard includes a dedicated set of metrics to help IT admins understand how effectively Harmony is handling employee requests autonomously. These metrics give you a clear picture of your support operation's performance over time. * **Autonomous vs. escalated requests** - See how many employee requests Harmony resolved without human intervention versus how many were escalated to an agent * **Deflection trend over time** - Track whether your autonomous resolution rate is improving, declining, or holding steady Use these metrics to identify opportunities to improve self-service coverage and reduce agent workload. ### Tracking AI Deflection and Escalation Two dedicated metrics let you monitor where your AI agent is succeeding and where it is handing off to humans: * **Deflected by AI** - Counts conversations where the AI agent made at least one meaningful action (tool call) and resolved the issue without a support ticket being created. This is a clear signal of self-service success. * **Escalated** - Tracks conversations that were handed off to a human agent, letting you monitor where the AI reached its limits. Both metrics appear as widgets in your reporting dashboard and can be tracked over time to measure the impact of changes to your AI configuration and workflows. ### Viewing AI Resolved vs. Escalated Tickets The **AI Resolved vs. Escalated Tickets** chart shows the split between tickets the AI handled end-to-end and tickets that required human involvement: * **AI-resolved tickets** - Tickets the AI handled and closed without human involvement * **Escalated tickets** - Tickets where the AI attempted to help but either automatically escalated based on your workflows, or the user chose to escalate to IT support themselves Use this chart to track AI performance over time and identify trends in escalation that may indicate gaps in your automation coverage. ### Tracking Estimated Savings **Estimated Savings** metrics quantify the real-world value your AI-powered support is delivering by measuring the impact of resolved conversations on your team's workload and operational spend. Savings are broken down across multiple dimensions: * **Time saved** - Estimated seconds saved from AI-resolved conversations * **Cost savings (conservative, typical, and enterprise)** - Three pricing scenarios that reflect the financial impact of automated resolutions across different team contexts Use these figures to demonstrate the ROI of your Harmony deployment and inform decisions about expanding automation coverage. ### Monitoring Agent Run Status **Agent Runs by Status** shows outcomes of Harmony AI agent runs over time: * **Completed** - Successful runs * **Failed** - Runs that failed * **Cancelled** - Runs that were cancelled Built-in agents only; custom workflows are excluded. ![Agent Runs by Status widget (Completed/Failed/Cancelled)](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-ad52372a41780e4eb9fda5750fe333ec49236727%2Fagent-runs-status.png?alt=media) ### Analyzing Agent Runs by Name **Agent Runs by Name** shows run counts by agent name. Displays top 5 agents; others are grouped. Built-in agents only. ### Analyzing Agent Runs by Category **Agent Runs by Category** shows run counts by agent category over time. Built-in agents only. ### Tracking Agent Run Frequency The **Agent Runs** metric gives you visibility into how often your AI agents are being triggered. Use it to understand usage patterns, compare run frequency over time, and optimize your automation workflows. This metric is derived from workflow completion events and is available in both the analytics dashboard and detailed reports. {% hint style="info" %} **Tip:** Harmony ensures both workflow start and completion events are consistently recorded, so the agent run counts you see in reports and usage dashboards accurately reflect what actually ran. This also underpins billing accuracy for your account. {% endhint %} ### Monitoring Workflow Run Status **Workflow Runs by Status** shows outcomes of *custom* workflow runs: * **Completed** * **Failed** * **Cancelled** Custom workflows only; built-in agents are excluded. ![Workflow Runs by Status widget](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-bc965bd49f9b79a61ab3f41cc3155dd76b4450f1%2Fworkflow-runs-status.png?alt=media) ### Analyzing Workflow Runs by Name **Workflow Runs by Name** shows run counts by custom workflow name. Add from the Widget Library. {% hint style="info" %} **Agents vs Workflows:** Agent widgets cover built-in Harmony AI agents. Workflow widgets cover custom workflows you create. Both use the same underlying run events but filter by category. {% endhint %} *** ## Related Resources
Asset Management SettingsEOL policies, low stock alerts, discoveryhttps://github.com/harmonyso/public-docs/tree/main/guides/configuring-asset-management/README.md
Asset Views & DetailsNavigate and manage assetshttps://github.com/harmonyso/public-docs/tree/main/guides/managing-asset-views-and-details/README.md
Managing SoftwareView and manage software applicationshttps://github.com/harmonyso/public-docs/tree/main/guides/managing-software-applications/README.md
Service Desk MetricsAnalyze service desk performancehttps://github.com/harmonyso/public-docs/tree/main/guides/analyzing-service-desk-metrics/README.md
Working with WidgetsAdd and configure dashboard widgetshttps://github.com/harmonyso/public-docs/tree/main/guides/working-with-dashboard-widgets/README.md
# Managing Dashboard Access and Permissions Harmony's role-based access control (RBAC) for dashboards lets you define precisely who can view and interact with your analytics content. Permissions are enforced at every level - from the dashboard itself down to individual widgets and the data source queries that power them. This means each user sees only the data they are entitled to view, without requiring separate dashboard builds for different audiences. This article explains how dashboard permissions work, what each role can do, and how to configure sharing and access settings. *** ### How Dashboard Permissions Work Access control is applied at three levels: * **Dashboard level** - controls who can open and view a dashboard. * **Widget level** - controls which widgets are visible to a given user within a dashboard they can access. * **Data source level** - controls which underlying queries and data sources a user's role permits them to retrieve data from. When a user opens a dashboard, Harmony evaluates their role at all three levels simultaneously. Widgets or data that fall outside their permitted scope are automatically hidden or restricted - no extra configuration is needed on a per-widget basis once roles are assigned correctly. *** ### Roles and What They Can Access Harmony uses the following roles in the context of dashboard access: #### Administrators Administrators have full access to all dashboards, widgets, and data sources. They can create, edit, share, and delete dashboards, and they can manage permissions for other users and roles. #### Analysts and Editors Users with an analyst or editor role can view and, depending on their specific permissions, edit dashboards that have been shared with them. Their access to individual widgets and data sources is scoped to what their role permits. #### Desk Operators Desk operators have a focused access model. They can access dashboards that have been explicitly shared with them or with the desk operator role, allowing them to monitor relevant metrics without exposure to broader analytical content or sensitive data sources outside their scope. #### Viewers Viewers can open dashboards shared with them but cannot edit or reconfigure any content. Widget and data source restrictions still apply based on their assigned role. *** ### Sharing a Dashboard You can share a dashboard with specific users or with an entire role group. 1. Open the dashboard you want to share. 2. Select **Share** from the dashboard actions menu (top-right corner). 3. In the sharing panel, choose one of the following: * **Share with a user** - search for the user by name or email address and select their access level. * **Share with a role** - select a role group (for example, Desk Operators or Analysts) to grant access to all users assigned that role. 4. Confirm the access level you are granting - typically **View** or **Edit**. 5. Select **Save** to apply the sharing settings. Users who are added individually take on the access level you specify. Users who receive access through a role assignment inherit the permissions of that role. > **Note:** Sharing a dashboard with a user or role does not override widget-level or data source-level restrictions. If a widget queries a data source the viewer's role cannot access, that widget remains hidden for them even after the dashboard is shared. *** ### Widget-Level Permissions Individual widgets inherit the permission context of the viewer. When a user opens a shared dashboard: * Widgets that query permitted data sources are displayed normally. * Widgets that query data sources outside the user's permitted scope are not rendered for that user. This behavior is automatic. You do not need to manually hide widgets per user - the system evaluates each widget's data source query against the viewer's role at render time. If you notice a widget is unexpectedly hidden for a user, check that their role has the appropriate data source permissions configured. *** ### Data Source Permissions Data sources can be restricted by role at the source level. This provides a foundational layer of control that cascades up through widgets and dashboards. To review or update data source permissions: 1. Navigate to **Settings** > **Data Sources**. 2. Select the data source you want to configure. 3. Under the **Access** or **Permissions** tab, add or remove the roles that are permitted to query that source. 4. Save your changes. Any widget that references a restricted data source will automatically be hidden from users whose roles are not listed in the data source's permitted roles. *** ### Best Practices * **Use role-based sharing over individual sharing** where possible. Sharing with a role ensures that new team members automatically receive the correct access as soon as they are assigned the role, reducing manual upkeep. * **Audit data source permissions before sharing dashboards broadly.** Because widget visibility is driven by data source access, reviewing data source restrictions first helps you predict exactly what each role will see. * **Test access as a different role** by using the impersonation or preview feature (if available in your plan) before rolling out a shared dashboard to a large group. * **Avoid granting edit access to desk operators** unless they need to customize their own views. Viewer or view-only access keeps dashboards consistent for operational use. *** ### Troubleshooting Access Issues | Symptom | Likely Cause | What to Check | | ------------------------------------------------------- | ---------------------------------------------------------- | --------------------------------------------------------------------- | | A user cannot see a dashboard | Dashboard has not been shared with them or their role | Review the dashboard's sharing settings | | A widget is missing for one user but visible to another | The user's role lacks access to the widget's data source | Check data source permissions for that role | | A desk operator cannot open any dashboards | No dashboards have been shared with the desk operator role | Share at least one dashboard with the desk operator role | | A user with edit access cannot modify a widget | Widget editing may require a higher role level | Confirm the user's role includes edit permissions at the widget level | If you continue to experience access issues after reviewing permissions, contact your Harmony administrator or reach out to Harmony Support. # Monitoring Third-Party Service Status Harmony can display the live operational status of third-party services your organization depends on, directly within your dashboard. When a vendor experiences an outage or scheduled maintenance, Harmony surfaces that information alongside your own monitoring data so your team has full context without switching between multiple status pages. This article explains how third-party service status monitoring works, which services are supported, and what provider types Harmony uses to collect status information. ### How It Works Harmony polls the official status pages of supported third-party services at regular intervals. When a service reports degraded performance, a partial outage, or full downtime, the current status is reflected in your Harmony dashboard automatically. No manual configuration is required to start seeing status updates for the services in the catalog. Status information is pulled from three provider types: * **Statuspage.io** - the most widely used hosted status page platform * **status.io** - a second hosted status platform used by a number of enterprise vendors * **RSS/Atom feeds** - a general-purpose feed format used by vendors who publish status updates through their own infrastructure Supporting all three provider types means Harmony can monitor services regardless of how each vendor chooses to publish their operational status. ### Supported Third-Party Services The following services are included in the Harmony status catalog: | Service | Provider Type | | --------------- | ------------- | | Microsoft 365 | status.io | | Microsoft Azure | status.io | | Google Cloud | RSS/Atom feed | | Slack | Statuspage.io | | Okta | Statuspage.io | | GitLab | Statuspage.io | | Docker | Statuspage.io | This list continues to grow as new services are added to the catalog. If you rely on a third-party service that is not currently listed, contact Harmony support to request its addition. ### Status Severity Levels Status updates from third-party services use the same severity model you see elsewhere in Harmony: * **Operational** - the service is functioning normally * **Degraded Performance** - the service is available but running slower than expected or with reduced functionality * **Partial Outage** - some components or regions of the service are unavailable * **Major Outage** - the service is broadly unavailable * **Maintenance** - the vendor has announced a planned maintenance window The exact labels shown depend on what the vendor reports through their status page. Harmony maps vendor-specific terminology to these standard levels wherever possible. ### Viewing Third-Party Status in Your Dashboard Third-party service statuses appear in the dashboard alongside your own monitors. You can use this information to: * Quickly determine whether an alert you are investigating is caused by a problem on your side or a known vendor outage * Identify when a vendor's maintenance window overlaps with your own release or deployment schedules * Share vendor status context with stakeholders without asking them to check external pages manually Because Harmony pulls status from the vendor's official source, the information you see reflects what the vendor has publicly acknowledged. Harmony does not independently verify or detect vendor incidents beyond what the vendor publishes. ### Frequently Asked Questions **Do I need to configure anything to see third-party service statuses?** No. Services in the Harmony status catalog are monitored automatically. You do not need to add credentials, API keys, or any additional configuration. **How often is the status information updated?** Harmony polls supported status sources at regular intervals so that new incidents and updates are reflected promptly. The exact polling frequency may vary by provider type. **Can I receive alerts when a third-party service changes status?** Yes. You can configure alert rules in Harmony that trigger when a monitored third-party service moves into a degraded or outage state, the same way you configure alerts for your own monitors. **What if a service I use is not in the catalog?** Contact Harmony support to request that a service be added. Include the URL of the service's official status page to help the team evaluate and add it quickly. # Using Harmony Insights Harmony Insights gives you on-demand analysis of your support data, surfacing recommendations and patterns that help you make better decisions about your knowledge base, automation, and team workflows. You can run analyses against your conversation history, your ITSM ticket history, or both - then filter and compare results to identify what is driving volume and where improvements will have the most impact. ### Data Sources for Analysis When you trigger an Insights analysis run, you choose which data source to analyse: * **Conversation history** - analyses interactions handled through Harmony's conversational channels. This is the original Insights behaviour and works exactly as before. * **ITSM ticket history** - analyses historic support tickets from your connected ITSM platform, giving you a second, independent source of signal. Using both sources together lets you cross-reference findings and confirm whether a pattern is channel-specific or organisation-wide. ### Running an Analysis 1. Navigate to **Dashboard** and select the **Insights** tab. 2. Click **Run Analysis**. 3. Under **Data Source**, select either **Conversation History** or **Ticket History**. 4. Configure any additional filters such as date range or category, then click **Confirm**. Harmony queues the analysis and notifies you when results are ready. Run time varies depending on the volume of data in the selected source. ### Filtering and Comparing Results After an analysis completes, you can filter the results by source. This makes it straightforward to: * View findings from conversations and tickets side by side. * Identify recommendations that appear in both datasets - a strong signal that an issue is widespread. * Spot patterns that are unique to one channel, which can help you prioritise channel-specific improvements. Use the **Source** filter at the top of the results view to switch between datasets or display both at once. ### Interpreting Recommendations Each recommendation in the results view includes: * **Topic** - the subject area or issue cluster Insights identified. * **Volume** - how frequently the topic appeared in the analysed data. * **Source** - whether the finding came from conversation history, ticket history, or both. * **Suggested action** - the improvement Harmony recommends, such as creating a new knowledge article, updating an existing one, or reviewing an automation flow. Prioritise recommendations that appear across both data sources and carry a high volume count, as these represent the broadest opportunities for improvement. ### Tips for Getting the Most from Insights * **Run analyses on both sources regularly** - ticket and conversation trends can shift independently, so comparing them over time helps you stay ahead of emerging issues. * **Use a consistent date range** when comparing results across sources so that the findings reflect the same period. * **Act on recommendations promptly** - Insights is most valuable when its findings are translated into knowledge base updates or automation changes before the underlying issues grow in volume. # Using Harmony Insights for KB and Service Catalog Recommendations Harmony Insights continuously analyzes your resolved support conversations to surface patterns that help you improve self-service. Previously, the engine focused exclusively on recommending new knowledge base (KB) articles. It now also recommends service catalog items, so you can address both knowledge gaps and recurring service requests from a single workflow. This article explains how the recommendation engine distinguishes between the two suggestion types, where to find them in the dashboard, and how to act on each one. *** ### How the Recommendation Engine Works When enough resolved conversations share a common theme, Insights groups them into a pattern and classifies the pattern into one of two categories: * **Knowledge gap** - Users are repeatedly asking troubleshooting or how-to questions that could be answered by a self-service article. Insights generates a KB article suggestion, including a recommended title, outline, and relevant source conversations. * **Recurring service request** - Users are repeatedly submitting requests for something to be done on their behalf (for example, software provisioning, access grants, hardware orders, or account changes). Insights generates a service catalog item suggestion, including recommended form fields, a ticket type, and a priority level. The classification happens automatically. You do not need to tag or categorize conversations manually. The engine uses the content and resolution patterns of closed tickets to decide which suggestion type fits each detected pattern. *** ### Viewing Recommendations in the Insights Dashboard To see your current recommendations: 1. Open the **Harmony** dashboard and navigate to **Insights** in the left sidebar. 2. Select the **Recommendations** tab. 3. Use the **Type** filter at the top of the list to toggle between: * **KB Articles** - suggestions derived from knowledge gap patterns. * **Service Catalog Items** - suggestions derived from recurring service request patterns. * **All** - both types displayed together. Each recommendation card shows: * The detected pattern and a summary of the conversations that triggered it. * The suggestion type (KB article or service catalog item). * For service catalog suggestions: the recommended form fields, ticket type, and priority. * For KB article suggestions: the recommended title and content outline. * The number of resolved conversations that contributed to the pattern. *** ### Acting on a KB Article Recommendation 1. Click a KB article recommendation card to open the detail view. 2. Review the suggested title, outline, and the source conversations linked in the panel. 3. Choose one of the following actions: * **Create Article** - opens the KB editor pre-populated with the suggested title and outline, ready for you to write and publish. * **Dismiss** - removes the suggestion from your active list if it is not relevant. * **Snooze** - hides the suggestion temporarily and resurfaces it after a period you specify. *** ### Acting on a Service Catalog Item Recommendation 1. Click a service catalog item recommendation card to open the detail view. 2. Review the following fields that Insights has pre-populated: * **Item name** - a suggested display name for the catalog entry. * **Form fields** - a list of input fields recommended based on what agents collected in the source conversations. * **Ticket type** - the category Insights believes best fits the request pattern. * **Priority** - the default priority level recommended for tickets created from this item. 3. Choose one of the following actions: * **Create Catalog Item** - opens the Service Catalog editor with all recommended fields pre-filled. You can adjust any field before publishing. * **Dismiss** - removes the suggestion from your active list. * **Snooze** - hides the suggestion temporarily and resurfaces it later. > **Tip:** You are not locked into the pre-filled values. The recommendations are a starting point. Review the linked source conversations before publishing to confirm the form fields cover everything your agents typically collect. *** ### Frequently Asked Questions **How many resolved conversations are needed before a suggestion appears?** The engine requires a minimum threshold of similar resolved conversations before surfacing a pattern as a recommendation. This threshold is designed to filter out one-off requests and focus your attention on genuinely recurring topics. **Can I convert a KB article suggestion into a service catalog item, or vice versa?** Not directly from the recommendation card. If you believe the engine has misclassified a pattern, dismiss the suggestion and create the item type you prefer manually. You can also use the source conversations linked on the card as a reference. **Will dismissed suggestions ever reappear?** A dismissed suggestion will not reappear unless new resolved conversations create a fresh pattern that meets the detection threshold independently. **Who can view and act on Insights recommendations?** Access to Insights recommendations follows your account's role-based permissions. Agents and admins with access to the Insights section of the dashboard can view suggestions. Creating a KB article or service catalog item from a suggestion requires the same permissions as creating those items directly. *** ### Related Articles * Setting Up and Navigating the Harmony Insights Dashboard * Creating and Managing Knowledge Base Articles * Building and Publishing Service Catalog Items * Understanding Harmony Insights Data and Conversation Analysis # Understanding Estimated Savings Metrics Harmony's estimated savings metrics give you a clear, quantifiable picture of the value your AI-powered support is delivering. Rather than tracking only conversation volume or resolution rates, these metrics translate automated resolutions into two practical measures: time recovered for your team and money saved for your organization. Savings data is available directly within Harmony's reporting and analytics, so you can monitor impact over time and share results with stakeholders without needing to build separate calculations. *** ### What estimated savings measure When Harmony resolves a conversation without requiring a human agent to step in, that resolution has a real effect on your team's workload and your operational budget. Estimated savings metrics quantify that effect across two dimensions. #### Time saved Time saved represents the estimated number of seconds recovered from AI-resolved conversations. This figure is based on the average handling time that a human agent would have spent on a comparable conversation. As your AI resolution volume grows, the cumulative time saved gives you a concrete sense of capacity that has been returned to your team. #### Cost savings Cost savings translate those resolved conversations into estimated financial impact. Because support team costs vary significantly across organizations, Harmony provides three pricing scenarios rather than a single figure: | Scenario | What it reflects | | ---------------- | ----------------------------------------------------------------------------------- | | **Conservative** | Lower-cost team structures, useful as a floor estimate | | **Typical** | A mid-range benchmark representing common support team costs | | **Enterprise** | Higher-cost team structures, useful for larger or specialized support organizations | Presenting three scenarios lets you identify the estimate that best fits your context, or use the range to frame a minimum-to-maximum impact story for internal reporting. *** ### Where to find savings metrics Estimated savings data appears within Harmony's reporting and analytics section. You can view it alongside your other key metrics such as resolution rate and conversation volume, giving you a unified view of both operational performance and business value. *** ### How to use savings data effectively **Reporting to stakeholders** - Use the cost savings range to build a business case or demonstrate ROI. The conservative figure sets a defensible floor, while the enterprise figure illustrates upside potential. **Tracking trends over time** - Monitor time saved on a weekly or monthly basis to understand whether your AI's impact is growing as you expand coverage, refine your knowledge base, or adjust routing rules. **Sizing capacity decisions** - Time saved is a useful input when your team is planning headcount. If the AI is consistently recovering dozens or hundreds of agent-hours per month, that context helps frame hiring decisions or reallocation of existing capacity. **Benchmarking improvements** - When you make changes to your AI configuration, compare savings metrics before and after to assess whether those changes are increasing automated resolution value. *** ### Notes on estimation methodology Estimated savings are calculated based on AI-resolved conversations - specifically, conversations that were handled to resolution without escalation to a human agent. The time and cost figures use standardized assumptions about average handling time and agent cost rates, mapped to the three pricing tiers described above. These are estimates intended to give you a directional, evidence-based view of impact. They are most useful when tracked consistently over time and compared against your own internal benchmarks where available. # Analyzing Conversation Insights and AI Enrichments Harmony automatically analyzes every conversation through its evaluation pipeline and surfaces the results as AI enrichments - structured signals that help you understand what happened in a conversation and why. You can use these enrichments to filter, explore, and act on your conversation data directly in the conversations viewer, without any manual configuration or refresh steps. This article explains the available AI enrichments, how scoring and reasoning work, and how to use filters to find the conversations that matter most. {% hint style="info" %} The AI enrichment filters in the conversations viewer replace the previous conversations analytics in the management dashboard. All conversation insights are now consolidated in a single place. {% endhint %} ### How AI Enrichments Work Each conversation is automatically assessed by Harmony's evaluation pipeline after it ends. The pipeline evaluates the conversation across several dimensions and writes the results back to that conversation record in real time. Because enrichments are synced continuously, the filters you apply always reflect the latest assessed data - there is no need to manually trigger a refresh or export. Every enrichment produces two pieces of information: * **Score** - a structured value (such as a label or numeric rating) that categorizes the conversation for that dimension * **Reasoning** - a plain-language explanation of why the conversation received that score, giving you the context behind the assessment ### Available AI Enrichments #### Sentiment Sentiment reflects the overall emotional tone of the conversation as assessed by the AI. Use sentiment to quickly identify frustrated or dissatisfied users who may need follow-up, as well as highly positive interactions worth highlighting. The score indicates the detected tone (for example, positive, neutral, or negative), and the reasoning describes the specific signals in the conversation that led to that assessment. #### Interest Level Interest level captures how engaged or motivated the user appeared during the conversation. A high interest score typically indicates a user who is actively exploring your product or service, while a low score may suggest passive browsing or uncertainty. The reasoning for interest level can help you understand what topics or moments drove engagement, which can inform content and product decisions. #### Resolution Resolution indicates whether the conversation reached a successful outcome - meaning the user's question or goal was addressed. This enrichment helps you identify conversations where the AI or your team fully resolved an issue versus those that ended without a clear answer. Use resolution scores to spot patterns in unresolved conversations and find areas where your knowledge base or bot configuration may need improvement. ### Filtering Conversations by AI Enrichments AI enrichment filters are available directly in the conversations viewer. 1. Open the **Conversations** viewer from the main navigation. 2. Select **Filters** to open the filter panel. 3. Choose any of the available AI enrichment dimensions - **Sentiment**, **Interest Level**, or **Resolution**. 4. Select the score values you want to include and apply the filter. 5. Click on any conversation in the results to read the full enrichment details, including the reasoning explanation for each scored dimension. You can combine multiple enrichment filters with other conversation filters (such as date range, channel, or agent) to narrow results further. ### Using Reasoning to Understand Scores The reasoning field is particularly useful when a score is unexpected or when you want to validate the AI assessment before taking action. For example, if a conversation is scored as unresolved but you expected it to be complete, the reasoning will point to the specific turn or gap that caused the assessment. Reasoning explanations are written in plain language and reference the content of the conversation, so no additional interpretation is required. ### Tips for Getting Value from AI Enrichments * **Identify at-risk users** - Filter for negative sentiment combined with low resolution to find conversations where users may have left unsatisfied. * **Spot high-value leads** - Filter for high interest level to surface users who showed strong engagement and may benefit from proactive outreach. * **Improve bot coverage** - Regularly review unresolved conversations to find recurring questions your bot is not answering well. * **Validate quality** - Use sentiment and resolution together as a quick quality check across a time period or a specific channel. # Understanding Service Desk and Managing Tickets Learn how to use the Harmony Service Desk to create tickets, manage conversations, assign work, use canned responses, and track SLA. {% hint style="info" %} **Path:** `/tickets/desk/$deskId` (or `/tickets/desk/all` for all desks) {% endhint %} ### Understanding the Service Desk The Service Desk is where you create, triage, and resolve IT support tickets. Tickets can be submitted via Slack, Microsoft Teams, email, or the web portal. The Harmony AI agent handles many requests automatically; human agents handle escalations and complex cases. #### Understanding Desks A **desk** is a service desk that groups teams and tickets. You may have access to one or more desks based on your roles. Each desk has its own teams, custom fields, tags, and canned responses. #### Navigating the Tickets View Open **Tickets** from the sidebar. Routes: * **`/tickets/desk/$deskId`** - Tickets for a specific desk * **`/tickets/desk/all`** - All tickets across desks (when you have access to multiple desks) The main view shows a table of tickets with columns for subject, status, priority, assignee, desk, SLA, and more. Use the toolbar filters and search to find specific tickets. #### Switching Between Different Desks Use the desk selector (sidebar or page header) to switch desks. Select a desk to see only its tickets. #### Viewing All Tickets Across Desks When you have access to multiple desks, choose **All desks** to see tickets from every desk you can access. ![Ticket table with desk selector](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-13125ffc784640237bd5d1ed8695aa7908fa9c53%2Fticket-table-all-desks.png?alt=media) *** ### Creating and Managing Tickets #### Creating a New Ticket ![Create Ticket dialog with form fields](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-8a139b114b6d5ed4d514ed6a6050dceccabac639%2Fcreate-ticket-dialog.png?alt=media) Click **Create Ticket** to open the creation dialog. Fill in the form and click **Create**. You can also ask the **IT Copilot** to create a ticket on your behalf. Describe what you need in a conversation and the Copilot will collect all required details - title, ticket type, priority, and service desk - before asking for your confirmation. Nothing is created until you confirm. #### Understanding Ticket Properties | Property | Description | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | **Title** | Required. Up to 255 characters. | | **Description** | Required. Rich text (markdown). Up to 5000 characters. You can paste images from the clipboard or attach files from the editor. | | **Ticket Type** | Request, Incident, Question, Task, or Change. | | **Priority** | Low, Medium, High, or Urgent. | | **Desk** | Which desk the ticket belongs to. Required. | | **Assignee** | Team member or Harmony AI. Optional; defaults to Unassigned. | | **Reporter** | (Service desk variant) Who reported the ticket. The reporter's office location is displayed next to their name for workload context. | | **Triggered Agent** | A clickable link to the specific AI agent run that was triggered on this ticket, if any. | The Properties section uses a clean horizontal layout with one property per line. The reporter row is fully clickable - selecting the name, location, or dropdown chevron all open the reporter selector. #### Setting Ticket Priority and Status **Priority** is set when creating a ticket. **Status** is changed in the ticket preview panel: use the status selector in the Properties section. Statuses include Open, In Progress, Pending (Reporter, Approval, Internal Team, Third Party), **Pending - On Hold**, Resolved, Closed, Canceled. **Pending - On Hold Status** The **Pending - On Hold** status gives your team a dedicated way to mark tickets that are paused and waiting, without conflating them with other pending states: * **SLA timers pause** automatically while a ticket is on hold, so your metrics accurately reflect active work time. * **All status transitions** are available to and from Pending - On Hold, so agents can move tickets freely without restrictions. * Notifications fire as expected when a ticket enters or leaves this status. #### Attaching Files to Tickets * **Create form:** Use the Attachments dropzone. Drag and drop files or paste images from the clipboard. Files upload before the ticket is created. * **Description editor:** Use the file picker in the Tiptap editor to attach files inline. #### Using Custom Fields in Tickets Custom fields are configured per desk and appear when you select that desk. Supported types: | Type | Control | | ----------------- | ------------------------------------ | | **Text** | Text input | | **Number** | Number input | | **Checkbox** | Yes/No | | **Single Select** | Dropdown with predefined options | | **Multi Select** | Multi-select with predefined options | Mandatory custom fields are marked with an asterisk. Custom fields reset when you change desks. #### Asset Fields for Desk Members When a catalog item includes an asset selector field configured for desk member completion, agents see a searchable asset combobox in the ticket properties panel after the ticket is created. The selected asset is saved automatically. This field is only visible to desk members - portal users do not see or interact with it. #### Creating and Linking Related Tickets When creating a ticket (service desk variant), you can link it to an existing ticket: 1. In the **Linked ticket from your desk** section, choose a **Relationship type**: Relates to, Blocks, Blocked by, Duplicate of, Duplicated by, Depends on, Used by. 2. Use the **Ticket** combobox to search and select the ticket to link. The new ticket is created and linked in one action. #### Viewing Linked External ITSM Tickets If your organization uses external ITSM tools such as ServiceNow or Jira, all active sync mappings for a ticket are available via the API. Pass `include_linked_tickets=true` as a query parameter when fetching a ticket to receive a `linked_tickets` field in the response. Each entry includes the provider name, ticket ID, display ID, and a direct URL so you can navigate straight to the corresponding record. Multiple mappings are fully supported - if a ticket has been exported to more than one tool, all links are returned in a single call. #### Changing Ticket Type with the AI Agent Harmony's AI Service Desk Agent can reclassify the type of an existing ticket without manual intervention. You can ask the agent to change a ticket to any of the following types: * **Request** - a standard service request * **Incident** - an unplanned disruption or service degradation * **Task** - an actionable work item (note: converting away from Task discards its checklist) * **Change** - a planned modification to your environment The agent will confirm the reclassification with you before applying it, following the same confirmation flow as any other field update. #### Creating Tickets from Catalog Forms When an employee submits a catalog item form from the portal or Slack, the ticket is created directly from the saved form values. You receive your ticket confirmation immediately after submitting the form, with no additional processing steps or delays. *** ### Working with Ticket Conversations #### Viewing Ticket Details Click a ticket row to open the **ticket preview panel** on the right. It shows description, properties, SLA, approvals, linked tickets, related assets/software, and chat. ![Ticket preview panel with chat and properties](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-b6832a7e88020985ff483e9c2e2129a87ddfe81f%2Fticket-preview-panel.png?alt=media) #### Understanding the Ticket Preview Panel The preview panel has configurable sections: SLA, Approvals, Properties, Linked tickets, Assigned assets, Assigned software, and Chat. Use the header settings to show, hide, or reorder sections. Some sections (e.g. Approvals, Linked tickets) can be set to "If exist" so they only appear when there is data. #### Seeing Which Agent Was Triggered A **Triggered Agent** field appears in the Properties section of the ticket preview panel as a clickable link, taking you directly to the specific agent run. In the ticket table view, a **Triggered Agent** column is also available - it is shown by default but can be hidden via column settings. #### Resizing the Ticket Chat Panel The chat section has a drag handle at the top. Drag it to resize the chat area. The entire preview panel can also be resized horizontally by dragging the left edge. #### Adding Messages to Tickets Type in the chat input at the bottom and send. You can mark messages as **internal** (visible only to agents) or **external** (visible to the reporter). #### Ticket Status Updates in Conversation Threads Key ticket events are automatically posted as system messages in the relevant conversation thread - whether you are working in Slack, Microsoft Teams, or the Harmony portal. The following events appear as thread messages: * **Ticket created** - a message appears when a new ticket is opened * **Status changed** - updates are shown whenever a ticket's status changes * **Priority changed** - the thread reflects any changes to ticket priority * **Assignee changed** - the thread shows reassignment events This keeps your team fully informed without switching views. #### Using @Mentions in Messages Type `@` to open a list of participants (reporter, assignee, watchers, others in the conversation). Select a person to insert a mention. Mentioned users receive notifications. Mentions use the format `<@employeeId|DisplayName>` and render as clickable badges that link to the person's profile. #### Message Editing During Active Approvals When a ticket is undergoing an active approval process, the edit and delete controls on all conversation messages are automatically hidden. This ensures that content being reviewed cannot be changed mid-decision. Once the approval is completed or overridden, the controls reappear automatically within a few seconds. #### Replying to Ticket Conversations Send messages in the chat. Replies appear in chronological order. You can attach files to messages. #### Viewing Ticket Activity History Activity (status changes, assignments, workflow events, approval actions, etc.) appears in the chat timeline and in the ticket's activity log. The activity timeline now captures all key stages of the workflow and approval lifecycle - see [Workflow Activity in the Timeline](#workflow-activity-in-the-timeline) and [Approval Activity in the Audit Log](#approval-activity-now-visible-in-ticket-audit-log) below for details. #### Workflow Activity in the Timeline Workflow lifecycle events are recorded directly in the ticket activity log. When a workflow starts, progresses through approval steps, or is cancelled, these events appear in the ticket's activity timeline - giving agents and managers a clear picture of what happened and when. This makes it easier to audit workflow execution and understand how automated processes have interacted with a given ticket. *** ### Assigning and Reassigning Tickets #### Assigning Tickets to Team Members Use the **Assignee** selector in the ticket Properties section. You can assign to any employee on the desk (or on the ticket's team when a team is set). #### Assigning Tickets to Teams Use the **Team** selector in Properties to assign the ticket to a team. Team membership filters the assignee list to that team's members. #### Assigning Tickets to AI Agents The assignee selector includes **Harmony AI** as an option. Assigning to Harmony AI routes the ticket to the AI agent for triage and resolution. #### Moving Tickets Between Desks Use **Move to another desk** in Properties. Select the target desk and confirm. The ticket's desk changes; custom fields may reset for the new desk. #### Moving Tickets Between Teams Use **Move to team** in Properties. Select the target team on the same desk. Assignee options update to the new team's members. #### Reassigning Your Tickets Change the assignee in Properties. The previous assignee is replaced by the new one. *** ### Watching Tickets #### Adding Watchers to Tickets You can add any active employee in your organization as a watcher on a ticket - not just desk members or platform admins. The **Add Watcher** picker lists all active employees alphabetically, so you can notify the right people regardless of their role or team membership. #### Automatic Watcher on Comment Any user who posts a comment on a ticket is automatically added as a watcher, keeping them informed of all subsequent activity. This applies to all commenters, not only those who are explicitly mentioned or tagged. Watcher status persists if the ticket is moved to a different desk. AI agent responses do not trigger auto-watching. #### Email CC Recipients as Watchers When a ticket is created via email, anyone CC'd on that email is automatically added as a watcher. This ensures that all relevant parties receive ongoing updates without needing to be added manually. *** ### Using Email as a Service Desk Channel #### Automatic Reply Threading When a user replies directly to an original inbound email, their reply is added as a new message within the existing ticket rather than creating a duplicate ticket. This applies to CC'd users and any other recipients replying to the original email. #### CC Recipients Added as Watchers When a ticket is created via email, anyone CC'd on that email is automatically added as a watcher so they receive updates throughout the ticket's lifecycle. *** ### Using Canned Responses #### What are Canned Responses? Canned responses are reusable templates for common replies. Insert them into ticket messages to save time and keep responses consistent. #### Creating Canned Response Templates Canned responses are created in desk settings (Settings → Tickets → Canned Responses). Each template has a name, content, availability (Personal or Shared), and optional attachments. #### Searching and Inserting Canned Responses In the ticket chat, use the canned response action to open the **Search canned responses** dialog. Search by name, preview the content, and click to insert. Variables in the template are replaced with current ticket data before insertion. ![Search canned responses dialog](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-d979dbc23c39f3dac96c42329614ef7e7f076a30%2Fcanned-response-search.png?alt=media) #### Using Variables in Canned Responses Insert variables into templates. They are replaced when the template is used: | Variable | Replaced with | | ------------------------ | ------------------- | | `{{ticket.subject}}` | Ticket title | | `{{ticket.id}}` | Ticket ID | | `{{ticket.description}}` | Ticket description | | `{{ticket.reporter}}` | Reporter name | | `{{ticket.agent}}` | Assignee/agent name | | `{{ticket.status}}` | Status | | `{{ticket.priority}}` | Priority | | `{{ticket.source}}` | Source | | `{{ticket.ticket_type}}` | Type | | `{{desk_name}}` | Desk name | | `{{currentUser}}` | Current user name | | `{{portalUrl}}` | Portal URL | #### Creating Personal vs Shared Canned Responses When creating a template, set **availability** to Personal (only you) or Shared (all desk members). #### Managing Canned Response Attachments Templates can include attachments. Upload them when creating or editing the template. Attachments are included when the template is inserted. *** ### Working with Knowledge Base Solutions #### Inserting KB Solutions into Tickets When a ticket has a **KB resolution** (AI-suggested solution from the knowledge base), you can use **Respond with knowledge base solution**. A modal shows the answer summary. Use **Add as comment** to insert it as a message (from Harmony AI) into the ticket. {/\* IMAGE: Respond with knowledge base solution modal → /guides/understanding-service-desk-and-managing-tickets/screenshots/kb-solution-modal.png | UI: frontend-app/src/features/service-desk/components/kb-solution-modal.tsx | Route: /tickets/desk/$deskId \*/} #### Using the KB Solution Search The KB solution is surfaced when the AI finds a matching article. The modal displays the summary and sources. You can copy the answer or add it as a comment. *** ### Understanding AI Insights and Classification #### How AI Insights Work Harmony's AI automatically classifies tickets to suggest category, priority, summary, and desk routing. AI Insights use the ticket's title, description, and conversation history as primary inputs - so the most informative fields on a ticket directly shape routing and priority suggestions. #### AI Re-classification on Title and Description Changes When you update a ticket's title or description, AI Insights automatically re-classify the ticket. This ensures that category, priority suggestion, summary, and desk routing always reflect the current state of the ticket rather than only its comment history. Previously, changes to these key fields could leave triage results stale; now they are included as first-class inputs alongside comments. *** ### Triggering Custom Agents from Tickets #### Using Custom Agents on a Ticket A **Custom Agents** section in the ticket sidebar lists all your manually-triggerable agents. You can trigger any of them directly from the ticket view without leaving the conversation: * **Search agents by name** to quickly find the right one. * A **confirmation step** ensures agents are never triggered accidentally. * **Ticket context is automatically injected** - the current ticket, desk, and requester are passed into the agent so you do not need to fill them in manually. *** ### Using the IT Copilot for Tickets #### Creating Tickets with the Copilot Ask the IT Copilot to create a new support ticket by describing what you need. The Copilot collects all required fields - title, type, priority, and service desk - through a natural conversation, then asks for your confirmation before submitting. Nothing is created without your explicit approval. #### Updating Tickets with the Copilot The Copilot can update ticket fields on behalf of agents during a conversation. It can modify priority, status, assignee, and other ticket fields in real time through tool calls, keeping tickets accurate as conversations progress. *** ### Managing Ticket Approvals #### Understanding Ticket Approvals Some tickets require approval before they can proceed. Approvals are configured in workflows and appear in the ticket's Approvals section when present. #### Viewing Ticket Approval Status The **Approvals** section in the ticket preview shows each approval step with status: Requested, Pending, Approved, Rejected, or Removed (cancelled). Approvers are displayed with avatars. {/\* IMAGE: Approvals section in ticket preview → /guides/understanding-service-desk-and-managing-tickets/screenshots/ticket-approvals-section.png | UI: frontend-app/src/features/service-desk/components/ticket-preview/ticket-approvals-section.tsx | Route: /tickets/desk/$deskId \*/} #### Approving and Denying Ticket Requests Approval actions (approve/deny) are available from the Approvals section or workflow actions when the ticket is in an approval state. Exact UI depends on workflow configuration. #### Approval Outcomes Posted to the Ticket Thread When a workflow approval resolves, an internal note is automatically posted to the ticket thread summarising the outcome. The note includes whether the request was approved or denied, who made the decision, and any reason provided for a denial. This gives agents full visibility into what happened without leaving the ticket view. #### Cancelling a Ticket Approval Desk managers can cancel an approval requirement on a ticket at any point before a decision is made, without it counting as an approval or denial: * The cancelled approval is shown as **removed** in the Approvals card - not approved and not rejected. * Pending approvers are automatically notified via Slack or Teams that their approval is no longer needed, and any scheduled reminders are stopped. * The cancellation is recorded in the ticket's activity log for full auditability. #### Understanding Approval Chains Multiple approval steps are shown in order. A connector indicates flow: once a step is approved, the next can proceed. Rejected steps halt the chain. #### Approval Activity Now Visible in Ticket Audit Log The activity timeline captures all key stages of the approval lifecycle: * **Approval requested** - logged each time an approval request is sent to an approver * **Approved** - logged when an approver accepts the request * **Rejected** - logged when an approver declines the request * **Overridden** - logged when an admin overrides the approval decision * **Cancelled** - logged when an approval requirement is removed before a decision Each event appears in the timeline with the relevant user and a description, giving you a complete audit trail without leaving the ticket view. *** ### Closing Tickets #### Closing Tickets with Comments To close a ticket, change the status to Resolved or Closed. If **mandatory close comment** is enabled for the desk, a dialog prompts for an internal comment (min 3 characters) before closing. Enter the comment and confirm. {/\* IMAGE: Mandatory close comment dialog → /guides/understanding-service-desk-and-managing-tickets/screenshots/close-ticket-comment-dialog.png | UI: frontend-app/src/features/service-desk/components/close-ticket-comment-dialog.tsx | Route: /tickets/desk/$deskId \*/} #### Understanding Ticket Closure Workflow Closing moves the ticket to Resolved or Closed. The ticket remains in the list but is excluded from "open" filters by default. #### Ticket Status After Closure Resolved and Closed are terminal states. Reopening requires changing status back to Open or In Progress, if your workflow allows it. *** ### Understanding and Tracking SLA #### Understanding SLA Policies SLA policies define response and resolution targets per desk. They are configured in desk settings. #### Understanding SLA Timers Each ticket can have SLA timers: **Response** (time to first reply) and **Resolution** (time to resolve). Timers start when the ticket is created and may pause based on status or business hours. SLA timers also pause automatically when a ticket is set to **Pending - On Hold**. #### Viewing Ticket SLA Status The **SLA** section in the ticket preview shows each timer with deadline, hours remaining, and status (e.g. in progress, completed, breached). Expand to see details. ![SLA section in ticket preview](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-d0c092f03520884a4eb604d0ec1688a788cfdd4b%2Fticket-sla-section.png?alt=media) #### Track # Organizing Tickets and Table Views Learn how to filter, search, sort, and manage ticket views and table columns in the Harmony Service Desk. {% hint style="info" %} **Path:** `/tickets/desk/$deskId` {% endhint %} ### Filtering Tickets The ticket table supports faceted filters. Use the filter popover in the toolbar to apply one or more filters. Filters are combined (AND logic). Clear individual filters or use **Reset filters** to remove all. #### By Status Filter by ticket status: Open, In Progress, Pending (Reporter, Approval, Internal Team, Third Party), Resolved, Closed, Canceled. The default view shows open statuses (excludes Resolved and Closed). Select multiple statuses to include in the view. #### By Priority Filter by Low, Medium, High, or Urgent. #### By Assignee Filter by assignee. Include **Unassigned** to see tickets without an assignee. **Assigned to me** is a quick filter that shows only tickets assigned to you. #### By Reporter Filter by the employee who reported the ticket. #### By Source Filter by ticket source: Slack, Harmony, Teams, Freshservice, Email, JSM, SolarWinds, SIIT. #### By Tags Filter by desk tags. Tags are defined per desk and applied to tickets. Tags are displayed as colored badges in the filter panel, matching the colors assigned to each tag for quick identification. System tags are excluded from filtering to keep the view clean and relevant. #### By Team Filter by team (subdesk) within a desk. You can also select **Unassigned** within the Team filter to surface tickets that have not been routed to any team yet. Combine **Unassigned** with one or more specific teams in a single filter to get a broader view of your queue - this is useful for identifying tickets that may have slipped through routing and need to be manually assigned. #### By Watcher Filter by one or more watchers to find tickets that specific team members are monitoring. Selecting multiple watcher IDs returns a combined set of results. Leaving the watcher filter empty has no effect on your current view. The watcher filter works alongside all existing filters, including status and assignee. #### By Ticket Type Filter by ticket type across all views - All Desks, individual desks, and Other. The following types are supported: * **Request** * **Incident** * **Task** * **Change** Each type is displayed with its colored icon in the filter panel for quick identification. You can select one or multiple types, and the filter persists in the URL and across page reloads. It works with saved views and can be combined with all other filters. #### By Last Updated Filter tickets by when they were last meaningfully updated. The **Last Update** timestamp reflects significant activity on a ticket, including: * A new comment or reply from a requester, agent, or system * Status changes (e.g. Open to In Progress to Resolved) * Assignment changes to a different agent or team * Priority changes * New attachments added * Custom field value changes * Resolution added or changed * Internal notes * Automated workflow actions Use this filter alongside sorting by Last Update to quickly spot tickets that need attention or have gone stale. #### By Resolution Date Filter tickets by the date they were resolved or closed. Use a date range to view tickets resolved within a specific period (e.g. this week, this month). You can also identify reopened tickets by combining this filter with an Open status - tickets that have a Resolution Date but are currently showing an Open status have been reopened. #### By Service Catalog Item Filter tickets by the Service Catalog item used during ticket creation. All catalog items that were used to create tickets are listed as options, including any that have since been deleted - deleted items are clearly marked as "Deleted" so you always have full visibility. This filter is scoped per desk. #### By Auto-Tag Properties Filter tickets using the auto-tag properties that Harmony has automatically assigned: * **Auto-tag categories** - filter tickets by their assigned category (e.g. "MFA Reset", "Billing Issue") * **Auto-tag entities** - narrow results to tickets associated with specific detected entities * **Auto-tag symptoms** - surface tickets that share a common symptom pattern These filters can be combined with your existing ticket search parameters and all other filters. #### By Desk Filter tickets by desk to narrow your view to one or more specific desks. This filter is available in the all tickets overview and is particularly useful when working across multiple desks. #### Quick Filters * **Assigned to me** - Built-in view that filters tickets assigned to you. Available across all desks, so you do not need to manually configure an assignee filter each time. Same as setting assignee to your employee ID. * **Default view** - Shows open statuses and unassigned by default. You can change the default view. ![Ticket table with filter popover](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-89f456209ca632ff27859626d2dca5598fe930d1%2Fticket-filters.png?alt=media) *** ### Searching for Tickets Use the **Search** input in the toolbar. Search queries the ticket title (subject). Results update as you type (debounced). Search is combined with active filters. {% hint style="info" %} Search matches ticket title. For full-text content search across descriptions and messages, use export with filters or external tools. {% endhint %} *** ### Sorting Ticket Lists Click a column header to sort by that column. Click again to toggle ascending/descending. Sortable columns include: Priority, Status, Title, Source, Created at, Last Update, Resolution Date, Resolution SLA, and others. The default sort is Created at (newest first). Sorting is persisted in saved views. ![Ticket table with sortable column headers](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-34e7559c3327da9c501b98706fcc0428dff4dd47%2Fticket-table-sorting.png?alt=media) *** ### Managing Saved Ticket Views Saved views store filters, sorting, and search. Switch views from the dropdown next to the desk name (e.g. **Desk name > View name**). System views (Default view, Assigned to me) cannot be modified or deleted. #### Personal and Public Views Each saved view can be set as personal or public: * **Personal views** are visible only to you, just as before. * **Public views** are shared with all users in your account, so teammates can access the same filtered ticket lists without recreating them. * Public views display the creator's name so everyone knows who set up the view. #### Creating Saved Views 1. Apply the filters, sorting, and search you want. 2. Click the view dropdown. 3. Select **Save current view**. 4. Enter a name and click **Save view**. The new view is created and selected. ![View dropdown with Save current view](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-3c8d6d318cc93d9e8d3a3110c1bce37dd30e5600%2Fsaved-views-dropdown.png?alt=media) #### Updating Saved Views 1. Select the view to update. 2. Change filters, sorting, or search. 3. Open the view dropdown and click the ⋮ next to the view name. 4. Select **Update view**. The view is updated with the current settings. Modified views show **(Modified)** until you update or switch away. #### Renaming Saved Views Open the view dropdown - ⋮ next to the view - **Rename**. Enter the new name and confirm. #### Deleting Saved Views Open the view dropdown - ⋮ next to the view - **Delete**. System views cannot be deleted. #### Setting Default View Open the view dropdown and click the star icon next to a view to set it as default. The default view is applied when you first open the desk (unless you arrive via a shared link with URL parameters). *** ### Understanding Ticket Table Columns The ticket table includes columns such as: | Column | Description | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | **Ticket ID** | Ticket identifier with type icon. Click to open. | | **Title** | Ticket subject. | | **Status** | Current status. Editable inline. | | **Priority** | Priority level. Editable inline. | | **Source** | Origin (Slack, Teams, etc.). | | **Assignee** | Assigned employee or AI. Editable inline. | | **Reporter** | Who reported. Editable inline. | | **Desk** | Desk the ticket belongs to. Visible in the all tickets overview. | | **Team** | Team (subdesk) if assigned. | | **Tags** | Colored tag badges assigned to the ticket. System tags are excluded. | | **Resolution SLA** | SLA deadline and status. | | **Resolution Date** | Timestamp when the ticket was moved to a resolved or closed status. | | **Last Update** | Timestamp of the most recent meaningful activity on the ticket. | | **Created at** | Creation timestamp. | | **Approval** | Approval status when applicable. | | **Insights** | Automated solution or knowledge base indicator (if enabled). | | **CSAT** | Customer satisfaction score for the ticket. Optional column, only available for desks with CSAT enabled. Not shown by default. | Some columns are hidden on mobile. Column visibility and order can be customized. *** ### Customizing Column Visibility Click the **Manage columns** (settings) button in the toolbar. A dropdown lists all hideable columns with checkboxes. Toggle columns on or off to show or hide them. Changes are saved per user. The **CSAT** column is not shown by default - enable it when you want to analyze customer satisfaction alongside resolved tickets. It is only available for desks that have CSAT enabled in their desk settings, and it is included in downloaded exports. ![Manage columns dropdown with column checkboxes](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-e0494ab07da96d89098ff6781bc19568511e59a5%2Fmanage-columns.png?alt=media) *** ### Reordering Table Columns In **Manage columns**, drag the grip handle next to a column to reorder. The new order is persisted. Some columns (e.g. selection) are fixed to the left and cannot be moved. *** ### Using Table Pagination The table paginates tickets. Use the pagination controls at the bottom to change page or page size. Page size options typically range from 10 to 200 rows. Page index and size are reflected in the URL for sharing. *** ### Navigating Large Datasets #### Keyboard Shortcuts When the tickets table is focused: | Shortcut | Action | | --------- | -------------------------------------------- | | `/` | Focus search | | `Escape` | Clear search | | `↑` / `↓` | Move focus between rows | | `Enter` | Open focused ticket (after using arrow keys) | | `←` / `→` | Previous / Next page | | `Shift+R` | Refresh table | | `Shift+X` | Reset all filters | Arrow key navigation tracks a focused row. Press Enter to open that ticket. Hovering a row also updates focus. #### Opening Tickets in New Tabs You can use standard browser navigation gestures directly from the tickets list: * **Right-click** a ticket to open the browser's native context menu, letting you open the ticket in a new tab or window. * **Middle-click** (scroll wheel click) on a ticket to instantly open it in a new browser tab. * **Ctrl+click** (Windows/Linux) or **Cmd+click** (Mac) on a ticket to open it in a new tab. *** ### Using Bulk Actions on Tickets Select multiple tickets with the row checkboxes. When rows are selected, bulk action buttons appear in the toolbar. ![Ticket table with selection and bulk action toolbar](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-e812084578d6742c04311da9d37f3d423daa0f64%2Fticket-bulk-actions.png?alt=media) #### Selecting Multiple Tickets Click the checkbox in each row, or use the header checkbox to select all visible rows on the current page. #### Bulk Updating Ticket Status Use **Bulk status** to change status for all selected tickets. If the desk requires a close comment for Resolved/Closed, you will be prompted for an internal comment. #### Bulk Updating Ticket Priority Use **Bulk priority** to set priority (Low, Medium, High, Urgent) for all selected tickets. #### Bulk Assigning Tickets Use **Bulk assignee** to assign all selected tickets to an employee or Harmony AI. All selected tickets must be on the same desk; bulk assign across multiple desks is not supported. #### Bulk Moving Tickets Between Desks Use **Move between desks** to move multiple tickets from one desk to another in a single action. Select any number of tickets within the same desk, then click **Move between desks** in the bulk actions bar. A guided modal walks you through the transfer: * **Target desk selection** - choose from all desks you have permission to view. * **Assignee** - optionally pick a default assignee from the destination desk. If left blank, tickets are auto-assigned based on the desk's routing logic, or left unassigned if no agent is available. This is useful when reorganizing or reassigning work across your support teams. #### Understanding Bulk Action Limits Bulk updates apply to all selected tickets on the current page. The API processes them in a single request. If assignment fails (e.g. tickets span multiple desks or assignee is not a desk member), an error toast explains the issue. *** ### Viewing Ticket Activity from the List You can view a ticket's full activity history directly from the ticket preview modal, without needing to open the ticket in full. An Activity drawer slides in alongside the preview, showing a chronological log of events that have occurred on the ticket - including status changes, assignment changes, comments, and more. This lets you get a complete picture of what has changed and when, without losing your place in the ticket list. Ticket cards in the list also surface notification indicators so you can see at a glance which tickets have new activity or updates, making it easier to prioritize and respond to incoming requests faster. *** ### Related Resources
Service Desks & TeamsCreate and manage service desks and teamshttps://github.com/harmonyso/public-docs/tree/main/guides/managing-service-desks-and-teams/README.md
Service Desk & TicketsHow to create and manage tickets in the service deskhttps://github.com/harmonyso/public-docs/tree/main/guides/understanding-service-desk-and-managing-tickets/README.md
Managing PeopleEmployee directory and profileshttps://github.com/harmonyso/public-docs/tree/main/guides/managing-people/README.md
Service Desk MetricsAnalyze desk performance and SLAhttps://github.com/harmonyso/public-docs/tree/main/guides/analyzing-service-desk-metrics/README.md
# Setting Up Email-to-Ticket Email-to-ticket lets you connect a dedicated email address to any desk in Harmony. When someone sends an email to that address, Harmony automatically creates a ticket, routes it through the AI Agent for classification, and notifies the right people - all without requiring the sender to log in to the portal. This is useful for customers, external partners, or internal teams who prefer email over the self-service portal. *** ### How it works When an incoming email is received on a desk's assigned address, Harmony does the following automatically: * **Creates a new ticket** - The email subject becomes the ticket title and the email body becomes the ticket description. * **Attaches files** - Any attachments included in the email are added directly to the ticket. * **Sets the reporter** - The sender is recorded as the ticket reporter. If they do not already have a Harmony account, one is created for them automatically. * **Adds CC recipients as watchers** - Anyone copied on the email is added as a watcher on the ticket so they receive updates. * **Routes through the AI Agent** - The new ticket is passed to the AI Agent for classification and initial handling, just like tickets created through any other channel. *** ### Prerequisites Before setting up email-to-ticket, make sure you have: * A desk already created in Harmony that you want to connect. * An email address you intend to assign to that desk (for example, a dedicated support inbox or an alias you control). * Admin or desk manager permissions in Harmony. *** ### Setting up email-to-ticket for a desk 1. Navigate to **Service Desk** in the main navigation and open the desk you want to configure. 2. Go to the desk's **Settings**. 3. Find the **Email-to-Ticket** section and enter the email address you want to assign to this desk. 4. Save your changes. Once saved, any email sent to that address will be converted into a ticket on the desk automatically. > **Tip:** Each desk must have its own unique email address. You cannot share a single email address across multiple desks. *** ### Email-to-ticket field mapping The table below shows how each part of an incoming email maps to ticket fields. | Email component | Ticket field | | --------------- | ------------------------------------ | | Subject | Title | | Body | Description | | Attachments | Ticket attachments | | Sender | Reporter (account created if needed) | | CC recipients | Watchers | *** ### Reporter account creation If the sender's email address does not match an existing Harmony account, a new account is created for them automatically using their email address. This means external users can submit tickets without any manual setup on your part. These auto-created accounts are standard reporter accounts. You can manage them later from the **Users** section in your admin settings if needed. *** ### AI Agent routing Every ticket created through email-to-ticket is automatically routed through the AI Agent, the same way tickets submitted via the portal are handled. The AI Agent will attempt to classify the ticket, suggest a category, and apply any configured automation rules for that desk. This ensures a consistent experience regardless of how a ticket was originally submitted. *** ### Troubleshooting **Emails are not creating tickets** * Confirm the email address is correctly saved in the desk settings. * Check that emails are actually being delivered to the configured address and are not being blocked by a spam filter or mail server rule. **Attachments are missing on the ticket** * Verify the attachments are in a supported file format and within the size limits configured for your Harmony instance. **The reporter account shows unexpected details** * Auto-created accounts use the sender's email address as the account identifier. If the sender has a display name set in their email client, that name may be used as the account name. # Ticket Events and Webhooks Harmony's service desk can emit real-time events whenever a support ticket is created or updated. By subscribing to these events through webhooks, you can connect external tools and services directly to your ticket workflow - eliminating the need to poll the API for changes. Common use cases include: * Syncing ticket data with a CRM or customer success platform * Triggering automated workflows when a ticket is opened or its status changes * Feeding ticket activity into analytics platforms or custom dashboards * Notifying downstream systems in real time as support interactions progress ### How Ticket Events Work When a ticket is created or updated in the Harmony service desk, Harmony generates an event and delivers it as an HTTP POST request to the webhook endpoint URL you configure. Each request contains a JSON payload describing the event and the current state of the ticket. Events are emitted for the following activity: * **Ticket created** - a new support ticket is opened in the service desk * **Ticket updated** - any field on an existing ticket changes, including status, priority, assignee, or custom fields ### Configuring a Webhook Endpoint To receive ticket events, you need to register a webhook endpoint that Harmony can send requests to. 1. Navigate to **Settings** and open the **Integrations** section. 2. Select **Webhooks** and click **Add Webhook**. 3. Enter the URL of your endpoint in the **Endpoint URL** field. The URL must be publicly accessible and accept HTTPS requests. 4. Under **Event Types**, select **Ticket Created**, **Ticket Updated**, or both, depending on which events you want to receive. 5. Click **Save** to activate the webhook. Harmony immediately begins sending events to the configured endpoint once you save. ### Event Payload Structure Each webhook request contains a JSON body with information about the event and the affected ticket. The payload follows this general structure: ```json { "event": "ticket.created", "timestamp": "2024-06-10T14:32:00Z", "ticket": { "id": "ticket_abc123", "subject": "Login issue after password reset", "status": "open", "priority": "high", "assignee": "agent@example.com", "requester": "user@example.com", "created_at": "2024-06-10T14:32:00Z", "updated_at": "2024-06-10T14:32:00Z", "custom_fields": {} } } ``` The `event` field will be either `ticket.created` or `ticket.updated`. The `ticket` object reflects the full current state of the ticket at the time the event was generated. ### Responding to Webhook Requests Your endpoint must return an HTTP `2xx` status code to acknowledge receipt of the event. Harmony treats any other response code as a delivery failure. If delivery fails, Harmony retries the request using an exponential back-off strategy. After a defined number of consecutive failures, the webhook may be automatically disabled and you will be notified so you can investigate and re-enable it. Keep your endpoint response time short. Process the event asynchronously if your integration requires heavy computation, and return the `200 OK` acknowledgment immediately. ### Securing Your Webhook Endpoint Harmony signs each webhook request so you can verify that it genuinely originated from Harmony and has not been tampered with in transit. * A signature is included in the `X-Harmony-Signature` request header. * The signature is an HMAC-SHA256 hash of the raw request body, computed using the secret key displayed when you create the webhook. * Store the secret key securely and recompute the signature on your server when you receive a request. Only process the payload if the signatures match. You can rotate the secret key at any time from the webhook settings page. After rotating, update your endpoint to use the new key. ### Testing Your Integration Before going live, use the **Send Test Event** option in the webhook settings to deliver a sample payload to your endpoint. This lets you verify that your endpoint is reachable, correctly parses the payload, and returns a successful response - without waiting for real ticket activity. You can also review recent delivery attempts and their response codes in the **Delivery Logs** tab of the webhook settings page to help debug any issues. ### Disabling or Deleting a Webhook * To temporarily stop event delivery without losing your configuration, toggle the webhook to **Inactive** in the webhook settings. * To permanently remove a webhook, click **Delete**. Delivery stops immediately and the configuration is removed. # Using the Requests Dashboard The Requests dashboard gives you complete visibility into every employee interaction that Harmony has handled - whether the AI resolved it autonomously or it was escalated to a human agent. Previously, you could only see requests that became tickets. Now, you can track every conversation from start to finish, all in one place. ### Accessing the Requests Dashboard To open the Requests dashboard, select **Requests** from the main navigation menu. This section contains two tabs: * **Tickets** - the existing view of all escalated support tickets * **Conversations** - a new view listing every interaction Harmony has handled, including those the AI resolved without human involvement ### The Conversations Tab The **Conversations** tab gives IT admins a full, filterable list of all employee interactions with Harmony. Each row in the list includes: * **Request ID** - a unique identifier for the interaction * **Employee details** - the name and relevant information of the person who submitted the request * **Category** - the type of request, such as access, hardware, or software * **Resolution status** - how the request was resolved, whether autonomously by the AI or by a human agent Click any row to open the full message thread for that interaction, so you can review exactly what was said and how the request was handled. ### How Harmony Classifies Resolution Status Harmony uses a layered approach to accurately determine how each request was resolved. This process checks: 1. The ticket assignee, to identify whether a human agent was involved 2. The event-log history, to trace the sequence of actions taken during the interaction This classification ensures the resolution status you see in the dashboard reflects what actually happened, giving you reliable data for tracking AI performance and agent workload. ### Filtering and Searching Interactions You can use the available filters in the Conversations tab to narrow down the list by category, resolution status, date range, or employee. This makes it straightforward to find a specific interaction or review trends across a particular type of request. ### What This Means for Your Team With the Requests dashboard, you no longer have a blind spot around AI-resolved interactions. You can: * Confirm that employees are receiving accurate, timely help even when no agent is involved * Identify categories of requests that the AI handles well versus those that frequently escalate * Audit any specific interaction by reviewing the complete message thread * Use resolution data to make informed decisions about automation coverage and staffing # Automatic Re-Evaluation of ITSM Tickets Harmony can automatically re-evaluate your ITSM tickets using the latest AI agent logic, so ticket assessments stay accurate as conversations evolve. When a re-evaluation is triggered, Harmony reruns the full agent evaluation workflow against the ticket, overrides the previous results in the Harmony ticket record, detects relevant workflows, and regenerates internal notes. Your team always has the most current context available without needing to intervene manually. ### How Automatic Re-Evaluation Works When a re-evaluation is triggered for an ITSM ticket, Harmony performs the following steps: 1. **Reruns the full agent evaluation workflow** - Harmony processes the ticket through the same AI agent logic used during the initial evaluation, applying any updates or improvements made to the agent since the ticket was first assessed. 2. **Overrides previous results** - The existing assessment in the Harmony ticket record is replaced with the new evaluation output, ensuring the record always reflects the most current AI-driven analysis. 3. **Detects relevant workflows** - Harmony identifies workflows that apply to the ticket based on the updated evaluation. 4. **Regenerates internal notes** - Internal notes are rewritten to reflect the latest context, giving your team an accurate and up-to-date summary directly within the ticket. ### When Re-Evaluation Is Triggered Re-evaluation can be triggered automatically as a ticket conversation evolves - for example, when new messages or updates are added to the ticket. This means assessments remain aligned with the full conversation history rather than only the state of the ticket at the time of initial evaluation. ### Benefits * **Accuracy over time** - Ticket assessments are not frozen at the moment of creation. As more information becomes available in a conversation, the evaluation reflects that updated context. * **Up-to-date internal notes** - Your team does not need to manually review and rewrite notes when a ticket changes. Harmony handles regeneration automatically. * **Consistent application of the latest AI logic** - Any improvements made to your AI agent configuration are applied to re-evaluated tickets, keeping your assessments aligned with your current setup. * **Reduced manual effort** - Because the process runs automatically, your team can focus on resolving tickets rather than maintaining assessment accuracy. ### Considerations * Re-evaluation **overrides** the previous results in the Harmony ticket record. If you need to retain a history of prior evaluations, ensure your workflows or integrations account for this before enabling the feature. * Internal notes are **regenerated** during re-evaluation, so any manually edited notes in the Harmony record may be overwritten. Review your team's note-taking practices to avoid losing manually added context. # ITSM Ticket Type Mapping When Harmony syncs tickets from your ITSM platform, it needs to translate the source issue type (for example, Jira's "Service Request" or Freshservice's "Incident") into a Harmony ticket type. This mapping determines how tickets are classified, routed, and handled inside Harmony. Harmony now uses a direct mapping approach for ticket type classification, giving you more consistent and predictable results across your connected ITSM sources. ### How Ticket Type Mapping Works Harmony follows a two-step process when determining the ticket type for any synced issue: 1. **Direct mapping** - Harmony first checks whether the source issue type has a known, direct equivalent in Harmony's ticket type taxonomy. If a match is found, that mapping is applied immediately. 2. **AI-based fallback** - If no direct mapping exists for the source issue type, Harmony automatically falls back to its AI-based classification engine, which infers the most appropriate ticket type based on the ticket's content and context. This approach means that common, well-defined issue types are handled consistently every time, while less common or custom issue types still benefit from intelligent classification. ### Supported Source-to-Harmony Mappings The direct mappings cover standard issue types from popular ITSM platforms. The examples below illustrate how source types translate to Harmony ticket types: | Source Platform | Source Issue Type | Harmony Ticket Type | | ----------------------- | ----------------- | ------------------- | | Jira Service Management | Service Request | Service Request | | Jira Service Management | Incident | Incident | | Freshservice | Incident | Incident | | Freshservice | Service Request | Service Request | | Freshservice | Problem | Problem | | Freshservice | Change | Change | For issue types not listed here, or for any custom types defined in your ITSM platform, Harmony applies AI-based classification automatically. ### Benefits of Direct Mapping * **Consistency** - The same source issue type always maps to the same Harmony ticket type, regardless of ticket content or wording. * **Predictability** - Your team can rely on ticket types being accurate from the moment a ticket is synced, reducing the need for manual reclassification. * **Seamless fallback** - Custom or unrecognized issue types are still classified intelligently through AI, so no tickets are left without a type. ### When AI Fallback Is Used AI-based classification is triggered automatically in the following situations: * The source issue type does not have a direct mapping in Harmony. * The source platform uses custom or non-standard issue type names. * The issue type field is missing or empty in the synced data. No configuration is required on your part - the fallback happens transparently behind the scenes. ### Frequently Asked Questions **Does this change affect tickets that were already synced before this improvement?** This improvement applies to tickets synced going forward. Previously synced tickets retain their existing classification. If you need to reclassify older tickets, you can do so manually from the ticket detail view. **Can I customize the mapping between source types and Harmony ticket types?** At this time, the direct mappings are managed by Harmony based on standard ITSM type definitions. If you have a specific mapping requirement for a custom issue type, contact Harmony support for assistance. **What happens if my ITSM platform uses a non-English issue type name?** If the issue type name does not match a known direct mapping, Harmony's AI fallback will classify the ticket based on its content. This ensures tickets are still typed correctly even when non-standard naming conventions are used. # Automatic ITSM Ticket Import and Classification Harmony now supports automatic ticket import from your ITSM platform (such as Freshservice), combined with AI-powered pre-processing that classifies and routes each ticket before it enters your support workflow. This removes the need to manually triage incoming tickets, reducing response times and ensuring consistency across your service desk operations. When a ticket is imported, Harmony analyses its content and context to determine several key attributes automatically. ### How It Works As soon as a ticket is imported from your connected ITSM platform, Harmony runs an AI classification step that resolves the following attributes for each ticket: * **Ticket type** - Harmony categorises the ticket based on its content and context, for example as an incident, service request, or change. * **Relevant desk** - The ticket is routed to the appropriate support desk automatically, based on the classified type and content. * **Reporter identification** - Harmony extracts and maps the original requester, including their email address, to the correct contact record in Harmony. * **Original assignee** - If the ticket was already assigned in your ITSM platform, Harmony preserves that assignment and maps it to the corresponding agent in Harmony. This means tickets arrive in Harmony already structured and directed to the right team, with no manual intervention required. ### Supported Platforms The following ITSM platforms are currently supported for automatic ticket import: * **Freshservice** Additional platform integrations may be added over time. If you require a specific integration, contact your Harmony account representative. ### Setting Up Automatic Ticket Import To enable automatic ticket import and classification, you need to connect your ITSM platform to Harmony and configure the import settings. 1. Navigate to **Settings** in your Harmony account. 2. Open the **Integrations** section and select your ITSM platform (for example, Freshservice). 3. Provide the required credentials or API key to authorise the connection. 4. Configure which ticket queues or groups should be imported into Harmony. 5. Save your settings. Once the connection is active, Harmony begins importing tickets and applying AI classification automatically. Existing open tickets can be imported as part of the initial sync, depending on your configuration. ### What Happens After Classification After Harmony classifies an imported ticket, it appears in the relevant desk queue with the resolved attributes already populated. Agents can review the classification details at any time and make corrections if needed. Any manual changes you make are respected and will not be overwritten by subsequent imports. Reporters receive communications through Harmony as normal, and the original requester information carried over from your ITSM platform ensures continuity of context for your support team. ### Benefits * **Faster triage** - Tickets are classified and routed the moment they are imported, so agents can begin working on them immediately. * **Consistent routing** - AI-driven classification applies the same logic to every ticket, reducing inconsistencies caused by manual triage. * **Preserved context** - Reporter details and existing assignments from your ITSM platform are carried over automatically, giving agents the full picture from the start. * **Reduced manual effort** - Your team spends less time on administrative tasks and more time resolving issues. # Managing People Learn how to use the People directory to search, filter, view employee profiles, manage accounts, and export data. {% hint style="info" %} **Path:** `/people` {% endhint %} ### Understanding the People Directory The People directory lists all employees in your organization. It requires admin access. Open **People** from the sidebar to view the list at `/people`. Each row shows the employee name, avatar, status, department, level, location, source, type, employment dates, last login, and related assets and software. #### Navigating the People List The People page displays a data table with sortable columns. Click a row to open that employee's profile. Use the toolbar for search, filters, refresh, and export. The table supports pagination with configurable page size (10-200 rows). Employee data is cached in your browser for up to one week and automatically refreshed in the background every 15 minutes, so the People table, ticket reporter filters, and other views that rely on employee data load much faster - especially on lower-powered hardware. ![People data table with toolbar and filters](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-abff5f2fa588f91de0cc9a6cb1249965d5c4f57e%2Fpeople-list.png?alt=media) #### Searching for Employees Use the **Search** input in the toolbar. Search matches display name, work email, department, location, and job title. Results update as you type (debounced). Search is combined with active filters. #### Filtering Employees Use the filter popover to apply one or more filters. Filters use AND logic. Available filters: | Filter | Description | | ---------------- | -------------------------------------------------------------------------------------------------------- | | **Status** | Employment status: Active, Terminated, On leave, Pending, Other | | **Type** | Employee type: Person, Bot, Service account | | **Department** | Department name (values from data) | | **Level** | Employee position level or seniority tier (values from data) | | **Location** | Location (values from data) | | **Source** | Integration source (Okta, Microsoft Entra, etc.) - displays integration icons alongside each source name | | **IdP Status** | Identity provider status (values from data) | | **Start Date** | Filter by employment start date (e.g. target new hires joining after or before a specific date) | | **VIP Reporter** | Quick filter for VIP reporters (hidden column) | Clear individual filters or use **Reset filters** to remove all. By default, the view shows active employees of type Person. You can combine department, level, location, start date, and status filters together for more precise results - for example, to identify new hires in a specific team joining within a given date range. #### Sorting the People List Click column headers to sort. Supported sort fields include display name, status, IdP status, department, level, location, source, type, start date, last login, related assets, related devices, and software count. Toggle between ascending and descending. #### Understanding Employee Avatars In the People list, each employee appears with an avatar (photo or initials), display name, and secondary text (job title or email). VIP employees show a VIP badge on the avatar. Service accounts display a settings icon instead of a photo. #### Understanding the Level Column A **Level** column appears in the People table after the Department column, showing each employee's position level or seniority tier. Empty values display as `--` or `N/A` where data is not available. Use the **Level** filter in the filter bank to quickly segment your workforce by seniority or position tier. #### Understanding the IdP Status Column The **IdP Status** column shows each employee's Identity Provider status directly in the People table, making it easier to spot discrepancies between HR records and identity provider accounts - for example, when someone is active in your HR system but has been deactivated in Okta. The column reflects data from Okta, Microsoft Entra, and Google Workspace. When multiple sources are available, the most recent status is displayed. The IdP Status column is hidden by default. Enable it via column settings. You can also filter by IdP Status to quickly find employees in a specific state across your connected identity providers. When you suspend or deactivate an employee using ticket quick actions, their IdP status is updated immediately in connected providers such as Okta, Microsoft Entra, and JumpCloud - rather than waiting for the next scheduled sync cycle. This means access is revoked faster and your identity provider stays in sync with actions taken directly in Harmony. #### Using Employee Selector Fields Elsewhere in Harmony (e.g., ticket assignee, reporter, asset assignment), employee selector fields let you search and pick employees. The selector is connected to a live backend search, so results are filtered in real time as you type rather than loading a full list upfront. This is especially helpful in larger organizations where scrolling through an unfiltered list was time-consuming. When you hover over a selected employee in these fields, a hover card shows name, email, department, location, phone numbers, and links to message via Slack or Teams when available. You can copy the employee's email address directly from the hover card using the copy icon - a confirmation toast message confirms the copy was successful. #### Bulk Updating Employee Types You can select multiple employees in the People table and update their employee type in a single action - useful when onboarding new members or designating service accounts at scale. * Select one or more employees using the selection column in the People table. * Use the **Set Type** bulk action to update all selected employees at once. * The **Set Type** button shows the number of currently selected employees and is disabled when none are selected. * A maximum batch size is enforced to ensure reliable processing of large updates. *** ### Viewing Employee Details Click an employee row to open their profile at `/people/$employeeId`. The profile shows the header (avatar, name, status, type, source, action buttons) and an Overview section with work details, contact details, assigned assets, software, custom fields, and related tickets. ![Employee profile with Overview tab](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-72fbb5fb764378597a7ff1a61522628dee6674e8%2Femployee-profile.png?alt=media) #### Understanding Employee Profiles The employee header includes: * Avatar with VIP badge (if applicable) * Display name and employment status badge * Type (Person, Bot, Service account) - editable via dropdown * Source(s) - links to HRIS/IdP profile when available * **Reset Password** - only for Okta test tenants * **Manage Groups** - only for Okta test tenants with Okta-sourced users * **VIP** toggle - mark or remove VIP status (not for service accounts) * **Message** button - opens a direct message with the employee in Slack or Microsoft Teams (whichever your organization uses), removing the need to manually search for a colleague in your messaging app #### Viewing Employee Profile Information The **Overview** tab includes: **Work Details** * Job title, Department * Level (position level or seniority tier) * Direct manager (with avatar and hover card), Employment contract * Start date, End date (when terminated), Tenure **Contact Details** * Email address (with copy icon to copy directly to clipboard), Phone numbers (mobile and work, with clear labels) * Location (with office name when available) * IdP Status (showing the provider icon and original status value) * Last login (timestamp of last SSO login, with a tooltip explaining how this value is determined) **Custom Fields** All custom fields associated with the employee profile are displayed directly within the detail page, giving you a more complete and accurate picture of each employee without needing to look elsewhere. #### Viewing Employee Assets The **Assigned assets** section lists devices and non-device assets assigned to the employee. Asset cards display the asset's serial number, making it easier to identify and cross-reference physical devices using the meaningful identifier your team already works with. Asset cells support hover previews showing name, type, status, and compliance. Use pagination when there are many assets. #### Viewing Employee Software The **Assigned software** section lists software applications assigned to the employee. For MDM-based integrations, an **Installed on** column shows which device each application is installed on. Hovering over a device in that column surfaces a Device Info card with key details, and clicking it takes you to the full Asset Details page for that device. Use the source and status filters to narrow results. Pagination is available. #### Viewing Employee Tickets The **Related tickets** section lists tickets associated with the employee (as reporter, assignee, or otherwise). You can filter and search within the tickets list. #### Understanding Employee VIP Status VIP employees appear with a VIP badge in the People list and on their profile. Use the gem icon button in the employee header to mark or remove VIP status. VIP status is used to prioritize reporters in the service desk. Service accounts cannot be marked as VIP. *** ### Managing Employee Accounts #### Resetting Employee Passwords **Reset Password** is shown only for Okta test tenants. Click the button to send an "Email Password Reset" workflow to the employee. The employee receives an email with instructions to reset their password. #### Managing Employee Groups **Manage Groups** is shown only when the tenant is a test tenant and the employee has an Okta source. Click the button to open the Manage Groups dialog. #### Assigning Users to Groups In the Manage Groups dialog, use the group selector to add the user to Okta groups. Search and select groups, then add them. The user will be a member of the selected groups in Okta. #### Understanding Group Assignments * Only Okta groups can be managed from Harmony. * System groups such as **Okta Administrators** and **Everyone** cannot be removed; they are shown for reference only. * Group membership is synchronized with Okta. #### Removing Users from Groups In the Manage Groups dialog, remove the user from a group by clicking the remove action next to that group. System groups (Okta Administrators, Everyone) cannot be removed. *** ### Exporting People Data #### Exporting Employee Data to CSV Click **Export** in the People toolbar. The export uses the current filters, search, and sort settings. A CSV file downloads with a name like `harmony-people-export-YYYY-MM-DD.csv`. Export includes all employees that match the filters; large exports may take a moment. #### Understanding People Export Fields The CSV includes columns such as Display Name, Employee ID, First Name, Last Name, Work Email, Job Title, Manager, Department, Level, Location, Employment Status, Employee Type, IdP Status, Sources, Start Date, Last Login, Related Devices, Related Assets, Related Apps, and associated asset details. Column visibility and order from the table are respected when possible. #### Filtering People for Export Apply filters before exporting to limit which employees are included. Supported export filters: search (display name, email, department, location, job title), department, level, location, employment status, type, sources, IdP status, start date. Sort order is also applied to the export. *** ### Related Resources
Asset Views & DetailsAssign assets to employees and view asset detailshttps://github.com/harmonyso/public-docs/tree/main/guides/managing-asset-views-and-details/README.md
Managing SoftwareView software assigned to employees and manage applicationshttps://github.com/harmonyso/public-docs/tree/main/guides/managing-software-applications/README.md
Service Desk & TicketsCreate and manage tickets linked to employeeshttps://github.com/harmonyso/public-docs/tree/main/guides/understanding-service-desk-and-managing-tickets/README.md
# Configuring Domain Aliases for Employee Identity Matching When your organization uses different email domains across integrations - for example, a legacy domain in your MDM while employees log in with a newer domain in Okta - Harmony may create duplicate user records instead of recognizing these as the same person. Domain alias support lets you tell Harmony which domains are equivalent, so employee identities are unified correctly across all connected integrations. This is especially useful during domain migrations, acquisitions, or any situation where a single employee might appear under more than one email domain depending on the source system. ### How Domain Aliases Work When you configure a domain alias, Harmony treats the alias domain as equivalent to your primary domain when matching employee records. For example, if your primary domain is `company.com` and you add `oldcompany.com` as an alias, an employee appearing as `jane@oldcompany.com` in your MDM will be matched to `jane@company.com` in Okta and unified into a single identity. This means: * Asset assignments from integrations using the alias domain are correctly attributed to the right employee * Ticket routing works as expected regardless of which domain appears in the source system * Duplicate user records caused by domain mismatches are eliminated automatically Harmony resolves identities using either domain without any manual merging required. ### Configuring Domain Aliases To add a domain alias for your employee directory: 1. Navigate to **Settings** in the Harmony sidebar. 2. Select **People Management** from the settings menu. 3. Locate the **Employee Directory** section and open the **Domain Aliases** configuration. 4. Click **Add Alias**. 5. Enter the alias domain you want to map - for example, `oldcompany.com`. 6. Confirm the primary domain it should resolve to. 7. Save your changes. You can add one or more aliases to cover all alternate domains your organization uses. ### When to Use Domain Aliases Consider configuring domain aliases in the following situations: * **Domain migration** - Your organization is moving from one email domain to another, and different integrations are still using the old domain during the transition period. * **Acquisitions or mergers** - Employees from an acquired company retain their original email domain in some systems while being onboarded to the parent company domain in others. * **Multiple email domains** - Your organization operates under several domains and different tools authenticate users under different ones. * **Okta and Google Workspace mismatches** - Your Okta login domain differs from the domain used in Google Workspace, your MDM, or other connected tools. ### What to Expect After Saving Once you save a domain alias, Harmony begins applying it to identity resolution across all connected integrations. Existing duplicate records caused by the domain mismatch will be unified, and going forward, Harmony will automatically resolve employees regardless of which domain appears in the source data. No additional configuration is required within individual integrations. The alias applies globally across your employee directory. ### Considerations * Domain aliases are applied at the directory level and affect all integrations simultaneously. * Adding an alias does not modify data in the connected source systems - it only affects how Harmony matches and displays employee identities internally. * If you need to remove an alias, return to the **Domain Aliases** configuration, locate the entry, and delete it. Harmony will stop resolving that domain as equivalent to the primary domain on the next sync. # Managing VIP Reporters VIP Reporters is a feature that lets you designate specific employees as high-priority ticket reporters. When an employee is marked as a VIP Reporter, their tickets are automatically treated with elevated urgency, and they are visually distinguished throughout the platform so your team always knows to act quickly on their requests. This article explains how to assign and manage VIP Reporter status on the People page. ### What Is a VIP Reporter? A VIP Reporter is an employee whose tickets receive priority treatment. This is useful for employees such as executives, board members, or other individuals whose issues require fast resolution. When an employee has VIP Reporter status: * A **VIP badge** and **diamond icon** appear on their avatar across all tables, dropdowns, and hover tooltips for reporters and assignees, so your team can identify them at a glance. * **Automatic priority** is applied to tickets they submit, ensuring those tickets receive the attention and urgency they deserve from the moment they are created. {% hint style="info" %} VIP Reporter status cannot be assigned to service accounts - only to regular employee profiles. {% endhint %} ### Marking an Employee as a VIP Reporter To designate an employee as a VIP Reporter: 1. Navigate to the **People** page. 2. Locate the employee you want to flag as a VIP Reporter. 3. Open the employee's profile or action menu and click **Mark as VIP Reporter**. The employee is immediately marked as a VIP Reporter. Their avatar will now display the VIP badge and diamond icon wherever they appear throughout the platform. ### Removing VIP Reporter Status If an employee no longer needs VIP treatment, you can remove their status at any time: 1. Navigate to the **People** page. 2. Locate the employee whose VIP Reporter status you want to remove. 3. Open the employee's profile or action menu and click **Remove VIP Reporter** (or the equivalent toggle, depending on your platform version). The VIP badge and diamond icon are removed immediately, and their tickets will no longer receive automatic priority treatment going forward. ### Where VIP Indicators Appear Once an employee is marked as a VIP Reporter, the VIP badge and diamond icon on their avatar are visible in the following places: * **Ticket tables** - Anywhere the employee appears as a reporter or assignee in a list or grid view. * **Dropdowns** - When selecting a reporter or assignee from a dropdown menu. * **Hover tooltips** - When hovering over an employee's avatar or name anywhere in the platform. This consistent visibility ensures your team never misses a VIP ticket, regardless of where they are working in the platform. ### Best Practices * Reserve VIP Reporter status for employees who genuinely require faster response times to avoid diluting the priority signal for your team. * Review your list of VIP Reporters periodically to make sure the designations are still appropriate as your organization changes. * Communicate with your support team about what VIP Reporter status means and the expected response standards, so the visual indicators translate into consistent action. # Automatic Employee Deletion Sync from HR and Identity Systems When you connect Harmony to an HR or identity system - such as an HRIS platform or a directory provider - Harmony continuously synchronizes your employee data to keep your agent roster and contact list accurate. As part of this synchronization, Harmony now automatically detects and processes employee deletions from your connected platform, removing departed or deactivated employees from your workspace without any manual intervention. This means your team's data stays consistent across systems at all times, and former employees will no longer appear as active agents or contacts in Harmony. ### How It Works When an employee is removed from your connected HR or identity system, Harmony detects the deletion during the next synchronization cycle and automatically removes that employee from your Harmony workspace. This applies to employees who have been: * Deactivated or suspended in your HR or identity platform * Fully deleted from your connected system * Removed from a synced group or directory that feeds into Harmony No manual cleanup is required on your end. The synchronization handles the removal automatically, keeping your agent and contact data up to date. ### What Changes in Harmony When a deletion is detected and processed, the affected employee will no longer: * Appear as an active agent in your workspace * Show up as an available contact for routing or assignment * Be counted as an active user in your roster This reduces confusion for your team, improves the accuracy of your workspace data, and ensures that departed employees cannot remain visible as active participants. ### Supported Integrations This automatic deletion behavior applies to employees synchronized from connected HR and identity systems. Check your integration settings in Harmony to confirm which platforms are currently connected and actively syncing employee data. ### Things to Keep in Mind * Deletions are processed as part of the regular synchronization cycle. There may be a short delay between the time an employee is removed in your external system and when the change is reflected in Harmony. * If an employee is removed from Harmony by sync but later needs to be restored, you can re-add them manually or re-include them in the relevant group or directory in your connected system so they are picked up in a future sync. * Make sure your HR or identity system integration has the appropriate permissions configured to allow Harmony to read deletion or deactivation events. If deletions are not being reflected, review your integration permissions or contact support. # Employee Sync: External Status Data Employee sync in Harmony now includes external status data as part of each synced employee and agent record. When your HR or identity system defines a status for a person - such as active, inactive, on leave, or any custom status your organization uses - that status is carried through into Harmony automatically during sync. This means each employee and agent record now holds a more complete picture of the person's current state as defined in your connected source system, without requiring any manual cross-referencing between platforms. ### What Changed Previously, synced records reflected core employee attributes but did not include the status information held in your external HR or identity system. You would need to check the source system separately to understand whether a given person was active, inactive, or in another state. Now, external status data is included as part of the source data payload for every synced employee and agent record. The status value is pulled directly from your connected system and kept in sync alongside the rest of the employee's information. ### What This Means for Your Workflows Because external status data is now part of the synced record, any automations or workflows in Harmony that rely on employee data can reference this richer status context directly. You do not need to reconfigure existing automations or set up additional integrations to take advantage of this. Some examples of how this can help: * **Access and provisioning workflows** - Trigger or modify actions based on whether an employee is active or inactive in your HR system. * **Offboarding automations** - Detect status changes such as a transition to inactive or terminated without waiting for manual updates. * **Audit and compliance processes** - Cross-reference Harmony records against HR system statuses in one place rather than switching between systems. ### Supported Source Systems External status data is included for any HR or identity system you have connected to Harmony through employee sync. The specific status values available depend on what your source system defines and exposes. Harmony carries those values through as-is, so the terminology and statuses you see on synced records will match what is configured in your external system. ### No Additional Configuration Required This improvement is available automatically. You do not need to update your sync configuration, reconnect your HR or identity system, or modify existing automations to start seeing external status data on synced records. The next sync cycle after this update will begin including the status information on employee and agent records. If you have automations that you want to update to act on external status values, you can do so at any time through the standard workflow and automation configuration in Harmony. # Syncing Employee Data from Your HRIS Harmony can connect directly to your HR information system (HRIS) and automatically pull employee records into the platform. Once your HRIS is connected, your support team always has accurate, up-to-date employee context without anyone needing to manually enter or maintain that information. The sync uses a unified API to read employee data from your connected HR system, so the process works consistently regardless of which HRIS you use. ### How the Sync Works Harmony keeps employee records current through a combination of scheduled syncs and event-driven triggers: * **Scheduled sync** - Harmony periodically pulls the latest employee records from your HRIS on a recurring schedule, ensuring data stays fresh even when nothing has explicitly changed. * **New connection trigger** - When you first connect an HRIS, a sync runs automatically so your employee data is available in Harmony right away without any manual action. * **Change detection** - Each sync uses robust change detection to compare incoming records against what is already stored. Only real changes are written, so the process is efficient and avoids unnecessary updates. ### What Data Is Synced Harmony pulls employee records directly from your HRIS. The specific fields available depend on what your HR system exposes, but typically include core employee information such as name, employment status, department, job title, and manager. This context is then accessible to your support team when handling requests. ### Connecting Your HRIS To start syncing employee data, you need to connect your HRIS to Harmony. To do this: 1. Go to **Settings** in Harmony. 2. Navigate to the **Integrations** section. 3. Select your HRIS from the list of available integrations. 4. Follow the prompts to authorize the connection. Once the connection is established, the initial sync begins automatically. You do not need to trigger it manually. ### Keeping Data Accurate After the initial sync, Harmony continues to update employee records on a scheduled basis. If an employee's information changes in your HRIS - such as a department transfer or a title change - that update will be reflected in Harmony during the next sync cycle. Because only genuine changes are applied, there is no risk of records being overwritten with duplicate or unchanged data. This means your support team can rely on the employee information in Harmony being a consistent reflection of what is in your HR system, without any manual reconciliation effort on your part. ### Frequently Asked Questions **Do I need to manually re-sync after making changes in my HRIS?** No. Harmony syncs on a schedule automatically. Your changes will be picked up during the next scheduled run. **What happens if the HRIS connection is temporarily interrupted?** Harmony will resume syncing once the connection is restored. Employee records will be updated at the next successful sync. **Can I sync multiple HRIS systems?** This depends on your Harmony plan and configuration. Contact your account team if you need to connect more than one HR system. # Syncing Out-of-Office Status from HRIS and Google Workspace Harmony can automatically mark agents as unavailable when they are out of office, removing the need for manual status updates and keeping ticket assignment accurate at all times. By connecting your HRIS provider or Google Workspace, Harmony pulls approved time-off and out-of-office data in real time and reflects it across the platform. This article explains which sources are supported, how the sync works, and what agents and administrators can expect. *** ### Supported Data Sources Harmony can sync out-of-office status from the following sources: #### HRIS Providers (via Apideck) * **HiBob** * **SAP SuccessFactors** When an agent has an approved time-off request in your HRIS, Harmony retrieves that data through the Apideck integration and stores it. Agents on approved leave are automatically excluded from ticket assignment for the duration of their absence. #### Google Workspace (Google Calendar) Harmony detects native out-of-office events created in Google Calendar. These events are recorded alongside any HRIS data, so both sources contribute to the agent's availability status in Harmony. *** ### How the Sync Works Harmony fetches time-off data using a targeted date range - from yesterday through the next 14 days - combined with an approved-status filter. This means only relevant, upcoming records are retrieved rather than months of historical data, resulting in faster and more consistent syncs. A graceful fallback chain is in place to maintain sync reliability. If a connected HRIS provider does not support date range filtering, Harmony falls back to an alternative retrieval method automatically, so syncs continue without interruption. Once data is retrieved, agents with active out-of-office periods are reflected as unavailable across the platform in real time. *** ### Impact on Ticket Assignment When an agent is marked as unavailable due to an out-of-office sync: * They are **excluded from automatic ticket assignment** for the duration of their absence. * No manual status change is required from the agent or an administrator. * As soon as their out-of-office period ends, their availability is restored automatically. This keeps your routing rules accurate and reduces the risk of tickets being assigned to agents who are not available to respond. *** ### Setting Up the Integration To enable out-of-office syncing, you need to connect at least one of the supported sources to Harmony: 1. **HRIS via Apideck** - Connect your HiBob or SAP SuccessFactors account through the Apideck integration in your Harmony settings. Once connected, Harmony will begin syncing approved time-off requests automatically. 2. **Google Workspace** - Connect your Google Workspace account to Harmony. Harmony will detect out-of-office events in agent calendars and record them alongside any HRIS data. You can connect one or both sources. When both are connected, data from each is combined to provide a complete picture of agent availability. *** ### Notes and Considerations * Only **approved** time-off requests from your HRIS are synced. Pending or rejected requests are not reflected in Harmony. * Out-of-office events must be created as native out-of-office entries in Google Calendar to be detected by Harmony. * The sync covers a rolling window of yesterday through the next 14 days, so upcoming absences are captured in advance. * Large organizations with high volumes of time-off data benefit from the optimized sync, which reduces API calls and retrieves only the data needed for the current window. # Managing Asset Views and Details Learn how to navigate asset views, filter and search assets, view asset details, manage purchase information, record retirement, and track asset activity. {% hint style="info" %} **Path:** `/assets` {% endhint %} ### Understanding Asset Management The Assets area shows devices and non-device assets (monitors, peripherals, etc.) from your MDM, integrations, or manual imports. Open **Assets** from the sidebar to view the list at `/assets`. You can switch between a **List** view (individual assets) and a **Warehouse** view (aggregated by model, vendor, and type). #### Navigating the Assets View The Assets page has a view-mode toggle (List / Warehouse). The List view shows a table of assets with sortable columns. Click a row to open the asset detail page. The Warehouse view shows aggregated counts by asset type, model, and vendor; click a row to apply those filters and switch to the List view. #### Using the Asset List View The List view displays assets with columns for: Asset (name and type), Status, Retirement Reason, Vendor, Model, Serial, OS Version, Supplier, Ownership, Source, Location, Employee Location, Compliance, MDM Status, EOL Date, Warranty End Date, Assignee, Former Assignee, Last seen, Last Enrolled, Purchase Date, Order Number, and CPU. EDR-related columns (EDR Status, EDR Agent Version, Active Threats, Last Scan) are available but hidden by default - use the column visibility dropdown to show them. Use the toolbar for search, filters, refresh, export, bulk actions, and import. #### Using the Warehouse View The Warehouse view aggregates assets by asset type, model, and vendor. Each row shows counts for different statuses (in stock, active, in repair, EOL planned, EOL grace period, EOL reached, retired) and locations. Click a row, a status, or a location to apply filters and navigate to the List view. Use the view-mode toggle to switch back. ![Warehouse view with aggregated counts](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-dc8906ff38c8d71c58dc1f4fc707ba68eeeabc07%2Fwarehouse-view.png?alt=media) #### Understanding Aggregated Asset Counts In the Warehouse view, counts reflect how many assets match each model/vendor/type combination for a given status or location. Clicking a count filters the List view accordingly. #### Understanding Asset Types Assets are categorized by type: Laptop, Monitor, Phone, Tablet, and others. The asset type appears in the Asset column and in filters. Device types (e.g., Laptop, Phone) typically have MDM data; non-device types may have limited or no specifications. *** ### Filtering and Searching Assets #### Filtering Assets by Status Use the filter popover to filter by status: In stock, Active, In repair, EOL planned, EOL grace period, EOL reached, Retired. Select one or more values. Filters combine with AND logic. #### Filtering Assets by Compliance Filter by compliance status. Values come from your MDM or integrations (e.g., compliant, non-compliant). #### Filtering Assets by Employee Filter by **Assignee** to see assets assigned to specific employees. Use **Unassigned** to show assets with no assignee. #### Filtering Assets by Location Filter by location. Location values are derived from assigned employees or asset metadata. Location and age filters are processed server-side, making them faster and consistent with all other asset filters. #### Filtering Assets by CPU Use the **CPU** filter to narrow assets by processor type. The CPU filter is a multi-select panel, and selecting a CPU type automatically adjusts the available options in all other active filters. #### Filtering Assets by OS Version OS version filters use a grouped, hierarchical view that organizes versions under their major release, so you can filter by a broad release or drill down to a specific build: * **macOS** - minor versions (e.g., macOS 13.6.0, macOS 13.6.1) are grouped under their major release (e.g., macOS 13, macOS 14, macOS 15 Sequoia) * **iOS** - patch versions (e.g., iOS 17.3.1, iOS 17.6.1) are grouped under major releases (e.g., iOS 16, iOS 17, iOS 18) * **Windows** - editions and builds are grouped under their major version #### Using Asset Quick Filters Quick filter cards at the top of the page apply preset filters with one click: | Quick Filter | Description | | ---------------------- | -------------------------------------- | | **Unassigned assets** | Assets with no assignee | | **Assets reached EOL** | Status EOL reached or EOL grace period | | **MacOS assets** | Assets with a macOS OS version | | **Windows assets** | Assets with a Windows OS version | | **Phones & Tablets** | Asset types Phone and Tablet | Click a card to apply the filter; click again to clear. Active quick filters are highlighted. ![Quick filter cards (Unassigned, EOL, MacOS, etc.)](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-88cf1d5ff0cdbc81567b69f79ba653e27994a3a8%2Fasset-quick-filters.png?alt=media) *** ### Managing Asset Details Click an asset row to open its detail page at `/assets/{assetId}`. The page shows the header (name, status, location, building, source), action buttons, and sections for Overview, Specifications, and (when applicable) Related software. ![Asset detail page Overview with header and cards](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-db7c191c9c45f59b3f1d10623a958d9cb0c7c41d%2Fasset-detail-overview.png?alt=media) #### Viewing Asset Details The asset header includes: * Asset name and status badge * Location (editable inline) * Building (when available) * Source (MDM or integration, shown with the source logo; click to open in external system when a device URL exists) * **Status** dropdown - change status; selecting **Retired** opens the retirement modal * **Activity log** button - opens the activity timeline (shows unread indicator when there is new activity) * **Get recovery key** - shown when the asset has FileVault/BitLocker key data #### Understanding Asset Properties The **Asset details** card shows: Compliance status, Ownership (editable), Assigned to (employee dropdown), Former Assignee, Asset ID, Department (from assignee), Last seen, and Last Enrolled. Use the Status dropdown to change lifecycle status. **Former Assignee** is automatically maintained - whenever the assigned employee changes, the previous assignee is captured and stored. This makes it easier to audit device history and trace ownership chains without digging through activity logs manually. **Last Enrolled** shows when the device was most recently enrolled across all supported MDM providers, including Jamf, Intune, and Kandji. #### Adding Purchase Details to Assets The **Purchase details** card shows order information. If no details exist, click **Add purchase details** to open the form. If details exist, click **Edit** to update. **Purchase details fields:** | Field | Description | | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------- | | **Order number** | Purchase or PO number | | **Purchase date** | Date of purchase | | **Price** | Purchase price (or estimated price when available) | | **Supplier** | Vendor or supplier | | **Warranty type** | Standard or Extended | | **Warranty description** | Notes shown inline directly after the warranty type; long descriptions are truncated with an ellipsis and reveal in full on hover | | **Warranty end date** | When warranty expires | #### Recording Asset Retirement To retire an asset: 1. Open the asset detail page. 2. Use the **Status** dropdown and select **Retired**. 3. The retirement modal opens. Select a reason: Disposed, Sold, Given away, Broken, Stolen, or Other (with optional notes). 4. Confirm. The modal reminds you to unenroll from MDM, wipe data, and reclaim licenses before disposition. ![Retirement modal with reason selection](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-1787f92e960975bbf4d7ddba4a77c25d9328e763%2Fretirement-modal.png?alt=media) #### Understanding Asset Retirement Workflow Retirement sets the status to Retired and stores the reason and notes. Retired assets appear in filters and the Warehouse view. Retirement reasons help with reporting and audits. #### Managing Recovery Keys When an asset has FileVault (macOS) or BitLocker (Windows) key data, the **Get recovery key** button appears in the Overview section. Click it to open the recovery key modal and copy the key. Use this when you need to recover access to an encrypted device. #### Adding Notes to Assets Click the notes button in the Overview section to add or edit a note for the asset. Notes appear in hover previews and on the asset detail page. They are included in activity logs. #### Managing Local Admin Rights For JumpCloud-managed devices, you can grant or revoke local admin privileges directly from the asset detail page using the quick actions menu - no manual steps in JumpCloud required. * **Grant Local Admin** - elevates the device's primary user to local admin for a set time period (minutes, hours, days, or unlimited) * **Revoke Local Admin** - removes local admin rights from the primary user at any time * The asset owner is notified when admin access is granted * All actions and outcomes are recorded in the device activity log Support for additional MDM providers is coming soon. #### Viewing Asset Technical Specifications The **Specifications** section shows device and hardware information when available from MDM or integrations. #### Understanding Device-Specific Specs For devices, specifications include: Model, MAC address, Serial number, IP address, OS version, Disk encryption. Monitors have specialized specs (e.g., size, resolution). Non-device assets may show limited or no specs. #### Viewing Asset Hardware Information The **Hardware specifications** card shows: CPU, Battery health (and cycles when available), Memory, Storage (used/total), Network interfaces, Manufacturer, and Last Restart time (for Jamf and Kandji managed devices). Values are populated from MDM when supported. **Last Restart** is retrieved automatically from each MDM. Jamf reads from Extension Attributes, recognizing common attribute names such as "Last Reboot", "System Boot Time", and "Last Boot Time". Kandji parses the relative `time_since_boot` field and converts it into an absolute timestamp. #### Viewing Disk Encryption Status The **Device Specifications** card displays a color-coded disk encryption badge for every managed device: | Indicator | Meaning | | -------------------------------------- | ------------------------------------------------------------ | | **Green dot** + encryption method name | Disk encryption is active (e.g., FileVault, BitLocker, LUKS) | | **Red dot** + "Disabled" | Disk encryption is turned off | | **Amber dot** + "Unknown" | Encryption state could not be determined | Harmony derives the specific encryption technology in use - FileVault for macOS, BitLocker for Windows, and LUKS for Linux - replacing the previous plain "True"/"False" display. #### Viewing EDR Security Information If you have an active SentinelOne or CrowdStrike integration, EDR security data is available on each asset's detail page and in the assets table. The following columns can be shown in the table (hidden by default): | Column | Description | | --------------------- | ------------------------------------------------------------------------------------------ | | **EDR Status** | Whether the agent is Active, Degraded, or Inactive; includes an outdated version indicator | | **EDR Agent Version** | The installed agent version with provider icon; sortable ascending/descending | | **Active Threats** | Number of active threats detected on the device | | **Last Scan** | When the device was last scanned by the EDR agent | The outdated version indicator is shown inline in the table row, so you can identify assets running out-of-date EDR agents without opening each record. To show the EDR columns, open the column visibility dropdown and enable them. #### Viewing Software Information on Assets For MDM-managed devices, the **Related software** section lists applications installed or assigned to the device. Click an application to open its software detail page. Use the source link to open the device in your MDM. *** ### Tracking Asset Activity and Lifecycle #### Viewing Asset Activity Log Click the **Activity log** button in the asset header to open the activity sheet. It tracks changes to the asset: user actions, system updates, MDM syncs, automation events, and discovery events. New activity is indicated by an unread badge on the button. ![Activity log sheet with event list](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-c35461928e9071f21c6ae6a94ed8bdd3237670fb%2Factivity-log-sheet.png?alt=media) #### Filtering Asset Activity Use the **Filters** popover to filter by: **Source (event type):** * User action * System event * MDM sync * Automation * Discovery **Category:** * Lifecycle * Purchase details * Device info * Compliance * Notes * Identity Use the search input to find events by text. Click **Reset** or the X on applied filter badges to clear filters. #### Understanding Activity Events Each event shows who or what made the change (user, system, MDM, automation, discovery), when it happened, and what changed. Events are ordered by time (newest first). #### Understanding Asset Lifecycle States | Status | Description | | -------------------- | ------------------------------------ | | **In stock** | Available, not assigned | | **Active** | Assigned and in use | | **In repair** | Being repaired | | **EOL planned** | End-of-life planned | | **EOL grace period** | Past EOL, grace period | | **EOL reached** | End-of-life date passed | | **Retired** | Disposed, sold, or otherwise retired | #### Tracking Asset Compliance Status Compliance status reflects MDM or integration data (e.g., device policy compliance). Use the compliance filter in the list and the compliance badge on the asset detail page. #### Tracking Asset Warranty Information Warranty end date appears in the list (when present) and in the Purchase details card. Add or edit purchase details to record warranty type and end date. The warranty description is shown inline directly after the warranty type on the asset detail page, so you can read it at a glance without hovering over a tooltip. *** ### Related Resources
Asset Management SettingsEOL policies, low stock alerts, discovery, agent configurationhttps://github.com/harmonyso/public-docs/tree/main/guides/configuring-asset-management/README.md
Asset Organization & ImportImport assets, bulk update location and ownership, and exporthttps://github.com/harmonyso/public-docs/tree/main/guides/managing-asset-organization-and-importing/README.md
Managing PeopleAssign assets to employees and view employee assetshttps://github.com/harmonyso/public-docs/tree/main/guides/managing-people/README.md
Asset & Automation MetricsAnalyze asset metrics and automation performancehttps://github.com/harmonyso/public-docs/tree/main/guides/analyzing-asset-and-automation-metrics/README.md
# Managing Asset Organization and Importing Learn how to update asset location, ownership, and assignment; use bulk actions; import assets from CSV; and export asset data. {% hint style="info" %} **Path:** `/assets` {% endhint %} ### Managing Asset Organization Asset organization controls where assets are, who owns them, and who they are assigned to. Update these values individually on the asset detail page or in bulk from the asset list. ![Asset detail page with Asset details card (Ownership, Assigned to)](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-643dbd63c7dbd422dc6bdbc83256aec7d785d4ef%2Fasset-detail-org-fields.png?alt=media) #### Updating Asset Location **Single asset:** On the asset detail page or in the list view Location column, click the cell to open the location selector. Choose an existing location, type to create a new one, or select **Clear location** to remove it. An autocomplete dropdown surfaces existing location values to keep naming consistent and prevent duplicates (for example, avoiding both "TLV" and "TLV Office"). Location is stored as manual location; it overrides MDM-derived and employee-derived locations when set. **Bulk:** Select multiple assets, then use **Change location** in the bulk actions toolbar. Pick a location or create a new one; it applies to all selected assets. #### Changing Asset Ownership **Single asset:** On the asset detail page, use the **Ownership** dropdown in the Asset details card. Options: Company Owned, Leased, Personal, Released. **Bulk:** Select multiple assets, then use **Change ownership** in the bulk actions toolbar. Choose an ownership value; it applies to all selected assets. This is especially useful during onboarding, offboarding, or team restructuring when ownership needs to change across many assets at once. #### Assigning Assets to Employees On the asset detail page, use the **Assigned to** dropdown in the Asset details card. Search for an employee and select them. To remove an assignment, select the **Unassigned** option from the dropdown. Assets with no employee assigned display **"Unassigned"** clearly rather than an empty field. Assigned assets appear in the employee's profile in the People directory. **Note:** Unassigning an asset does not automatically trigger a status change. Only assigning an asset to an employee activates the IN\_STOCK status transition. When you assign a device, the Department field is automatically pre-populated based on the assigned employee's department, saving manual data entry. If Harmony later discovers via your MDM that a device belongs to a different employee, the assignment may be updated accordingly. #### Understanding Asset Compliance Status Compliance status comes from your MDM or integration (e.g., policy compliance). It is read-only and cannot be edited directly. Use the compliance filter in the list and the compliance badge on the asset detail page. #### Managing Asset Metadata Asset metadata (name, model, serial, manufacturer, source, etc.) is primarily sourced from MDM or integrations. For manually imported assets, you can add or edit purchase details, notes, location, ownership, and assignment. The asset detail page shows the full set of properties. #### Viewing Estimated Asset Prices If an asset does not have a purchase price manually entered, Harmony automatically displays a catalog-derived estimated price sourced from a hardware price database. An info icon appears next to any estimated price with an "Estimated price" tooltip, so it is always clear when a price is an estimate rather than an actual recorded value. If neither a purchase price nor an estimated price is available, no price is shown. #### Auto-Assigning Owners to Autodiscovered Assets When an autodiscovery scan runs on a device that already has an employee assigned, all peripherals and accessories found on that device - such as monitors, headphones, and keyboards - automatically inherit the same owner. This keeps your asset inventory accurate and ownership tracked from the moment a new asset is discovered, without any manual assignment needed. This applies to assets discovered in new scans going forward; previously scanned assets are updated in the next scan cycle. *** ### Using Bulk Actions on Assets #### Selecting Multiple Assets In the asset List view, use the checkboxes in the first column to select rows. Select individual assets or use the header checkbox to select all on the current page. Bulk actions apply only to the currently selected assets. ![Asset list with checkboxes and bulk actions bar](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-0382e8c2c44971a21fbce0a34362bc280704c564%2Fasset-bulk-actions.png?alt=media) #### Bulk Updating Asset Location 1. Select one or more assets. 2. Click **Change location** in the bulk actions bar. 3. Choose an existing location or type to create a new one. Use **Clear location** to remove location from all selected assets. 4. Confirm. The update applies to all selected assets. #### Bulk Updating Asset Ownership 1. Select one or more assets. 2. Click **Change ownership** in the bulk actions bar. 3. Select an ownership value (Company Owned, Leased, Personal, Released). 4. Confirm. The update applies to all selected assets. #### Understanding Bulk Action Limits Bulk location and ownership updates apply to all assets you have selected. Selection is limited to assets on the current page unless you select all on the page. For large updates, apply filters first to narrow the list, then use the header checkbox to select the filtered set. *** ### Adding Assets Manually You can add individual assets directly through the UI without preparing a CSV file. On the Assets page, click **Add asset** and choose to add a single asset manually or import from CSV - both workflows are available from the same place. The manual entry form supports the following fields: * **Display name** (required), **Asset type** (required), and **Vendor** (required) * **Model**, **Serial number**, **Quantity**, **Ownership**, **Location**, and an optional **Note** * **Status** defaults to "In stock" automatically * Serial numbers are optional and can be left blank *** ### Importing Assets #### Importing Assets from CSV 1. Open **Assets** and click **Import** in the toolbar. ![Import dialog with template download](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-1294e5a8ef06b8ed922aa69cd07d86a1e592097e%2Fasset-import-dialog.png?alt=media) 2. Download the CSV template from the import dialog. 3. Fill the template with your asset data. Required columns: Display name, Asset type, Manufacturer. 4. Upload the CSV file. The file is validated before import. 5. If validation passes, click **Import**. After import completes, a summary shows records created, updated, and failed. If you have assets in an eToro spreadsheet template, Harmony recognises eToro's specific column structure and layout directly - you do not need to reformat your data before uploading. Assets without serial numbers are also handled correctly during import. #### Understanding Asset Import Fields The CSV must use these exact column headers. Data is matched by column name, not by position. | Column | Required | Description | | ----------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Display name** | Yes | Asset name. Max 100 characters. | | **Asset type** | Yes | One of: LAPTOP, DESKTOP, MONITOR, PRINTER, MOUSE, KEYBOARD, PHONE, TABLET, SERVER, DOCKING\_HUB, HEADPHONES, MICROPHONE, WEBCAM, MOBILE\_CONNECTIVITY, UNKNOWN. | | **Manufacturer** | Yes | Manufacturer name. Max 100 characters. | | **Asset Tag** | No | Stored in note with Description. | | **Description** | No | Stored in note with Asset Tag. | | **Asset State** | No | Status: in\_stock, active, in\_repair, planned, grace\_period, expired, retired. Case insensitive. Defaults to in\_stock. | | **Serial number** | No | Max 100 characters. Auto-generated if empty or if Quantity > 1. | | **Model** | No | Model name. Max 100 characters. | | **P.O Number** | No | Purchase order number. Max 100 characters. | | **Location** | No | Manual location. Max 255 characters. | | **Quantity** | No | 1-1000. Defaults to 1. When > 1, serial numbers are auto-generated. | | **Ownership** | No | COMPANY\_OWNED, LEASED, PERSONAL, RELEASED. | | **MDM Status** | No | ACTIVE, INACTIVE, IN\_REPAIR, END\_OF\_LIFE. | #### Mapping CSV Columns During Import Import uses fixed column headers. Your CSV must include the exact header names from the template (e.g., `Display name`, `Asset type`, `Manufacturer`). Rename your columns to match; there is no column-mapping UI. #### Previewing Asset Import Data After you upload a CSV, the import dialog validates the file. If validation succeeds, a green message shows how many assets are ready for import. If validation fails, up to 10 errors are shown (row number, field, and message). Fix errors in your CSV and upload again. #### Handling Import Errors * **File-level errors:** Missing required columns, file too large (5MB max), too many rows (1000 max), total assets exceed limit (10,000 after quantity expansion). Resolve these before import. * **Row-level errors:** Invalid asset type, invalid status, invalid ownership, invalid MDM status, length limits exceeded. Rows with errors are skipped; valid rows are imported. * **Post-import:** The summary shows successful inserts, successful updates, and failed inserts. Duplicate assets from MDM supersede manually imported assets when both exist. *** ### Exporting Assets #### Exporting Assets to CSV Click **Export** in the Assets toolbar. The export uses the current filters, search, and sort settings. A CSV file downloads with a name like `harmony-assets-export-YYYY-MM-DD.csv`. Export includes all assets that match the filters; large exports may take a moment. The exported CSV reflects exactly what you see on screen - including which columns are visible and the order they appear in your table. Any columns you have hidden will not appear in the export, and the column order in the CSV matches the order shown in your table. This makes exported data easier to work with and consistent with your configured view. #### Filtering Assets for Export Apply filters before exporting to limit which assets are included. Supported export filters: search, MDM status, status, compliance, assignee, source, asset type, vendor, model, supplier, OS version, ownership, retirement reason, age, location. Sort order is also applied to the export. #### Understanding Asset Export Fields The CSV includes columns such as Asset, Asset Type, Status, Retirement Reason, Vendor, Model, Serial, OS Version, Supplier, Ownership, Source, Location, Compliance, MDM Status, EOL Date, Warranty End Date, Assignee, Assignee Email, Last seen, Age, and others. The columns shown and their order reflect your current table layout. Any columns you have hidden in the table will be excluded from the export. *** ### Related Resources
Asset Management SettingsEOL policies, low stock, discovery policieshttps://github.com/harmonyso/public-docs/tree/main/guides/configuring-asset-management/README.md
Asset Views & DetailsView asset details, purchase info, and specificationshttps://github.com/harmonyso/public-docs/tree/main/guides/managing-asset-views-and-details/README.md
Managing PeopleAssign assets to employees and view employee profileshttps://github.com/harmonyso/public-docs/tree/main/guides/managing-people/README.md
# Discovering Unmanaged Network Assets Harmony can automatically scan your local network and surface every connected hardware device that is not already tracked in your Asset Inventory. This removes the need for manual hardware audits and gives IT administrators a complete, continuously updated picture of what is physically present on the network - including devices that have never had the Harmony agent installed. Network discovery uses ARP cache inspection combined with active ARP scanning to detect connected devices, then applies MAC address fingerprinting to resolve each device to its vendor and model. Newly discovered devices are pushed directly into Asset Inventory with no additional steps required. Discovery runs through Harmony's custom script infrastructure and is supported on endpoints running **macOS** and **Windows**. *** ### How Network Discovery Works When a discovery scan runs, Harmony performs the following steps on a managed endpoint: 1. **ARP cache inspection** - The endpoint reads its local ARP cache to identify devices it has already communicated with on the same network segment. 2. **Active ARP scanning** - The endpoint sends ARP requests across the local subnet to uncover devices that are not yet in the ARP cache. 3. **MAC address fingerprinting** - Each responding device's MAC address is matched against a vendor and model database to produce human-readable identification details. 4. **Inventory push** - All discovered devices are automatically added or updated in your Asset Inventory, keeping your hardware records current without any manual input. Because the scan runs directly from a managed endpoint, no dedicated network scanner appliance or additional infrastructure is required. *** ### Supported Platforms The network discovery script runs on managed endpoints with the following operating systems: | Operating System | Supported | | ---------------- | --------- | | Windows | Yes | | macOS | Yes | At least one managed Windows or macOS endpoint must be present on a network segment for discovery to cover that segment. *** ### What Gets Discovered For each detected device, Harmony attempts to record: * **IP address** assigned at the time of the scan * **MAC address** of the network interface * **Vendor** derived from the MAC address prefix (OUI) * **Model information** where fingerprinting data is available Devices are classified as unmanaged assets when they do not have an active Harmony agent associated with them. This includes printers, switches, access points, smart devices, and any other network-connected hardware. *** ### Viewing Discovered Assets After a scan completes, discovered devices appear in **Asset Management > Asset Inventory**. You can filter the inventory to show unmanaged assets to quickly identify hardware that falls outside your current management scope. From the inventory list you can: * Review vendor and model details for each discovered device * Compare discovered devices against your known hardware records * Take follow-up action such as tagging, assigning ownership, or flagging devices for investigation Because results are pushed automatically after every scan, the inventory reflects your current network state without requiring you to manually import or reconcile data. *** ### Running a Discovery Scan Network discovery is delivered as a Harmony custom script. To run a scan: 1. Open **Asset Management** and navigate to the **Scripts** section. 2. Locate the network discovery script for your target platform (Windows or macOS). 3. Deploy the script to one or more managed endpoints on the network segments you want to scan. 4. Wait for the script execution to complete. Results are pushed to Asset Inventory automatically once the scan finishes. You can schedule the script to run on a recurring basis to keep your unmanaged asset records up to date as devices join or leave the network. *** ### Considerations and Best Practices * **Segment coverage** - ARP scanning is limited to the local subnet of the endpoint running the script. To cover multiple network segments, deploy the discovery script to at least one managed endpoint on each segment you want to monitor. * **Scan frequency** - Running discovery on a regular schedule (for example, daily or weekly) reduces the window in which new or rogue devices go undetected. * **Device churn** - IP addresses recorded during a scan reflect point-in-time assignments. If your network uses DHCP with short lease times, treat IP address data as approximate and rely on MAC addresses as the stable identifier. * **Permissions** - Ensure the endpoint running the script has sufficient privileges to execute ARP operations. On some operating systems, active ARP scanning may require elevated permissions. * **Network impact** - Active ARP scanning generates a low volume of broadcast traffic. This is not expected to affect normal network operations, but you should be aware of it in highly sensitive or bandwidth-constrained environments. # Ingesting Custom Script Results from Managed Devices Harmony lets you ingest the results of custom scripts running on managed devices directly into the platform for asset discovery and data enrichment. This ingestion path works with any MDM solution - including Kandji, JumpCloud, and others - so you are not limited to natively supported integrations. When a script runs on a managed device, its standard output is automatically captured, compressed, and uploaded to Harmony using secure, authenticated requests. No extra configuration is required inside the script itself. ### How It Works The ingestion flow has two main parts: 1. **Script execution** - Your MDM schedules and runs a script on managed devices as it normally would. 2. **Result upload** - The script's standard output is redirected to a temporary file, compressed, and sent to Harmony using an access key for authentication. This approach keeps transfers efficient and ensures that only trusted devices can submit data to your Harmony environment. ### Prerequisites Before setting up custom script ingestion, make sure you have: * An active Harmony account with asset management permissions. * An access key generated from the Harmony settings. Access keys are used to authenticate upload requests from your scripts. * An MDM solution capable of deploying and scheduling scripts on managed devices (any MDM platform is supported). ### Setting Up Access Key Authentication Access keys ensure that only authorized devices can submit script results to Harmony. To generate an access key: 1. Navigate to **Settings** in Harmony. 2. Open the **Access Keys** section. 3. Select **Create Access Key** and give it a descriptive name so you can identify which integration it belongs to. 4. Copy the generated key and store it securely - you will reference it in the upload step of your script. Keep your access key confidential. If a key is compromised, rotate it immediately from the same settings page. ### Writing a Custom Script Your script does not need any special logic to handle uploads. Harmony captures standard output automatically. Focus the script on collecting the data you want - hardware inventory, installed software, configuration details, or any other asset information. A typical script structure looks like this: 1. Collect the data you need (for example, system profiler output, installed package lists, or custom inventory fields). 2. Print the results to standard output. 3. Exit cleanly. The upload wrapper handles compression and transmission after your script finishes. ### Automatic Result Capture and Upload When the script runs on a managed device, Harmony's upload mechanism: * **Redirects standard output** to a temporary file on the device. * **Compresses the file** before transmission to keep the payload small and transfers fast. * **Sends the compressed result** to Harmony using your access key in the authentication header. This happens automatically without any changes to the script itself. Once the data arrives in Harmony, it is processed and made available for asset discovery and enrichment. ### Supported MDM Platforms This ingestion method works alongside any MDM solution. Platforms that have been validated include: * **Kandji** * **JumpCloud** * Any other MDM capable of running shell or Python scripts on managed endpoints If your MDM can deploy a script and schedule its execution, it is compatible with this feature. ### Firewall and Network Considerations The upload uses standard HTTPS outbound traffic, making it compatible with most corporate firewall policies without requiring special rules. Ensure managed devices can reach the Harmony API endpoint on port 443. ### Troubleshooting | Symptom | Likely Cause | Resolution | | --------------------------------------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------- | | Upload fails with an authentication error | Access key is missing or incorrect | Verify the key in your script matches the one generated in Harmony settings | | No results appear in Harmony after script runs | Script produced no standard output | Confirm the script prints output and exits with a zero status code | | Compressed file is empty | Script exited before producing output due to an error | Check the script's error output via your MDM console for runtime failures | | Data appears in Harmony but fields are not enriched | Output format is not recognized | Review the expected output format in the Harmony documentation for your script type | ### Next Steps * Review the asset discovery dashboards in Harmony to confirm ingested data is appearing correctly. * Schedule your script on a recurring basis through your MDM to keep asset data up to date. * Use access key rotation as part of your regular security hygiene to minimize exposure. # Windows Peripheral and Display Discovery Harmony extends its peripheral and display discovery capabilities to Windows devices, giving you a more complete picture of the hardware connected across your fleet. You can now automatically inventory USB devices, Bluetooth devices, and connected displays on Windows endpoints - all through native PowerShell-based detection that does not require additional tooling or agents. These capabilities are part of Harmony's Unmanaged Asset Discovery and work alongside the existing macOS support to give you consistent hardware visibility across operating systems. *** ### USB Device Discovery Harmony discovers USB devices connected to Windows endpoints by running native PowerShell scripts that query WMI directly on the device. This replaces a previous dependency on osquery, resulting in more reliable and broader coverage across your Windows fleet. #### How it works * Enumerates connected USB devices using WMI * Maps device classes to the appropriate asset types in Harmony * Filters out USB hubs and devices that report invalid or missing serial numbers, keeping your inventory clean and meaningful Discovered USB devices appear as assets within Harmony's Unmanaged Asset Discovery results, attributed to the Windows endpoint they were found on. *** ### Bluetooth Device Discovery Harmony also detects Bluetooth devices paired or connected to Windows endpoints using the same native PowerShell approach. Both paired and actively connected devices are surfaced so you have a complete view of wireless peripherals associated with each machine. #### How it works * Detects Bluetooth devices using native Windows PowerShell scripts, without requiring osquery * Surfaces paired and connected devices as assets linked to the Windows endpoint * Provides device details to help you identify and track Bluetooth peripherals across your fleet *** ### Connected Display Detection Harmony can now discover and inventory monitors connected to Windows devices, extending the display detection capability that was previously available only on macOS. This gives you consistent display visibility across your entire managed fleet, regardless of operating system. #### How it works Harmony uses a multi-source detection strategy to reliably identify monitors across your Windows fleet: * Detects displays regardless of connection type, including USB-C connected monitors * Identifies displays based on current connection status as well as previously connected displays * Works on older Windows systems running PowerShell 5, so no PowerShell upgrade is required #### Display information collected For each detected display, Harmony parses raw EDID (Extended Display Identification Data) directly from the hardware to extract: | Field | Description | | ----------------- | ------------------------------------------------ | | **Manufacturer** | The brand or maker of the display | | **Model name** | The specific model identifier of the monitor | | **Serial number** | The unique hardware serial number of the display | This level of detail allows you to accurately identify and track individual monitors, helping you manage display assets, enforce hardware standards, and investigate equipment across your organization. *** ### Requirements | Capability | Requirement | | -------------------------- | ------------------------------------------- | | USB device discovery | Windows endpoint with PowerShell available | | Bluetooth device discovery | Windows endpoint with PowerShell available | | Display detection | Windows endpoint with PowerShell 5 or later | No additional agents, tools, or PowerShell upgrades are required beyond what is already present on supported Windows systems. *** ### Viewing Discovered Peripherals and Displays Discovered USB devices, Bluetooth devices, and displays appear within Harmony's Unmanaged Asset Discovery results. Each discovered item is linked to the Windows endpoint it was found on, making it straightforward to trace peripherals back to specific machines in your fleet. To review discovered assets, navigate to the Asset Management section of Harmony and open Unmanaged Asset Discovery. Filter by asset type to focus on USB devices, Bluetooth peripherals, or displays as needed. # Managing Bluetooth and Peripheral Devices Harmony's asset management capabilities extend to Bluetooth and peripheral devices connected across your environment. This article explains how Harmony identifies and catalogs Bluetooth peripherals, with a focus on Logitech device recognition, and what that means for your inventory accuracy. ### How Harmony Identifies Bluetooth Peripherals When Harmony discovers devices in your environment, it cross-references hardware identifiers against its device catalog to resolve manufacturer attribution and specific model information. For Bluetooth peripherals, this process relies on device-reported identifiers to match each device to a known model. Accurate identification at the model level is important because it directly affects: * **Asset inventory accuracy** - each device appears with the correct name, manufacturer, and model, rather than as an unresolved or generic entry * **Manufacturer attribution** - devices are credited to the correct vendor, preventing incorrect third-party lookups * **Asset cataloging** - your inventory reflects a precise picture of the peripherals deployed across your organization ### Logitech Bluetooth Device Recognition Harmony includes enhanced identification for Logitech Bluetooth peripherals. Rather than relying on generic or third-party lookups, Harmony resolves Logitech devices to their specific models and correctly attributes them to Logitech as the manufacturer. #### What Is Covered This recognition covers **65 Logitech Bluetooth devices** across the following categories: | Category | Example Devices | | --------- | ----------------------------------------- | | Mice | MX Master 3S, M720 Triathlon | | Keyboards | MX Keys S | | Headsets | Various Logitech Bluetooth headset models | #### What Changed Previously, Logitech Bluetooth devices could appear as unresolved entries or be misattributed to an incorrect manufacturer due to third-party lookup fallbacks. Harmony now identifies these devices at the model level directly, which means: * Logitech peripherals are no longer misattributed to third-party vendors * Devices that previously showed as unresolved now resolve to a specific Logitech model * Your asset catalog and inventory reports reflect accurate, model-level detail for Logitech Bluetooth hardware ### Impact on Your Asset Inventory If your environment includes Logitech Bluetooth peripherals, you may notice the following changes in your asset inventory after this improvement takes effect: * Devices that were previously unresolved or listed under an incorrect manufacturer now display the correct Logitech model name and manufacturer attribution * Asset counts and groupings based on manufacturer or model will more accurately reflect your actual hardware * Reports and dashboards that surface peripheral data will show cleaner, more reliable entries for Logitech devices No action is required on your part. Harmony applies these identification improvements automatically as part of its asset discovery and cataloging process. ### Supported Device Categories Harmony's Bluetooth peripheral identification is not limited to Logitech devices. The asset management engine resolves peripherals from a broad range of manufacturers. Logitech-specific improvements are part of ongoing investment in expanding and refining the device catalog to support more accurate inventory management across your environment. If you have peripherals that appear unresolved or incorrectly attributed in your inventory, contact Harmony support for assistance. # Retrieving Device Recovery Keys from Intune and Kandji Harmony can now retrieve device recovery keys directly from Microsoft Intune and Kandji. Your IT and security teams can access unlock PINs and recovery keys from within Harmony without switching between MDM consoles, reducing friction during device recovery and support workflows. ### Supported MDM Platforms Recovery key retrieval is supported for the following MDM platforms: * **Microsoft Intune** - recovery key retrieval is available as part of the existing Intune integration. * **Kandji** - recovery keys and unlock PINs are fetched via the Kandji Device Secrets API. ### Prerequisites #### Microsoft Intune No additional configuration is required beyond your existing Intune integration. Recovery key retrieval is supported automatically once your Intune connection is active in Harmony. #### Kandji To enable recovery key retrieval for Kandji-managed devices, your Kandji API token must have the **Device secrets** permission enabled. Without this permission, Harmony cannot fetch recovery keys or unlock PINs from the Kandji Device Secrets API. To verify or update your API token permissions: 1. Log in to your Kandji admin console. 2. Navigate to **Settings** and select **Access** or **API Token** management. 3. Locate the API token used for your Harmony integration. 4. Ensure the **Device secrets** permission is enabled on that token. 5. Save your changes. Once the permission is in place, Harmony will be able to retrieve recovery keys and unlock PINs for your Kandji-managed devices. ### Retrieving Recovery Keys in Harmony After the prerequisites are met, you can access device recovery keys directly from the Harmony interface: 1. Open Harmony and navigate to the **Devices** section. 2. Select the device for which you need the recovery key. 3. Look for the **Recovery Key** or **Unlock PIN** option in the device details panel. 4. Harmony fetches the key in real time from the connected MDM platform and displays it to authorized users. ### Permissions and Access Control Recovery key retrieval is a sensitive operation. Ensure that only authorized members of your IT and security teams have access to this functionality within Harmony. Review your Harmony role assignments to confirm that recovery key visibility is restricted to the appropriate users. ### Troubleshooting | Issue | Likely Cause | Resolution | | ----------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------ | | Recovery key not available for a Kandji device | **Device secrets** permission missing on the API token | Enable the **Device secrets** permission on your Kandji API token as described above | | Recovery key not available for an Intune device | Intune integration not active or misconfigured | Verify your Intune connection is healthy in the Harmony integrations settings | | Permission denied error when fetching key | Insufficient API token scope | Review and update the API token permissions in the respective MDM console | # Viewing Device Hardware Details (Disk & Battery) Harmony now surfaces richer hardware details for devices managed through JumpCloud and Kandji. Alongside existing device information, you can view disk information and battery health data directly within Harmony - giving your team a more complete picture of each device's condition without needing to switch between tools. This data is collected automatically as part of the MDM integration. No additional configuration is required. ### What You Can See #### Disk Information Harmony tracks disk details per device and stores them for ongoing visibility. This includes data about the storage hardware present on each managed device, allowing you to monitor disk status over time. Disk information is collected automatically from devices enrolled through your JumpCloud or Kandji integration. #### Battery Health Battery health data helps you proactively identify devices with aging or degraded batteries before they cause productivity issues or unexpected downtime. Rather than waiting for a user to report a problem, your team can spot at-risk devices early and take action. Battery health is surfaced per device alongside other hardware details. ### Supported Integrations Disk information and battery health are available for devices managed through the following MDM integrations: * **JumpCloud** * **Kandji** If you are using a different MDM integration, this hardware data may not be available at this time. ### Viewing Hardware Details for a Device 1. Navigate to the **Devices** section in Harmony. 2. Select the device you want to inspect. 3. On the device detail page, locate the hardware information section. 4. Review the available **disk information** and **battery health** data displayed for that device. Harmony collects and updates this data automatically as part of its ongoing MDM sync, so the information you see reflects the current state reported by your MDM provider. ### Why This Matters Having disk and battery data in one place helps your team: * **Reduce reactive support** - Identify failing or degraded hardware before users are impacted. * **Plan device replacements** - Use battery health trends to prioritize which devices need to be refreshed. * **Maintain device hygiene** - Keep a complete and accurate record of each device's hardware condition over time. # Resilient MDM Device Data Processing Harmony now processes device data from Mobile Device Management (MDM) integrations in a more resilient and reliable way. Two focused improvements work together to reduce the chance of sync failures, incomplete asset records, or devices appearing as unrecognised - even when MDM-provided data contains minor inconsistencies or unexpected formatting. ### What Changed #### More Permissive Data Parsing Harmony previously used a stricter approach when parsing records from MDM integrations. Minor variations in data formatting, unexpected field values, or edge cases in individual data points could cause processing failures that resulted in: * Devices failing to sync correctly * Assets appearing as unrecognised in your account * Incomplete device data being written to asset records * Inconsistent handling of end-of-life events for managed devices Harmony now uses a more permissive parsing approach. This means that when MDM-provided data contains minor inconsistencies or malformed individual data points, the platform can still process the record successfully rather than failing or skipping it entirely. #### More Consistent End-of-Life Event Handling End-of-life event processing for managed devices has been made more consistent and reliable as part of these improvements. Devices reaching end-of-life status through your MDM integration are now handled in a more predictable way, reducing gaps in your asset records during those transitions. #### Streamlined Error Logging Error logging for MDM integration data processing has been streamlined. When issues do occur, the improved logging makes it faster and easier to identify and resolve them - reducing the time between a problem appearing and a fix being delivered. ### Benefits for Your Asset Records These changes combine to give you a more accurate and complete view of your managed device inventory in Harmony: * Fewer devices appearing as unrecognised due to formatting quirks in MDM data * More complete device information written to asset records during syncing * Reduced risk of processing gaps caused by individual malformed data points * More reliable overall sync behaviour between your MDM integration and Harmony ### Supported Integrations These improvements apply to all MDM integrations connected to Harmony. No configuration changes are required on your part - the more resilient processing behaviour is applied automatically. # Unified MDM Device Management Harmony now provides a unified API for managing devices across multiple Mobile Device Management (MDM) platforms. Instead of switching between vendor-specific consoles or building separate integrations for each provider, you can interact with all your connected MDM platforms through a single, consistent interface. This unified approach abstracts away the differences between MDM vendors, so you can focus on managing your devices rather than navigating platform-specific quirks. ### Supported MDM Platforms The unified MDM API currently supports the following providers: * **Kandji** * **JumpCloud** Additional MDM platforms may be added over time as integrations are expanded. ### What You Can Do Through the unified MDM API, you can perform the following actions across all your connected platforms from one place: #### Send Device Commands Issue commands to managed devices without logging into each vendor console separately. Commands are routed to the appropriate MDM provider automatically based on which platform manages the target device. #### Upload and Deploy Custom Applications Package and deploy custom applications to managed devices across your MDM providers. You no longer need to repeat the upload and deployment process in each vendor's interface - a single operation handles distribution to all targeted devices regardless of which MDM manages them. #### Deploy Custom Scripts Push and execute custom scripts on devices across all supported MDM platforms simultaneously. This makes it straightforward to enforce configurations, run diagnostics, or automate remediation tasks at scale without duplicating effort per provider. #### Interact with Multiple MDM Providers The API presents a consistent interface regardless of which underlying MDM platform manages a given device. This means your workflows, automations, and integrations remain uniform even as you add or change MDM providers over time. ### Benefits * **Reduced operational overhead** - Manage all your MDM platforms from one place instead of maintaining separate processes for each vendor. * **Consistent automation** - Build scripts and workflows once and apply them across every connected MDM provider. * **Faster response times** - Send commands or deploy content to devices on any platform without switching contexts. * **Scalability** - As your device fleet grows across different MDM providers, the unified API scales with you without requiring additional integrations. ### Getting Started To begin using the unified MDM API, ensure that your MDM providers are connected to Harmony and that the relevant integrations are configured. Once your platforms are connected, you can use the unified API endpoints to send commands, deploy applications, and run scripts across all supported MDM providers in your environment. For details on connecting specific MDM providers, refer to the integration guides for Kandji and JumpCloud in the Integrations section of this documentation. # Automatic Device Sync When Connecting an MDM Integration When you connect a new Mobile Device Management (MDM) integration in Harmony, a device sync starts automatically as soon as the setup is complete. This means your managed devices appear in your asset inventory right away, without any extra steps on your part. ### How It Works Once you finish configuring a new MDM integration, Harmony immediately triggers a device sync in the background. The sync pulls in all devices managed by that MDM and populates your device inventory automatically. You do not need to: * Wait for a scheduled sync to run * Manually trigger a sync after setup Your devices are available as soon as the initial sync completes. ### Getting Started To take advantage of automatic device sync, connect your MDM integration as you normally would: 1. Navigate to **Asset Management** and open the integrations settings. 2. Select your MDM provider and complete the configuration steps. 3. Once the integration is saved, Harmony automatically starts syncing your devices. 4. Refresh your device inventory to see your managed devices as they are pulled in. No additional configuration is required to enable the automatic sync - it happens by default for every new MDM integration you connect. ### What to Expect After Setup * **Immediate sync** - A sync begins the moment your integration setup is complete. * **Populated inventory** - Your managed devices appear in the asset inventory once the sync finishes, typically within a few minutes depending on the size of your device fleet. * **Ongoing scheduled syncs** - After the initial automatic sync, Harmony continues to sync your devices on the regular scheduled cadence to keep your inventory up to date. ### Troubleshooting If your devices do not appear after connecting an MDM integration, check the following: * Confirm the integration was saved successfully and shows an active status. * Verify that the credentials or permissions provided during setup allow Harmony to read device data from your MDM. * If the inventory still appears empty after several minutes, you can manually trigger a sync from the integration settings to retry. # Managing Software Applications Learn how to navigate the software list, view application details, manage licenses, assign and revoke user access, use bulk actions, and export software data. {% hint style="info" %} **Path:** `/software` {% endhint %} ### Understanding Software Management The Software area shows applications discovered from your integrations (e.g., Okta, Microsoft Entra, NinjaOne) as well as applications you add manually. Open **Software** from the sidebar to view the list at `/software`. Applications are synced from your identity provider or MDM; you manage their status, licenses, user access, contracts, and custom fields in Harmony. #### Navigating the Software List The Software page displays a data table with sortable columns. Click a row to open that application's detail page. Use the toolbar for search, filters, refresh, export, and bulk actions. The table supports pagination with configurable page size. At the top of the Applications page, a row of insight widgets gives you an at-a-glance summary of your SaaS portfolio's health. See [Application Insight Widgets](#application-insight-widgets) for details. The **Users** column has been renamed to **Connected Users**. Where a direct integration exists, it displays the format `connected/licensed users` with an info icon tooltip for context. ![Software list with toolbar and filters](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-9d3f3bba15609a2d05395ae3f6b28e9f7593f348%2Fsoftware-list.png?alt=media) #### Adding New Software Software applications are discovered automatically from your integrations (Okta, Microsoft Entra, NinjaOne, and other MDM providers). You can also manually create applications that are not auto-detected. Click the **Add manual application** button on the Applications page to create one. Manually added applications are visually distinguished from discovered apps with a clear badge, and you can filter by source to view only manual applications. #### Viewing Software Details Click an application row to open its detail page at `/software/$appId` (or `/software/v2/$appId`). The page shows the header (name, icon, status, monthly cost, detected logins, end of contract), overview (description, category, vendor, source, stakeholders), licenses table, users table, contracts, compliance certifications, custom fields, and activity history. ![Application detail page with Licenses and users](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-06c585d0a2781598345533755fbab8a20b341da9%2Fsoftware-detail.png?alt=media) #### Understanding Application Types Applications have a **category** (e.g., Communication, Productivity, Security) from your integration. Use the category filter in the list to narrow results. Applications also have a **source** (Okta, Microsoft Entra, NinjaOne, etc.) and **vendor**. #### Updating Software Status On the application detail page, use the status dropdown in the header to change status. In the list, select one or more applications and use **Change status** in the bulk actions toolbar. Available statuses: Discovered, Under review, Approved, Rejected, Ignored, Retired. #### Filtering Software by Status Use the filter popover to filter by status. By default, the view may show Discovered and Approved. Select one or more statuses; filters combine with AND logic. #### Searching for Software Use the **Search** input in the toolbar. Search matches application names. Results update as you type (debounced). Search is combined with active filters. #### Sorting Software Lists Click column headers to sort. Supported sort fields include total users, monthly cost, end of contract, application name, custom field columns, and others. Toggle between ascending and descending. #### Understanding Software Status | Status | Description | | ---------------- | -------------------------------- | | **Discovered** | Newly detected, not yet reviewed | | **Under review** | Pending approval decision | | **Approved** | Approved for use | | **Rejected** | Rejected for use | | **Ignored** | Excluded from tracking | | **Retired** | No longer in use | #### Application Insight Widgets A row of insight widgets appears at the top of the Applications, Instances, and Users pages, giving you an immediate summary of your SaaS portfolio's health. Available widgets include: * **Inactive Apps / Instances** - apps or instances with no logins from any user in the last 90 days (requires at least 1 week of data; partial-data periods are labelled accordingly) * **Shadow Apps** - apps detected on endpoints that have no corresponding identity provider login activity * Additional health and hygiene indicators surfaced automatically based on your connected data Click any widget to filter the list to the relevant applications, so you can act on problem areas without manual filtering. #### Live Application Health Status You can see real-time health status for applications directly in your app catalog, powered by each app's public status page. Harmony automatically monitors over 600 supported applications and surfaces their current operational state so your team can instantly spot outages, degraded services, or maintenance windows without leaving the platform. * **Color-coded health indicators** are displayed on each supported application: Operational (green), Under Maintenance (blue), Degraded Performance (yellow), Partial Outage (orange), and Major Outage (red) * **Status page URL** is available on each application's detail page for quick reference * **Filter by status** in the app catalog to quickly identify which applications are currently experiencing issues * No manual configuration is required - Harmony polls status pages automatically #### Multi-Instance App Visibility When an application has more than one instance - such as separate Production and Development environments - it expands into a detailed list showing each instance individually. For each instance you can see: * **Instance name and custom label** (e.g., "Slack Production" tagged as Production, or "Slack Development" tagged as Staging/Development/Test) * **Source identity provider** (Okta, Entra ID, etc.) and last sync date * **Login URL** specific to that instance * **User count** with a full breakdown available on the instance detail page The Instances page also includes insight widgets at the top, consistent with the Applications page. *** ### Managing Software Licenses #### Understanding Software Licenses Licenses track seat counts, cost, billing cycle, and renewal dates for an application. Add licenses on the application detail page to record contract information. Monthly cost is derived from active licenses. #### Adding Software Licenses 1. Open an application detail page. 2. In the **Licenses** section, click **Add license**. 3. Fill in: License type, Status, Seats (or Unlimited), Cost, Currency, Billing cycle, PO number (optional), Start date, Renewal date. ![Add license form with seats, cost, billing cycle](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-a5a4ed229c4c06d6206bb4b37a45f941c37a0a94%2Fadd-license-form.png?alt=media) 4. Click **Add license** or **Save**. #### Editing License Details In the Licenses table, use the row actions menu and select **Edit**. Update any field and save. You can also delete licenses from the row actions menu. #### Tracking License Expiration The **Renewal date** and **Start date** are stored per license. Use the Licenses table to see expiration. Licenses can have status Active, Expired, Suspended, or Cancelled. #### Viewing License Usage The Licenses table shows **Seats** as used/total (e.g., 45/50 or 45/Unlimited). Usage data comes from your integration when available. #### Understanding License Types License type is a custom label (e.g., Enterprise, Professional, Standard). Enter the type that matches your contract. Billing cycle options include Monthly, Quarterly, and Yearly. Seats can be a fixed number or **Unlimited**. *** ### Managing App Permissions and User Access #### Understanding App Permissions App permissions control who has access to an application. User access is managed through your identity provider (e.g., Okta). Harmony shows users per application and, for Okta test tenants, supports provisioning and revoking access via workflows. #### Assigning App Permissions to Users For Okta test tenants: On the application detail page, in the **Users** section, click **Add** to open the Assign App Permissions dialog. Select an employee and confirm. The "Provision Application Access" workflow provisions access for that user across Okta instances. Refresh the page to see the updated user list. #### Managing User Access to Applications User access is controlled in your IdP (Okta, Microsoft Entra). Harmony displays detected users and their roles. For Okta test tenants, you can provision new access or revoke existing access from the application detail page. #### Viewing Users Per Application The **Users** section on the application detail page lists employees with access to the application. Columns include name, email, role, source, department, last login, license tier, and a 90-day usage trend sparkline. Use the toolbar to search, filter by source, role, status, employment status, license tier, or insight, and export users. Usage trend sparklines render immediately for each user row, showing login activity over the past 90 days. Sorting by last login correctly places users who have never logged in at the bottom when sorting descending, and at the top when sorting ascending. #### Richer Usage Insights Per User Harmony automatically maps each user to a license tier (Paid, Free, or Unknown) based on data from your application inventory, sourced directly from the provider (e.g., Zoom's "licensed" or "basic" plan). You can filter and sort users by license tier to understand how seats are actually being used. #### Revoking Access For Okta test tenants: In the Users table, use the row actions menu and select **Revoke access**. Confirm the action. The "Revoke Application Access" workflow revokes access for that user. Refresh the page to see the updated list. *** ### Viewing Application Usage and Activity Trends #### Active Users and Usage Trends in the Application Overview The Application Overview surfaces the following usage breakdowns: * **Active users by application** - the total number of distinct active users across all instances of an application * **Active users by user in instance** - which individual users are active within a specific application instance * **Usage trend by application** - login activity over time across all instances of an application * **Usage trend by user in instance** - how individual users' activity has changed over time This data is available directly within the Application Overview without navigating to a separate report. #### Google SSO and SAML Login Data Harmony unifies login data across both Google SSO and Google SAML authentication methods. All login activity, user counts, and trends account for both authentication types, with users deduplicated so no one is counted twice. The login trend column in the application table reflects activity across both SAML and SSO. *** ### Managing Contracts for Applications #### Contracts Tab on Application Detail Pages Each application detail page includes a dedicated **Contracts** tab. From here you can create, view, and manage all contracts associated with that application. Contracts support a rich set of attributes including: * **Contract types** to categorize the nature of each agreement * **Contract status** to track where each contract is in its lifecycle * **Payment method** and **billing cycle** settings to reflect how and when payments are structured * **Line items** for detailed cost breakdowns * Additional structured fields with built-in validation Use the sortable, filterable, paginated contracts table to browse contracts. Filters and sort order are synced to the URL so your view persists when you share a link or return to the page. #### Cross-Application Contracts List A cross-application contracts view shows enriched contract data across your entire software portfolio in one place, making it easy to review agreements without opening each application individually. #### Renewal Management Tab Within the Contracts section, a dedicated **Renewal Management** tab gives you a complete view of upcoming software contract renewals and their associated costs. The tab includes: * **Summary Widgets** - aggregated annual spend broken down by category and by vendor, plus a count of total contracts split by auto-renewal vs. manual renewal * **12-Month Renewals Calendar** - a forward-looking calendar grouped by month, showing each month's renewal count and total value; expand any month to see individual contract details including contract name, vendor, and renewal date *** ### Managing Compliance Certifications On each application's overview page, you can view and manage compliance certifications. Harmony pre-populates compliance data using an AI scan of each vendor's official website, giving you a head start without manual entry. You have full control to add, edit, or delete records to reflect your organization's actual posture. Each compliance record supports: * **Framework** - standard certifications such as ISO 27001, SOC 2, GDPR, HIPAA, PCI DSS, and more, each with its own identifying icon * **Status** - Active or Expired, with color-coded card borders for quick visual identification *** ### Using Custom Fields for Applications #### Understanding Custom Fields You can add custom fields to applications to track any additional information that matters to your organization, keeping everything in one place. Custom fields for applications work the same way as they do for Employees and Assets. #### Managing Custom Fields on Application Detail Pages The application detail page includes a dedicated **Custom Fields** section where you can view, edit, add, and remove fields. Custom fields can be shared across all applications or specific to a single one. #### Custom Fields in the Applications Table Custom field columns appear alongside standard columns in the applications table, with full support for sorting and filtering - so you can slice your software inventory by any field you define. *** ### Viewing Application Activity History A dedicated activity history is available for every application from its detail view. Click the history or activity option to open a slide-out timeline panel showing every change made to the application. Each entry displays: * The exact UTC date and time of the change * The actor who made the change (a user, integration, or Harmony automation) * A plain-language summary of what happened * The old and new values where applicable The activity log tracks a wide range of change types including stakeholder additions and removals, status changes, field edits, contract updates, and more. *** ### Using Bulk Actions on Software #### Selecting Multiple Software Items In the Software list, use the checkboxes in the first column to select rows. Select individual applications or use the header checkbox to select all on the current page. Bulk actions apply only to the currently selected applications. #### Bulk Updating Software Status 1. Select one or more applications. 2. Use the **Change status** combobox in the bulk actions toolbar. 3. Choose a status (Discovered, Under review, Approved, Rejected, Ignored, Retired). 4. The update applies to all selected applications. #### Using Bulk Actions Toolbar The bulk actions toolbar appears when you have selected applications. Available actions: * **Change status** - Set application status for all selected apps. * **Set owner** - Assign application owner(s) to selected apps. Supports partial selection (applies to apps that don't already have the owner). * **Set budget approver** - Assign budget approver(s) to selected apps. * **Set IT approver** - Assign IT approver(s) to selected apps. ![Software bulk actions toolbar with Change status](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-2a8d18543cf36df3aa95bb682407c59f30eff4e1%2Fsoftware-bulk-actions.png?alt=media) *** ### Exporting Software Data #### Exporting Software to CSV Click **Export** in the Software toolbar. The export uses the current filters, search, and sort settings. A CSV file downloads with a name like `harmony-software-export-YYYY-MM-DD.csv`. Export includes all applications that match the filters. #### Exporting Application Users On an application detail page, in the **Users** section, click **Export** (the download button) in the toolbar. A CSV downloads with users for that application. The export uses your currently active filters - including search, role, status, employment status, license tier, and insight - and sort order. For instance-level pages, the exported filename includes the instance name for easy identification. #### Understanding Software Export Fields The software CSV includes columns such as Application Name, Status, Source, Connected Users, Licenses, Monthly Cost, Category, Vendor, Application owner, Budget approver, IT approver, and others. Column visibility and order from the table are respected. Extra fields include Application ID, Total Seats, Used Seats, and Contract End Date when available. Custom field columns are also included where applicable. #### Unauthorized Applications Report - Direct App Links The Unauthorized Applications report CSV includes a **Link** column on each row. Clicking the link takes you directly to that application's page in your Harmony portal, replacing the previous workflow of copying an app name and searching for it manually. #### Filtering Software for Export Apply filters before exporting to limit which applications are included. Supported export filters: search, status, source, category, vendor. Sort order is also applied to the export. *** ### NinjaOne Application Data Software and application data from NinjaOne is now fully supported as an application source in Harmony. Installed apps across your NinjaOne-managed devices are ingested, processed, and available in your application inventory alongside data from other MDM integrations. NinjaOne appears as a selectable source in filters, the same as other supported providers. *** ### Software Catalog Quality and Coverage Harmony's software catalog is continuously improved to give you a cleaner, more accurate picture of the applications in use across your organization: * **Expanded vendor coverage** - the catalog includes a broader set of recognized applications, vendor entries, and application icons, so more of the tools your team uses are automatically identified with accurate vendor attribution and up-to-date branding * **Improved catalog matching** - approximately 70 low-quality entries (test apps, demo submissions, browser extensions, personal/consumer websites, and garbled display names) have been removed, and around 150 duplicate and variant entries for major vendors - including Adobe, Okta, Atlassian, Microsoft, Google, and others - have been consolidated * **Contract continuity** - contracts associated with an application are correctly carried over when catalog entries are updated or reassigned, ensuring your contract data stays linked to the right application at all times *** ### Related Resources
Managing PeopleView employees and their assigned softwarehttps://github.com/harmonyso/public-docs/tree/main/guides/managing-people/README.md
Asset Views & DetailsView software on assets and related applicationshttps://github.com/harmonyso/public-docs/tree/main/guides/managing-asset-views-and-details/README.md
Asset & Automation MetricsAnalyze software and automation metricshttps://github.com/harmonyso/public-docs/tree/main/guides/analyzing-asset-and-automation-metrics/README.md
# Managing Contracts The Contracts feature in Harmony's Software Management module lets you create, track, and manage vendor contracts directly alongside the applications they support. From capturing pricing details and renewal dates to monitoring spend across your portfolio, everything you need to stay on top of your software commitments is available in one place. This article explains how contracts work, how to create and manage them, and how to get the most out of the visibility and automation features built into the experience. *** ### What You Can Track on a Contract Each contract you create can capture a comprehensive set of details: **Core contract details:** * Contract name, vendor name, plan type, and status (Active, Pending, Expired, Renewed, or Cancelled) * Lifecycle dates: start date, end date, auto-renewal toggle, cancellation notice period, and an auto-calculated renewal date **Flexible pricing models to match how you are billed:** * **Seat-based** - seat count (or unlimited seats), cost per seat, and billing frequency * **Flat fee** - a fixed recurring or one-time cost * **Usage-based** - variable costs tied to consumption * **Custom** - any other structure that does not fit standard models **Contract line items:** * Individual line items representing each component of a contract (for example, separate modules, add-ons, or user tiers) * Each line item can be linked to a specific application so it appears on that application's Contracts tab *** ### Contract Value Auto-Calculation You do not need to manually tally up line items to determine a contract's total value. Harmony can derive the contract value automatically: * **On contract creation** - if you provide line items but leave the contract value blank, the total value and currency are calculated automatically from those items. * **Manual override** - if you explicitly enter a contract value during creation, that value and currency are preserved exactly as entered. * **Empty contracts** - if no line items exist, the contract value remains whatever you provided, or defaults to 0. * **Live recalculation** - as you add, edit, or remove line items after creation, the contract value updates automatically to reflect the current sum. This keeps your contract totals accurate without requiring manual updates every time something changes. *** ### Creating Contracts #### Single Contract Creation To create a contract, navigate to the Contracts page within Software Management and use the creation form. Fill in the core details, select a pricing model, and add any relevant line items. If you want the contract to be visible on a specific application's Contracts tab, make sure each line item is linked to the appropriate application. #### Bulk Contract Creation When you need to set up contracts across a large number of applications at once, you can create multiple contracts in a single action rather than repeating the process one at a time. This significantly reduces setup time when onboarding a large software portfolio. #### Draft Contracts Before publishing a contract, you can save it as a **Draft**. This lets you build out contract details incrementally, review them with your team, and correct any issues before the contract becomes active in your records. When you are ready to publish, validation checks run automatically to catch any incomplete or incorrect data before the contract goes live. This reduces the risk of publishing contracts with missing information. *** ### Managing Contract Status You have full manual control over the status of any contract. From the contract detail page, you can set a contract to any of the following statuses: | Status | When to Use | | ------------- | ------------------------------------------------------- | | **Active** | The contract is currently in effect | | **Pending** | The contract has been agreed but has not yet started | | **Expired** | The contract term has ended | | **Cancelled** | The contract was terminated before its end date | | **Draft** | The contract is being prepared and is not yet published | | **Renewed** | The contract has been rolled over into a new term | Previously, statuses like Expired and Pending were computed automatically and could not be changed. You can now explicitly set any status to reflect real-world situations such as early terminations, data corrections, or bulk imports where computed states would not be accurate. Auto-renewing contracts display a dedicated **renewal date** column in the contracts table, so it is always clear when each contract is due to roll over. *** ### Spotting Unlinked Contract Line Items Linking a line item to an application is what makes a contract visible in that application's Contracts tab. If a line item is not linked, it will not appear in any application view. To help you keep everything connected, Harmony flags unlinked line items with clear visual indicators: * An **amber warning icon** with a "No related application" tooltip appears next to unlinked items in the contracts table and the renewal management table. * In the add/edit contract item modal, unlinked items are highlighted with an **amber border** and a "No related application" label. When you see these indicators, edit the line item and link it to the appropriate application to ensure it surfaces in the right place. *** ### Contract Insight Widgets At the top of the Contracts page and within individual application Overview tabs, a row of insight widgets gives you an at-a-glance summary of your contract landscape without requiring you to manually scan the table. The following widgets are available: * **Annual Cost** - displays the total annual contract cost across the Contracts page, or scoped to a single application when viewed in that application's Overview tab. * **Active Contracts** - shows the count of contracts currently in an Active status. Clicking this widget filters the table to show only active contracts. * **Upcoming Renewals** - visible on the Contracts page, this widget highlights contracts approaching their renewal dates so you can take action before they auto-renew or expire. These widgets update dynamically as your contract data changes. *** ### Viewing Contracts Per Application Every application in the Software Management module has a dedicated **Contracts** tab. This tab shows all contracts that have at least one line item linked to that application, giving you a focused view of the commitments associated with each tool. The application's Overview tab also includes the Annual Cost and Active Contracts widgets so you can assess spend at a glance without switching to the full Contracts page. *** ### Tips for Getting the Most Out of Contracts * **Link every line item to an application** - unlinked items will not appear in application views and are flagged with amber indicators. Resolve these promptly to keep your data complete. * **Use Draft status during bulk imports** - when importing a large number of contracts, save them as drafts first so you can review and validate before publishing. * **Let auto-calculation handle totals** - avoid manually entering contract values when you have line items. Allow Harmony to calculate the total so it stays in sync as items change. * **Set status manually when needed** - if a contract was terminated early or imported with an incorrect state, update the status directly from the contract detail page rather than waiting for automatic transitions. # Building and Managing Workflows Learn how to build custom agents with triggers, actions, and conditional logic; use template variables; and test and publish agents. {% hint style="info" %} **Path:** `/agents` {% endhint %} ### Understanding Agents and Automation Custom agents let you automate work that runs based on triggers (manual, scheduled, events, or inbound webhooks) and execute a sequence of steps. Agents can integrate with Slack, Teams, Okta, HRIS systems, MDM tools, ServiceNow, GitHub, Jira, and Harmony itself. #### Understanding the Agent Builder The Agent Builder is a visual editor where you design agents by adding nodes and connecting them. Open **Agents** from the sidebar, then create a new agent or open an existing one. The builder shows a canvas with a trigger node at the top and action/logic nodes below. #### Understanding the Canvas The canvas is a drag-and-drop area where steps are laid out. Nodes connect via edges (lines). Use the zoom controls (bottom-left) to zoom and pan. Right-click on the canvas or on nodes to open context menus. Use Shift+drag to select multiple nodes. The canvas snaps nodes to a grid. The canvas clips cleanly to rounded corners that match the surrounding content card, so the builder looks consistent throughout. #### Navigating the Agents List Open **Agents** at `/agents` to see all custom agents. Each card shows the agent name, description, enabled state, and toggle. Click an agent to edit it. Click **Build custom agent** to start a new one (when the Agent Builder feature is enabled). #### Creating Your First Agent 1. Click **Build custom agent** on the Agents page. 2. You're taken to the builder with a default **Manual** trigger. 3. Click the **+** handle below the trigger (or drag from it) to add a step. 4. Choose an action (e.g., Slack, Okta, Harmony) and an operation. 5. Configure the step in the Properties panel. 6. Add more steps as needed. 7. Save and enable the agent. *** ### Building Agents #### Adding Steps * **From the trigger:** Click the **+** handle at the bottom of the trigger node, or drag from it. A step selector appears; pick a category (Slack, Okta, Harmony, etc.) and an operation. * **From an existing step:** Drag from the output handle of a step to create a connection. Drop on the canvas to add a new step, or drop on another step's input handle to connect. * **Context menu:** Right-click the canvas to add a step at that position. #### Connecting Steps Drag from a step's output handle (bottom) to another step's input handle (top) to connect them. Connections define execution order. You can insert a new step into an existing connection by dropping the new step onto the edge. #### Understanding Node Types | Type | Description | | ----------- | ----------------------------------------------------------------------------------------------------------- | | **Trigger** | Starts the agent. One per agent. Types: Manual, Scheduled, Event, Webhook. | | **Action** | Performs an operation (Slack message, Okta request, create ticket, etc.). | | **Logic** | Condition (if/else), Sleep (wait), or For Each (iterate over a list). Branches, delays, or loops execution. | *** ### Understanding Agent Triggers #### Using Manual Triggers The default trigger. The agent runs only when executed manually (from the toolbar **Run** button). You can define agent inputs (e.g., employee ID, ticket ID) that users provide when running. #### Using Scheduled Triggers Runs the agent on a schedule. In the trigger configuration, select **Scheduled** and set: * **Cron expression** - Standard cron format (e.g., `0 9 * * 1-5` for 9:00 AM weekdays). * **Timezone** - Timezone for the schedule (e.g., America/New\_York). #### Using Event Triggers Runs when a specific event occurs. Select **Event** and choose an event type: | Event | Description | | ------------------------- | ------------------------------------- | | **Ticket Created** | When a new ticket is created. | | **Ticket Assigned** | When a ticket is assigned to someone. | | **Ticket Status Changed** | When a ticket's status changes. | | **Ticket Resolved** | When a ticket is marked as resolved. | When you select an event trigger, the condition builder shows a dropdown of valid fields specific to that event type. Typing `{{ trigger.` in any step input surfaces an autocomplete list of available fields, so you always know exactly which fields are available without guessing. Available fields by event type: * **Ticket Created** - ticket ID, title, priority, status, reporter, and desk * **Ticket Status Changed** - fields reflecting the previous and new status, plus ticket metadata #### Using Webhook Triggers Runs when an external system sends an HTTP request to a unique webhook URL generated for the agent. When you save an agent with a webhook trigger, the URL is created automatically and is ready to use immediately. The full request body is passed into your agent as `{{ trigger.* }}` data, so every field sent by the external system is available in downstream steps. **Authentication options:** | Method | Description | | -------------------- | ---------------------------------------------------- | | **API key (header)** | Include a pre-shared key in a request header. | | **HMAC signature** | Validate request authenticity using a shared secret. | | **Bearer token** | Standard Authorization header with a bearer token. | You can retrieve the webhook URL at any time using `GET /workflows/{id}/webhook-url`. #### Configuring Trigger Conditions For event triggers, you can add conditions to filter when the agent runs (e.g., only for certain desks, statuses, or types). Use the conditions section in the trigger configuration. *** ### Using Agent Actions #### Understanding Action Blocks Action blocks are steps that call an external system or Harmony. Each block has a schema-driven configuration form with inputs. Many inputs support template variables to pass data from previous steps or the trigger. Integration identifiers are surfaced on blocks so you can precisely target the right connection, and the integration selector dropdown shows the friendly name you assigned to each integration rather than internal system identifiers. #### Integration Actions | Category | Examples | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Slack** | Send message, update message, add/remove reaction, get thread replies. | | **Microsoft Teams** | Send message, update message, get thread replies. | | **Okta** | Get user, list groups, add/remove user from group, reset password, provision access, terminate sessions, deactivate user, unlock user, retrieve recovery email, add/remove users from groups. | | **HiBob** | Get/create/update employee, list departments/jobs/employees. | | **Workday** | Get/create/update employee, list departments/jobs/employees. | | **BambooHR** | Get/create/update employee, list departments/jobs/employees. | | **ServiceNow** | Run Flow, Create Ticket (incident/request), Create Service Request, discover available flows. | | **GitHub** | Search users, retrieve SAML identities, list org teams and repo collaborators, add/remove team members. | | **Jira / JSM** | Look up issues, manage projects and service management requests. | #### HTTP Actions Use the **HTTP** block to make HTTP requests to any API. Configure URL, method, headers, and body. Supports template variables in the request. #### MDM Actions | MDM | Examples | | ---------- | ----------------------------------------- | | **Kandji** | Get device, list devices, custom request. | | **Jamf** | Get device, list devices, custom request. | | **Intune** | Get device, list devices, custom request. | #### Identity Provider Actions | IdP | Examples | | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Okta** | Get user, list groups, add/remove users from groups (accepts a list of employee IDs), unlock user, terminate sessions, retrieve recovery email, reset password, deactivate user. | | **Microsoft Entra** | Get user, list groups, add/remove users from groups, reset password, terminate sessions, deactivate user, unlock user, retrieve recovery email. | | **Google Workspace** | Get user, list groups, add/remove users from groups, terminate sessions, unlock user, retrieve recovery email, custom request. | | **JumpCloud** | List groups, add/remove users from groups, reset password, deactivate user, unlock user, terminate sessions, custom request. | | **Active Directory (on-premises)** | Unlock user accounts and additional identity management operations. | Group membership actions accept a list of employee IDs so you can add or remove multiple users in a single step. The action formerly called "Add to Groups" is now named **Add Users to Groups**. #### AI Actions Use the **AI** block to analyze content or generate responses. Useful for automated triage, summarization, or classification. #### OTP Verification Actions Use the **OTP Verification** blocks to add secure one-time password identity checks to your agents. The flow is handled end-to-end: a code is generated, delivered to the employee by email, and they are prompted to submit it via a Slack or Microsoft Teams form - all within the agent itself. Sensitive values such as OTP codes and temporary passwords are encrypted at rest and are never exposed in plain text in run history, API responses, or step outputs. #### Harmony Actions | Action | Description | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | **Approval** | Pause for human approval before continuing. | | **Create Ticket** | Create a Harmony ticket. | | **Get/Update Ticket** | Fetch or update a ticket. | | **List Tickets** | List tickets with filters. | | **Get Employee** | Fetch employee data by ID or email address. | | **List Employees** | List employees, with filters for VIP status, employment status, location, and employment start date range (all applied server-side). | | **Get Devices** | Fetch devices for an employee. | | **Update Device** | Update device attributes. | | **Update Asset** | Update asset attributes, including setting a manual sale price. | | **List/Get Application** | Fetch application data. | | **Get Employee Applications** | List apps for an employee. | | **Send Email** | Send an email. | | **Resolve Approver** | Resolve who should approve. | | **Resolve Identity Provider** | Resolve IdP for an employee. | | **Generate CSV Report** | Generate a CSV report. | **Looking Up Employees** The **Get Employee** block supports two lookup methods - by employee ID or by email address. Both methods return the same employee data and work seamlessly with downstream steps. **Filtering Employee Lists** The **List Employees** block supports server-side filtering by: * VIP status * Employment status * Location * Employment start date range **Setting Asset Sale Prices** In the **Update Asset** block, add a **Manual Sale Price** value to save a price directly to the asset's purchase details. Only the price fields are updated - no other purchase details (such as ABM-sourced data) are overwritten. *** ### Using Conditional Logic #### Using Conditional Logic (If/Else) Add a **Condition** block from the Logic category. Configure a condition; the agent branches to different paths based on whether the condition is true or false. Connect follow-up steps to the "true" or "false" output handles. #### Setting Up Conditions In the Condition block form, select a field (from trigger or prior steps), an operator (equals, contains, greater than, etc.), and a value. You can add multiple conditions and choose whether all or any must match. #### Understanding Field Operators Common operators: equals, not equals, contains, not contains, starts with, ends with, greater than, less than, is empty, is not empty. The available operators depend on the field type. #### Building Complex Conditions Combine multiple conditions with AND/OR. Use nested Condition blocks for complex branching. *** ### Using Logic Blocks #### Pausing an Agent with the Sleep Block Add a **Sleep** block from the Logic category to pause the agent for a precise amount of time before continuing to the next step. The timer is fully durable - it survives server restarts and continues reliably even across multi-day waits without consuming processing resources. **Duration options:** * Specify the wait in minutes, hours, or days - or combine all three for an additive total (e.g., 1 day + 2 hours + 30 minutes). * Use a template expression for dynamic durations (e.g., `{{ config.jit_duration_minutes }}`), so wait times can vary based on agent data. #### Iterating Over Lists with the For Each Block Add a **For Each** block to iterate over a list and execute a set of steps for each item. This is useful for bulk actions such as notifying a list of employees, processing multiple tickets, or enriching a set of records. Key configuration options: | Option | Description | | ---------------------------- | ----------------------------------------------------------------------------------------------------------- | | **`items`** | The list to iterate over, specified as a dynamic expression (e.g., `{{ steps.list_employees.employees }}`). | | **`max_parallel`** | How many items are processed at the same time. Default: 5, maximum: 20. | | **`continue_on_item_error`** | Whether a failure on one item stops the entire loop or allows remaining items to continue. | *** ### Working with Variables and Templates #### Using Template Variables Reference data from the trigger or previous steps using `{{ ... }}` syntax: * **Agent inputs:** `{{ input.employee_id }}` (manual trigger inputs) * **Trigger event data:** `{{ trigger.ticket_id }}` (event triggers) * **Webhook data:** `{{ trigger.* }}` (any field from the webhook request body) * **Step outputs:** `{{ steps.step_id.output_field }}` (outputs from prior steps) #### Understanding Available Variables Variables depend on the current node's position. Only inputs and outputs from steps that run before the current node are available. The Template Picker and Token Input show available variables with autocomplete. #### Inserting Variables in Actions In action block fields that support templates, type `{{` to open the template picker, or click the variable button. Select a variable to insert it into the field. #### Using the Template Picker The Template Picker modal shows a tree of available variables grouped by source (inputs, trigger, steps). Expand nodes to find the path, then insert it into your field. #### Working with Token Inputs Fields that support templates use a Token Input. It shows inserted variables as tokens. Click a token to edit or remove it. Type to search available variables. #### Understanding Token Autocomplete When typing `{{` in a token input, autocomplete suggests variables. Variables are filtered by the current node's context (preceding steps and trigger). When typing `{{ trigger.` in any step input, autocomplete surfaces the specific fields available for the selected trigger event type. *** ### Managing and Testing Agents #### Editing Existing Agents Open an agent from the Agents list. The builder loads the agent. Make changes to nodes, connections, or configuration. Save to persist. Unsaved changes are indicated in the toolbar. #### Testing Agent Steps Select an action node and click **Test this step** (or the play icon on the node). The Execute Step modal opens. Provide test values for required inputs and run the step in isolation - without running the full agent. Inputs are validated against the block's schema before execution, so you get a clear error immediately if something is misconfigured. View the output to verify the step works before running the full agent. #### Re-executing Failed Steps From a run's detail view, you can re-run a specific failed step using its original inputs or modified ones. This means you can fix a misconfiguration and retry just that step without replaying the entire agent. #### Executing Agents Click **Run** in the toolbar to execute the agent. For manual triggers, provide any required inputs in the dialog. The agent runs and the Runs drawer opens with the run result. #### Viewing Agent Run History Click the **Runs** (History) button in the toolbar to open the Runs drawer. It lists recent runs with status, duration, and timestamps. Click a run to expand and see step-by-step execution. #### Understanding Agent Run Details Each run shows: Run ID, status (running, completed, failed), duration, and step list. Expand a step to see its input, output, and any error. Completed steps show green; failed steps show red with the error message. Sensitive values such as OTP codes are never exposed in plain text in run history or step outputs. #### Viewing Step Execution Results In the Runs drawer, expand a run and a step to see Input (JSON sent to the step), Output (JSON returned), and Error (if the step failed). #### Understanding Agent Errors When a step fails, the error message appears in the step details. Common causes: invalid inputs, integration misconfiguration, API rate limits, or missing permissions. Use the error message and step input/output to troubleshoot. #### Troubleshooting Failed Steps 1. Check the error message in the step details. 2. Verify inputs (templates resolve correctly, required fields are set). 3. Confirm the integration is connected and has the right scopes. 4. Use **Test this step** to test the step in isolation with sample data. 5. From the run detail view, re-run the failed step with corrected inputs. #### Monitoring Agent Health Harmony automatically monitors the health of your agents and detects when a dependency an agent relies on becomes unavailable. When a desk, sub-desk, or employee referenced by an agent is deleted or terminated, that agent is instantly marked as **degraded** with a reason and timestamp - so broken agents surface immediately rather than silently failing when triggered. You can retrieve an agent's current health status at any time using `GET /workflows/{id}/health`. The response includes the status (`healthy` or `degraded`) and, when degraded, the reason and the time it was detected. #### Getting Notified on Agent Failures Each agent can be configured with its own failure notification target. When a step fails, Harmony sends an alert immediately to your chosen destination. Notifications include: * The agent name and the specific step that failed * The error message with full context * A direct link to the failed run so you can jump straight into debugging Supported notification targets: Slack channels, Slack DMs, Microsoft Teams channels, and Teams direct messages. Configure the notification target in the agent **Settings** drawer. #### Managing Agent Versions You can add a human-readable description to each agent version to track what changed. When saving or updating a version, include a short note - for example, "Fixed approval timeout from 48h to 72h" or "Added JIT support." * Descriptions appear alongside the version number, timestamp, and author in the version history list. * You can set or update a description at any time after a version is created. * Descriptions are optional; versions without one still appear in the history list. #### Duplicating Agents Duplicate an existing agent via the API using `POST /workflows/{id}/duplicate`. The copy is a fully independent agent - editing the duplicate never affects the original. The duplicate includes all steps, triggers, configuration schema, error handling, metadata (icon, tags), and branch logic. You can supply an optional `name` in the request body; if omitted, the copy is named "{original name} (copy)". The duplicate starts at version `1.0.0` and is created in a disabled state. #### Bulk Deleting Agents Delete multiple agents in a single API call using `POST /workflows/bulk-delete`. Pass an array of up to 50 agent IDs. All in-flight runs are cancelled and related signals, trigger subscriptions, and event waits are removed for each deleted agent. If one or more agent IDs fail to delete, the response includes details of which deletions succeeded and which failed so you can handle partial failures gracefully. #### Deleting Agents Open the agent **Settings** drawer (gear icon) and scroll to the **Danger zone**. Click **Delete Agent** and confirm. The agent is permanently removed. *** ### Using the Agent Toolbar and Properties #### Using the Agent Toolbar The toolbar at the top includes: * **Back** - Return to the Agents list. * **Agent name** - Click to edit. Click the emoji to change the agent icon. * **Undo/Redo** - Revert or reapply edits. * **Run** - Execute the agent. * **Runs** - Open the run history drawer. * **Save** - Save the agent. * **Settings** - Open agent settings (name, description, error notifications, delete). * **Enabled** - Toggle agent on/off (publish/unpublish). * **AI** - Open the AI agent builder. # Workflow Events and Webhooks Harmony can notify your external systems in real time whenever important things happen inside a workflow - requests being created or updated, messages being sent, and more. These notifications are delivered as **workflow events** and can be forwarded to any endpoint you control via **webhooks**. This article explains the event types available, the data each event carries, and how to use that data to build reliable, precise integrations. *** ### How Workflow Events and Webhooks Work When activity occurs in Harmony - such as a new request being opened or a message being sent - Harmony emits a structured event. If you have a webhook configured, Harmony sends an HTTP POST request containing the event payload to your specified endpoint. This lets your downstream systems react immediately without polling the API, making it straightforward to: * Sync request data to your CRM or helpdesk * Trigger automations in third-party tools * Build audit logs and reporting pipelines * Filter and route activity based on context *** ### Configuring Webhooks To receive events, you need to register a webhook endpoint in your Harmony workspace settings. 1. Go to **Settings** and open the **Integrations** section. 2. Select **Webhooks** and click **Add Webhook**. 3. Enter the destination URL for your endpoint. 4. Choose the event types you want to subscribe to. 5. Save your configuration. Harmony will begin delivering events to your endpoint immediately. Each delivery is an HTTP POST request with a JSON body and a `Content-Type: application/json` header. *** ### Event Types #### Request Lifecycle Events Request lifecycle events fire when a request is created or updated. These are the primary events for tracking the state of work moving through your workflows. **`RequestCreated`** Emitted when a new request is opened. The payload includes full request metadata so your systems can immediately index or act on the new request. **`RequestUpdated`** Emitted whenever a request is modified - for example when its status changes, it is assigned to an agent, or it is resolved. **Resolution Details on Request Events** Both `RequestCreated` and `RequestUpdated` events now include two additional fields that tell your downstream systems how a request was resolved, without requiring any follow-up API calls: | Field | Type | Description | | --------------- | ----------------- | ---------------------------------------------------------------------------------------------- | | `resolution` | string or null | How the request was resolved - for example `escalated`, `handled_by_ai`, or `closed_by_agent`. | | `resolution_at` | timestamp or null | The date and time at which the resolution was determined. | Both fields are **optional** and default to `null` when no resolution has been recorded yet. This means the change is fully backward-compatible - your existing integrations will continue to work without any modification. **Example payload fragment:** ```json { "event": "RequestUpdated", "request_id": "req_01abc123", "status": "resolved", "resolution": "handled_by_ai", "resolution_at": "2024-06-10T14:32:00Z" } ``` When a request has not yet been resolved, these fields appear as: ```json { "resolution": null, "resolution_at": null } ``` *** #### Message Events **`MessageCreated`** Emitted whenever a new message is added to a request conversation. This event is useful for building notification systems, logging conversation history, or triggering follow-up automations based on message content. **Source Attribution with `event_source`** The `MessageCreated` event includes an `event_source` field that tells you exactly where the message originated. This gives you the context you need to build more precise filtering and automation logic. | Value | Description | | ---------- | --------------------------------------------------- | | `customer` | The message was sent by the end user or customer. | | `agent` | The message was sent by a human agent. | | `workflow` | The message was generated by an automated workflow. | **Example payload fragment:** ```json { "event": "MessageCreated", "request_id": "req_01abc123", "message_id": "msg_09xyz789", "body": "Thanks for reaching out, I'll look into this now.", "event_source": "agent", "created_at": "2024-06-10T14:33:00Z" } ``` You can use `event_source` to, for example: * Only forward customer messages to your CRM * Trigger a satisfaction survey only after an agent closes a conversation * Skip logging automated workflow messages in your audit trail *** ### Payload Structure Every event payload shares a common envelope, regardless of event type: | Field | Type | Description | | ------------ | --------- | --------------------------------------------- | | `event` | string | The name of the event, e.g. `RequestCreated`. | | `created_at` | timestamp | When the event was emitted. | | `request_id` | string | The unique identifier of the related request. | Event-specific fields are included alongside these common fields in the same flat JSON object. *** ### Reliability and Retries Harmony expects your endpoint to respond with an HTTP `2xx` status code to acknowledge successful receipt. If your endpoint returns a non-`2xx` response or does not respond within the timeout window, Harmony will retry delivery using an exponential back-off strategy. To avoid processing duplicate events during retries, design your endpoint to be idempotent - that is, handling the same event more than once should produce the same result as handling it once. *** ### Backward Compatibility Harmony follows an additive-only policy for event payloads. This means: * New fields may be added to any event at any time. * Existing fields will not be removed or renamed without advance notice. * Optional fields default to `null` when not applicable, so your integration is never broken by their absence. You should write your event consumers to **ignore unknown fields** rather than treating them as errors. This keeps your integrations resilient as new capabilities are introduced. # Workflow Health Status and Alerts Harmony automatically monitors the resources that each agent depends on and alerts you when something breaks. If a dataset, desk, catalog item, approver employee, or any other linked resource is deleted or an approver is terminated, the affected agent is immediately flagged as unhealthy - so you can find and fix problems before they prevent an agent from running correctly. This article explains how health statuses work, what triggers an unhealthy state, and where to find health information in the UI and activity log. *** ### How Agent Health Monitoring Works Every agent in Harmony can depend on one or more external resources, such as: * **Datasets** - used to source or route work * **Desks** - used to assign tasks to a team or queue * **Catalog items** - referenced as part of an agent step * **Approver employees** - designated to review or approve work items Harmony continuously checks whether these resources are still available and valid. When all dependencies are intact, the agent has a **Healthy** status. When one or more dependencies are broken, the agent is marked as **Unhealthy**. This monitoring runs automatically - you do not need to configure it or turn it on. *** ### What Triggers an Unhealthy Status An agent is marked unhealthy when any of the following occurs: | Cause | Example | | ---------------------------------- | ------------------------------------------------------ | | A linked dataset is deleted | The dataset feeding an agent step no longer exists | | A linked desk is deleted | The desk assigned to receive tasks has been removed | | A catalog item is deleted | A step references a catalog item that no longer exists | | An approver employee is terminated | A designated approver is no longer an active employee | Any one of these conditions is enough to flag the agent as unhealthy, even if all other dependencies are intact. *** ### Viewing Health Status in the UI Agents with broken dependencies are clearly marked in the agent list and agent detail views with a health indicator. The indicator shows: * **What is wrong** - the type of dependency that is broken * **Which resource is affected** - the specific dataset, desk, catalog item, or employee that caused the issue This lets you immediately understand the problem without having to investigate each step manually. #### Finding Unhealthy Agents 1. Navigate to **Agents** in the main menu. 2. Look for agents marked with the unhealthy indicator in the list. 3. Select an agent to open its detail view and see the full breakdown of which dependency is broken. *** ### Agent Activity Log and Audit Trail Every health status change is recorded in the agent's activity log. This gives you a full audit trail that includes: * When the agent became unhealthy * Which resource change triggered the status update * When the agent was restored to a healthy state (after the issue is resolved) To view the activity log, open the agent detail view and go to the **Activity** tab. You can use this log to understand the history of any health changes and demonstrate compliance or investigate disruptions. *** ### Resolving an Unhealthy Agent To restore an agent to a healthy state, you need to address the broken dependency. Depending on the cause, this may involve: * **Replacing a deleted resource** - assign a new dataset, desk, or catalog item to the affected agent step * **Updating an approver** - replace a terminated employee with an active approver in the agent configuration Once the broken dependency is resolved and all required resources are valid again, the agent health status returns to **Healthy** and the change is recorded in the activity log. *** ### Summary | Status | Meaning | | ------------- | ----------------------------------------------------------------------- | | **Healthy** | All dependencies are intact and the agent can run correctly | | **Unhealthy** | One or more dependencies are broken and the agent may not run correctly | Agent health monitoring is always on, requires no setup, and ensures that broken dependencies are surfaced immediately - so your team can act quickly and keep agents running without interruption. # Data Sets Learn how to create and manage Data Sets in Harmony, structured tables used to store and reuse data across agents, service catalog forms, and Slack integrations. {% hint style="info" %} **Path:** Settings → Data Sets {% endhint %} ### What are Data Sets? Data Sets are structured tables that let you store and manage rows of data directly in Harmony. Think of them as spreadsheets built into the platform. Each Data Set has typed columns you define and rows you populate, either manually or through agents. Once created, a Data Set can be used across Harmony: * **Agents** can query, insert, update, delete, and bulk upsert rows as part of automation steps. * **Service catalog forms** can pull a dataset's rows to populate dropdown options dynamically. * **Slack modals** can surface dataset rows as searchable select options for employees. * **Custom fields** on assets, employees, and applications can reference dataset values through data set selector fields. * **Custom Agents** can reference datasets to bring structured business data into agents. *** ### Managing Data Sets Data Sets are managed from **Settings → Data Sets**. From this page you can create new datasets, view existing ones, and open any dataset to manage its columns and rows. #### Creating a Data Set 1. Go to **Settings → Data Sets** and click **New Data Set**. 2. Enter a **name** (must be unique) and an optional **description**. 3. Add columns to define the structure (see [Managing Columns](#managing-columns) below). 4. Click **Save** to create the dataset. #### Managing Columns Each column has a **name**, a **type**, and optional settings for whether it is required and whether it has a default value. | Column type | What it stores | | ----------- | --------------------------------- | | Text | Any string value | | Number | Numeric values | | Boolean | True / False | | Date | Date values | | Email | Email addresses | | URL | Web links | | Employee | A reference to a Harmony employee | You can add, rename, and reorder columns at any time. Deleting a column hides it from view but does not erase the data already stored in existing rows. This keeps historical records intact. #### Managing Rows Open a Data Set to view and edit its rows in a table view. You can: * **Add rows** manually by clicking **Add Row** and filling in the fields. * **Edit rows** inline by clicking a cell. * **Delete rows** individually using the row menu. * **Import rows** in bulk by uploading a CSV file (up to 1,000 rows at a time). #### Display Column Each Data Set has a **display column**: the column whose value is shown as the human-readable label when the dataset is used in a dropdown (e.g. in a Slack modal, service catalog form, or data set selector custom field). You can set this in the dataset settings. If no display column is set, Harmony defaults to the first column in the table. When a data set selector custom field is configured, you can also override the display column at the field level, so different uses of the same dataset can surface the most meaningful label for their context. *** ### Using Data Sets in Agents The agent block library includes blocks for interacting with Data Sets. Find them under the **Data Sets** category when adding a step to your agent. #### Query Data Set Looks up rows from a dataset based on filters you define. Use this to retrieve data during a run, for example, finding the approver for a given department. * Configure filters using any column (e.g. "department equals Engineering") * Combine multiple filters with **All** (AND) or **Any** (OR) logic * Set a limit on how many rows to return (up to 100; defaults to 1) * The block outputs the matching rows and a `first_row` shortcut for single-lookup cases #### Insert Data Set Adds a new row to a dataset. Use this to write data from a run, for example, logging a completed action or recording a form submission. * Map agent values to dataset columns * The block outputs the newly created row #### Update Data Set Updates all rows that match a set of filters. Use this to keep dataset records in sync, for example, marking an employee's status as inactive after offboarding. * Define filters to target the right rows * Provide the new values to write * The block reports how many rows were updated and surfaces any errors #### Delete Data Set Deletes all rows that match a set of filters. * Define filters to target the rows to remove * Optionally cap the number of rows deleted * The block reports how many rows were deleted #### Bulk Upsert Data Set Inserts or updates multiple dataset records in a single agent step. Use this when you need to keep a dataset in sync as part of an automated process that handles batches of records - for example, syncing a list of tickets, contacts, or any other structured data your agents rely on. * Define the column to match on when deciding whether to insert or update each record * Map agent values to dataset columns for each record in the batch * Removes the need to chain individual insert or update steps together, making bulk operations significantly faster to build and maintain *** ### Using Data Sets in Service Catalog Forms When building a service catalog form, you can configure a dropdown field to pull its options directly from a Data Set. The form will always show the current rows in the dataset, so you can update the available choices at any time without editing the form itself. The value shown in each dropdown option comes from the dataset's **display column**. #### Cascading Filters on Data Set Selector Fields You can configure cascading filters on data set selector fields in the Service Catalog form builder. This means the options shown in a data set dropdown can be automatically narrowed down based on the value a user selects in another field on the same form - keeping choices relevant and reducing noise. You can add multiple cascading filter rules to a single field. All active filters are applied simultaneously using AND logic, so only options that satisfy every rule are shown. Each filter rule includes the following settings: * **Filter column**: choose which column in the dataset to filter on * **Source field**: select another form field whose runtime value drives the filter * **Match operator**: choose between *equals* or *contains* to control how the comparison is made You can add and remove filter rules freely. Filtering is applied automatically when the form is rendered, with no additional configuration needed beyond defining the rules. *** ### Using Data Sets in Slack When an agent presents a select menu in a Slack modal, you can point it at a Data Set to populate the options. Employees can type to search through the options live. Up to 100 options are shown at a time. The label for each option in the list comes from the dataset's **display column**. You can also use a **data set selector** field in Service Catalog form modals presented directly in Slack. When filling out a catalog form in Slack, users can search and select from dataset rows using a typeahead-backed dropdown without leaving the conversation. This gives catalog form builders a consistent, searchable experience for both data set selector and asset selector fields in Slack. *** ### Using Data Sets as Custom Fields You can add **data set selector** custom fields to assets, employees, and applications from **Field Management** settings. This gives you a consistent, dynamic field type across all your entity management surfaces - not just service catalog forms. #### Configuring a Data Set Selector Custom Field When setting up a data set selector custom field, you can define the following options: * **Dataset**: choose which dataset the field draws its values from * **Allow multiple**: permit users to select more than one value * **Cascading filters**: filter available options based on other field values on the same record * **Display column**: specify which column from the dataset is shown to users Values entered into these fields are validated against the referenced dataset, ensuring data integrity across entities. #### Editing Data Set Selector Values on Entity Pages Once a data set selector custom field is added to an entity type, users can select and update values directly on asset, employee, and application detail pages using the full dropdown UI. Inline editing is supported on all entity detail pages. *** ### Using Data Sets in Custom Agents You can reference Data Sets inside your Custom Agents to bring structured business data - such as product catalogs, account lists, or any custom records - into your agents without relying on external systems. Custom Agents support full CRUD operations on datasets, columns, and rows, including bulk updates. The **Employee** column type lets you link dataset records directly to members of your team, making it easy to build agents that incorporate people data alongside other structured records. *** ### Common Use Cases #### Approver routing table Create a dataset with columns for **Department** and **Approver Email**. In your approval agent, add a **Query Data Set** step that filters by the ticket's department and returns the matching approver. Use that email to route the approval request without hardcoding any values. #### Audit log Add an **Insert Data Set** step at the end of an agent to record what happened, including who triggered it, what action was taken, and when. The dataset builds up a running log you can review in the Data Sets UI or export. #### Dynamic Slack dropdowns Create a dataset of office locations with columns for **City** and **Country**. Point a Slack select field at it. When a new office opens, just add a row to the dataset and the Slack dropdown updates automatically without any agent changes. #### Cascading location selector Create a dataset with columns for **Country** and **City**. Add two fields to a service catalog form - one for Country and one for City. Configure a cascading filter on the City field so it only shows cities that match the selected Country. This keeps the options focused and reduces the chance of mismatched selections. #### Bulk syncing records vian agent Use the **Bulk Upsert Data Set** block to keep a dataset in sync as part of a scheduled or triggered agent. For example, when a batch of onboarding tickets is processed, upsert all the relevant employee records into a tracking dataset in a single step rather than looping through individual inserts. *** ### Things to Know **Deleting a column does not delete existing data.** The column is hidden from the table view and no longer appears in agents or forms, but the values already stored in rows are preserved behind the scenes. **Dataset names must be unique.** You cannot have two datasets with the same name. If you need to organize datasets, consider including a prefix in the name (e.g. "HR - Approvers", "IT - Office Locations"). **Bulk imports are capped at 1,000 rows.** If you need to import more, split the data into multiple CSV files. **Agent operations on large datasets are capped at 10,000 rows.** Update and Delete agent blocks process up to 10,000 matching rows per run. If your dataset is larger than this, use the **limit** setting on the block to control scope. **The display column affects all dropdowns.** Whichever column is set as the display column will be used as the label in every Slack modal, service catalog form, and data set selector custom field that references this dataset - unless overridden at the field level. Make sure it contains a value that is meaningful to end users. **Cascading filters use AND logic.** When multiple cascading filter rules are configured on a single field, all rules must be satisfied for an option to appear. There is no OR logic between rules. **Data set selector custom fields are validated against the dataset.** Values stored in data set selector custom fields on assets, employees, and applications must exist in the referenced dataset, keeping your entity data consistent. # Using the Harmony Portal Learn how to use the Harmony Portal to chat with AI agents, view and manage your tickets, and approve or deny requests. {% hint style="info" %} **Path:** `/portal` {% endhint %} ### Understanding and Using the Portal #### What is the Harmony Portal? The Harmony Portal is the end-user interface for employees to get IT support. It provides a simplified view where you can chat with an AI agent, view your tickets, respond to approval requests, manage your app access, and stay on top of announcements - without needing access to the full admin dashboard. #### Understanding Portal vs Dashboard | Aspect | Portal | Dashboard | | --------------- | -------------------------------------------------------------------------- | ---------------------------------------------- | | **Audience** | End users (employees) | Admins and agents | | **Entry** | `/portal` | `/dashboard`, `/tickets`, etc. | | **Features** | Chat with AI, your tickets, your approvals, app marketplace, announcements | Full service desk, assets, workflows, settings | | **Ticket view** | Simplified (no SLA, linked tickets, or PDF export) | Full ticket details and tools | Non-admin users are typically redirected to the Portal when they access Harmony. Admins can still use the Portal and see a "View in Platform" link on tickets to open the full dashboard view. #### Accessing the Portal Open the Portal at `/portal`. If you're a non-admin user, you may be automatically directed here. You can also reach it from the sidebar or by navigating directly to the Portal URL. #### Navigating the Portal Interface The Portal home shows: * **Hero section** - Welcome message and main chat input * **Tabs** - **Tickets** and **Approvals** for viewing your submitted tickets and pending approval requests * **Chat entry** - Type in the hero input or go to **Threads** to start or continue conversations * **Applications** - Apps provisioned to you and a marketplace to discover new tools * **Announcements** - Organization-wide updates you can mark as read Click **Threads** (or the chat icon) to open the thread view with a sidebar of conversation history. ![Portal home with hero and Tabs (Tickets, Approvals)](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-9ae444f7f70d6a622e55877ab6fc464a88017319%2Fportal-home.png?alt=media) #### Using the Portal Hero Section The hero appears at the top of the Portal. It includes: * **Title** - Often personalized (e.g., "Hi, {userName}") based on your tenant's branding * **Background** - Image or gradient configured by your organization * **Chat input** - Main place to start a new conversation; type your message and press Enter or click Send Entering a message in the hero creates a new thread and opens the conversation view. ![Hero with chat input and branding](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-4ac573d0233f48c71142206a66c90122ceeab7c6%2Fportal-hero-chat.png?alt=media) #### Understanding Portal Branding Your organization can customize the Portal's look: * **Hero title** - Welcome text, including `{userName}` for personalization * **Hero background** - Image or gradient * **Primary and secondary button colors** * **Portal name and logo** Admins can preview branding changes by adding `?preview=true` to the Portal URL and configuring preview settings. *** ### Managing Chat Threads and Conversations #### Using the Chat Input The chat input supports: * **Rich text** - Formatting, lists, and more * **Attachments** - Add files to your message * **Mentions** - Reference people or resources * **Send** - Enter or click the send button to submit #### Starting a New Conversation 1. On the Portal home, type in the hero chat input and send, or 2. Go to **Threads** and click **New chat** (or use the new-chat link) 3. Your message is sent to the AI agent 4. A new thread is created and you're taken to the conversation view #### Creating New Chat Threads Each conversation is a separate thread. Use **New chat** in the Threads sidebar to start a fresh conversation. You can also start from the hero input - sending a message there creates a new thread. ![Threads view with sidebar and conversation](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-7e8d74ccb40cde60c7e87e5fee87298ac678d075%2Fportal-threads.png?alt=media) #### Viewing Thread History The Threads sidebar lists your past conversations. Click a thread to open it. Threads are ordered by activity. Thread titles are generated automatically so you can identify conversations at a glance - you can also rename or delete them from the sidebar menu. #### Navigating Between Threads Click a thread in the sidebar to switch to it. The active thread is highlighted. Use the sidebar to move between different conversations. #### Starting a New Conversation from a Locked Thread If you're in a thread that is already dedicated to an existing ticket, you can start a new conversation with a single click. Instead of copy-paste instructions, the agent shows a clickable link that opens a new conversation automatically. Your original request is carried over and pre-filled, so you don't need to retype anything. If you have multiple unresolved requests, they are presented clearly so you can choose which to continue. #### Searching Conversations Global search across chat threads is not available. Search is available within the **Tickets** and **Approvals** tabs (by title, description, etc.). #### Understanding Thread Status Threads can be active (ongoing conversation) or ended. When a conversation has ended, the thread may show "This conversation has ended" and the chat input may be read-only, depending on the thread version. #### Understanding Agent "Thinking" Status After you send a message, the agent processes it. While processing, you see a thinking indicator (e.g., "Just a second..."). The agent's response streams in when ready. If the response takes longer than expected (\~200 seconds), you may see: "The response is taking longer than expected. Please try sending your message again." You can resend your message to retry. #### Viewing Ticket Results in Chat When the AI agent looks up or creates a ticket during a conversation, the results appear as interactive cards rather than plain text. Each card shows: * **Priority icon** and **status badge** so you can immediately see where a ticket stands * **Ticket type, source, and assignee** for full context without leaving the conversation * **A clickable link** that takes you directly to the full ticket detail page When a new ticket is created through the chat, an inline ticket-created card appears in the thread. The card includes a direct URL so you can navigate straight to the ticket without searching for it manually. #### Submitting Satisfaction Surveys in Chat When a ticket is resolved, an interactive satisfaction survey card appears inline in the conversation thread. You can submit your rating directly from the portal without switching to Slack or Teams. #### Auto-Close Reminders in Ticket Threads If a ticket is approaching automatic closure, a reminder appears as an inline pill directly inside the relevant ticket thread. This surfaces the warning in context alongside the conversation history, making it easier to take action before the ticket is automatically closed. #### Using Smart Forms for Service Requests When you start a conversation with the AI agent, a relevant service request form may be suggested automatically based on your request. Forms use rich, interactive fields instead of plain text inputs: * **Rich field types** - Dropdowns, date pickers, text inputs, and more * **Conditional fields** - Fields can appear or disappear based on your previous selections, keeping forms concise and relevant * **Search in selector fields** - Type to filter options in single and multi-select fields in real time, so you can quickly find the right value without scrolling through long lists * **AI-powered summary** - Before you submit, a summary of your selections is shown for review * **Instructions fields** - Guidance added by your admin appears with a ⓘ symbol; long instructions collapse automatically and can be expanded when needed #### Understanding Copilot Responses Harmony Copilot assists agents and employees during AI interactions. Copilot responses include your employee identity context so answers are tailored to you. If the underlying AI service is temporarily unavailable, you receive a clear fallback response instead of an unexpected error. Internal processing details are filtered out so you see only relevant, meaningful output. *** ### Viewing and Managing Your Tickets #### Viewing Your Submitted Tickets Open the **Tickets** tab on the Portal home. The table lists tickets you've submitted, with columns for title, ticket type, status, priority, desk, and created date. By default, the list shows only open and in-progress tickets so your view stays focused on active work. Use the status filter to include resolved, closed, or canceled tickets when needed. Use pagination to browse if you have many tickets. ![Portal Tickets tab with ticket list](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-7ed25e44d9cf6fbf64823afd6768bdbfe11bf07c%2Fportal-tickets-tab.png?alt=media) #### Checking Ticket Status The **Status** column shows the current state (e.g., open, in progress, pending, resolved, closed). Use the status filter in the toolbar to show only certain statuses (open, in progress, pending, resolved, closed, canceled). Use the priority filter to narrow by priority (low, medium, high, urgent). #### Understanding Ticket Card Timestamps Each ticket card clearly indicates whether the displayed timestamp refers to when the ticket was last updated or originally created: * **Updated X ago** - shown for tickets that have had activity since creation * **Created X ago** - shown for tickets with no subsequent updates This removes any ambiguity about what the date on each ticket card represents. #### Closing Your Own Tickets You can close your own tickets directly from the portal without needing to contact an agent. From both the ticket list and the ticket detail view, select one of the following terminal statuses: * **Resolved** - mark the issue as successfully handled * **Closed** - close the ticket without a resolution * **Canceled** - cancel a ticket that is no longer needed The status selector in the portal shows only these closing options, keeping the interface simple and focused. #### Viewing Ticket Details from Portal Click a ticket to open its detail view. You see: ![Portal ticket detail with Chat and Activity tabs](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-7753949e843799eea97404d65d198ffe66dbf935%2Fportal-ticket-detail.png?alt=media) * **Chat tab** - Conversation and messages; add replies here * **Activity tab** - History of updates and changes * **Properties** (on mobile) - Key ticket metadata Some dashboard-only sections (SLA, linked tickets, related assets, related software, PDF export) are hidden in the Portal view. Admins see a "View in Platform" link to open the full ticket in the dashboard. #### Adding Messages to Your Tickets In the ticket detail view, open the **Chat** tab. Use the message input at the bottom to add a reply. You can include attachments and mentions. Toggle **Internal** if you want to add an internal note (when available). Your message is saved and appears in the thread. #### Understanding Ticket Updates Ticket updates appear in the **Activity** tab. You'll see status changes, assignments, and other events. When an agent replies or the status changes, the ticket reflects the update. In the Chat tab, new messages appear in the conversation. *** ### Managing Approvals #### Understanding Approval Requests Approval requests are items that require your decision - for example, approving access to an application or granting a software request. These may be created by workflows, agents, or agents when you submit a ticket. #### Viewing Pending Approvals Open the **Approvals** tab on the Portal home. The table lists active approval requests. Each row shows the request type, subject (app or service), reporter, ticket ID, and created date. Use search and filters to find specific requests. ![Portal Approvals tab with Approve/Deny actions](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-41f6c4c0180757f9bd9f1b2b35c906f782cf3826%2Fportal-approvals-tab.png?alt=media) #### Viewing Approval Details Click an approval to open its details. You see the request context, related ticket (if any), and options to Approve or Deny. The pending approvals page shows the request title, requester, message, and how long the request has been pending. #### Approving Requests Click **Approve** on an approval. Depending on the request type: * **App access requests** - Choose how to grant access: direct assignment or a specific group. Select the group from the dropdown (or "Direct assignment") and confirm. * **Approvals requiring a choice** - Select from dropdown options when an approval requires a specific selection before responding. * **Other approvals** - You may be able to add an optional comment before approving. Click **Approve** to confirm. #### Denying Requests with Reasons Click **Deny** on an approval. A reason is required. Enter your denial reason in the text area and submit. The requester and workflow can use this reason for follow-up. #### Approving or Denying from the Ticket View If you are listed as an approver on an active approval step, you can approve or deny requests directly from the ticket view in the portal - no special admin role is required. Your decision is recorded as a vote without triggering an admin-override stamp, keeping the approval workflow intact. #### Selecting Groups for App Access For app access approval requests, the approve modal shows available groups. Pick "Direct assignment" to assign the app directly to the user, or choose a group (e.g., a security group) to grant access through. The options depend on how the request and integration are configured. #### Viewing Approval Status After you approve or deny, only the affected row updates in place - your scroll position and the rest of the table are preserved so you can continue working through approvals without disruption. The approval moves out of the pending list, and its status is reflected in the related ticket or workflow. Cards in Slack or Teams are also updated in real time after you respond from the portal. #### Understanding Approval History Approval actions are recorded in the related ticket's **Activity** tab. Open the ticket to see the history of approvals, denials, and other updates. *** ### Managing Applications #### Viewing Your Provisioned Apps Your Portal home shows every application provisioned to you via SSO, paginated in batches of 20 with the newest additions surfaced at the top. Click any app to launch it with a single click. #### Discovering and Requesting New Apps The **Applications Marketplace** lets you find and request tools you don't yet have access to: * **Recommended applications** are surfaced based on what is most popular across your department and role, filtered to show only apps you don't already have access to and that are available to request * Recommendations are ranked by a combination of department-level usage, active users, and total users - so the most widely used and relevant tools appear first * Browse the full catalog or use search to find a specific app, then submit a request directly from the marketplace *** ### Managing Announcements #### Marking Announcements as Read Your Portal shows organization-wide announcements relevant to you. Once you have reviewed an announcement, you can mark it as read directly in the Portal. Announcements marked as read no longer appear in your active announcements list, so you always see only updates that still need your attention. *** ### Related Resources
Service Desk & TicketsHow agents and admins manage tickets in the full dashboardhttps://github.com/harmonyso/public-docs/tree/main/guides/understanding-service-desk-and-managing-tickets/README.md
Getting StartedOverview of Harmony and the dashboard for adminshttps://github.com/harmonyso/public-docs/tree/main/guides/getting-started-with-harmony-dashboard/README.md
# Managing Service Desks and Teams Learn how to create and manage service desks, add teams, configure members and roles, set working hours, and adjust desk settings. {% hint style="info" %} **Path:** `/settings/desks` {% endhint %} ### Understanding Service Desks #### What are Service Desks? A **service desk** is a top-level unit that organizes support work. Each desk has a name, emoji, description, inbox email, and members. Desks contain **teams** (also called subdesks), which group agents and can have their own working hours and routing. Tickets belong to a desk and are routed to teams and agents based on your configuration. #### Understanding Desk Structure Each desk has: * **Main team** - A special default team (`main`) for the desk * **Custom teams** - Additional teams with names, timezones, descriptions, working hours, and members * **Desk members** - People who can work on the desk; team members must be desk members first Desks also have settings for email inbox, automation, SLA, notifications, tags, custom fields, and canned responses. Access these from the desk's settings pages. #### Understanding Desk Hierarchy **Desk → Teams.** A desk is the parent. Teams are children. Routing can send tickets to a specific team based on the team's timezone or description (configured at the desk level). *** ### Managing Service Desks #### Creating a New Desk 1. Go to **Settings** → **Desks**. 2. Click **Create Desk**. 3. Create a custom desk or choose a predefined template: * **Custom** - Enter name, emoji, and description. * **From template** - Select a template that preconfigures common desk setups (IT, HR, Legal, Finance, Workplace, Marketing, and Security). 4. Click **Create**. While filling in the description, you can click **Improve with AI** to generate a polished, routing-optimized description automatically. Enter your raw notes or key points about the desk's purpose and the AI rewrites them into a clear, precise description that helps your agent route conversations accurately. The AI uses tailored prompts for each of the seven predefined templates and a general fallback for custom desks. It is also aware of your other active desks to minimize ambiguity between them. ![Desks list with Create Desk button](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-493604e9aeef6bb30ad23581006f63b1f4d7c13a%2Fdesks-list.png?alt=media) ![Create Desk modal (custom vs template)](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-7dd972093ecf2949cee003a7cf707c63d668ee29%2Fcreate-desk-modal.png?alt=media) #### Editing Desk Settings 1. Open a desk from the Desks list. 2. Use **Edit** (or the desk header) to change the name, emoji, and description. Editing opens a focused modal so you can make changes without leaving the current page. 3. On template-based desks, the desk name and emoji remain fixed to preserve their core identity. You can update the description at any time to influence how Harmony's AI agent classifies and routes incoming tickets. 4. On custom desks, all fields - name, emoji, and description - are fully editable at any time. You can also use **Improve with AI** in the Edit Desk dialog to regenerate the description from new notes at any time. Desk descriptions now support up to **1,000 characters** (increased from 500), giving you more room to provide detailed context and routing guidance. Your unsaved changes are also preserved if you switch browser tabs while editing. #### Configuring Desk Details {% hint style="info" %} **Path:** `/settings/desks/$deskId` {% endhint %} From the desk overview, you can configure: * **Email** - Enable email-to-ticket, set inbox address, and choose whether CC'd addresses become watchers. * **Members and teams** - Add/remove desk members and manage teams. * **Automation** - Assignment rules, status management, auto-close, surveys. * **SLA** - Response and resolution targets by priority. * **Notifications** - Destinations for ticket created, status changed, SLA breach. * **Tickets** - Tags, custom fields. * **Templates** - Canned responses. ![Desk overview with Email, Members, Automation, SLA tabs](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-3981b7c135362caaccc6feed035eb20ae947654a%2Fdesk-overview-tabs.png?alt=media) #### Hiding and Reordering Desks You can hide desks you don't need to reduce clutter and reorder visible desks to match your team's priorities. These controls are available from the Desks list and keep your support environment organized and focused on what matters most. #### Deleting a Desk 1. Open the desk and go to **Settings** or use the delete option. 2. Confirm by typing the desk name. 3. The desk and all associated tickets are permanently deleted. ![Delete confirmation dialog with name confirmation](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-a24c90ed8b3beea6a8bc2904c61fda9749b739ca%2Fdelete-desk-dialog.png?alt=media) #### Understanding Desk Status When the disabled-desks feature is enabled, desks can be turned on or off. Use the **Enabled** toggle in the desk header. Disabled desks no longer receive new tickets and may be hidden from some views. *** ### Configuring Desk Members {% hint style="info" %} **Path:** `/settings/desks/$deskId/members` {% endhint %} #### Adding Members to a Desk 1. Go to **Settings** → **Desks** → select a desk → **Members** tab. 2. Click **Add Member** (or use the command/search popover). 3. Search for employees and add them to the desk. ![Members tab with Add Member and member list](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-f4f43a320952bd01800f92fe0f2996ee7d2f9a1a%2Fmembers-tab.png?alt=media) All team members must first be desk members. #### Adding Members When SCIM Is Enabled When SCIM user management is active, desk membership is normally controlled through your Identity Provider (IDP) groups. You can now supplement that SCIM-managed membership by manually adding specific employees to a desk on a per-desk basis. Manually added members extend access beyond what the IDP group provides without overriding or disrupting your existing SCIM configuration. #### Removing Members from a Desk 1. Open the **Members** tab for the desk. 2. Find the member and click **Remove**. 3. You must remove a member from all teams before removing them from the desk. If they're still on a team, remove them from the team first. #### Understanding Member Roles Member roles depend on your configuration: * **Legacy mode** - All members appear as "Admin." * **Groups-based mode** - Roles come from access management. Use **Manage users** (main desk) or the Add Member popover (team view) to assign roles. Options are provided by the access-management integration. *** ### Managing Desk Teams Teams and desk members are managed together from a unified settings page, with separate tabs for each. Each team has a name, timezone, and description, and can be deleted at any time - members return to the desk and existing ticket assignments are preserved. #### Creating Teams 1. Go to the desk → **Members** tab → **Teams** sub-tab. 2. Click **Create Team**. 3. Enter team name, timezone (default from desk or browser), and description. 4. Configure auto-assignment directly in the creation dialog (see [Configuring Team Auto-Assignment](#managing-team-settings) below). All auto-assignment options pre-populate with the desk's current settings so you have a sensible starting point. 5. Click **Create**. The **Teams table** displays an "Auto-assignment" column so you can see at a glance which teams have auto-assignment active and which rely on desk-level logic. The Create Team dialog also shows a **"Selected routing method" badge** indicating whether timezone-based or description-based routing is currently active for the desk, so you know which team property - timezone or description - is most important to fill in. ![Create Team dialog and Teams list](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-68b344c40d8e65ca6a8c7e23032cb68abad4bfe2%2Fcreate-team-dialog.png?alt=media) #### Editing Team Details {% hint style="info" %} **Path:** `/settings/desks/$deskId/teams/$teamId` {% endhint %} 1. Open the team from the Teams list. 2. Use **Edit** to change name, timezone, and description. The Edit Team modal also shows a **"Selected routing method" badge** so you can see which routing property is currently driving ticket assignment for this desk. #### Deleting Teams 1. Open the team and use **Delete Team** (or the delete option in the Teams pane). 2. Confirm. You are redirected to the desk members view. #### Managing Team Members **Adding members to teams** 1. Open the team detail page. 2. Click **Add Member**. The popover shows two sections: * **Desk Members** - Employees already on the desk. * **Employees** - Everyone else in your organisation not yet on the desk. 3. Selecting someone from the **Employees** section shows a confirmation dialog explaining they will be automatically added to the desk before being added to the team. The entire flow completes in one place without navigating away. **Removing members from teams** 1. Open the team's members list. 2. Click **Remove** next to the member. **Assigning team roles** When groups-based member management is enabled, team members use the same role model as desk members. Three team-level roles are available: | Role | Access | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | **Team Manager** | Full read/write access to tickets assigned to their team, plus the ability to manage team configuration via **Settings > Desks > Team Settings** | | **Team Operator** | Full read/write access to tickets assigned to their team | | **Team Observer** | Read-only access to tickets assigned to their team | These roles give support organisations finer-grained control over ticket visibility across subdesks, addressing privacy and operational boundary needs. Assign roles via the member management UI. #### Configuring Team Routing Desks have a **routing method** that determines how tickets are assigned to teams: | Method | Description | | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Route by timezone** | Tickets are routed to the team whose timezone matches the ticket context. Ensure all teams have a timezone configured. | | **Route by description** | The AI agent routes based on each team's description. Write clear descriptions of what each team handles. Team descriptions can use natural language; the AI classifies incoming tickets to the most relevant team automatically. | Set this in the desk's Members/Teams area under **Settings > Desks > \[Your Desk] > Members & Teams > Teams tab**. Changing the routing method now prompts a **confirmation dialog** warning you of the impact before the change takes effect, helping you avoid accidental misrouting. *** ### Configuring Working Hours for Teams #### Understanding Working Hours Working hours define when a team (or the main desk) is "open" for SLA calculations. Outside working hours, SLA timers typically pause. Each team and the main desk can have their own schedule. #### Setting Up Working Hours 1. Open the desk or team settings. 2. Find **Working hours**. 3. Choose **24 × 7 support** (always open) or **Custom working hours**. 4. For custom hours, set timezone and enable/disable each day with start and end times (30-minute steps). ![Working hours section with 24/7 and Custom options](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-68bf26aadcb9db3131edff58d27e2e0b7292da2c%2Fworking-hours.png?alt=media) #### Configuring 24/7 Availability Select **24 × 7 support** to have the desk or team count as always available. SLA timers run continuously. #### Understanding Working Hours Impact on SLA * **Desk SLA** - Uses the main desk's working hours (and holidays). * **Teams** - Inherit working hours and holidays from their parent desk by default, but these can be overridden at the team level. * **Holidays** - Use the **Holiday calendar** section to add custom holidays or import a country calendar. Teams can inherit the desk's holiday calendar. *** ### Configuring Desk Settings #### Configuring Desk Automation From **Settings** → **Desks** → *desk* → **Automation**: * **Auto-assignment** - Choose method: round-robin, least-loaded, fixed, or first-responder. Set scope (agents) at desk or team level. * **Status management** - Auto status: reporter reply → "In Progress"; agent reply → "Pending Reporter." * **Auto-close** - Mandatory close comment; auto-close resolved/pending after inactivity; reminder hours; auto-close linked tickets by link type and eligible statuses. * **Require closing comment** - When enabled, agents must leave a comment before closing a ticket to ensure every closure is properly documented. When closing multiple tickets in bulk, a single modal appears so agents can submit one comment that applies to all affected tickets. This setting is off by default and can be enabled per desk at any time. * **Surveys** - Enable/disable satisfaction surveys; optional reminder after X hours. #### Setting Up Desk Notifications From **Settings** → **Desks** → *desk* → **Notifications**: Configure destinations for: * **Ticket created** * **Ticket status changed** * **SLA breach** Destinations can include Slack, Teams, and other configured channels. #### Configuring Desk SLA Policies From **Settings** → **Desks** → *desk* → **SLA**: Set response and resolution targets by priority (Urgent, High, Medium, Low). Working hours for the main desk determine when SLA timers run. See the Automation and SLA guide for details. #### Configuring Ticket Settings per Desk From **Settings** → **Desks** → *desk* → **Tickets**: * **Tags** - Create, edit, and delete tags (name, color; system vs custom). * **Custom fields** - Define custom fields (type, mandatory, internal, description, options). #### Managing Team Settings Per-team settings: * **Working hours** - 24/7 or custom; option to inherit from desk. * **Holiday calendar** - Use desk holidays or configure team-specific holidays. * **Auto-assignment** - Configure when creating the team or update afterward. Choose from the same methods as the desk (round-robin, least-loaded, etc.), scoped to team members. Auto-assignment is disabled by default for new teams so members follow desk-level logic until you explicitly enable it. *** ### Related Resources
Automation & SLAConfigure assignment, status, auto-close, and SLA targetshttps://github.com/harmonyso/public-docs/tree/main/guides/configuring-automation-and-sla/README.md
Ticket SettingsCustom fields, tags, and canned responseshttps://github.com/harmonyso/public-docs/tree/main/guides/managing-ticket-settings/README.md
Service Desk & TicketsHow to create and manage tickets in the service deskhttps://github.com/harmonyso/public-docs/tree/main/guides/understanding-service-desk-and-managing-tickets/README.md
Organizing TicketsTable views and filters for ticketshttps://github.com/harmonyso/public-docs/tree/main/guides/organizing-tickets-and-table-views/README.md
Service Desk MetricsAnalyze desk performance and SLAhttps://github.com/harmonyso/public-docs/tree/main/guides/analyzing-service-desk-metrics/README.md
# Configuring Automation and SLA Learn how to configure desk automation (assignment, status, auto-close, surveys) and SLA policies for response and resolution targets. {% hint style="info" %} **Paths:** Automation: `/settings/desks/$deskId/automation` · SLA: `/settings/desks/$deskId/sla` {% endhint %} ### Configuring Automation Rules Automation rules control how tickets behave without manual action: who gets assigned, when status changes, and when tickets close. Configure these per desk from **Settings** → **Desks** → *desk* → **Automation**. #### Understanding Automation Rules Automation includes: * **Ticket assignment** - How unassigned tickets are routed to agents (round-robin, least-loaded, first responder, or fixed) * **Status management** - Automatic status changes when reporter or agent replies * **Auto-close** - Closing tickets after inactivity or when linked tickets resolve * **Surveys** - Satisfaction feedback collection after resolution #### Creating and Editing Automation Automation is configured per desk. Open the **Automation** tab for the desk. Each section has its own enable/disable and configuration. Changes save immediately when you update settings. ![Automation tab with ticket assignment (round-robin, least-loaded, etc.)](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-4e98eeeb33ca4ccb7117874ac757f8bbef560d48%2Fauto-assignment.png?alt=media) *** #### Configuring Auto-Assignment You can automatically assign incoming tickets to agents within a desk, eliminating the need for manual triage. Enable auto-assignment from the **Automation** tab in desk settings and choose an assignment method from the dropdown. Each method in the dropdown includes a description to help you understand how tickets are distributed before making a selection. **Assignment methods** * **Round-robin** - Rotates new tickets evenly through available agents in a consistent order (selected by default). The rotation pointer advances through the full agent list, preserving fairness over time. * **Least-loaded** - Assigns each new ticket to the agent with the fewest currently open tickets. Only available agents are considered when calculating load. * **Fixed** - Always routes tickets to one specific agent you designate. * **First responder** - Automatically assigns an unassigned ticket to the first agent who sends a public reply (via Slack, Teams, or the ticket chat). This rule only fires when the ticket has no assignee, is not yet resolved or closed, and the responder is a desk agent. For round-robin and least-loaded methods, you can control which agents are included in the assignment pool. **Skipping out-of-office agents** When Round Robin or Least Loaded is selected, a **Skip members who are currently out of office** checkbox appears in your auto-assignment settings. When enabled: * **Round Robin** - The rotation pointer continues to advance through the full agent list, preserving fairness. Out-of-office agents are simply passed over without resetting the rotation order. * **Least Loaded** - Only agents who are currently available are considered when calculating workload and making assignments. This ensures work lands with someone who is actually available without disrupting the overall assignment logic. **Automatic status update on assignment** When an agent is automatically assigned to a ticket after the first-responder rule fires, the ticket status automatically moves from **Open** to **In Progress**. This ensures your queue reflects real-time activity without requiring manual status updates. The status change only occurs when the ticket is currently **Open** - tickets already in another status are not affected. SLA time-to-response tracking begins as soon as the status transitions to In Progress. **Assignment reliability** Auto-assignment includes retry logic for the membership checks that determine which agents are eligible to handle incoming tickets. If a brief or transient issue occurs in the underlying access management service, the system automatically re-attempts these checks with exponential backoff - resolving the vast majority of transient failures without any impact to your team's routing or first-responder assignments. *** #### Configuring Auto-Close Settings Auto-close is **disabled by default** and must be explicitly enabled per desk. When enabled, tickets in a resolved state are moved to "Closed" after the configured inactivity period has elapsed. Each auto-closure is recorded as a system event in the ticket's activity log, noting the status transition. Agents can still manually reopen tickets if needed. **Inactivity-based closure** * **Resolved tickets** - Close after 1-365 days of reporter inactivity (no reply from reporter). * **Pending tickets** - Close after 1-365 days of reporter inactivity. * **Reminder** - Optional reminder 1-200 hours before closing to prompt reporter action. Auto-close timers respect your team's business schedule. Only time within your defined business hours and working days counts toward the auto-close threshold, so tickets are not closed during off-hours, weekends, or holidays. Calendar holidays configured for the desk also pause the timer on non-working days. **Pre-closure reminders for reporters** Before a ticket is auto-closed, reporters can automatically receive a personal Slack or Microsoft Teams notification containing the ticket name, current status, and a direct link to the Self-Service Portal. This gives them a clear window to respond before the ticket closes. Configure this option under **Desk Settings** → **Automation**. **Reopen on comment** You can configure resolved tickets to reopen automatically when a reporter adds a comment via Slack, Teams, or the Self-Service Portal. This lets reporters reopen their own tickets simply by replying, without needing to contact support directly. Configure this option under **Desk Settings** → **Automation**. **Linked tickets** When a parent ticket is resolved, downstream linked tickets can auto-close based on: * **Link types** - Depends on, Blocked by, Duplicate of * **Eligible statuses** - Open, In Progress, Pending reporter, Pending approval, Pending internal team, Pending third party, Resolved **Mandatory close comment** Require an internal comment when closing a ticket. When enabled, agents must add a comment before closing. ![Automation tab with inactivity-based closure options](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-523b6954c15daf9d9e6bf33aec53bb0eda136c43%2Fauto-close-settings.png?alt=media) *** #### Setting Up Status Management **Comment-driven status** When status management automation is enabled, ticket statuses update automatically based on who replied most recently, eliminating the need for agents to manually move tickets between states: * **Reporter (employee) replies** - The ticket automatically moves from "Pending Reporter" back to **In Progress**, signalling that the ball is in the agent's court. * **Agent replies** - The ticket automatically moves to **Pending Reporter**, indicating the team is waiting on the reporter. Enable or disable this behavior in the **Status management** section of the Automation tab. **Approval workflow outcomes** You can now configure different ticket status transitions depending on the outcome of an approval step in your workflows. Each outcome - approved, rejected, or any other configured result - can automatically move the ticket to a distinct status. This gives your team finer control over how tickets progress through your support process after human review decisions, rather than applying a single status update regardless of outcome. #### Understanding Status Transitions Status automation uses these transitions: * **Pending Reporter** → **In Progress** - When the reporter replies * **In Progress** (or similar) → **Pending Reporter** - When an agent replies Other status changes (e.g., Resolved, Closed) are manual or driven by workflows and approvals. Approval workflow outcomes can be mapped to custom statuses as described above. #### Configuring Status Automation Use the **Status management** toggle to turn comment-driven status on or off. No additional configuration is needed for the standard transitions; they are fixed as described above. For approval-outcome-based status changes, configure the desired status per outcome within your approval workflow settings. *** #### Configuring Survey Settings (Feedback) * **Enable/disable** - Turn satisfaction surveys on or off independently for each desk (enabled by default). * **Delay** - Set a custom delay for when the survey is sent after ticket resolution. * **Reminder** - If the reporter has not completed the survey within 1-200 hours of resolution, send an optional reminder. Surveys are sent to service requesters via Slack or Microsoft Teams direct message after a ticket is resolved. Each survey asks "How would you rate the service you received?" with a 1-5 scale and includes the ticket ID, status, and a link to the self-service portal for context. Once a requester submits their rating, the survey is marked complete and cannot be resubmitted. **Survey rating order** Rating options in Slack and Teams notifications appear from positive to negative - starting with **Excellent** and ending with **Very bad** - following standard UI/UX conventions that make it easier and more intuitive for end users to respond. **Low-rating follow-up** When a user rates their experience as **Average (3)**, **Bad (2)**, or **Very Bad (1)**, they are prompted with "What could we have done better?" and must provide a response before submitting. This gives your team richer context on negative feedback. Ratings of **Good (4)** and **Excellent (5)** submit immediately, unchanged. This applies across both Slack and Microsoft Teams. **Bulk survey management** You can perform bulk actions on surveys, making it faster to manage multiple surveys at once. Select multiple surveys and apply actions across all of them in a single operation - especially useful for teams managing large volumes of surveys or needing to make consistent changes at scale. Results are used for reporting and compliance. *** ### Configuring SLA Policies SLA (Service Level Agreement) policies define response and resolution targets by ticket priority. Configure from **Settings** → **Desks** → *desk* → **SLA**. #### Understanding SLA Policies An SLA policy sets: * **Response time** - How quickly an agent must first respond (e.g., acknowledge the ticket) * **Resolution time** - How quickly the ticket must be resolved * **Working hours** - When the SLA clock runs (24/7 or custom schedule) * **Warning thresholds** - When to alert before breaching (e.g., 80% of target elapsed) #### Setting Up SLA Policies 1. Open the desk → **SLA** tab. ![SLA tab with response and resolution targets by priority](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-f45920b6e89352a536a7b12756f52f9adf0496e5%2Fsla-policies.png?alt=media) 2. Enable SLA for the desk (if disabled). 3. Set response and resolution times for each priority. 4. Configure working hours (or use 24/7). 5. Optionally adjust warning percentages for breach alerts. #### Configuring Priority-Based SLAs Each priority has its own targets: | Priority | Typical default (response / resolution) | | ---------- | --------------------------------------- | | **Urgent** | 12 hours / 24 hours | | **High** | 24 hours / 48 hours | | **Medium** | 4 hours / 24 hours | | **Low** | 8 hours / 48 hours | #### Configuring SLA Targets by Priority Level For each priority (Urgent, High, Medium, Low), set: * **Response time** - First response target * **Resolution time** - Full resolution target Response time must be less than or equal to resolution time. Both use the same time options. #### Setting Response Time Targets Available options: 15 minutes, 30 minutes, 1 hour, 2 hours, 4 hours, 8 hours, 12 hours, 24 hours, 48 hours, 72 hours, 1 week. Response time is the deadline for an agent to first respond (e.g., add a comment or change status). #### Setting Resolution Time Targets Same options as response time: 15 minutes through 1 week. Resolution time must be at least as long as the response time for that priority. It defines when the ticket should be resolved (e.g., closed or marked resolved). #### Understanding SLA Working Hours SLA timers run only during **working hours** unless you use 24/7. Working hours are configured per desk (main) or per team. Outside working hours, the SLA clock pauses. Holidays (from the holiday calendar) also pause the clock. **SLA timers and Pending status** SLA timers automatically pause whenever a ticket enters the **Pending** status. Time spent waiting on a customer or third party no longer counts against SLA targets, so your metrics accurately reflect only the time your team is actively working on an issue. Once the ticket moves out of Pending, the SLA timer resumes from where it left off. **Holiday calendars** You can configure holiday calendars for your desks to ensure SLA timers automatically pause on public holidays and custom time-off days. This keeps response and resolution targets accurate without requiring manual adjustments around holidays. * **Import official holiday calendars** by country - each entry includes the holiday name, date, and location, with data stored up to 5 years in advance. * **Add custom holidays or team-off days** by selecting a date from the calendar and entering an event name, useful for local observances or company-wide days off. * **Remove calendar entries** at any time to adjust your schedule. #### Setting Up 24/7 SLA Tracking Select **24 × 7 support** in the Working hours section to run SLA timers continuously. No pauses for nights or weekends. Use this when your team provides around-the-clock support. #### Understanding SLA Breach Handling **Breach detection** A breach occurs when the response or resolution deadline passes without the required action. Status values: *active* (in progress), *breached* (deadline passed), *completed* (target met). **Display** * **Ticket preview** - Response and resolution SLA shown with color: red (breached), green (active/met), gray (completed). Each ticket displays both **Time to First Response** and **Time to Resolution** SLA indicators with clear status states (on track, at risk, or breached). * **Tickets table** - A dedicated **Time-to-Resolution** column is available, sortable so you can quickly prioritize tickets at risk of breaching their SLA. The TTR cell shows SLA status and date; breached tickets have a red icon. **Notifications** Configure **SLA breach** as a notification type in the desk's Notifications settings. When a ticket breaches, the event is sent to the configured destinations (e.g., Slack, Teams). **Dashboard and reporting** * SLA Breached Tickets widget shows breach count. * SLA compliance metrics (e.g., breach count, compliance rate) are available for dashboards and reports. *** ### Related Resources
Service Desks & TeamsDesk structure, teams, and working hourshttps://github.com/harmonyso/public-docs/tree/main/guides/managing-service-desks-and-teams/README.md
Ticket SettingsCustom fields, tags, canned responses, notificationshttps://github.com/harmonyso/public-docs/tree/main/guides/managing-ticket-settings/README.md
Service Desk & TicketsCreate and manage tickets that SLAs apply tohttps://github.com/harmonyso/public-docs/tree/main/guides/understanding-service-desk-and-managing-tickets/README.md
Service Desk MetricsAnalyze SLA compliance and breach trendshttps://github.com/harmonyso/public-docs/tree/main/guides/analyzing-service-desk-metrics/README.md
# Managing Ticket Settings Learn how to manage custom fields, tags, canned responses, and ticket configuration for your service desk. {% hint style="info" %} **Path:** `/settings/desks/$deskId/tickets` {% endhint %} ### Managing Ticket Settings Ticket settings configure how tickets look and behave for a desk. Open **Settings** → **Desks** → *desk* → **Tickets** for custom fields and tags, or **Templates** for canned responses. #### Understanding Ticket Configuration Ticket configuration includes: * **Custom fields** - Extra fields on tickets (text, number, select, etc.), now also scopeable by ticket type (Incident or Request) across all desks * **Tags** - Labels for categorizing and filtering tickets, scoped per service desk * **Priorities** - Urgent, High, Medium, Low (configured in SLA) * **Canned responses** - Reusable reply templates * **Custom metadata** - Structured metadata attached to tickets for enrichment and integrations #### Managing Custom Fields {% hint style="info" %} **Path:** `/settings/desks/$deskId/tickets` {% endhint %} Custom fields let you capture the information that matters most to your team directly on tickets. You can define fields at the desk level or scope them to a specific ticket type (Incident or Request) so they appear automatically across all desks for that type. **Creating custom fields** 1. Go to **Settings** → **Desks** → *desk* → **Tickets**. 2. Open **Custom fields** and click **Create custom field**. 3. Enter name and description. 4. Choose field type and options. 5. Set whether the field is required and/or internal (visible only to desk members). 6. Optionally choose a **ticket type scope** (Incident or Request) to make the field appear on all tickets of that type across every desk, with no per-desk configuration needed. 7. Optionally define **visibility conditions** so the field only appears when relevant. 8. For single/multi select, add the option list. 9. Save. ![Custom fields list and Create custom field](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-574f5aad054e89d427a5dbc4e986c29fbc3115b1%2Fcustom-fields.png?alt=media) **Understanding custom field types** | Type | Description | | ----------------- | -------------------------------------------------------------- | | **Text** | Single-line or multiline text. | | **Number** | Numeric value. | | **Checkbox** | Yes/no. | | **Single select** | One option from a list. Configure options when creating. | | **Multi select** | Multiple options from a list. Configure options when creating. | **Setting custom field requirements** * **Required** - Field must be filled before the ticket can be submitted or closed (depending on desk configuration). * **Internal** - Field is visible only to desk members (agents), not to employees submitting requests through the portal and not to the AI agent. A lock icon is displayed on internal fields within the ticket view so agents can identify them at a glance. Note that the internal option is only available for non-mandatory fields - required fields cannot be marked as internal. **Scoping custom fields by ticket type** You can now define custom fields that apply across all tickets of a given type - Incident or Request - regardless of which desk the ticket belongs to. This means you no longer need to configure the same field on every desk individually. Fields scoped to a ticket type appear automatically wherever that ticket type is used. You can also define visibility conditions on ticket-type-scoped fields so they only appear when relevant to the current ticket context. **Custom field identifiers** Custom field configurations are UUID-keyed, so renaming a field never breaks historical data or existing integrations. **Ordering custom fields** Custom fields are shown in the order returned by the API. Reordering is not available in the UI. #### Attaching Custom Metadata to Tickets In addition to structured custom fields, you can attach arbitrary custom metadata to any service desk ticket. This lets you enrich tickets with context from your own systems - such as account details, priority signals, or workflow-specific data - without relying on workarounds. Ticket events are published in real time, so downstream automations and integrations can react immediately when tickets are created, updated, or have watchers added or removed. To attach metadata, use the ticket metadata field available via the API when creating or updating a ticket. #### Managing Ticket Tags Tags are scoped individually to each service desk, so your team only sees and applies tags relevant to that specific desk. This keeps workflows clean and organized when running multiple service desks. Administrators can also manage tags at the tenant level from a single place, creating, updating, and deleting tags that apply across all service desks in your account to maintain consistent tagging taxonomies at scale. **Creating tags** 1. Open the desk → **Tickets** tab → **Tags** section. 2. Click **Create tag**. 3. Enter name and choose a color (from the preset palette). 4. Save. You can also create a new tag directly from the ticket preview without leaving the ticket view. This lets you create and assign a new tag in one step, on the fly, without interrupting your workflow. ![Tags section with Create tag and color palette](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-acbd92330fe28bd3a822ce09f7ffe5918ec9c088%2Ftags-section.png?alt=media) **Editing tags** Click a tag to edit name and color. System tags cannot be edited or deleted. **Deleting tags** Click **Delete** on a tag. Only non-system tags can be deleted. The tag's usage count is shown; clicking it filters tickets by that tag. **Assigning tags** You can assign tags to tickets using either tag names or tag IDs. Both options are fully supported, making it easier to configure tag assignment in workflows and automations without needing to look up internal IDs. **AI-powered automatic tag classification** Harmony can automatically classify and tag tickets in real time using AI, without any manual effort. As soon as a ticket is created or a new message is added, the classification pipeline analyses the content and applies the appropriate tags automatically. Key behaviors include: * New and updated tickets are classified immediately as they arrive. * Tags you have manually corrected are respected and never overwritten by automatic classification. * A cooldown period prevents unnecessary re-classification of recently tagged tickets, while still allowing reclassification once the cooldown has elapsed. **Default tags for imported tickets** Tickets imported from external service desks are automatically labelled with default tags that indicate both that the ticket was imported and which provider it came from. Supported provider tags include **FreshService** and **JSM (Jira Service Management)**. This makes it straightforward to filter, search, and manage imported tickets separately from natively created ones. #### Managing Ticket Priorities Priorities (Urgent, High, Medium, Low) are configured in the **SLA** tab. Set response and resolution time targets per priority. See [Automation & SLA](https://github.com/harmonyso/public-docs/tree/main/guides/configuring-automation-and-sla/README.md) for details. #### Configuring Ticket Sources Ticket sources (Slack, Teams, Email, etc.) are determined by how tickets are created. There is no separate configuration UI for sources. Sources are used for filtering, display, and canned-response variables. #### Managing Canned Responses {% hint style="info" %} **Path:** `/settings/desks/$deskId/templates` {% endhint %} Canned responses (templates) let agents insert predefined replies quickly, allowing your team to respond to frequently asked questions in seconds instead of typing from scratch every time. Configure at **Settings** → **Desks** → *desk* → **Templates**. **Creating canned responses** 1. Open **Templates** and click **Create template**. 2. Enter name (up to 160 characters) and content using the rich-text editor with full formatting support. 3. Add variables if needed (e.g., `{{ticket.subject}}`, `{{reporter}}`). 4. Choose **Personal** (only you) or **Shared** (all desk members). 5. Optionally add attachments (when enabled). 6. Save. ![Canned responses section with Create template](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-e522a47d5e8f455e74f67a4c60c9a897f627f990%2Fcanned-responses.png?alt=media) **Editing canned responses** Click a template to edit name, content, variables, availability, and attachments. **Managing canned response variables** Use **Add variable** in the editor to insert ticket data. Available variables include: * `{{subject}}`, `{{id}}`, `{{description}}` * `{{reporter}}`, `{{agent}}` * `{{status}}`, `{{priority}}`, `{{source}}`, `{{ticket_type}}` * `{{desk_name}}`, `{{currentUser}}`, `{{portalUrl}}` Variables are replaced with actual values when the template is used. **Sharing canned responses** * **Personal** - Only visible to you. * **Shared** - Visible to all desk members. *** ### Related Resources
User ManagementUsers, groups, roles, and notification channelshttps://github.com/harmonyso/public-docs/tree/main/guides/managing-user-management/README.md
Service Desks & TeamsDesk structure and team configurationhttps://github.com/harmonyso/public-docs/tree/main/guides/managing-service-desks-and-teams/README.md
Automation & SLASLA targets and automation ruleshttps://github.com/harmonyso/public-docs/tree/main/guides/configuring-automation-and-sla/README.md
Service Desk & TicketsCreate and manage ticketshttps://github.com/harmonyso/public-docs/tree/main/guides/understanding-service-desk-and-managing-tickets/README.md
# Managing User Management Learn how to manage users, groups, and roles for your organization. {% hint style="info" %} **Path:** `/settings/user-management` {% endhint %} ### Managing Users and Groups User and group management is org-level. Open **Settings** → **User Management**. #### Understanding User Management User management shows users who have roles (Platform or Desk) and the groups they belong to. Users and groups are synced from your identity provider (IdP). You assign roles and desk access via groups. Role and group data is kept consistent in real time. Role names, group role assignments, and resource access information are reliably reflected throughout the platform, so what you see in the UI and what the API returns always matches the current state of your configuration. #### Viewing All Users 1. Go to **Settings** → **User Management** → **Users** tab. 2. The table lists users with roles. Users without roles are hidden. 3. Use search (name/email), filter by role, and pagination to find users. 4. Click a row to open the user detail pane. ![Settings > User Management > Users tab](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-4e3afbbeaeebe057d608c99279d9aef2c21a3d5f%2Fusers-tab.png?alt=media) #### Viewing User Details In the user detail pane: * **Avatar, name, email** * **Groups** - Groups the user belongs to, with roles (e.g., Platform admin, Desk agent). * **Desks** - Desks the user has access to, with desk-level roles (Manager, Agent, Observer). Click a group or desk row to go to its settings. ![User detail pane with Groups and Desks](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-92dfdc92a5307d1cc66c380adbefd406e35af3af%2Fuser-detail-pane.png?alt=media) #### Managing User Groups **Viewing groups** 1. Go to **Settings** → **User Management** → **Groups** tab. 2. The table shows group name, roles, desks count, and members count. 3. Click a row to open the group detail pane. ![Groups tab with Import group button](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-950d493b281e8620234f76b4ab48d766685db039%2Fgroups-tab.png?alt=media) **Creating user groups** Groups come from your IdP. Use **Import group** to bring an IdP group into Harmony and assign roles and desks. You do not create groups in Harmony directly. **Editing group details** 1. Open a group's detail pane. 2. Click **Edit** to open the Import/Edit group modal. 3. Change role assignments (Platform and Desk roles) and desk assignments. 4. Save. This replaces the group's existing role configuration. **Importing groups** 1. Click **Import group**. 2. Select an IdP group from the dropdown. 3. Assign Platform roles (Platform admin, Platform agent, Platform observer) if needed. 4. Assign Desk roles (Desk manager, Desk agent, Desk observer) and select which desks each role applies to. 5. Save. The group's roles replace any previous assignment. ![Import group modal with IdP dropdown](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-df56c688f9aaa8dc32c2ce12dbadb284d345cd1d%2Fimport-group-modal.png?alt=media) **Deleting groups** Groups are defined in the IdP. To remove a group's access in Harmony, open **Edit** and clear all role and desk assignments, then save. The group remains in the IdP but no longer has Harmony access. #### Assigning Users to Groups Users are assigned to groups in your IdP (Okta, Entra, etc.). Harmony reflects IdP membership. To give a user access, add them to a group in the IdP and ensure that group is imported into Harmony with the right roles and desks. #### Setting User Permissions Permissions come from roles. Assign users to groups, then assign roles to those groups. See [User Roles and Permissions](https://github.com/harmonyso/public-docs/tree/main/guides/understanding-user-roles-and-permissions/README.md) for role descriptions. #### Managing User Roles **Assigning roles** Assign roles at the group level: * **Platform roles** - Platform admin, Platform agent, Platform observer (org-wide). * **Desk roles** - Desk manager, Desk agent, Desk observer (per desk). When importing or editing a group, select the roles and, for Desk roles, the desks they apply to. **Understanding role hierarchy** * **Platform admin** - Full org access. * **Platform agent** - Broad access across desks. * **Platform observer** - Read-only org access. * **Desk manager** - Manages a specific desk. * **Desk agent** - Works tickets on a specific desk. * **Desk observer** - Read-only access to a specific desk. **Understanding role overlap** When a group has multiple roles that assign the same desk (e.g., Desk manager and Desk agent), the UI may show an overlap warning. Resolve this by simplifying role assignments so each desk has a single role per group, or by splitting into separate groups. #### Viewing Resource Assignees You can look up who has access to a specific resource using the dedicated resource assignees endpoint. This gives you a clear, up-to-date view of all users assigned to a given resource, making it easier to audit access and troubleshoot permission issues without having to cross-reference individual user or group records. *** ### Related Resources
Notification ChannelsSet up Slack, Teams, and Email notification destinationshttps://github.com/harmonyso/public-docs/tree/main/guides/managing-notification-channels/README.md
User Roles and PermissionsRole definitions and access levelshttps://github.com/harmonyso/public-docs/tree/main/guides/understanding-user-roles-and-permissions/README.md
Service Desks & TeamsDesk structure and team configurationhttps://github.com/harmonyso/public-docs/tree/main/guides/managing-service-desks-and-teams/README.md
Understanding IntegrationsConnect Slack, Teams, and notification channelshttps://github.com/harmonyso/public-docs/tree/main/guides/understanding-integrations/README.md
# Managing Notification Channels Configure where notifications are sent (Slack, Teams, Email) for desk tickets, AI agent events, and asset alerts. {% hint style="info" %} **Paths:** `/settings/desks/$deskId/notifications` (per desk) · `/settings/asset-management` (org-level assets) {% endhint %} ### Managing Notification Channels Configure where notifications are sent (Slack, Teams, Email). Destinations are configured per desk for tickets and AI agent events, and org-level for asset events. #### Understanding Notification Channels Notifications can be delivered to **Slack** or **Microsoft Teams** channels, or via **Email**. Both Slack and Teams require a configured integration and are added per desk via **Add destination**. You can add multiple independent destinations, each with its own channel and event type selection. * **Slack** - Requires Slack integration. Supports ticket events, SLA events, AI agent events, workflow events, announcement broadcasts, and operator notifications. * **Microsoft Teams** - Requires Teams integration. Supports the same event categories as Slack. * **Email** - Used for reporter notifications, announcement broadcasts, and IDP quick action alerts. Each destination card lets you pick the target channel and choose which event types (ticket, SLA, AI agent, or workflow events) it receives. You can add as many destinations as needed - for example, route critical alerts to one Teams channel and general updates to another - and configure each one independently. #### Setting Up Slack Notifications 1. Ensure Slack is connected under **Settings** → **Integrations**. 2. Open **Settings** → **Desks** → select a desk → **Notifications**. 3. Click **Add destination** and choose **Slack**. 4. Select the Slack channel from the dropdown on the destination card. 5. Check the event types you want delivered to that channel. Slack notifications for Desk operators are supported, keeping your team informed of ticket activity directly in Slack. When key events occur on a ticket - such as new messages or updates - a notification is sent to the configured Slack channel or user. All notification events are also logged in the ticket's activity log for full traceability. #### Setting Up Microsoft Teams Notifications 1. Ensure Microsoft Teams is connected under **Settings** → **Integrations**. 2. Open **Settings** → **Desks** → select a desk → **Notifications**. 3. Click **Add destination** and choose **Microsoft Teams**. 4. Select the organization and channel on the destination card. 5. Check the event types you want delivered to that channel. ![Ticket notifications section showing Slack and Microsoft Teams destination cards](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-0aa15c594bf0b51140aedbd12f78ad0c114d2605%2Fticket-notifications.png?alt=media) #### Emailing Reporters About Ticket Updates This is a separate feature from the Slack/Teams channels above. It automatically emails the **person who submitted a ticket** when their ticket is updated - useful so reporters stay informed without needing access to Harmony. Once enabled per desk, reporters automatically receive emails for the following ticket events: * **Ticket created** - confirmation that the request was received, including ticket ID, subject, priority, and status. * **Status updated** - notifies the reporter when the ticket status changes. All email notifications from Harmony are sent from ****, aligned with SPF and DKIM authentication records to improve deliverability and reduce the likelihood of messages being marked as spam. Reply-To headers are correctly set so that replies are routed back to the appropriate support inbox for your workspace. 1. Open **Settings** → **Desks** → select a desk → **Notifications**. 2. Find the **Email reporters about ticket updates** toggle. 3. Enable it. ![Email reporters about ticket updates toggle](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-99f4d3b4688cc1692aca078a3bbeed89458e06c4%2Femail-reporters.png?alt=media) {% hint style="info" %} This toggle notifies ticket **reporters** (submitters) only. It is not a notification channel for agents or admins. This setting is disabled by default and is configured independently per desk. {% endhint %} #### Sending Company Announcements You can send company announcements directly to your team through Slack, Microsoft Teams, and email. Announcements support a title, body, an announcement type badge, and an optional call-to-action button - ensuring your message looks polished across every channel. Announcement notifications display a visual emoji icon before the announcement type label in the card header on both Slack and Teams (for example, "🚨 Outage / Incident"). A dedicated **Invitation** announcement type is also available, represented by the 📧 emoji in Slack notifications. #### Configuring Notification Destinations Each destination (Slack channel, Teams channel, or Email) can have different event types. Use the checkboxes on each destination card to choose which events go to that channel. You can add multiple destinations and configure each independently. Notification preferences are configurable at the desk level, so different desks can have independent notification behaviours without interfering with one another. Both per-desk and global notification configurations are supported for full backward compatibility with existing setups. #### Managing Notification Channels * **Add** - Use **Add destination** and pick Slack or Teams. Email appears automatically for ticket notifications once any integration is configured. * **Edit** - Change the channel or event types on a destination card. * **Delete** - Remove the destination from the card menu. #### Configuring Notification Types **Ticket notifications** (per desk, `/settings/desks/$deskId/notifications`) Default types: ticket created, ticket status changed, SLA breach. Additional ticket-related events may be available (e.g., mentioned in ticket). Ticket event notifications can also be delivered directly inside **conversation threads**, keeping all relevant updates in context alongside the original conversation. When a ticket is created, assigned, or has its status or priority changed, a notification is automatically posted into the associated thread. System messages generated by these notifications are hidden from the admin ticket chat view, so the conversation stays clean and easy to follow. Thread delivery works alongside existing Slack and Teams notification channels. **Approval notifications** (per desk) When an approval request is sent, the notification card includes the ticket title and a direct link to the ticket, so approvers can immediately see which ticket the request relates to without opening it separately. For approvals not tied to a specific ticket - such as those added as a step in Agent Builder - the notification displays correctly without a ticket reference. **SLA notifications** (per desk) Included in Service Desk destinations: `sla_breach` and related SLA events. **AI Agent notifications** (per desk) A dedicated **AI Agents Events** section is available under **Desks → Notifications**, alongside the existing Ticket Events and SLA Events categories. Configure alerts for: * **Agent run failures** - Receive instant push notifications whenever a Harmony Agent run fails (ends in a human escalation). Set up failure notifications under **Settings → Service Desk Notifications** and route them to a dedicated Slack or Teams channel. Each notification includes details about the affected agent and run. This is especially valuable for high-scale environments where many Agents are running simultaneously. * **Failed to respond** - Enable the **"Failed to respond"** checkbox to receive alerts when your AI Agent fails or times out during a conversation before a support ticket has been created. Each alert includes the name of the user who was interacting with the agent and the last message they sent. Choose which Slack or Teams channels receive these alerts. **IDP Quick Action notifications** (per desk) You can opt in to receive notifications when IDP quick actions are triggered on a ticket. Notifications can be delivered via email, Slack, or Microsoft Teams. **Workflow failure notifications** (per desk) You can receive notifications when an Automated Workflow fails, delivered through all supported notification channels: * Email notifications for workflow failures * Slack notifications for workflow failures * Microsoft Teams notifications for workflow failures Workflow failure notifications also surface directly on the desk page, so agents are immediately aware of issues without having to navigate elsewhere. **Asset Management notifications** (org-level) Configure at org asset settings. Default types: EOL planned, EOL reached, EOL grace period expired, low stock threshold reached. **Low stock notifications** (org-level) Part of Asset Management: `low_stock_threshold_reached` and related stock alerts. In both Slack and Teams notifications, Vendor and Location fields appear on the same row for a more compact layout. A **View Assets** button is included in both Slack and Teams notifications when a link is available, letting you jump directly to the relevant assets without leaving your messaging app. #### Notification Reminders and In-Place Updates You can configure Slack and Teams notifications to automatically remind recipients who have not responded and update the original message in place rather than sending a new one. This is particularly useful for time-sensitive actions like satisfaction surveys and approval requests. * **Notification reminders** - Set a timeout after which a reminder is automatically sent to users who have not acted on a notification, re-alerting them within the same message thread. * **In-place message updates** - Existing notifications can be updated in place rather than generating a new message, keeping conversations uncluttered. When a pending reminder has an active parent conversation with replies, Harmony automatically sends an updated notification reflecting the latest state rather than a stale alert. Reminders tied to conversations with no responses continue to behave as before, and update-type notifications cannot themselves trigger further update reminders. #### Understanding Notification Categories | Category | Scope | Events | | ---------------------------------- | --------------- | ---------------------------------------------------------------------------- | | **Ticket notifications** | Per desk | ticket\_created, ticket\_status\_changed, sla\_breach, thread delivery, etc. | | **Approval notifications** | Per desk | Approval requests with ticket title and link | | **AI Agent notifications** | Per desk | Agent failures, failed to respond, run events | | **IDP Quick Action notifications** | Per desk | Identity provider quick actions on tickets | | **Workflow failure notifications** | Per desk | Automated workflow failures | | **Announcement notifications** | Org / broadcast | Company announcements via Slack, Teams, Email | | **Asset notifications** | Org | EOL lifecycle, low stock | #### Selecting Notification Types Per Channel On each destination card, use the checkboxes to choose which event types are sent to that channel. Different destinations can receive different events. Notifications are routed with the correct group context to ensure alerts reach the right team and reduce the chance of misrouted or missed updates. *** ### Related Resources
Service Desks & TeamsDesk structure and team configurationhttps://github.com/harmonyso/public-docs/tree/main/guides/managing-service-desks-and-teams/README.md
Understanding IntegrationsConnect Slack, Teams, and notification channelshttps://github.com/harmonyso/public-docs/tree/main/guides/understanding-integrations/README.md
User ManagementUsers, groups, and role assignmentshttps://github.com/harmonyso/public-docs/tree/main/guides/managing-user-management/README.md
Ticket SettingsCustom fields, tags, and canned responseshttps://github.com/harmonyso/public-docs/tree/main/guides/managing-ticket-settings/README.md
# Configuring Asset Management Learn how to configure EOL policies, low stock alerts, discovery policies, and asset notifications. {% hint style="info" %} **Path:** `/settings/asset-management` {% endhint %} ### Configuring Asset Management Settings Asset management settings control how assets are discovered, when EOL (End-of-Life) notifications are sent, when low stock alerts trigger, and how employees can purchase company devices. Open **Settings** → **Asset management** to access these sections. The settings page is organised into two tabs: * **Notifications** - EOL notifications, low stock alerts, and their destinations * **Policies** - EOL policies, discovery policies, and asset purchase policies #### Understanding Asset Settings Asset settings include: * **EOL policies** - Lifecycle and notification rules per asset type * **Low stock alerts** - Thresholds for in-stock inventory * **Discovery policies** - Rules for which assets are included in discovery * **Asset purchase policies** - Rules governing how employees can purchase company devices * **EOL notifications** - Where to send EOL and low stock alerts (Slack, Teams, Email) #### Configuring Asset Settings Each section has its own form or table. Changes save when you click Save or confirm the action. EOL notifications use the same destination model as desk notifications: add destinations and select event types per channel. #### Managing EOL (End-of-Life) Policies EOL policies define when assets reach end-of-life and when to notify. Configure at **Settings** → **Asset management** → **EOL policies** (within `/settings/asset-management`). **Creating EOL policies** 1. Click **Create policy**. 2. Select **Asset type** (e.g., Laptop, Monitor). 3. Set **Lifecycle** - Expected lifespan in months (1-120). 4. Set **Notification threshold** - How many months before EOL to send the first notification. 5. Set **Grace period** - Months after EOL before the asset is considered fully EOL (0-12). 6. Optionally scope by **Vendor**. 7. Save. ![EOL policy form with asset type, lifecycle, and notification settings](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-658c1c26cb17aeb0b0b86118004ac3c1cc2cebb7%2Feol-policy-form.png?alt=media) **Editing EOL policies** Click **Edit** on a policy. Default (system) policies cannot be edited; you can create a new policy instead. **Deleting EOL policies** Click **Delete** on a non-default policy. Default policies cannot be deleted. **Understanding EOL notifications** EOL events are sent to the destinations configured in **EOL notifications**: * **eol\_planned** - When an asset reaches the notification threshold * **eol\_reached** - When an asset reaches its EOL date * **eol\_grace\_period\_expired** - When the grace period ends Configure destinations (Slack, Teams, Email) and select which events to receive per channel. ![EOL notifications pane with destinations](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-d947e098454fd7f550dde897b2e248870bbf0262%2Feol-notifications.png?alt=media) #### Managing Low Stock Alerts Low stock alerts fire when in-stock quantity falls below a threshold. Configure at **Settings** → **Asset management** → **Low stock alerts** (within `/settings/asset-management`). **Creating low stock alerts** 1. Click **Create alert**. 2. Select **Asset type**. 3. Set **Stock threshold** (1-10,000). 4. Optionally scope by **Vendor** and **Warehouse location**. 5. Save. ![Low stock alert form with asset type and threshold](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-b2e3e136e24d1a8f23d49e913b4ff8c028fa41ca%2Flow-stock-alert-form.png?alt=media) **Editing stock alert thresholds** Click **Edit** on an alert. Asset type is locked; you can change the threshold, vendor, and warehouse. **Deleting stock alerts** Click **Delete** on an alert. Confirm to remove it. **Understanding alert triggers** An alert triggers when the in-stock count for the matching assets (type, vendor, warehouse) drops below the threshold. The table displays an **Available stock** column (previously labelled "Current stock") showing a colour-coded dot indicator - green when stock meets or exceeds the threshold, and red when stock falls below it. Use the in-stock assets link to view filtered assets for that alert. #### Managing Discovery Policies Discovery policies control which assets are included when discovery runs. Configure at **Settings** → **Asset management** → **Discovery policies** (within `/settings/asset-management`). **Creating discovery policies** Each asset type has one policy. Open the policy for an asset type (or create if none exists) and configure rules. **Configuring discovery rules** * **Vendor/model rules** - Add rows with vendor and optional model(s). Only assets matching these vendor/model combinations are included. You can type to search and filter vendors directly within the dropdown. If no vendors are available for a given asset type, a "No vendors yet" message is shown. * **Network rules** - Add IP subnets (CIDR) and WiFi SSIDs. Assets discovered on matching networks are included. You can enter multiple Wi-Fi networks and subnets at once using comma-separated values instead of adding them one at a time. Add multiple rules as needed. Rules are validated (e.g., CIDR format). Vendor and model dropdowns span the full width of their input fields for a consistent layout. ![Discovery policy with vendor/model and network rules](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-142867fd4109d785fb21e29b78177f00dba74504%2Fdiscovery-policy.png?alt=media) **Excluding asset types from discovery** Use **Exclude asset type** to hide an asset type from discovery. Toggle the switch to exclude or include. Excluded types do not appear in asset views from discovery. **Managing asset type exclusions** Each asset type can be excluded independently. Change the exclusion toggle to update the policy. **Preview** Use **Check matching assets** to preview how many assets match the current policy before saving. #### Managing Asset Purchase Policies Asset purchase policies give your organisation control over how employees can purchase company laptops upon termination, upgrade, or from stock. Configure at **Settings** → **Asset management** → **Asset purchase policy** (within `/settings/asset-management`). **Pricing methods** Choose one of the following pricing methods for calculating the employee purchase price: * **Straight-line depreciation** - The asset value decreases by a configurable annual degradation percentage, with a minimum salvage value as a fallback. * **Fixed tiered pricing** - Set a fixed price per year bracket (e.g. year 1-2, year 3-4). * **Fixed percentage discount** - Apply a flat percentage discount regardless of asset age, with a minimum salvage value as a fallback. **Supported purchase cases** Enable or disable the scenarios in which employees are eligible to purchase: * **Upon termination** - Employee can purchase their assigned device when leaving the organisation. * **Upon upgrade** - Employee can purchase their current device when receiving a new one. * **From stock** - Employee can purchase an available device from inventory. You can also set a minimum asset age and minimum employee tenure before purchase is permitted. **Model-level filtering** Restrict a purchase policy to specific device models for finer-grained control over purchase eligibility: * Select **All models** (the default) to preserve existing vendor-level behaviour. * Select one or more specific models (e.g. MacBook Pro M1, Dell XPS 13) to target exact devices within a vendor. Available model options are dynamically filtered based on the vendor(s) selected in your policy. *** ### Related Resources
Asset Views & DetailsNavigate and manage assets in the asset listhttps://github.com/harmonyso/public-docs/tree/main/guides/managing-asset-views-and-details/README.md
Asset OrganizationImport and organize assetshttps://github.com/harmonyso/public-docs/tree/main/guides/managing-asset-organization-and-importing/README.md
User ManagementConfigure EOL and asset notification destinationshttps://github.com/harmonyso/public-docs/tree/main/guides/managing-user-management/README.md
# Managing Knowledge Base Learn how to configure the Knowledge Base (sources, articles, permissions) for AI agents and search. {% hint style="info" %} **Path:** `/settings/knowledge-base` {% endhint %} ### Managing Knowledge Base Sources The Knowledge Base stores articles that AI agents use to answer questions and provide support. Sources can be uploaded manually or connected from third-party tools. Configure at **Settings** → **Knowledge Base**. Personal preferences (theme, Enter key, desk visibility) are configured in [Profile & Preferences](https://github.com/harmonyso/public-docs/tree/main/guides/managing-your-profile-and-preferences/README.md). #### Understanding the Knowledge Base The Knowledge Base enhances AI agent responses with your organization's documentation. Articles from sources are indexed and made available to agents. You can toggle **Enhance with general AI knowledge** to control whether agents use only KB content or can also use general knowledge. This toggle is located in the page header, alongside the "Knowledge base" title, making it easy to find at a glance. #### Understanding KB Sources Sources provide articles to the Knowledge Base: * **Manual upload** - PDF files you upload directly * **Third-party** - Confluence, Notion, Freshservice, SharePoint (requires integration) Each source can have multiple articles. Articles sync periodically; status (Completed, Pending, Failed) is shown per article. #### Adding Knowledge Base Sources 1. Go to **Settings** → **Knowledge Base**. 2. Click **Add source** (or Add knowledge source). 3. Choose: * **Upload file** - For manual PDF uploads * **Third-party** - Confluence, Notion, Freshservice, or SharePoint (when the integration is configured) ![Add source dropdown (Upload file, third-party)](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-589884f7096a4d7bb1668458c58d9705beb6cb0d%2Fkb-add-source.png?alt=media) #### Uploading Files Manually 1. Choose **Upload file** from the Add source dropdown. 2. Drag and drop PDF files or click to browse. 3. **Supported file types** - PDF only. 4. **File size limit** - 50 MB per file. 5. Save. Articles are created and synced. AI tagging applies automatically to manually uploaded PDFs, just as it does for integration-sourced content. Any PDFs you uploaded before this feature was introduced have been retroactively tagged, so your entire knowledge base benefits from consistent AI-driven categorization regardless of how content was added. #### Connecting Third-Party Sources **Prerequisites:** The integration (Confluence, Notion, Freshservice, SharePoint) must be connected in **Settings** → **Integrations**. If not configured, the add-source flow links to integrations. **Steps:** 1. Choose the third-party source from the Add source dropdown. 2. A selection dialog opens with a tree view of available content (spaces, pages, etc.). 3. Search or browse to find articles. 4. Select the items to add. 5. Click **Save & sync** to add them and start syncing. ![Selection dialog with tree of spaces/pages](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-0e97b40ad636865161003aca5cd28606d8441aad%2Fkb-third-party-dialog.png?alt=media) #### Understanding KB Sync Status Each article has a sync status: | Status | Description | | ------------- | ------------------------------------------ | | **Completed** | Article synced successfully. | | **Pending** | Sync in progress or queued. | | **Failed** | Sync failed. Hover for the failure reason. | #### Monitoring KB Sync Progress The Knowledge Base table shows sync status per article. Use the status filter to see Pending or Failed items. For Failed items, hover the status badge to view the failure reason (e.g., permission error, invalid source). ![Knowledge Base table with articles and sync status](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-d358a2ef12fcea6386eb8ea59543c2f00a46ff30%2Fkb-table-sync-status.png?alt=media) #### Understanding Sync Failures When sync fails, the status badge shows **Failed**. A tooltip displays the `failure_reason`. Common causes: permission changes in the source, deleted content, or integration issues. Fix the underlying issue and re-sync (or re-add the source). #### Controlling Private Information Detection Harmony automatically detects and excludes documents containing sensitive or private data during knowledge base ingestion. This helps ensure that confidential information is not indexed and cannot be surfaced in AI-generated responses to your customers. *** ### Organizing KB Articles #### Searching Knowledge Base Articles Use the search box in the Knowledge Base table. It filters articles by the query string (e.g., title, content). #### Filtering KB Articles by Status Use the status filter: **Completed**, **Pending**, or **Failed**. Combine with other filters as needed. #### Filtering KB Articles by Source Filter by source type: Manual, Confluence, Notion, Freshservice, SharePoint. #### Filtering KB Articles by AI Insights When AI Insights is enabled, a dedicated set of filter options appears in the filter panel. You can narrow down articles across multiple AI-analyzed dimensions: * **Knowledge type** - filter by the type of knowledge an article represents (also shown as a subtitle under each article title for quick scanning) * **Category** - filter articles by their AI-assigned top-level category * **Sub-category** - narrow results further within a category * **Solution method** - filter by how the underlying issue is typically resolved #### Sorting KB Articles Sort by: * **Title** * **Status** * **Owner** * **File size** * **Last synced** Default sort is by last synced (newest first). Toggle ascending/descending. #### Understanding Article Metadata | Field | Description | | ------------------ | ------------------------------------------------------------- | | **Article owner** | Employee who owns or is associated with the article (avatar). | | **File size** | Formatted size (B, KB, MB, GB). | | **Last sync date** | When the article was last synced, or "-" if never. | *** ### AI Insights and Tagging #### Understanding AI-Generated Tags During each KB sync, Harmony automatically classifies articles across two tag dimensions: * **Content tags** - visible in the KB table; describe what an article covers, including: * **Knowledge Type:** Troubleshooting, Setup, Policy, Information, or FAQ * **Category / Subcategory:** Matches your ticket tag taxonomy (e.g., Software > Productivity) * **Usage tags** - used by the AI Service Agent and Copilot to improve recommendations AI tagging applies to all articles regardless of source, including manually uploaded PDFs. #### Viewing AI Insights on Articles A dedicated **AI Insights** column in the Knowledge Base table displays tag pills for each article, giving you a quick at-a-glance summary of how Harmony has classified your content. Each article shows up to three tags inline, with a **+N** indicator when there are more. Hovering over the tags opens a detail card that breaks down the AI insights into structured sections: * **Knowledge Type** - the broad classification of the article's content * **Category** and **Sub Category** - hierarchical topic groupings * **Solution** - the resolution method associated with the article *** ### AI-Generated KB Recommendations #### Understanding KB Recommendations Harmony's insights engine analyzes your resolved support tickets and support conversations to automatically surface Knowledge Base article recommendations. The system clusters related topics and identifies gaps or drift in your existing content, helping you keep your knowledge base aligned with what customers are actually asking about. Recommendations appear in the **Recommendations** tab within the Knowledge Base page. The tab is only shown when there are pending recommendations - when none exist, the page displays a clean **Sources** header above your data table instead of an empty tabbed layout. When recommendations are present, the familiar **Sources** and **Recommendations** tabs appear as normal, and all table functionality including filters, pagination, and sorting continues to work in both views. Recommendations can include: * **New article drafts** - for topics with no existing KB coverage * **Update drafts** - for articles where resolution steps have drifted from current practice * **Rewrite drafts** - for articles with low success rates or high ticket reopens Each recommendation includes evidence from real ticket resolutions so you can trace exactly what drove the suggestion. #### Reviewing and Approving Article Updates When Harmony's drift detection identifies that an existing KB article needs updating, it surfaces an update recommendation in the Recommendations tab alongside new article suggestions - so everything is in one place. Update recommendations are visually distinguished from new article suggestions: * An **"Update available"** badge clearly identifies update-type recommendations at a glance * An **"Update article"** button replaces the standard "Create new article" call-to-action on update-type cards * A notice on the detail page shows which existing article the update applies to #### How Harmony Avoids Duplicate Insights The system identifies whether a new insight relates to an existing one by comparing the support conversations that drove each insight. If enough conversations overlap, it is recognized as the same problem and handled accordingly: * **No change detected** - if an insight already exists and its recommended resolution steps have not changed, it is left as-is * **Updated insight** - if the resolution steps have evolved, the existing insight is refined rather than duplicated This means the same underlying issue is improved over time rather than regenerated as a separate entry. #### Understanding Resolution Steps in Recommendations Resolution steps are displayed in a clear, structured format with explicit actor and action labels. Each role is represented by a distinct color-coded badge so you can immediately understand who is responsible for each action: | Badge | Color | | ------------------ | ------------------------------- | | **IT Agent** | Violet | | **Employee** | Sky blue | | **IT Operator** | Grey | | **Approver** | Green | | **Unknown actors** | Outlined (auto-formatted label) | Conditional step instructions (for example, "if ..." clauses) are displayed separately beneath the relevant step. #### Approved Insights Articles and AI Responses When you approve an article generated from your support insights, it is instantly published and indexed so the AI can draw on that knowledge when responding to customers. If an article is later dismissed, it is automatically removed from the AI's knowledge base, keeping responses accurate and up to date. This creates a continuous feedback loop where your team's curation directly improves the quality of AI-powered support. #### Filtering and Sorting Knowledge Sources by Conversation Count In the Insights engine you can filter and sort your knowledge sources by conversation count, making it easier to identify which sources are driving the most (or least) support conversations: * **Sort by conversation count** - order sources ascending or descending * **Filter by minimum conversation count** - focus only on sources with meaningful volume * **Filter by maximum conversation count** - narrow in on lower-traffic sources *** ### Managing KB Permissions #### Understanding KB Permissions KB permissions determine who can access articles. Permissions come from the source system (e.g., Confluence space permissions). Harmony displays them but does not let you change them in the Knowledge Base; update permissions in the source. #### Viewing Authorized Groups In the permissions view (or article detail), **Authorized groups** shows groups that have access. Each group appears as a badge. Groups are synced from the source. ![KB permissions dialog with Authorized groups](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-998513e1921d52ce67666e58864eaaa721c21aa3%2Fkb-permissions-dialog.png?alt=media) #### Viewing Authorized Users **Authorized users** shows individuals with direct access. Displayed as avatars or email badges. #### Understanding Unsynced Groups When some groups from the source are not synced to Harmony (e.g., IdP sync gap), an amber badge appears with "Some groups are not synced." Resolve by syncing groups in User Management or the IdP. #### Viewing Permission Warnings For Confluence (and similar) sources, a **Permissions** warning button (lock or alert icon) may appear when there are permission issues. Click to view details. Fix permissions in the source system. *** ### Maintaining KB Content #### Bulk Deleting KB Articles 1. In the Knowledge Base table, select one or more articles (checkboxes). 2. Click **Delete** in the toolbar. 3. Confirm in the dialog. Selected articles are removed from the Knowledge Base. ![Knowledge Base table with selection and Delete button](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-8c31b849894ff2c1fb9f945f935f61338907d42e%2Fkb-bulk-delete.png?alt=media) #### Single Delete Click the delete (trash) button on an article row to remove it individually. Confirm when prompted. #### Removing Knowledge Sources There is no separate "remove source" action in the Knowledge Base. To stop syncing from a third-party source, disconnect the integration in **Settings** → **Integrations**. Individual articles can be deleted from the table. #### Understanding KB Storage Limits * **Per-file limit** - 50 MB per uploaded file. * **Total storage** - No total storage or usage display in the UI. Storage is managed by your tenant limits. #### Controlling AI Agent Knowledge Scope You can configure whether the AI agent for Service Desk answers questions exclusively from your Knowledge Base, or also draws on its general trained knowledge. This setting is available in **Settings** → **Knowledge Base** via the **Enhance with general AI knowledge** toggle in the page header. * **Knowledge Base only mode** - The AI agent returns answers sourced only from your KB. If no relevant answer is found, the agent escalates the ticket to a human agent rather than generating a response from general training data. * **Knowledge Base + trained data mode** (default) - The AI agent uses your KB content first and supplements with its general trained knowledge when needed. *** ### Related Resources
Profile & PreferencesTheme, Enter key, desk visibilityhttps://github.com/harmonyso/public-docs/tree/main/guides/managing-your-profile-and-preferences/README.md
Understanding IntegrationsConnect Confluence, Notion, and other KB sourceshttps://github.com/harmonyso/public-docs/tree/main/guides/understanding-integrations/README.md
User ManagementNotification destinationshttps://github.com/harmonyso/public-docs/tree/main/guides/managing-user-management/README.md
# Understanding Integrations Learn how Harmony integrations work, how to view and connect them, and how OAuth authentication enables secure connections to third-party systems. {% hint style="info" %} **Path:** `/settings/integrations` {% endhint %} ### Understanding Harmony Integrations #### What are Integrations? Integrations connect third-party systems to Harmony. They enable Harmony to sync data, trigger actions, and work with tools like Slack, Okta, Jamf, Confluence, and many others. Each integration brings capabilities such as user sync, ticket creation, device management, knowledge base content, or notifications. #### Benefits of Integrations * **Single entry point** - Support and operations from one place instead of switching between tools * **Unified workflows** - Automate across systems (e.g., create tickets from Slack, provision access via Okta) * **Data sync** - Keep employees, assets, and applications up to date across your stack * **AI and automation** - AI agents and workflows use integration data to resolve issues and route work #### Viewing Available Integrations 1. Go to **Settings** → **Integrations**. 2. The page lists all available integrations, grouped by category. 3. Use **Search** to find a specific integration by name. 4. Use the **Category** filter to narrow by type (Collaboration, Identity Provider, MDM, etc.). 5. The URL supports `?integration-id=...` for deep linking to a specific integration. Each integration card shows the name, description, category, and connection status. ![Integrations list with category filter and cards](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-b76a3c6d6cb1de806fdeb377da8718596d19f19b%2Fintegrations-list.png?alt=media) *** ### Understanding Integration Categories Integrations are organized into categories: | Category | Description | Examples | | ----------------------- | -------------------------------- | ----------------------------------------------------- | | **Collaboration** | Team communication tools | Slack, Microsoft Teams | | **Identity Provider** | Identity and access management | Okta, Microsoft Entra, Google Workspace, JumpCloud | | **MDM** | Mobile device management | Jamf, Kandji, Intune, JumpCloud MDM | | **EDR** | Endpoint detection and response | CrowdStrike, SentinelOne | | **Ticketing** | Issue tracking and ticketing | Zendesk, Freshservice | | **ITSM** | IT Service Management | Atlassian, ManageEngine, SolarWinds | | **HRIS** | Human Resources systems | BambooHR, HiBob, Workday, Ceridian, Sage HR, UKG Pro | | **Knowledge Base** | Knowledge base platforms | Confluence, Notion, Freshservice, SharePoint, Simpplr | | **Software Management** | Software inventory and licensing | Torii | | **Asset Management** | IT asset management | Workwize | | **SaaS Applications** | General SaaS apps | GitHub, Monday, Zoom | | **Design** | Design and creative tools | - | | **AI** | AI and ML platforms | - | *** ### Understanding Integration Status #### Connected Status When an integration is connected, the card shows a **Connected** badge (green). For multi-instance integrations (e.g., multiple Slack workspaces), the count of instances is shown. Hover for a tooltip listing the instances. ![Integration card with Connected badge](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-7b984fef4746aca24b2e828e3baa67a13656dda8%2Fintegration-connected.png?alt=media) #### Disconnected Status When no instances exist, the integration is disconnected. There is no explicit "Disconnected" badge; the absence of "Connected" indicates it is not set up. Click **Connect** to start the setup flow. #### Deprecated Status Some integrations may be marked **Deprecated**. Deprecated integrations that are already connected can continue to work, but new configuration may be restricted. Plan to migrate to a supported alternative when available. #### Error and Syncing Status The UI does not currently display an "Error" or "Syncing" status on integration cards. Connection health is managed by the backend. If an integration stops working, disconnect and reconnect it, or check the integration's documentation for troubleshooting. *** ### Understanding OAuth Authentication Many integrations use OAuth for secure, delegated access. Harmony supports different auth types: #### What is OAuth? OAuth lets Harmony access a third-party service on your behalf without storing your password. You authorize the connection once; Harmony receives tokens to make API calls. Tokens can be refreshed automatically. #### OAuth Flow Overview ![Integration card with Connect button](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-c38bccff0379ee7650dc63298f0cff9ea3c03832%2Fintegration-connect.png?alt=media) **Standard OAuth2 flow:** 1. Click **Connect** on the integration card. 2. Harmony requests an install URL from the backend. 3. A popup window (600×700) opens the provider's authorization page. 4. Log in to the provider (if needed) and approve the requested permissions. 5. The provider redirects back; the popup closes. 6. Harmony detects the success and refreshes the integration list. A toast confirms the connection. **Descope-hosted OAuth2:** Some integrations use a Descope-managed flow. The process is similar: click Connect, complete the auth in a redirect or popup, and return to Settings. The redirect URL includes `integration-id` for context. #### Authorization Process When you authorize an integration: * The provider shows the permissions (scopes) Harmony is requesting. * Review and approve them. Without approval, the connection cannot be completed. * Some integrations may require admin approval in the provider (e.g., Slack workspace admin). #### Token Management Tokens are stored and managed by Harmony's backend (or Descope for Descope-based integrations). The UI does not expose tokens. Token refresh happens automatically. If a token expires and cannot be refreshed (e.g., revoked in the provider), disconnect and reconnect the integration. #### Understanding OAuth Scopes **Scopes** define what Harmony can do in the connected system (e.g., read users, send messages, list channels). Each integration has predefined scopes. The provider's authorization screen lists them. Harmony requests only the scopes needed for that integration's features. #### Credentials-Based Integrations Some integrations use **credentials** (e.g., API keys) instead of OAuth. For these, you enter the credentials in a configuration form after clicking Connect. Credentials are stored securely by the backend. *** ### Related Resources
Connecting IntegrationsConnect, configure, and disconnect integrationshttps://github.com/harmonyso/public-docs/blob/main/guides/connecting-and-managing-integrations/README.md
Integrations CatalogBrowse available integrationshttps://github.com/harmonyso/public-docs/blob/main/integrations/overview/README.md
User ManagementNotification destinations use connected integrationshttps://github.com/harmonyso/public-docs/blob/main/guides/managing-user-management/README.md
Knowledge BaseConnect KB sources (Confluence, Notion, etc.)https://github.com/harmonyso/public-docs/blob/main/guides/managing-knowledge-base/README.md
# Connecting and Managing Integrations Learn how to connect, configure, and manage Harmony integrations-including multi-instance integrations and disconnecting. {% hint style="info" %} **Path:** `/settings/integrations` {% endhint %} ### Connecting Your First Integration #### Prerequisites for Integration Prerequisites depend on the integration type: **Form-based (credentials)** * Prepare the required values (domain, API key, client ID/secret, etc.). The integration card or setup flow lists what you need. * **Okta** - Set up an app in the Okta Admin Console or Okta Integration Network, then provide Client ID, Client Secret, and Okta Domain. **OAuth2** * No form input before connecting. You authorize in the provider's popup. * Ensure you have admin access if the provider requires it (e.g., Slack workspace admin). **Descope OAuth2 (multi-instance)** * The integration must have an available Descope app slot. If all slots are used, you'll see "Maximum number of instances reached" and must delete an instance before adding another. #### Integration Setup Process 1. Go to **Settings** → **Integrations**. 2. Find the integration and click **Connect**. 3. Complete the flow for your integration type: * **Form-based** - Fill in the configuration form (domain, credentials, etc.) and submit. * **OAuth2** - A popup opens; log in to the provider and approve permissions. * **Descope OAuth2** - Complete the Descope flow; if the integration has post-OAuth config fields, fill those and submit. ![Settings > Integrations with integration cards](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-470e8378b6cbb525c01307c9a5f1d65fb6c7f203%2Fintegrations-connect.png?alt=media) #### Authorizing Integration Access For OAuth integrations, the provider's authorization page opens in a popup. You grant Harmony permission to access the service (users, channels, data, etc.). Harmony does not control the permission list; it is defined by the integration and provider. #### Granting Permissions Review the requested permissions on the provider's screen. Approve them to complete the connection. Without approval, the connection fails. Some providers require an admin to approve. #### Completing Connection * **Form-based** - After you submit the form, a success toast appears and the modal closes. * **OAuth2** - After you approve in the popup, the popup closes, a success toast appears, and the integration list refreshes. * **Descope with post-OAuth config** - After OAuth, a configuration form may appear. Fill it in and save to finish the connection. *** ### Configuring Integration Settings #### Understanding Integration Configuration Configuration is driven by the backend. Each integration defines **configuration fields** (e.g., text, password, select, textarea, file, email, URL). Some integrations use **plugins** that add custom UI (e.g., Confluence space picker, subdomain input for Freshservice/SolarWinds). When you open a setup modal for a supported integration, a **"For more details, visit our documentation ↗"** link appears at the top of the configuration panel. Clicking it takes you directly to the relevant docs page for that integration, so the right reference is always available without switching tabs or searching separately. This link is available across both single-instance and multi-instance integration modals. #### Configuring Integration Options 1. Open the integration (click the card or use the connect modal for a connected integration). 2. Edit the configuration fields as needed. 3. For plugins (e.g., Confluence), use the extended UI (space selection, subdomain) to set options. 4. Click **Save Changes** when done. ![Integration config modal with form fields and Save Changes](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-487bc58cce4e31ad3f5b8d6f51dc7990be063a51%2Fintegration-config-form.png?alt=media) #### Setting Integration Preferences * **Required fields** - Must be filled before saving. * **Validation** - Fields may have pattern or format checks. Errors appear on blur after a failed submit. * **Passwords/secrets** - Shown masked (`•••`) in read-only mode. Toggle visibility to view; changes require re-entering the value. * **URL fields** - Harmony automatically corrects common URL formatting issues across all integration configuration forms. URLs entered without `https://` are automatically prefixed, trailing slashes are normalized, and partial URLs (e.g., `cyera.kandji.com`) are expanded to a valid full URL. You do not need to worry about getting the exact format right. #### Post-Connection Configuration Some integrations allow configuration changes after connection. The modal shows **Save Changes** when there are unsaved edits. Saving updates the instance via the API. Read-only views show masked credentials. *** ### Using Multi-Instance Integrations #### Understanding Multi-Instance Support Some integrations support **multiple instances** (e.g., multiple Slack workspaces, multiple Okta orgs, multiple MDM providers). The integration card indicates this with a badge showing the number of connected instances. Hover over the badge to see the name of each individual instance without truncation. Multi-instance integrations use a different modal that lists instances. Multi-instance support is available for a wide range of integrations, including MDM providers such as Kandji, Jamf, JumpCloud, Intune, and Apple Business Manager (ABM), as well as Microsoft Teams, and others. Each instance is authenticated and managed independently, so device and application data from each source is tracked separately and never merged. #### Adding Multiple Integration Instances 1. Open the integration. 2. Click **Add instance** (or **Create instance**). 3. The **Instance name** field is automatically pre-filled with a suggested name based on the integration (for example, connecting Addigy pre-fills the field with "Addigy Instance"). You can edit this value before submitting, or clear it entirely - note that an empty name will be caught by validation. 4. **Form-based** - Fill in the configuration form. 5. **Descope** - Complete the OAuth flow. Each instance uses one Descope app ID; when all are used, you must delete an instance before adding another. 6. Submit. The new instance appears in the list. ![Multi-instance modal with Create instance and instance list](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-191455c9769881a6d54a9cf693f62bf42209958e%2Fmulti-instance-modal.png?alt=media) #### Managing Multiple Instances The modal lists all instances with icon, name, domain (if present), and a "Connected" badge. For each instance: * **View config** - Click to expand and see configuration (read-only when expanded). * **Delete** - Click the trash icon. Confirm in the dialog. The instance is permanently removed. #### Switching Between Instances Instances are listed in the modal. Click an instance to expand its configuration section. When the integration has config fields, the expanded view shows them (read-only). Collapse by clicking again or selecting another instance. The active instance for workflows and features is determined by context (e.g., which instance is used for a specific desk or destination). #### Connecting Multiple Microsoft Environments You can connect multiple Microsoft Teams and Intune instances to Harmony within a single tenant. Each instance is authenticated independently using its own Entra ID and OAuth credentials, so you can manage all of your Microsoft environments from a single Harmony account without any overlap between instances. #### Choosing the Right ServiceNow Connection Method When connecting ServiceNow, you will see two options in the ITSM category: **ServiceNow (OAuth)** and **ServiceNow (Service Account)**. Both options are displayed side by side to make comparison straightforward. The OAuth option displays a **Recommended** badge when it is not yet connected, helping you quickly identify the preferred setup method. The badge is automatically hidden once a connection is established. *** ### Filtering and Browsing Integrations #### Filtering by Connection Status You can filter the integrations list by connection status to quickly find what you need. Use the status filter to show only connected, disconnected, or pending integrations, rather than scrolling through the full catalog. This is especially useful when managing a large number of integrations across your workspace. #### Integration Card Layout The integrations settings page uses a compact card grid so you can see more integrations at a glance. Each card displays the vendor icon (with a consistent border for clear visual separation), the integration name, and connection status. When multiple instances are connected, a badge on the card shows the instance count - hover over it to see the individual instance names. *** ### Disconnecting Integrations #### Disconnecting an Integration **Single-instance** 1. Open the integration modal. 2. Click **Disconnect** in the footer. 3. Confirm in the dialog ("Are you sure you want to disconnect..."). 4. The instance is deleted. The modal closes and a success toast appears. **Multi-instance** 1. Open the integration modal. 2. Click the trash icon next to the instance you want to remove. 3. Confirm in the dialog ("Are you sure you want to delete this instance..."). 4. The instance is deleted. The list updates; the modal stays open. You can also remove an installed app from your workspace entirely from the integrations settings page. The uninstall process cleanly removes credentials and provider connections, and changes take effect immediately. #### Understanding Disconnection Impact * **Permanent** - The instance is deleted. There is no undo. * **Dependent features** - Notification destinations, Knowledge Base sources, workflows, and other features that use this instance will stop working. Fix them by reconnecting or switching to another instance. * **Asset and application data preserved** - Deleting an integration no longer removes the asset records or application data collected through it. All records - including any manual enrichments such as purchase info, assignee details, license information, or custom fields - remain visible and fully accessible in your dashboard after disconnection. * **Software discovery** - When an integration is deleted, all associated software discovery data is cleanly removed to keep your workspace free of stale or orphaned records. When a new identity provider integration is connected, application discovery is automatically triggered so newly accessible applications are detected right away. #### Reconnecting After Disconnection To use the integration again: 1. Go to **Settings** → **Integrations**. 2. Open the integration and click **Connect** (or **Add instance** for multi-instance). 3. Complete the setup flow (form or OAuth) as if connecting for the first time. 4. Reconfigure any dependent features (notifications, KB sources, etc.) to use the new instance. *** ### Related Resources
Integration Sync & CredentialsBidirectional sync, credentials, and securityhttps://github.com/harmonyso/public-docs/tree/main/guides/configuring-integration-sync-and-credentials/README.md
Understanding IntegrationsIntegration categories, status, and OAuthhttps://github.com/harmonyso/public-docs/tree/main/guides/understanding-integrations/README.md
Integrations CatalogBrowse available integrationshttps://github.com/harmonyso/public-docs/tree/main/integrations/overview/README.md
Ticket SettingsSet up notification channelshttps://github.com/harmonyso/public-docs/tree/main/guides/managing-ticket-settings/README.md
Knowledge BaseAdd KB sources from integrationshttps://github.com/harmonyso/public-docs/tree/main/guides/managing-knowledge-base/README.md
# Configuring Integration Sync and Credentials Learn how to configure bidirectional sync, update integration credentials, and manage credential security. {% hint style="info" %} **Path:** `/settings/integrations` {% endhint %} ### Configuring Sync Settings #### Understanding Sync Settings Some integrations support **outbound sync** - sending data from Harmony to the connected system (e.g., creating or updating tickets in Freshservice or SolarWinds). When enabled, Harmony can sync ticket data bidirectionally with the ITSM. #### Default Sync Settings by ITSM Integration When you connect an ITSM integration, Harmony automatically applies sensible default sync settings based on the specific tool you are connecting - no manual configuration is required to get started. Each vendor ships with defaults tailored to its typical use case: | Integration | Default Sync Settings | | --------------------------------- | ---------------------------------------------- | | **ServiceNow** | Import, export, and outbound sync all disabled | | **Jira** | Export and outbound sync enabled | | **Jira Service Management (JSM)** | Import enabled | | **Freshservice** | Import enabled | | **SolarWinds** | Import enabled | These defaults are applied automatically the moment the integration is connected. You can adjust them at any time from the integration configuration panel. #### Configuring Sync Frequency Sync frequency and schedule are managed by the backend. There is no UI to configure sync interval or timing. Sync runs according to the integration's default or backend configuration. #### Automatic Sync After Configuration Changes When you add or update a connected integration, Harmony automatically triggers data collection from the configured third party. This means your MDM, HRIS, and other connected platforms stay in sync without requiring any manual action after setup. Changes to your integrations take effect immediately, triggering the appropriate data flows in the background as soon as the configuration is saved. #### Understanding Bidirectional Sync **Bidirectional synchronization** means Harmony and the connected system can both create and update items (e.g., tickets). Data flows from Harmony to the ITSM and, when applicable, from the ITSM back to Harmony. This keeps tickets in sync across systems. #### Enabling Sync For integrations that support it (e.g., Freshservice, SolarWinds): 1. Open the integration and complete the connection (subdomain, credentials). 2. Find the **Bidirectional synchronization** toggle in the configuration. 3. Turn the toggle **on** to enable outbound sync. 4. Click **Save Changes** to confirm. The toggle does not apply instantly - your changes take effect only after saving. {% hint style="info" %} You can toggle sync on or off alongside other configuration changes (such as switching desks in JSM) and save everything at once. Closing the settings panel without saving will discard any unsaved toggle changes. {% endhint %} ![Bidirectional sync toggle in integration config](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-1205403b8e5fe29be85bad7425f6ba5d1e31fb86%2Fsync-toggle.png?alt=media) #### Disabling Sync Turn the **Bidirectional synchronization** toggle **off** and click **Save Changes** to stop Harmony from syncing data to the connected system. Inbound sync (from the ITSM to Harmony) may still occur depending on the integration. *** ### Monitoring Sync Status #### Understanding Sync Status Indicators The integration card and modal show **Connected** when the integration has at least one instance. Multi-instance integrations show the instance count. There is no dedicated sync-status indicator (e.g., "Syncing", "Last synced") in the integration settings. Sync runs in the background. ![Integration cards showing Connected state](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-877d2c4210f123d7f14d4733a0fb1b2f061205b6%2Fintegration-status.png?alt=media) #### Viewing Last Sync Time Last sync time is not displayed in the integration configuration UI. Some areas (e.g., Software Management) may show sync-related timestamps in their own views. Check the connected system or Harmony logs for sync activity if needed. #### Understanding Sync Progress Sync progress is not shown in the integration settings. Sync runs asynchronously. If sync fails, check the integration's configuration (credentials, permissions) and reconnect if necessary. #### Resilient Sync for Customer and Contact Data Harmony uses permissive parsing when syncing data from connected platforms. Previously, a single unexpected or malformed record could interrupt an entire sync. Now, Harmony processes as much data as possible and skips only records it cannot interpret, rather than halting the sync altogether. This means your customer and contact data stays more consistently up to date, even when source data contains irregularities. #### Recovery After Provider Outages Harmony is designed to recover from third-party provider outages without leaving data integrations permanently stuck: * **Extended retry window** - The maximum number of retries has been increased, giving integrations approximately 11 hours to recover from an outage rather than around 1 hour 15 minutes. * **Automatic cursor reset** - If a sync poll becomes stuck on a specific failing page (a "poison cursor"), Harmony automatically resets the cursor so the sync can continue from a clean state. #### Manually Syncing Identity Provider Groups You can trigger a manual sync of your identity provider (IDP) groups directly from the app access resource creation modal, without waiting for the next scheduled refresh. This makes any recent group changes in your IDP - such as new groups or membership updates - immediately available to select when configuring access. The sync runs as a tracked background job, so you can see its status and know when the latest group data is ready to use. #### Troubleshooting Sync Issues **Common causes of sync failure** * Invalid or expired credentials * Insufficient permissions in the connected system * Network or API errors * Integration disconnected or misconfigured **Steps** 1. Verify the integration shows **Connected**. 2. Open the integration and check that credentials are valid (re-enter if needed). 3. Ensure the connected system grants the required permissions (scopes, API access). 4. Disconnect and reconnect the integration to refresh tokens or re-authorize. 5. Check backend logs or support for specific error details. ![Integration modal with credential fields](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-f25bdd23acda782fc1dde3f05bb19e2ff87a4a78%2Fintegration-credentials-modal.png?alt=media) *** ### Understanding Integration Permissions #### Understanding Permission Requirements Integrations need permission to access the connected system. Requirements depend on the integration: * **OAuth** - Permissions (scopes) are requested during the authorization flow. The provider shows what Harmony is asking for. * **Credentials** - API keys, tokens, or admin access may be required. The integration form or documentation lists what you need. #### Viewing Required Permissions OAuth integrations request scopes during the connect flow. The provider's authorization screen lists them. There is no separate UI in Harmony to view or modify granted scopes. For credentials-based integrations, required fields are shown in the configuration form (e.g., API key, domain). #### Managing Permission Grants * **OAuth** - To change permissions, disconnect and reconnect. You may need to revoke access in the provider first, then reconnect to request new scopes. * **Credentials** - Update the configuration form and save. New credentials take effect when saved. #### Understanding Permission Scopes Scopes define what Harmony can do (e.g., read users, create tickets, list channels). Each integration has predefined scopes. Harmony requests only what it needs. If an integration fails with a permission error, the provider may require additional scopes - reconnect and approve the updated request. *** ### Managing Integration Credentials #### Understanding Credential Management Credentials are stored securely by Harmony's backend with encryption at rest, ensuring that sensitive authentication data such as API keys and tokens is protected with an additional layer of security. This applies automatically to all integrations - no action is required on your part. The UI does not display raw credentials. Passwords, API keys, tokens, and other secrets are obfuscated by default, so only a masked version is shown (`•••`). This reduces the risk of accidentally exposing credentials when sharing your screen, taking screenshots, or granting temporary access to your Settings page. You can update credentials by editing the integration configuration. #### Labelling Credentials for Easy Identification You can add an optional label to your integration credentials, making it easier to identify and manage multiple credential sets at a glance. This is especially useful when you have several credentials configured for the same integration type - for example, different accounts, environments, or teams. Simply provide a custom label when creating or updating a credential to keep your integrations organised. #### Updating Integration Credentials 1. Open the integration (Settings - Integrations - *integration*). 2. For connected instances, configuration may be read-only. To update credentials: * If the integration allows post-connection config: edit the fields and click **Save Changes**. * If credentials are locked: disconnect and reconnect with new credentials. 3. Enter new values (API key, password, etc.). Password fields support show/hide. 4. Optionally add or update the credential **label** so it remains easy to identify. 5. Save. The new credentials are used for subsequent API calls. #### Rotating API Keys There is no dedicated rotation flow in the UI. To rotate an API key: 1. Generate a new key in the connected system. 2. Open the integration configuration. 3. Replace the existing key with the new one and save. 4. Revoke the old key in the connected system after confirming the integration works. #### Managing OAuth Tokens OAuth tokens are managed by the backend. The UI does not expose tokens. Refresh happens automatically. If a token expires or is revoked: * The integration may show as connected but API calls will fail. * Disconnect and reconnect to obtain a new token. * In the provider, revoke the old app connection if desired before reconnecting. #### Credential Security Best Practices * **Minimal permissions** - Grant only the scopes or access the integration needs. * **Secure storage** - Credentials are encrypted at rest by Harmony. Do not share them outside the configuration flow. * **Obfuscation** - Credentials are masked in the UI by default, reducing the risk of accidental exposure. * **Rotation** - Rotate API keys periodically and when personnel changes. * **Revocation** - If credentials are compromised, revoke them in the provider and update the integration in Harmony. * **Access control** - Limit who can view and edit integration settings (via role permissions). * **Labels** - Use credential labels to clearly distinguish between accounts, environments, or teams, especially in complex workspaces. *** ### Related Resources
Understanding IntegrationsIntegration categories and OAuthhttps://github.com/harmonyso/public-docs/tree/main/guides/understanding-integrations/README.md
Connecting IntegrationsConnect and configure integrationshttps://github.com/harmonyso/public-docs/tree/main/guides/connecting-and-managing-integrations/README.md
Ticket SettingsNotification channels use integrationshttps://github.com/harmonyso/public-docs/tree/main/guides/managing-ticket-settings/README.md
# Configuring Application Health Notifications Harmony can send real-time notifications to Slack or Microsoft Teams whenever a monitored application's health status changes. Instead of checking the dashboard manually, your team receives alerts the moment an outage begins, worsens, recovers, or has an incident-level update. Notification rules are flexible, letting you configure two independent alert types for each rule so you only receive the signals that matter to your team. ### Alert types Each notification rule supports two independently configurable alert types: * **Overall status change alerts** - Triggered when an application transitions between health states, for example from Operational to Major Outage, or from Partial Outage back to Operational. These alerts also fire when a newly detected application is first seen in a non-operational state. * **Incident-level update alerts** - Triggered when individual incidents within a monitored application are created, updated, or resolved. You can enable either or both alert types on a single rule, giving you fine-grained control over notification volume. ### Prerequisites Before configuring notifications, make sure you have: * A Slack channel with an active incoming webhook, or a Microsoft Teams channel with an incoming webhook connector configured. * Access to the Harmony Settings area. ### Configuring a notification rule 1. In Harmony, open **Settings** and navigate to the **Notifications** section. 2. Click **Add notification rule**. 3. Choose your notification channel type - either **Slack** or **Microsoft Teams**. 4. Enter the **Webhook URL** for your chosen channel. 5. Select the applications you want this rule to monitor. You can select one application, multiple applications, or all monitored applications. 6. Under **Alert types**, enable one or both of the following: * **Overall status change** - to receive alerts when an application's top-level health state changes. * **Incident-level updates** - to receive alerts when individual incidents are created, updated, or resolved. 7. Click **Save** to activate the rule. Repeat these steps to create additional rules, for example to route critical application alerts to one Slack channel and incident-level updates to a separate Teams channel. ### Editing or removing a notification rule 1. In **Settings**, navigate to the **Notifications** section. 2. Locate the rule you want to change and click **Edit**. 3. Update any fields as needed and click **Save**, or click **Delete** to remove the rule entirely. Deleting a rule stops all notifications associated with it immediately. Existing incident history and application health data are not affected. ### Notification behavior reference | Scenario | Overall status change alert | Incident-level update alert | | ------------------------------------------------- | --------------------------- | --------------------------- | | App moves from Operational to Partial Outage | Sent | Not sent | | App moves from Partial Outage to Major Outage | Sent | Not sent | | App recovers to Operational | Sent | Not sent | | New app first detected in a non-operational state | Sent | Not sent | | Individual incident created on an app | Not sent | Sent | | Individual incident updated | Not sent | Sent | | Individual incident resolved | Not sent | Sent | ### Tips for reducing notification noise * Enable only **Overall status change** alerts for applications where you care about the headline status but not every incremental incident update. * Create separate rules for different teams or escalation paths rather than adding all recipients to a single webhook. * Use Microsoft Teams channel threading or Slack notification preferences to control how alerts surface for individual team members. # Broadcasting and Sending Company-Wide Announcements Harmony lets you create and send company-wide announcements directly from the platform, reaching employees through the channels they already use - including Slack, Microsoft Teams, email, and the self-service portal. You can target specific individuals, departments, locations, or user groups, and choose to publish immediately or schedule delivery for a later time. This article explains how to create announcements, configure delivery settings, and manage your announcement history. *** ### Announcement types When creating an announcement, you select a type that helps employees understand the context at a glance. The available types are: * **Outage** - Notify employees of a current or upcoming service disruption. * **Maintenance** - Communicate planned maintenance windows. * **What's New** - Highlight new features, tools, or process changes. * **Event** - Promote upcoming company or team events. * **Tutorial** - Share instructional content or how-to guidance. *** ### Delivery channels Announcements can be delivered through one or more of the following channels: * **Slack** - Delivered as a direct message or channel post, with rich text formatting rendered natively. * **Microsoft Teams** - Delivered as a direct message or channel post. * **Email** - Sent directly to employee inboxes, with bold, italic, and hyperlink formatting preserved. * **Self-service portal** - Displayed as a banner within the Harmony employee portal. You can select multiple delivery channels for a single announcement to ensure broad reach. *** ### Targeting your audience You can control exactly who receives an announcement. Harmony supports the following audience options: * **All employees** - Broadcast to your entire organization. * **Specific employees** - Select individual employees by name. * **Departments** - Target one or more departments. * **Locations** - Deliver to employees in specific office locations or regions. * **User groups** - Send to any defined user group configured in Harmony. Selecting a combination of these options lets you reach the right people without over-communicating to those who are not affected. *** ### Formatting announcements The announcement composer supports rich text formatting so your messages are clear and visually consistent across all channels: * **Bold** - Emphasize key information. * **Italic** - Add context or highlight terms. * **Hyperlinks** - Link to relevant resources, tickets, or documentation. Formatting renders natively in each destination channel, so a bold phrase in Slack appears bold in the Slack message, and the same is true in Teams and email. *** ### Creating and sending an announcement 1. Navigate to **Settings** in the Harmony Admin console. 2. Select **Announcements**. 3. Click **New Announcement**. 4. Choose an **announcement type** from the available options. 5. Write your message using the rich text composer. Apply bold, italic, or hyperlinks as needed. 6. Under **Audience**, select the employees, departments, locations, or user groups you want to reach. 7. Under **Delivery channels**, choose one or more channels - Slack, Teams, email, or portal banner. 8. Choose a delivery option: * **Send now** - The announcement is delivered immediately. * **Schedule** - Pick a future date and time for delivery. 9. Optionally, set an **expiration date** so the announcement is automatically retired after a specified date. This is particularly useful for time-sensitive notices such as outages or maintenance windows. 10. Click **Send** or **Schedule** to confirm. *** ### Scheduling and expiration * **Scheduled announcements** are queued and delivered at the date and time you specify. You can edit or cancel a scheduled announcement before it goes out. * **Expiration dates** automatically retire an announcement on the date you choose. After expiration, portal banners are removed and the announcement is marked as expired in the Admin console. This helps keep the portal and communication channels free of outdated information. *** ### Viewing announcement history All announcements - whether sent, scheduled, or expired - are recorded in the **Announcements** section of the Admin console. The history view includes: * **Announcement title and type** * **Status** - Sent, Scheduled, or Expired * **Audience** - The targeted groups or individuals * **Delivery channels** used * **Send date and expiration date** Use the history view to audit past communications, review who received a specific announcement, or reference previously shared information. *** ### Permissions Only **Harmony Admins** can create, send, schedule, or manage announcements. Standard users and managers do not have access to the Announcements settings. # Configuring Email Domains and DKIM Verification By default, Harmony sends email notifications from `notifications@harmony.io`. You can replace this with your own custom email domain so that your end users receive notifications from an address they recognize and trust. This guide explains how to add a custom email domain, complete DKIM verification, and manage your configured domains. ### How it works When you add a custom domain, Harmony generates a set of DKIM DNS records that you must add to your domain provider. Once those records propagate, you run a verification check inside Harmony. After a domain is verified, Harmony uses it as the sending address for all outbound email notifications. ### Adding a custom email domain 1. Go to **Settings** and open the **Email Domains** section. 2. Click **Add Domain**. 3. Enter your domain name (for example, `support.yourcompany.com`) and confirm. 4. Harmony generates the DKIM DNS records required for your domain. Copy these records. 5. Log in to your domain provider and add the DKIM records to your domain's DNS configuration. 6. Return to Harmony and click **Verify** to run the verification check. During verification, Harmony checks each DNS record individually and displays a per-record status in real time so you can see exactly which records have propagated and which are still pending. ### Understanding domain verification status Each domain in your domains table shows one of the following statuses: | Status | Description | | -------------- | --------------------------------------------------------------------------------------------- | | **Verified** | All DKIM records were detected successfully. Harmony can send notifications from this domain. | | **Unverified** | One or more DKIM records could not be detected. DNS changes may still be propagating. | | **Pending** | Verification has not been run yet for this domain. | ### Retrying DKIM verification DNS changes can take time to propagate, so verification may not succeed immediately after you add the records to your provider. If verification fails, you do not need to contact support - you can retry directly from the domains table. To retry verification: 1. Locate the domain in the **Email Domains** table. 2. Click the **Retry Verification** option next to the domain. 3. Harmony re-checks all DNS records and updates the per-record status in real time. Repeat this step as needed until your DNS changes have fully propagated and all records show a verified status. ### Managing configured domains The **Email Domains** table gives you a central view of every domain you have configured. From this table you can: * See the current verification status of each domain at a glance. * Retry verification for any domain that is not yet verified. * Add additional domains if you need to support multiple sending addresses. ### Tips for successful verification * DNS propagation can take anywhere from a few minutes to 48 hours depending on your provider and your TTL settings. * Double-check that each DKIM record was saved exactly as shown in Harmony - extra spaces or missing characters are a common cause of failed checks. * If your provider has a DNS cache, wait for it to clear before retrying verification. * Some providers require DKIM records to be entered in a specific format (for example, splitting long TXT record values). Consult your provider's documentation if a record fails repeatedly. # Configuring the Service Desk Agent The Service Desk Agent is a conversational AI assistant that handles employee requests across your organisation. It greets employees, gathers context about their issues, and routes or escalates requests to the right team - whether that is IT, HR, facilities, finance, security, or any other department you support. This article explains how to configure the Service Desk Agent so it reflects your organisation's structure, tone, and service scope. *** ### What the Service Desk Agent does The Service Desk Agent acts as the first point of contact for employees who need workplace support. It is designed to work across all departments, not just IT. When an employee starts a conversation, the agent: * Introduces itself as a multi-department service assistant covering IT, HR, facilities, finance, security, and other areas * Asks clarifying questions to understand the nature of the request * Routes the request to the appropriate desk or team * Escalates to a human support team when the issue cannot be resolved automatically Because the agent operates across your entire workplace service platform, employees only need one place to go for any kind of support request. *** ### Accessing the Service Desk Agent settings 1. Open **Settings** in your Harmony dashboard. 2. Select **Service Desk Agent** from the left-hand navigation. From this page you can configure the agent's identity, introduction message, department coverage, routing rules, and escalation behaviour. *** ### Configuring the agent identity The agent identity controls how the assistant presents itself to employees at the start of a conversation. #### Display name Enter the name employees will see when the agent responds. This can be a neutral name such as "Service Desk" or a custom name that fits your organisation's branding. #### Introduction message The introduction message is the first thing employees see when they open a conversation. It should make clear that the agent covers all departments, so employees know they can raise any kind of workplace request. A recommended starting point: > "Hi, I'm your workplace service assistant. I can help you with requests across IT, HR, facilities, finance, security, and more. What can I help you with today?" You can edit this message to match your organisation's tone. Keep the list of departments accurate so employees are not directed to the agent for services it does not cover. *** ### Configuring department coverage The agent supports requests across multiple departments out of the box. You can control which departments are active and how each one is labelled. #### Enabling or disabling departments Use the department toggles to turn coverage on or off for each area. Departments available by default include: * IT * HR * Facilities * Finance * Security If your organisation uses different naming conventions - for example "People Operations" instead of "HR" - you can rename each department using the **Label** field next to the toggle. The agent will use your custom labels when introducing itself and when confirming which team it is routing a request to. #### Adding custom departments To add a department that is not listed by default: 1. Scroll to the bottom of the department list and select **Add department**. 2. Enter a name for the department. 3. Configure its routing destination (see Routing rules below). 4. Save your changes. *** ### Configuring routing rules Routing rules determine which team or queue receives a request after the agent has gathered enough context to categorise it. #### How routing works The agent uses the content of the conversation to match the request to a department. Once a match is made, it confirms the routing with the employee using language such as: > "I'll send this to the Facilities team now. They'll be in touch shortly." The routing confirmation messages reference your configured department labels automatically, reinforcing that support is available across the whole workplace service platform. #### Setting a routing destination For each active department, you can specify: * **Queue or team name** - the internal queue or team the request is sent to * **Routing confirmation message** - the message shown to the employee when their request is routed (optional, overrides the default) To edit a routing destination: 1. Select the department from the list. 2. Under **Routing**, enter the target queue or team name. 3. Optionally edit the routing confirmation message. 4. Save your changes. *** ### Configuring escalation behaviour When the agent cannot resolve a request or the employee asks to speak to a person, the agent escalates the conversation to a human agent. Escalation messages are written to refer to the relevant support team rather than a specific department, so they remain accurate regardless of which department is handling the request. #### Default escalation message The default message employees see when a conversation is escalated is: > "I'm connecting you with a member of the support team now. Please hold on." You can customise this message in the **Escalation** section of the agent settings. Avoid replacing "support team" with a single department name unless the agent is scoped to that department only, as it may cause confusion for employees raising requests in other areas. #### Escalation triggers You can configure the conditions that trigger an escalation. Available triggers include: * Employee explicitly requests a human * Agent confidence falls below a set threshold * Request type is marked as always-escalate for a specific department * Conversation reaches a maximum number of turns without resolution To adjust triggers, select **Escalation triggers** and enable or disable each option as needed. *** ### Testing the agent configuration Before making changes live, use the built-in preview tool to test how the agent behaves. 1. In the Service Desk Agent settings, select **Preview**. 2. Type a sample request in the conversation window. 3. Confirm that the agent introduces itself correctly, routes to the expected department, and uses the right escalation language. Test at least one request per active department to make sure routing and messaging are consistent across all areas. *** ### Saving and publishing changes Changes to the Service Desk Agent configuration are saved as a draft until you publish them. This means you can make multiple edits before any of them go live. * Select **Save draft** to store your changes without publishing. * Select **Publish** to make the current configuration live for all employees. Published changes take effect immediately. There is no additional deployment step required. # Configuring Welcome Notifications for SCIM-Provisioned Users When you provision users in Harmony through SCIM (via identity providers such as Okta, Microsoft Entra, or similar), those users can now receive a welcome notification automatically - no manual outreach required. Within approximately 60 seconds of being provisioned, each new user gets a welcome message delivered through your chosen channel. This feature is managed from **Settings → General** and gives you full control over whether notifications are sent and what they say. *** ### How it works When an IT admin adds a user through their identity provider, Harmony detects the new SCIM-provisioned account and triggers a welcome notification on your behalf. The notification is delivered within approximately 60 seconds of provisioning completing. Welcome notifications can be delivered through any of the following channels: * **Email** * **Slack** * **Microsoft Teams** The delivery channel reflects the integrations you have active in your Harmony workspace. *** ### Enabling or disabling welcome notifications By default, you can turn this feature on or off at any time from the General settings page. 1. Go to **Settings → General**. 2. Locate the **Welcome Notifications** section. 3. Toggle the feature on or off using the enable/disable control. Changes take effect immediately. Users who are provisioned after you disable the feature will not receive a welcome notification until you re-enable it. *** ### Customizing the welcome message You can tailor the subject line and body of the welcome message to match your organization's tone and onboarding needs. 1. Go to **Settings → General**. 2. Locate the **Welcome Notifications** section. 3. Click the message customization area to edit: * **Subject** - the subject line displayed in email notifications or the heading shown in Slack and Teams messages. * **Body** - the main content of the welcome message. You can include instructions, links to onboarding resources, or any other information new users need on day one. 4. Save your changes. Any users provisioned after you save will receive the updated message. *** ### Considerations * Welcome notifications are triggered only for users provisioned through SCIM. Users added manually through the Harmony admin console are not affected by this setting. * If a user is deprovisioned and later re-provisioned, the welcome notification is sent again. * Make sure your Slack or Microsoft Teams integration is connected and healthy before relying on those channels for delivery. If the integration is disconnected at the time of provisioning, the notification may not be delivered. * Review your welcome message content periodically to ensure links and instructions stay current. # Customizing the Self-Service Portal and AI Bot Branding Harmony lets you shape how both the self-service portal and the AI bot appear to your end users. From a single **Branding** section in Settings, you can align the portal's visual style with your organisation's identity and give the AI bot a name and avatar that feel native to your team's Slack or Microsoft Teams environment. *** ### Customising the Self-Service Portal #### Accessing Portal Branding Settings 1. Open **Settings** from the main navigation. 2. Go to **Portal Preferences** (or the **Branding** section, depending on your view). 3. Look for the portal appearance options described below. #### Available Options **Accent Colour** Set a portal accent colour to match your brand palette. This colour is applied to key interactive elements across the self-service portal, giving users a consistent branded experience. To set the accent colour: 1. Click the colour picker or enter a hex value in the accent colour field. 2. Select your desired colour. 3. Save your changes - the new colour takes effect immediately for anyone accessing the portal. **Background Image** Upload a background image to personalise the visual experience of your self-service portal. This image appears behind the main portal interface, giving you further control over the look and feel. To upload a background image: 1. Click **Upload** next to the background image option. 2. Select an image file from your device. 3. Save your changes - the image is applied instantly. {% hint style="info" %} Branding changes to the portal take effect immediately. No republishing or cache-clearing is required. {% endhint %} *** ### Customising the AI Bot's Name and Avatar You can personalise how the Harmony AI bot presents itself to your team in Slack or Microsoft Teams. These settings are managed from the **Branding** section of the Settings page. #### Accessing Bot Branding Settings 1. Open **Settings** from the main navigation. 2. Select the **Branding** section. 3. Configure the options described below. #### Available Options **Custom Bot Name** Rename the bot from the default "Harmony AI" to any name that fits your organisation or team culture. To set a custom name: 1. Click the bot name field under **Branding**. 2. Clear the existing name and type your preferred bot name. 3. Save your changes. **Custom Avatar** Upload your own logo or image to replace the default bot avatar. **Requirements for the avatar image:** * Minimum size: **512 x 512 pixels** * The image must be **square** To upload a custom avatar: 1. Click **Upload** next to the avatar field. 2. Select an image file that meets the size and shape requirements. 3. Save your changes. **Channel or Team Scoping** Rather than applying customisations globally, you can target specific Slack channels or Microsoft Teams teams. This lets different groups see a differently branded bot if needed. To apply a scoped customisation: 1. In the **Branding** section, locate the scope selector. 2. Choose the specific Slack channel or MS Teams team you want to target. 3. Configure the bot name and avatar for that scope. 4. Save your changes. **Multiple Scopes** You can configure different bot appearances for multiple channels or teams simultaneously. To add another scope: 1. Click the **Add scope** button. 2. Select the additional channel or team. 3. Set the desired bot name and avatar for that scope. 4. Save your changes. Each scope is managed independently, so you can maintain distinct branding configurations side by side. {% hint style="info" %} If no scope is specified, the bot name and avatar settings apply globally across all connected channels and teams. {% endhint %} *** ### Summary of Branding Options | Setting | Where to Configure | Applies To | | ----------------------- | ----------------------------- | ----------------------------------------- | | Portal accent colour | Settings - Portal Preferences | Self-service portal | | Portal background image | Settings - Portal Preferences | Self-service portal | | Bot name | Settings - Branding | Slack / MS Teams bot | | Bot avatar | Settings - Branding | Slack / MS Teams bot | | Channel or team scope | Settings - Branding | Specific Slack channels or MS Teams teams | # Managing API Access Keys API access keys let you authenticate with Harmony's external API so you can build integrations, automate workflows, and connect third-party tools to your account without manual intervention. Instead of using your personal credentials, you generate a dedicated key that external systems use to identify and authorize their requests. This article explains how to create, view, and manage your API access keys. *** ### How API Access Keys Work Each access key acts as a credential that grants programmatic access to your Harmony account and data. When an external system - such as a custom integration or an automation tool - makes a request to the Harmony API, it includes the access key to prove it is authorized to do so. Because access keys are separate from your personal login credentials, you can: * Revoke a key at any time without affecting your account password or other keys. * Create multiple keys for different integrations or use cases. * Limit the blast radius of a compromised key by rotating or deleting it independently. *** ### Creating an API Access Key 1. Navigate to **Settings** in the main navigation. 2. Select the **API Access Keys** section. 3. Click **Create Access Key** (or **New Key**, depending on your account view). 4. Give the key a descriptive name so you can identify its purpose later - for example, `Zapier Integration` or `Data Export Script`. 5. Click **Create**. 6. Copy the key value that appears on screen. This is the only time the full key is displayed. Store it somewhere secure, such as a password manager or secrets vault, before closing the dialog. > **Important:** Once you close the creation dialog, the full key value cannot be retrieved again. If you lose it, you will need to delete the key and create a new one. *** ### Viewing Your Access Keys All existing access keys are listed in **Settings > API Access Keys**. For each key you can see: * The key name you assigned. * The date it was created. * The date it was last used (if available). The full key value is never shown again after creation, so only the metadata above is visible in the list. *** ### Deleting an Access Key When you no longer need a key - or if you suspect it has been compromised - delete it immediately. 1. Go to **Settings > API Access Keys**. 2. Locate the key you want to remove. 3. Click the **Delete** (or trash icon) button next to it. 4. Confirm the deletion when prompted. Once deleted, any system still using that key will receive authentication errors. Update or remove the key from all external tools before or shortly after deleting it. *** ### Best Practices * **Use one key per integration.** This makes it easy to revoke access for a single tool without disrupting others. * **Rotate keys periodically.** Create a new key, update your integration, then delete the old key on a regular schedule. * **Never commit keys to source code.** Store them in environment variables or a secrets management service. * **Delete unused keys.** If an integration is decommissioned, remove its key right away to reduce unnecessary access. *** ### Next Steps Once you have an access key, refer to the Harmony API documentation for details on how to include it in your requests, the available endpoints, and the data you can read or write programmatically. # Managing Custom Fields Custom fields let you capture and track information that is specific to your organization - details that go beyond the standard fields built into Harmony. You can add custom fields to Assets, Employees, and Requests, and manage all of them from a single location in your settings. This article explains how to create and manage custom fields, where they appear across the product, and how to use them in list views and detail pages. *** ### Field Management Settings Page All custom fields across Assets, Employees, and Requests are managed from one place: the **Field Management** settings page. To access it: 1. Go to **Settings** in the main navigation. 2. Select **Field Management**. From this page you can view, create, edit, and delete custom fields for all three entity types. Each entity type has its own tab - **Assets**, **Employees**, and **Requests** - so you can quickly find and manage the fields that belong to each section without leaving the page. Custom field forms are consistent across entity types, so the configuration experience is the same whether you are setting up a field for an asset, an employee record, or a request. *** ### Adding a Custom Field To add a new custom field: 1. Open **Settings** and navigate to **Field Management**. 2. Select the tab for the entity type you want to configure - **Assets**, **Employees**, or **Requests**. 3. Click **Add Field**. 4. Fill in the field details: * **Field name** - the label that will appear on records and in table columns. * **Field type** - choose from options such as text, number, date, or single-select. 5. Save the field. The field becomes available immediately on list tables and detail pages for that entity type. *** ### Editing and Deleting Custom Fields To edit an existing custom field, open **Field Management**, locate the field in the relevant tab, and select **Edit**. You can update the field name and other configuration options. To delete a custom field, select **Delete** next to the field. Deleting a field removes it from all records and list views, so make sure you no longer need the data stored in that field before removing it. *** ### Custom Fields in List Tables Once you have created custom fields, they appear as columns in the asset and employee list tables. These columns support both sorting and filtering, so you can organize and narrow down large lists using the values your team has entered. * **Sorting** - click a custom field column header to sort the list by that field. Sorting works for text, number, and date field types. * **Filtering** - use the filter controls to filter records by a custom field value, including equality and range filters for number and date fields. Performance is optimized so that sorting and filtering on custom fields is near-instant, even for organizations with very large record sets. Sorting is up to **335x faster** and filtering is up to **519x faster** compared to previous behavior, so large list views feel responsive regardless of how many records you have. *** ### Custom Fields on Detail Pages Custom fields also appear on the detail page for each asset and employee record. They are grouped in a dedicated **Custom Fields** section, separate from the standard built-in fields. You can edit custom field values directly on the detail page using inline editing - click a value to update it without navigating away from the record. *** ### Supported Field Types The following field types are supported for custom fields across Assets, Employees, and Requests: | Field Type | Sortable | Filterable | | ------------- | -------- | ---------- | | Text | Yes | Yes | | Number | Yes | Yes | | Date | Yes | Yes | | Single-select | Yes | Yes | Performance improvements for sorting and filtering apply automatically to all supported custom field types. No additional configuration is required. *** ### Tips * Use the **Field Management** page as your single source of truth for all custom field configuration. You do not need to visit separate settings sections for Assets, Employees, or Requests. * Custom field columns in list tables are optional - you can show or hide them using the column picker to keep your views focused on the data that matters most to your team. * If you need to capture the same type of information across multiple entity types, create the field separately under each relevant tab in **Field Management**. # Managing Secrets and Credentials The Secret Manager gives you a central, secure place to store API keys, passwords, tokens, and other sensitive credentials that your agents depend on. Instead of hardcoding sensitive values directly into agent steps, you define them once in the Secret Manager and reference them by name wherever they are needed. Secrets are encrypted at rest and resolved securely at runtime, so the plaintext value is never exposed in your agent configuration. ### How it works When you save a secret, Harmony encrypts and stores the value separately from your agent definitions. When an agent runs, the runtime resolves the secret reference and injects the value at that moment - the plaintext never appears in your agent configuration, logs, or exports. You reference a secret inside an agent step using its name. If you later rotate the underlying value, every agent that references that secret automatically picks up the new value the next time it runs, with no edits required to the agents themselves. ### Accessing the Secret Manager 1. Open **Settings** from the main navigation. 2. Select **Secret Manager** from the Settings menu. The Secret Manager is accessible across all Harmony modules, so the same credentials can be shared between agents without duplication. ### Adding a secret 1. In the Secret Manager, click **Add Secret**. 2. Enter a unique **Name** for the secret. This is the identifier you will reference inside your agents, so choose a clear, descriptive name (for example, `payment_api_key` or `crm_bearer_token`). 3. Enter the **Value** - the actual credential or sensitive string you want to store. 4. Click **Save**. The value is encrypted immediately on save. After saving, the plaintext value is no longer displayed in the interface. ### Rotating a secret Rotating a secret updates its stored value without changing its name. Because agents reference secrets by name, they automatically use the new value on their next run. 1. Find the secret you want to rotate in the Secret Manager list. 2. Click **Edit** next to that secret. 3. Enter the new value. 4. Click **Save**. All agents that reference this secret will now resolve to the updated value at runtime. ### Deleting a secret Before deleting a secret, check its usage count to understand which agents depend on it. Deleting a secret that is still referenced by active agents will cause those agents to fail at runtime. 1. Find the secret in the Secret Manager list. 2. Review the **Used in** count to see how many agents currently reference it. 3. Click **Delete** and confirm the action. ### Tracking secret usage Each secret in the Secret Manager displays a usage count showing how many agents are currently referencing it. Use this information to: * Identify unused secrets that can be safely removed. * Understand the blast radius before rotating or deleting a credential. * Audit which agents depend on a particular third-party service. ### Using secrets in Agent Builder Secrets are available inside the **HTTP Request** block in Agent Builder. Instead of entering a raw credential value into a header or parameter field, you select the secret by name from the available references. 1. Open an agent in Agent Builder and add or edit an **HTTP Request** block. 2. In the field where you would normally enter a sensitive value (for example, an `Authorization` header value or an API key parameter), use the secret reference format to point to your stored secret. 3. Save the agent. At runtime, Harmony resolves the reference and sends the actual credential value - without ever writing it into the agent definition itself. ### Security considerations * **Encryption at rest** - All secret values are encrypted before being stored. * **Runtime resolution** - Plaintext values are only resolved at the moment an agent step executes, and are never persisted in agent configuration or run logs. * **Least-privilege access** - Only users with appropriate Settings permissions can create, edit, or delete secrets. * **Rotation without downtime** - Because agents reference secrets by name, you can rotate credentials without editing or redeploying any agent. # Streaming Audit Logs via Webhook Harmony can forward audit log events to an external destination in real time via webhook. Each time a tracked user action occurs, Harmony sends an HTTP POST request containing a JSON payload to the URL you configure. This makes it straightforward to integrate your activity history with SIEM tools, log aggregation platforms such as Sumo Logic, and compliance systems - without any additional tooling or manual exports. ### Supported Event Types The following categories of events are captured and forwarded to your webhook destination: * **Authentication events** - user sign-ins and sign-outs * **Asset actions** - create, update, delete, and assignment changes * **Ticket and service desk actions** - status changes and mutations As Harmony adds support for additional tracked actions, they will be included in the stream automatically. ### Configuring a Webhook Destination To set up audit log streaming: 1. Navigate to **Settings** in your Harmony workspace. 2. Locate the **Audit Logs** section and select **Webhook**. 3. Enter the destination URL in the **Webhook URL** field. This must be a publicly reachable HTTPS endpoint that accepts HTTP POST requests. 4. Save your configuration. Once saved, Harmony will begin forwarding new audit events to the specified URL immediately. Events that occurred before the webhook was configured are not retroactively delivered. ### Payload Format Each event is delivered as an HTTP POST request with a `Content-Type: application/json` header. The request body contains a JSON object describing the event, including details such as the event type, the user who performed the action, a timestamp, and any relevant resource identifiers. The exact fields in the payload vary by event type, but all payloads share a common structure so you can parse and route them consistently in your receiving system. ### Receiving and Verifying Events Your endpoint should return a `2xx` HTTP status code to acknowledge successful receipt. If Harmony does not receive a successful response, it may retry delivery. To ensure the events you receive originate from Harmony, we recommend: * Restricting access to your endpoint so only known Harmony IP ranges are accepted, if your infrastructure supports it. * Validating the structure and required fields of each incoming payload before processing it. ### Use Cases * **SIEM integration** - forward events directly into your security information and event management platform to correlate Harmony activity with signals from other systems. * **Log aggregation** - stream events into platforms such as Sumo Logic for long-term retention, search, and dashboarding. * **Compliance auditing** - maintain a real-time, tamper-evident record of user actions in an external system that your compliance or legal team controls. ### Troubleshooting **Events are not arriving at my endpoint** Confirm that the destination URL is publicly reachable and returns a `2xx` status code. Check that no firewall or authentication layer is blocking inbound requests from Harmony. **My endpoint is receiving duplicate events** This can occur if your endpoint did not return a successful response during a previous delivery attempt, triggering a retry. Implement idempotency handling in your receiver using a unique event identifier from the payload. **I need to change the destination URL** Return to **Settings > Audit Logs > Webhook**, update the URL, and save. The new destination takes effect for all events going forward. # Configuring Service Catalog Forms and Fields Service Catalog forms let you collect structured information from employees when they submit requests. By configuring fields carefully - including field types, visibility rules, and who fills in what - you can reduce back-and-forth, improve ticket quality, and route requests more accurately. This article covers how to configure Service Catalog form fields, including attachment fields, desk-member-filled fields, and conditional logic rules. *** ### Adding and Configuring Form Fields Each Service Catalog form can include multiple fields to capture the information your team needs. When building or editing a form, you can configure each field with the following options: * **Field type** - Choose from text, dropdown, attachment, and other supported input types. * **Label and description** - Give each field a clear name and, optionally, a description to guide the submitter. * **Required or optional** - Mark fields as mandatory to ensure employees provide the information before submitting, or leave them optional. To access form configuration, navigate to **Settings > Service Catalog**, select the relevant catalog item, and open its form editor. *** ### Attachment Fields You can add an attachment field to any Service Catalog form, allowing employees to upload one or more files as part of their request. Attachment fields are fully supported across Slack, the Employee Portal, and Microsoft Teams. #### Adding an Attachment Field 1. Open the form editor for the relevant catalog item. 2. Add a new field and select **Attachment** as the field type. 3. Configure the following options: | Option | Description | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | **Required / Optional** | Mark the field as mandatory if the attachment is needed before the request can proceed, or leave it optional. | | **Button label** | Customize the label on the upload button to give employees clear context - for example, "Upload your invoice" or "Attach screenshot". | | **Description** | Add a description to communicate expected file formats, size limits, or any other guidance relevant to the upload. | 4. Save your changes. Employees will see the configured upload button and description when filling out the form, regardless of which supported channel they use. *** ### Desk-Member-Filled Fields Some fields are best completed by your IT desk team rather than the person submitting the request. For example, an asset assignment field may only be relevant once a desk member reviews the ticket. You can mark specific fields as "filled by desk member" so employees are not blocked from submitting their request when those fields are empty. #### How It Works * Any form field - including required fields - can be individually flagged as **filled by desk member**. * When a field is flagged this way, employees can submit their request without completing that field. * After the ticket is created, desk members can open the ticket and fill in those fields directly. #### Configuring a Field as Desk-Member-Filled 1. Open the form editor for the relevant catalog item. 2. Select the field you want to configure. 3. Enable the **Filled by desk member** option for that field. 4. Save your changes. Employees submitting a request will not be prompted to complete desk-member-filled fields, even if those fields are otherwise marked as required. Desk members retain full ability to update these fields on any existing ticket. *** ### Conditional Logic Conditional logic allows you to show, hide, or require fields based on the values that employees enter in other fields. This creates a more focused, relevant experience by surfacing only the fields that apply to each specific request. #### How Conditional Logic Is Evaluated Conditional rules are evaluated by the platform in real time - directly in the form interface - before any AI processing occurs. This means: * Fields appear or hide **instantly** as employees fill out the form, without any delay. * Routing rules and branching logic respond immediately to user input. * The experience is smooth and responsive across all supported channels. #### Condition Types You can configure the following conditional rules on any field: | Rule Type | Behavior | | ----------- | -------------------------------------------------------------- | | **SHOW** | The field is only visible when a specified condition is met. | | **HIDE** | The field is hidden when a specified condition is true. | | **REQUIRE** | The field becomes mandatory when a specified condition is met. | #### Validation at Ticket Submission When a ticket is submitted, Harmony evaluates all conditional field logic in real time against the actual values provided. This ensures the rules you configure behave correctly end-to-end, not just within the form settings interface. The following validation rules apply at submission: * **SHOW rules** - If a field is only visible when a condition is met and that condition is not met, any value submitted for that hidden field will be flagged as invalid. * **HIDE rules** - If a field is hidden because a condition is true, any submitted value for that field will be rejected. * **REQUIRE rules** - Required conditions are enforced based on the actual submitted values, ensuring mandatory fields are completed when their conditions are triggered. This end-to-end validation prevents inconsistent or unexpected data from reaching your team, keeping ticket quality high. #### Setting Up Conditional Logic 1. Open the form editor for the relevant catalog item. 2. Select the field you want to apply a condition to. 3. Choose the condition type - **SHOW**, **HIDE**, or **REQUIRE**. 4. Define the condition by selecting the source field and the value that triggers the rule. 5. Save your changes. You can add multiple conditions to a single field as needed. Test your form after saving to confirm fields appear, hide, and become required as expected. *** ### Best Practices * Use **desk-member-filled** fields for information only your IT team can provide - such as asset assignments, internal codes, or approval-related data - to avoid blocking employees from submitting requests. * Add **descriptions** to attachment fields to set clear expectations around file types and sizes. * Keep **conditional logic** focused and predictable. Avoid deeply nested conditions that may be difficult to maintain or test. * After making changes to conditional logic, always submit a test request to verify that SHOW, HIDE, and REQUIRE rules behave as intended from the employee's perspective. # Managing the Service Catalog The Service Catalog lets you build a structured library of requestable services that employees and customers can browse and submit through the self-service portal. Each catalog item maps to a specific desk, ticket type, and priority, and carries its own custom form so every request captures exactly the right information upfront. This article covers how to set up and manage your Service Catalog from Admin Settings - including categories, catalog items, form fields, access control, and the built-in analytics that help you understand how your catalog is being used. *** ### Getting started with the Service Catalog To open the Service Catalog settings, go to **Admin Settings** and select **Service Catalog**. You will see the catalog items table, which lists all items across every category with support for search, filtering, sorting, and pagination. Click any row in the table to open the full detail view for that item. #### Using preset categories and items If you are starting from scratch, Harmony includes built-in preset categories and items drawn from a standard ESM catalog. Instead of building everything manually, you can adopt presets with a single click. * **Preset categories** appear alongside your existing categories in the Manage Categories view so you can see what is available at a glance. * **Pre-populated item forms** automatically fill in the name, description, icon, ticket type, priority, and form fields - you only need to review and confirm before saving. Harmony provides 10 preset categories and 6 pre-configured catalog items to help you get up and running quickly. *** ### Managing categories Categories organise your catalog items into logical groups. Managing categories requires the Admin role. #### Creating and editing categories 1. In the Service Catalog settings, open **Manage Categories**. 2. Click **Add category** to create a new custom category and give it a name. 3. To rename an existing custom category, click the pencil icon next to its name, type the new name, then press **Enter** or click away to save. Press **Escape** to cancel without saving. Preset categories are fixed and cannot be renamed. #### Reordering categories Drag categories into the order you want them to appear in the portal. #### Deleting categories When you delete a category, it is soft-deleted rather than permanently removed immediately. This means the record is marked as removed and cleaned up automatically in the background, reducing the risk of accidental data loss. *** ### Managing catalog items Catalog items represent individual service request types within a category. Creating, updating, deleting, and reordering items within a category requires desk-level Manage permission. #### Creating a catalog item 1. From the catalog items table, click **Create item** (or use the **Create Form** dialog). 2. Fill in the following: * **Icon** - choose an emoji to represent the item visually. * **Name** - the title users will see in the portal. * **Category** - the group this item belongs to. * **Desk** - the desk that will handle requests from this item. * **Description** - a summary of what this service is for (see [AI-generated descriptions](#ai-generated-descriptions) below). * **Ticket type and priority** - define the type and urgency of tickets created from this item. * **Visibility** - control whether the item is visible in the portal. 3. Add the form fields users will complete when submitting a request (see [Configuring form fields](#configuring-form-fields) below). 4. Click **Save**. #### Editing a catalog item Click any row in the catalog items table to open its detail view. Make your changes and save. #### Reordering catalog items Within a category, drag items into the order you want them to appear. #### Deleting a catalog item Deleted items are soft-deleted rather than permanently removed immediately. Background cleanup handles the rest, so an accidental deletion does not result in instant data loss. #### Bulk moving items to a different desk You can reassign multiple catalog items to a different desk in a single action without updating them one by one. 1. In the catalog items table, use the checkboxes to select the items you want to move. You can select up to **200 items** at once. 2. When one or more items are selected, a bulk action bar appears. Click **Move to desk**. 3. Pick the target desk from the dialog and confirm. A per-item result summary shows exactly what succeeded or failed. A partial failure will not block the rest of the batch from completing. * This action is available to users with desk management permissions only. *** ### Configuring form fields Each catalog item has its own form that users complete when submitting a request. You can build this form from a range of field types. #### Available field types | Field type | Description | | ----------- | ---------------------------------------------------------------------- | | Text | Short free-text input | | Text area | Multi-line free-text input | | Date Picker | Lets the user select a date | | Time Picker | Lets the user select an hour and minute in 24-hour format (e.g. 14:30) | | Dropdown | A list of predefined options | | Checkbox | A true/false toggle | The **Time Picker** field is separate from the Date Picker. Use it when you need to capture a specific time for event requests or scheduling. It works across all supported surfaces, including the agent interface, Slack, and Microsoft Teams. #### Adding descriptions to fields When adding or editing a field, you can enter a **description** alongside the field label. This description is displayed to users within the form and gives them helpful context about what the field is for and how it should be filled in. Clear field descriptions help teams submit accurate, consistent information. *** ### AI-generated descriptions Well-written item descriptions improve how accurately Harmony's agents match incoming requests to the right catalog form. To help you craft effective descriptions, Harmony can generate an AI-optimised version for you. When creating or editing a catalog item, click the AI generate option in the description field. The AI uses the item's name, category, desk, team, and ticket type as context to produce a focused, precise description. * Generated descriptions support up to **500 characters**, giving enough room to capture meaningful detail while staying concise. * Better descriptions mean fewer misrouted tickets and a smoother experience for employees submitting requests. You can edit the generated description before saving if you want to refine it further. *** ### Restricting access to catalog items By default, catalog items are visible to all agents. If you need to limit who can see and use a specific form before full role-based access control is in place, you can restrict individual items to a list of designated agents. #### How per-item access control works * Each catalog item can have its own list of permitted users, defined by email address. * Restricted forms are **hidden entirely** from agents who do not have access - those agents will not see the form exists. * **Platform Admins always have access** regardless of the per-item permitted users list. #### Setting permitted users on a catalog item 1. Open the catalog item detail view. 2. Find the access control section and add the email addresses of the agents who should have access. 3. Save the item. Any agent whose email is not on the list, and who is not a Platform Admin, will not see the item in the catalog. *** ### Understanding catalog usage The catalog items table includes a **Usage** column showing how often each item is used per month. This data loads automatically after the table renders and the column is fully sortable. Items with no usage data sort last. You can use this information to identify which services are most in demand, spot underused items that may need better descriptions or visibility, and make informed decisions about catalog organisation. #### Resolution rates The detail view for each catalog item shows a resolution rate. This figure reflects only tickets that were actually created from that catalog item, giving you an accurate picture of how well requests submitted through that form are being resolved. *** ### Form layout and language settings The service catalog form uses a clean, responsive layout. Expanded sections use the full available width, and field spacing adjusts for good visual balance across different screen sizes. Language configuration has been removed from individual catalog items. Language handling is managed at the platform level, which reduces confusion when setting up and maintaining your catalog. # Custom Subdomains and Branded URLs Harmony now supports custom subdomains for each organization, giving you a dedicated URL that reflects your organization's identity. Instead of accessing Harmony through a generic address, your team navigates directly to a URL like `yourcompany.harmony.so`. This is the first step toward a fully branded Harmony experience, with more personalization options on the way. ### How Custom Subdomains Work Each organization is automatically assigned a unique subdomain when its tenant is provisioned. The subdomain is derived from your organization name and follows this format: ``` yourcompany.harmony.so ``` There is no manual DNS configuration required on your end. Harmony handles all subdomain provisioning automatically as part of the tenant setup process. Once your organization is set up, your subdomain is active and ready to use. ### Accessing Your Organization's URL To find your organization's subdomain, contact your Harmony administrator or check your onboarding details. Once you have your subdomain, you and your team can bookmark it and use it as the primary entry point to Harmony. All existing links and integrations that reference Harmony will continue to work. Your custom subdomain is an additional, organization-specific access point rather than a replacement for any existing configurations. ### What This Means for Your Team * **Clearer identity** - Your team lands on a URL that belongs to your organization, reducing confusion in multi-tenant environments. * **Consistent access** - Everyone in your organization uses the same dedicated address, making it easier to standardize bookmarks and internal documentation. * **No extra setup** - Subdomains are provisioned automatically, so there is nothing you need to configure manually. ### Coming Soon Custom subdomains are the foundation for a broader set of branding capabilities. Future updates will build on this to include: * Personalized login pages with your organization's branding * Organization-specific visuals and themes These upcoming features will give your organization a more cohesive and recognizable presence within Harmony. Stay tuned for announcements as these capabilities become available. # Connecting Harmony MCP Harmony MCP (Model Context Protocol) lets you connect AI assistants and compatible tools directly to your Harmony workspace. Authentication is handled through a dedicated OAuth login page that guides you through a secure token exchange and lands you back in your tool - ready to work. This article explains how to connect a supported MCP client to Harmony using the OAuth login flow. ### Before You Begin Make sure you have the following before starting the connection: * An active Harmony account with the permissions needed for the workspace you want to connect. * An MCP-compatible client or AI assistant (for example, a tool that supports the Model Context Protocol). * A stable internet connection to complete the OAuth redirect flow. ### Connecting Your MCP Client #### Step 1 - Initiate the Connection from Your MCP Client Open your MCP-compatible client and locate the option to add or connect a new MCP server. When prompted for the server URL or integration endpoint, enter your Harmony MCP endpoint. The exact location of this setting depends on the client you are using - refer to that tool's documentation if you are unsure where to add a new server. Once you confirm the endpoint, the client will redirect you to the Harmony MCP OAuth login page to complete authentication. #### Step 2 - Log In on the MCP OAuth Page The Harmony MCP OAuth login page handles authentication through a Descope token exchange flow. On this page: 1. Enter your Harmony credentials if you are not already signed in. 2. Review the permissions being requested by the MCP client. 3. Click **Authorize** to approve the connection. The page validates your authorization request before proceeding. If the request contains invalid or missing parameters, you will see a clear error message explaining the issue so you can correct it and try again. #### Step 3 - Return to Your MCP Client After you authorize the connection, the OAuth flow completes and you are redirected back to your MCP client. The client receives a secure access token and the connection to your Harmony workspace is established. You do not need to copy or paste any tokens manually. ### Troubleshooting #### Invalid Authorization Request Error If you see an error on the OAuth login page indicating that the authorization request is invalid, check the following: * The MCP client is using the correct Harmony MCP endpoint URL. * The client has been configured with the right OAuth parameters (client ID, redirect URI, and scopes). * Your Harmony account has the necessary permissions for the workspace being accessed. If the problem persists, re-initiate the connection from your MCP client to generate a fresh authorization request. #### Connection Not Completing If you are redirected to the OAuth page but the flow does not complete: * Check that your browser is not blocking redirects or third-party cookies. * Ensure you are logged in to the correct Harmony account before authorizing. * Try opening the OAuth page in a private or incognito window to rule out cached session issues. ### Revoking Access To disconnect an MCP client from your Harmony workspace, navigate to your account settings and review the list of authorized applications. Locate the MCP client entry and revoke its access. The client will no longer be able to use the issued token and will need to go through the OAuth flow again to reconnect. # Managing Integration Categories and Regional Settings Harmony gives you fine-grained control over how integrations are organized and how device data is collected across your organization. This article covers two areas of the Settings experience: the dedicated **SaaS Procurement** section that groups your procurement integrations together, and the regional configuration options available when connecting Mobile Device Management (MDM) sources. *** ### SaaS Procurement Integrations Procurement tools are now grouped in their own **SaaS Procurement** section under **Settings > Integrations**, separate from the rest of your SaaS catalog. This makes it easier to find, connect, and manage your procurement sources without scrolling through unrelated integrations. The following tools appear in this section: * **ZipHQ** * **NetSuite** * **Mesh Payments** #### Connecting ZipHQ and NetSuite Together ZipHQ and NetSuite both track overlapping contract and spend data. If you connect one of these tools and then attempt to connect the other, Harmony will display a warning to let you know that a procurement source is already active. You have two options when you see this warning: * **Connect both sources** - You can proceed with connecting the second tool and manage any duplicate contract or spend records manually. * **Wait for automatic deduplication** - If automatic source deduplication is available for your plan, you may prefer to hold off until that feature handles overlapping records for you. Harmony does not block you from connecting both tools at the same time. The warning is informational, giving you the context you need to make the right decision for your organization before proceeding. #### Mesh Payments Mesh Payments can be connected independently without any overlap warnings, since it tracks different spend data from ZipHQ and NetSuite. *** ### Regional MDM Support When connecting an MDM integration, Harmony now supports regional configuration to ensure device data is collected from the correct instance of your MDM platform. #### Why Region Matters Many MDM providers host data in region-specific environments - for example, separate instances for the United States and the European Union. If you select the wrong region during setup, Harmony may be unable to reach your MDM instance or may retrieve incomplete device data. #### Configuring Your MDM Region When you add or edit an MDM integration under **Settings > Integrations**, you will see a region selector as part of the connection flow. Select the region that matches where your MDM tenant or instance is hosted. If you are unsure which region applies to your organization, check your MDM provider's documentation or contact your MDM administrator before completing the connection. *** ### Related Settings * To manage all integrations in one place, navigate to **Settings > Integrations**. * To review connected procurement sources and check for duplicate records, open the **SaaS Procurement** section within the Integrations page. * For MDM connections, review the region selection any time you edit an existing integration to confirm it still matches your provider's hosting configuration. # Login Event Tracking from Identity Providers and Endpoints Harmony can now track login events pulled directly from your connected identity providers and endpoint management tools. This gives you a unified view of user authentication activity across your environment without requiring any additional configuration beyond your existing integrations. Harmony continuously polls supported integrations for sign-in data and normalises it into the same event stream as webhook-delivered events. This means there are no gaps in coverage regardless of how your tools deliver data - whether through webhooks or polling, all login activity lands in the same place. ### How It Works When you connect an identity provider or endpoint management tool to Harmony, the platform automatically begins polling that integration for sign-in events at regular intervals. Each event is normalised into a consistent format so you can correlate authentication activity across different tools and providers in one unified view. This polling-based approach works alongside any webhook-delivered events you already receive, ensuring complete coverage even for integrations that do not support real-time push notifications. ### Supported Integrations #### Microsoft Entra ID Harmony supports login event tracking from Microsoft Entra ID sign-in logs. Each event captured from Entra ID includes rich metadata across the following categories: * **User** - identity and account details for the authenticating user * **Application** - the application or service the user signed in to * **Device** - device information associated with the sign-in attempt * **Location** - geographic and network location data * **Risk** - risk signals and assessments associated with the sign-in event Additional identity providers and endpoint management tools will be added in future releases. ### Viewing Login Events Login events collected from identity providers and endpoint management tools appear in the same event stream as all other Harmony events. You do not need to switch between separate views or dashboards to see authentication activity - it is unified alongside the rest of your security event data. ### Prerequisites To track login events from a supported integration, you must have that integration already connected to Harmony. No additional configuration is required beyond the standard integration setup. If you have not yet connected your identity provider or endpoint management tool, refer to the relevant integration guide in the Integrations section. # Quick Actions for IDP and MDM Integrations Harmony lets you take direct action on users and devices from within the platform, without switching to your Identity Provider (IDP) or Mobile Device Management (MDM) console. Quick actions are available across your connected integrations and help you respond faster to security events, streamline user lifecycle management, and manage devices without leaving your workflow. This article describes every quick action available, which integrations support each action, and how to use them. *** ### Supported Integrations Quick actions are available across the following connected integrations: * **Identity Providers (IDP):** Okta, Microsoft Entra, Google Workspace, JumpCloud * **MDM providers:** Microsoft Intune, Jamf, Kandji, Hexnode, Mosyle, Addigy *** ### Identity Provider Quick Actions The following actions are available for users managed through your connected IDP. All four supported providers - Okta, Microsoft Entra, Google Workspace, and JumpCloud - support these actions unless noted otherwise. #### Reset Password Trigger a password reset for a user directly from Harmony. The user receives a prompt to set a new password through your IDP's standard reset flow. **When to use:** A user's credentials may be compromised, or a user has been locked out and needs to re-authenticate. #### Reset MFA Clear a user's existing MFA methods and require them to re-enroll. This removes all currently registered authenticators and forces the user to set up MFA again on their next login. **When to use:** A user has lost access to their authenticator device, or you suspect an MFA method has been compromised. #### Deactivate User Permanently deactivate a user account in your IDP. A deactivated account cannot be used to sign in and is typically not reversible without manual intervention in your IDP console. **When to use:** An employee has left the organization and their account should be disabled immediately. #### Suspend User Temporarily suspend access for a user. Unlike deactivation, suspension is reversible and allows you to restore access when appropriate. **When to use:** A user account shows suspicious activity and you need to block access while you investigate, without permanently removing the account. #### Add to Groups Assign a user to one or more groups in your IDP directly from Harmony. Group membership controls access policies, application permissions, and other entitlements managed through your IDP. **When to use:** A user needs access to a specific application or resource that is gated by IDP group membership. *** ### MDM Quick Actions The following actions are available for devices managed through your connected MDM provider. Availability varies by provider - see the notes under each action. #### Lock Device Remotely lock a managed device. The device becomes inaccessible until a PIN or password is entered. **When to use:** A device is lost, stolen, or left unattended in an unsecured location. #### Wipe Device Send a remote wipe command to erase all data on a managed device. This action is irreversible. **When to use:** A device is lost or stolen and data on the device must be protected from unauthorized access. #### Restart Device Remotely restart a managed device without requiring physical access. **When to use:** A device is unresponsive or requires a restart to apply a configuration or policy update. #### Sync Device Force a managed device to immediately sync with your MDM provider and pull down the latest policies, profiles, and configurations. **When to use:** A device has not checked in recently and may be running outdated policies. *** ### How to Use Quick Actions 1. Navigate to the relevant **Users** or **Devices** view in Harmony. 2. Locate the user or device you want to act on. 3. Open the detail panel by clicking the user or device name. 4. Click the **Quick Actions** menu or button. 5. Select the action you want to perform. 6. Confirm the action when prompted. Some actions - such as **Wipe Device** or **Deactivate User** - include an additional confirmation step because they are irreversible. Harmony sends the action request to the connected IDP or MDM provider. The result is reflected in the integration and, where applicable, updated in Harmony after the next sync. *** ### Notes and Considerations * Quick actions require an active, authenticated connection to the relevant IDP or MDM integration. If a connection is inactive or has insufficient permissions, the action may fail. Check your integration settings if an action returns an error. * Some actions depend on the permission scopes granted when the integration was configured. If an expected action is unavailable, review the scopes assigned to the Harmony integration in your IDP or MDM console. * Irreversible actions - **Deactivate User** and **Wipe Device** - cannot be undone from Harmony. You must use your IDP or MDM console directly to recover from these actions if needed. * Actions are logged in Harmony's audit trail so you have a record of who triggered each action and when. # IDP Group Sync Harmony can sync user group memberships directly from your identity provider (IDP), giving you accurate, up-to-date group data across the platform without manual maintenance. Once connected, Harmony queries your organization's group directory and refreshes it every 4 hours, so features like Service Desk, Application Management, and App Access always work from current membership information. Supported identity providers: * Okta * Google Workspace * Microsoft Entra *** ### How IDP Group Sync Works When IDP Group Sync is enabled, Harmony periodically pulls your organization's group directory from the connected identity provider. Each sync run captures group memberships and enriches them with metadata that powers context-aware automation across the platform. #### Sync frequency Harmony syncs group data every 4 hours. There is no manual trigger required - the process runs automatically in the background after your IDP is connected. #### What gets synced For each group, Harmony captures the following metadata: | Field | Description | | ---------------- | --------------------------------------------------------------------------------- | | **Group source** | Which IDP the group was learned from (Okta, Google Workspace, or Microsoft Entra) | | **Group ID** | A stable, unique identifier for the group within the IDP | | **Group name** | The human-readable label as it appears in your IDP | | **Display name** | The name shown within Harmony when referencing the group | This metadata is used to ensure accurate group resolution when applying policies, routing tickets, managing app access, and evaluating application assignments. *** ### Where Synced Groups Are Used Once groups are synced, they become available across several Harmony features: * **Service Desk** - Route tickets and apply policies based on a user's IDP group membership. * **Application Management** - Scope application configurations and assignments to specific groups. * **App Access** - Control which users can access which applications by referencing IDP groups directly. Because the data refreshes every 4 hours, changes made in your IDP - such as adding a user to a group or removing one - are reflected in Harmony without any manual intervention. *** ### Connecting Your Identity Provider IDP Group Sync relies on your identity provider being connected to Harmony. If you have not yet integrated your IDP, complete the integration for your provider before expecting group data to appear. * **Okta** - Connect Harmony to Okta through the Okta integration settings in your Harmony workspace. * **Google Workspace** - Connect Harmony to Google Workspace through the Google integration settings. * **Microsoft Entra** - Connect Harmony to Microsoft Entra through the Entra integration settings. Once the integration is active, the first group sync runs automatically. Subsequent syncs occur on the 4-hour schedule. *** ### Troubleshooting **Groups are not appearing after connecting my IDP.** The initial sync may take a few minutes to complete after the IDP connection is established. If groups still do not appear after 10 minutes, verify that the connected IDP account has sufficient permissions to read group directory information. **Group membership changes in my IDP are not reflected in Harmony.** Harmony syncs every 4 hours. If a change was made recently, wait for the next scheduled sync. If the issue persists beyond one sync cycle, check that the IDP integration credentials are still valid and have not expired. **A group exists in my IDP but is missing from Harmony.** Confirm that the group is visible to the account or service principal used for the IDP integration. Some groups may be excluded if the integration account does not have read access to them. # Working with AI Agents ### Understanding AI Agents Harmony AI agents are automated workflows that perform tasks such as software compliance checks, employee onboarding, device recovery, app access requests, password resets, and more. Agents are configured per workflow, can run on a schedule or manually, and may require approval before executing certain actions. #### Agent Types **Software Management**
Application Access Request Automates application access requests with approval workflow and identity provider provisioning.
License Expiration Monitoring Tracks software license expiration dates and creates tickets when licenses are nearing expiration.
Software Compliance Report Runs periodic software access compliance reviews with manager acknowledgment.
**Access Control**
Device Recovery Automates device recovery requests with identity verification and secure recovery key delivery.
Password Reset Request Automates password resets for identity provider users with identity verification.
MFA Device Reset Automates MFA resets for identity provider users with identity verification.
Group Membership Management Manages identity provider group assignments with approval workflow.
**Hardware Management**
Device Uptime Monitoring Identifies devices that have been running for an extended period without a restart.
Low Storage Device Monitoring Finds devices with critically low free storage and creates tickets for IT remediation.
**Employee Lifecycle**
Employee Onboarding Automates employee onboarding by creating parent and linked tickets for new hire preparation.
Employee Account Termination Automates employee offboarding with approval workflow and identity provider account deactivation.
*** ### Managing Agents #### Navigating the Agents List Open **Agents** from the sidebar to view the list. The Agents page displays all available agents organized by category with the following features: * **Filters button** - Filter agents by category, status, or approval requirements * **Search bar** - Search agents by name or description * **View toggles** - Switch between card view and table view * **Refresh button** - Reload the agents list ![Agents page with card view layout](https://1766914782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIWiU87MW3r16e1GcC8yt%2Fuploads%2Fgit-blob-7bda241a2e395cabc0812fe907f30cfc6b9d99e8%2Fagents-list.png?alt=media) Each agent card shows: * **Agent name and icon** - Identifies the agent type * **Category** - Software Management, Access Control, Hardware Management, Employee Lifecycle, or Compliance * **Status badge** - Enabled (green) or Disabled (gray) * **Description** - Brief explanation of what the agent does * **Approval requirement** - "Needs approval" or "No approval needed" * **Run statistics** - Number of runs and last run time * **Integration icons** - Shows which integrations the agent uses #### Viewing Agent Cards vs Table View Toggle between **Card layout** and **Table layout** to change how agents are displayed: * **Card view** - Shows larger cards with agent details, descriptions, and visual status indicators * **Table view** - Displays a compact data table with sortable columns for quick scanning #### Viewing Agent Details Click an agent card to open its detail page. The page has tabs: **Overview**, **Runs history**, and **Provisioning** (when applicable). The Overview tab shows the agent's workflow triggers, steps, and configuration panel. ![Agent detail page with Overview, Runs, Provisioning tabs](https://1766914782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIWiU87MW3r16e1GcC8yt%2Fuploads%2Fgit-blob-02aeddb6020290531609dbe2e3f6ccc9fd4fc1f7%2Fagent-detail-tabs.png?alt=media) *** ### Running and Monitoring Agents #### Running Agents Manually On the agent detail page, click **Run** to open the run dialog. Fill in the required inputs (e.g., employee, device, application) and click **Run** to start the workflow. The dialog varies by agent type. ![Agent Run dialog with inputs](https://1766914782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIWiU87MW3r16e1GcC8yt%2Fuploads%2Fgit-blob-9469063bdfec58233cb53b3dc6ecb2ed803010e5%2Fagent-run-dialog.png?alt=media) #### Understanding Agent Runs Each run has a unique Run ID, status, subject, duration, requester, and start time. Runs are triggered by schedules, events, or manual execution. #### Viewing Agent Run Details Click a run in the Runs history table to open the run details page. The page shows run metadata, step-by-step execution status, and outputs. Expand steps to see inputs, outputs, and errors. ![Agent run details page with step execution](https://1766914782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIWiU87MW3r16e1GcC8yt%2Fuploads%2Fgit-blob-b0617578461dc3641c2687b595bf3c736d11dbac%2Fagent-run-details.png?alt=media) #### Viewing Agent Execution History On the agent detail page, open the **Runs history** tab. The table lists past runs with Run ID, Status, Subject, Duration, Requester, and Start Time. Use search and the status filter to find specific runs. Sort by column headers. #### Understanding Agent Run Status | Status | Description | | ------------- | -------------------------------- | | **Running** | Execution in progress. | | **Completed** | All steps finished successfully. | | **Failed** | One or more steps failed. | | **Aborted** | Run was cancelled by user. | | **Time out** | Run exceeded the time limit. | | **Skipped** | Run or step was skipped. | #### Monitoring Active Agent Runs Runs with status **Running** show a live duration timer in the Runs history. Open the run details page to see which step is running and monitor progress in real time. #### Aborting Agent Runs On the run details page, for runs that are still **Running**, click **Abort** to stop execution. Confirm in the dialog. Aborting stops all remaining steps, actions already completed in external systems may need manual review. *** ### Exporting Agent Data #### Exporting Agent Run History To export agent run history to CSV: 1. Open the agent detail page 2. Click the **Runs history** tab 3. Apply any filters or search criteria you want (optional) 4. Click **Export** in the toolbar 5. The CSV file will download with the format `{agent-slug}-runs-YYYY-MM-DD.csv` # Configuring AI Agents Configure when agents run, how approvals work, and provisioning behavior for each agent type. ## Understanding Agent Configuration Each agent type has a configuration panel on the right side of the detail page. Options vary by agent but typically include: * **Schedule** - When the agent runs (daily, weekly, etc.) * **Approval** - Who must approve and how (for agents that require approval) * **Provisioning** - Access duration, auto-approval (for app access and similar agents) * **Agent-specific options** - Thresholds, ticket desk, filters, etc. ## Configuring Agent Settings 1. Open the agent detail page. 2. Use the configuration panel on the right. 3. Change options (schedule, approval, thresholds, etc.). 4. Click **Save** to apply. ![Agent detail page with configuration panel](https://1766914782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIWiU87MW3r16e1GcC8yt%2Fuploads%2Fgit-blob-498b860a988bab542e33e62f94fc968b6e558927%2Fagent-approvals.png?alt=media) ## Setting Agent Schedules In the **Run Schedule** section: **Recurring schedules** * **Frequency** - Daily, Weekly, Monthly, Quarterly (every 3 months), Semi-annually (every 6 months), Annually * **Day** - For weekly: day of week, for monthly/quarterly/semi-annually/annually: day of month (e.g., first, last, specific day) * **Time** - Hour and minute * **Timezone** - When the schedule runs in local time **Cron-based schedules** Agents use cron expressions internally. The UI exposes frequency, day, time, and timezone, these are converted to a 5-field cron expression for the backend. **One-time runs** Agents can be run manually. Use the **Run** button (or Run dialog) to trigger a one-time execution. This does not affect the schedule. ![Run Schedule section (frequency, day, time, timezone)](https://1766914782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIWiU87MW3r16e1GcC8yt%2Fuploads%2Fgit-blob-c55e044ae6cf5b16f9b1fed0183afba21a069915%2Fagent-schedule.png?alt=media) ## Configuring Agent Approval Workflows For agents that require approval (e.g., Application Access Request, Group Membership Management, Employee Account Termination): **Approval strategy** | Strategy | Description | | ---------------------------------------------- | ------------------------------------------------------------------------------ | | **Require approval from all** | Every listed approver must approve. | | **Require approval from one of** | Any one approver can approve. | | **Escalate if first approver doesn't respond** | First approver is tried, if no response within the timeout, escalation occurs. | **Approvers** * **Role-based** - Direct manager, app owners, IT approvers, budget approvers, etc. (options vary by agent) * **Employee-based** - Specific people from the employee directory Add up to 10 approvers. Configure per agent based on available role options. **Timeout** Set how many days (1–7) to wait for approval before timeout or escalation. **Reminders** Enable reminders (first and second) at configurable intervals (e.g., 4 hours, 24 hours) to nudge approvers. ![Approval strategy and approvers](https://1766914782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIWiU87MW3r16e1GcC8yt%2Fuploads%2Fgit-blob-483d6ee966b7dbad50b639711190be4999853599%2Fagent-provisioning.png?alt=media) # Sending Calendar Invites from Agent Workflows With Harmony AI Agents, you can send calendar invites directly from custom agent workflows - no manual steps required. This lets you build fully automated onboarding, offboarding, scheduling, and any other people-workflow that needs to include a meeting invitation as part of the process. The **Send Calendar Invite** action is available for both Google Calendar and Microsoft Outlook, and works alongside the rest of your workflow actions so you can combine it with approvals, notifications, data lookups, and more. *** ### Supported Integrations The Send Calendar Invite action is available under two providers in the workflow builder: * **Google Workspace** - sends invites via Google Calendar * **Outlook** - sends invites via Microsoft Outlook Calendar Make sure the relevant integration is connected in your Harmony settings before building a workflow that uses this action. *** ### Adding a Send Calendar Invite Action To add a calendar invite step to a custom agent workflow: 1. Open the **Agent Workflows** section from the left navigation. 2. Create a new workflow or open an existing one. 3. In the workflow builder, click **Add Action**. 4. Select either **Google Workspace** or **Outlook** from the integration list. 5. Choose **Send Calendar Invite** from the available actions. 6. Configure the action fields described in the next section. 7. Save and publish your workflow. *** ### Configuring the Action When you add a Send Calendar Invite action, you can configure the following fields: #### Recipients Choose who will receive the calendar invite. You have two options: * **Select employees from your HRIS** - search for and select specific people directly from your connected HR system. * **Use workflow variables** - reference a variable that resolves to one or more attendees at runtime, which is useful when the recipient depends on earlier steps in the workflow (for example, a newly hired employee or a manager assigned during an approval step). For each recipient, you can specify which email address to use - their **primary** work email or their **personal** email - depending on what is available and appropriate for the event. #### Event Details Fill in the standard calendar event fields: * **Title** - the name of the meeting as it will appear on the invite. * **Date and Time** - the scheduled start time of the event. You can set this as a fixed value or bind it to a workflow variable so it resolves dynamically. * **Duration** - how long the event will last. * **Description** - optional notes or agenda items to include in the invite body. * **Location** - optional physical or virtual location (for example, a conference room name or a video call link). *** ### Example Use Cases * **Automated onboarding** - when a new hire workflow completes, automatically send a Day 1 orientation invite to the new employee and their manager. * **Offboarding exit interviews** - trigger a calendar invite to HR and the departing employee as soon as an offboarding workflow is initiated. * **Recurring scheduling workflows** - combine the Send Calendar Invite action with conditional logic to schedule check-ins based on tenure, performance cycles, or other HRIS data. *** ### Tips and Best Practices * Use **workflow variables** for recipients and event times whenever the information is dynamic. This avoids hardcoding values and keeps your workflows flexible as your team changes. * Test your workflow in a non-production environment before publishing to confirm that invites are sent to the correct recipients with the right details. * If an integration connection expires or is disconnected, the workflow step will fail. Check the integration status in your Harmony settings regularly to avoid disruptions. * You can combine the Send Calendar Invite action with other workflow actions - such as sending a Slack message or updating a field in your HRIS - to build end-to-end automated processes without any manual handoffs. # Service Desk Agent The Service Desk Agent is an AI-powered assistant that handles incoming support requests by understanding user intent, searching your knowledge base, and delivering relevant answers in real time. It is designed to reduce resolution time by surfacing the right information automatically, without requiring agents or end users to search manually. This article walks you through what the Service Desk Agent does, how its response flow works, and how to get the most out of the knowledge base integration. *** ### How the Service Desk Agent Works When a user submits a request, the Service Desk Agent processes it through a sequence of live steps before returning a response. You can follow this pipeline in real time directly within the agent interface: 1. **Parsing intent** - The agent reads the incoming message and identifies what the user is asking for. 2. **Searching KB** - It queries your connected knowledge base using the parsed intent. 3. **Scanning articles** - Matching articles are retrieved and individually evaluated for relevance. 4. **Ranking results** - The top results are scored and ordered before being included in the response. These live status steps are visible as the agent works, so you always have a clear view of what is happening and why a particular response was generated. *** ### Knowledge Base Article References Alongside every Service Desk Agent response, you will see up to three knowledge base articles that are most relevant to the request. These references are designed to give users and agents quick access to supporting content without cluttering the main response. #### Collapsed View KB article references appear in a **collapsed view** by default. Each collapsed item shows the article title so you can quickly scan whether the results are relevant. #### Expanding an Article Reference Click on any collapsed article to expand it. The expanded view includes: * A **short summary** of the article content * A **direct link** to open the full article in your knowledge base This lets you verify the relevance of a source or share it directly with the user, all from within the same response view. *** ### Why This Matters Surfacing KB articles alongside agent responses means: * Users get supporting documentation immediately, reducing the need for follow-up questions. * Support agents can verify the sources behind a response in a single click. * Teams can identify gaps in their knowledge base when the ranked results are consistently off-topic or unhelpful. *** ### Prerequisites Before the Service Desk Agent can surface KB articles, make sure the following are in place: * A knowledge base is connected and indexed in your Harmony AI Agents workspace. * The Service Desk Agent is enabled for your account. * Articles in your knowledge base are published and accessible to the agent. If your knowledge base connection is not yet configured, refer to the knowledge base integration guide in this documentation space. *** ### Getting Started 1. Open the **Service Desk Agent** from your Harmony AI Agents dashboard. 2. Submit a test request that relates to a topic covered in your knowledge base. 3. Watch the live processing steps appear as the agent works through parsing, searching, scanning, and ranking. 4. Review the response and expand the KB article references to confirm the results are relevant. 5. If the surfaced articles do not match expectations, review your knowledge base content for coverage gaps or update article metadata to improve discoverability. # Application Access Request Automated application access requests with approval and provisioning. The **Application Access Request** agent automates application access requests with approval workflow and identity provider provisioning. ![Application Access Request agent overview](https://1766914782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIWiU87MW3r16e1GcC8yt%2Fuploads%2Fgit-blob-02aeddb6020290531609dbe2e3f6ccc9fd4fc1f7%2Fapp-access.png?alt=media) ### What it does * Triggered when a user requests access to an application * Classifies the request upfront - detecting whether the user needs new access, wants to modify existing access, is experiencing a technical issue, or has an unclear request - and routes accordingly * Checks the service catalog before proceeding to app access policy selection, ensuring requests are always routed through the right steps * Guides employees through selecting an access policy and, where configured, collecting a business justification * Sends approval request to one or more approvers and waits for response * On approval: provisions application access via identity provider, or notifies a responsible person for manual provisioning * Updates the ticket with the outcome and moves it to the correct status at each stage ### Triggers **Event** - Runs when agent detects Application Access Request made by user. ### Approval Requires approval by default. A single flexible approval block replaces multiple workflow-specific approval configurations. You can define approvers, resolution strategies (any/all/fallback), multi-tier sequential approvals, timeouts, and interactive fields such as group selection - all in one place. Approvers receive rich Slack or Teams notifications and admins can override or edit approvers mid-flight. Configure approvers (for example, application owners), approval logic (require one or all), and timeout settings. ### Configuration * **Approval** - Set approvers, approval logic, timeout duration * **Identity provider** - Supported: Okta, Microsoft Entra, Google Workspace * **Execution settings** - Approval request timeout (e.g., 2 days) * **Notifications** - Toggle notifications for approval status * **Business justification** - Optionally require employees to provide a business justification when submitting an access request (see [Business Justification](#business-justification) below) * **Manual provisioning** - Mark individual apps as manually provisioned for apps not connected to Okta (see [Manual Provisioning](#manual-provisioning) below) * **Post-approval message** - Compose a rich text message shown to users after their request is approved, with support for bold text, bullet lists, numbered lists, and hyperlinks ### Access Request Control per Application Each application in your organization has an **Access Request** status - either **Available** or **Unavailable** - that determines whether the App Access Request agent and AI assistant will offer provisioning or access options for that app. * All applications default to **Unavailable**, so no access requests are processed until an admin explicitly enables them. * A new **Access Request** column and filter in the Applications table lets you quickly see and sort which apps are enabled for access requests. * Only apps with **Discovered** or **Approved** status are considered when the agent evaluates access requests. Apps marked as **Ignored** are filtered out entirely and will not be surfaced to users or approvers. ### Provisioning Configurations Configure how users are granted access to applications by default. Choose between direct app assignment or group-based access for each application in your organization. ![Provisioning configurations table](https://1766914782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIWiU87MW3r16e1GcC8yt%2Fuploads%2Fgit-blob-f2059637d6048ff85ba568253069c1eb99216604%2Fapp-access-provision.png?alt=media) For each application, you can configure: * **Provisioning Method** - Dynamic assignment (automatic) or static assignment * **Access Duration** - Unlimited or time-limited (JIT) access. Available durations include: **1 hour**, **30 days**, **60 days**, **90 days**, and other preset windows * **Auto Approval** - Enable to bypass approval workflow for specific applications * **Application Owners** - Designate owners who can approve access requests * **Manual Provisioning** - Mark an app as manually provisioned when it is not connected to Okta (see below) The provisioning table displays all connected applications from your identity provider, including their instance names, current configuration, and assigned owners. Use the search bar to quickly find specific applications. #### App Group Selection When configuring group-based access, the group selection area is larger and more prominent, and badges wrap correctly so all labels remain visible. This makes it easier to browse and choose application groups, especially when working with multiple groups. ### Policy-Based and Group Access Employees can now request access to specific groups and resources within an application. The AI agent guides employees through selecting the right access policy for their needs. Approvers receive full context in their notifications - including the requested group, the employee's business justification, and the identity provider involved - without needing to look up details separately. When multiple instances of an app exist across different identity providers, the agent applies a priority hierarchy: 1. **Okta or Microsoft Entra instances are always preferred** over Google Workspace when both are available. 2. **Google Workspace is used as a fallback** only when no other identity provider source exists for the app. 3. **When multiple non-IDP instances exist**, the agent selects the single instance with the highest relevance. ### Business Justification You can require employees to provide a business justification when submitting app access requests, directly from the agent configuration. This setting is off by default. Two modes are available: * **Request justification for all applications** - Overrides any existing provisioning policy and always prompts for a justification, regardless of per-app settings. * **Request justification only for applications without an existing provisioning policy** - Applies only where no provisioning policy is already defined, leaving existing per-app policies unchanged. When a justification is provided, it is included in the approval notification so approvers have the full context they need. ### Just-in-Time (JIT) Access You can configure Just-in-Time provisioning as part of your app access workflows. When a user requests access to an application, the agent enforces temporary, time-limited access based on the provision policy defined for that application - ensuring access is automatically revoked after the specified duration. Available JIT access durations include: * **1 hour** - for short-lived, tightly scoped access needs * **30 days** * **60 days** - for longer-term access without repeated re-approval * **90 days** JIT duration is surfaced clearly in approval notifications delivered through Slack, Microsoft Teams, and email, so users and approvers always know when access will expire. Provisioning and revocation are handled end-to-end within the workflow. ### Manual Provisioning You can mark individual apps as manually provisioned in the agent configuration page, enabling access request workflows for apps that are not connected to Okta. * **Manual provisioning indicator** - A per-app checkbox in the agent configuration page identifies apps that require manual provisioning rather than automated Okta-based provisioning. * **Responsible person assignment** - When manual provisioning is enabled for an app, you designate a responsible person who automatically receives a message to provision access once a request is approved. ### Approval Notifications Approvers receive interactive approval requests via Slack or Microsoft Teams, including OTP verification support for Teams. Notifications include: * The name of the group for which access was requested * The employee's business justification (when provided) * JIT access duration (when applicable) * The identity provider context Approval notifications preserve their original structure and include clear details about the group and provider involved, so approvers can review and act with the right context at a glance. ### Ticket Status During Approvals When the agent is waiting on an approval before proceeding, the ticket is automatically moved to a **Pending Approval** status. This gives your team a real-time picture of where each request stands and makes it easier to identify tickets that are blocked on a human decision.
Working with AI AgentsLearn how to run and monitor agentsWorking with AI Agents
Configuring AI AgentsConfigure schedules, approvals, and provisioningConfiguring AI Agents
# License Expiration Monitoring Automated monitoring for software licenses expiring soon. The **License Expiration Monitoring** agent tracks software license expiration dates and creates tickets when licenses are nearing expiration to help avoid service disruptions. Built on Harmony's V2 workflow architecture, this agent provides reliable, consistent scheduling for time-sensitive license lifecycle events - ensuring your team stays ahead of critical deadlines without manual intervention. ![License Expiration Monitoring agent overview](https://1766914782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIWiU87MW3r16e1GcC8yt%2Fuploads%2Fgit-blob-d84b43768d6e64738d2236f6bb044c0c5ad4b3cb%2Flicense-expiration-monitoring.png?alt=media) ### What it does * Runs periodic checks for licenses expiring soon * Queries application licenses expiring within threshold period * Marks licenses as NEW or existing based on entity tracking * Generates CSV report with all licenses meeting expiry criteria - with correctly formatted values for accurate review and sharing * Creates ticket with CSV attachment for IT team review * Initiates downstream renewal steps automatically when expiring licenses are detected ### Triggers **Schedule** - Runs at configured frequency (e.g., monthly on first day of month) via cron. Cron-based triggers resolve configuration at runtime, ensuring scheduled license expiry checks fire accurately and consistently. ### Approval No approval required. The agent monitors and alerts, renewal actions are handled manually or by other workflows. ### Configuration * **Run Schedule** - Frequency (daily, weekly, monthly), specific day, time, timezone * **Detection Threshold** - Days before expiration to alert (e.g., 30 days) * **Ticket Destination** - Target desk (e.g., IT), priority level (low, medium, high), optional assignee
Working with AI AgentsLearn how to run and monitor agentsWorking with AI Agents
Configuring AI AgentsConfigure schedule and thresholdsConfiguring AI Agents
# Software Compliance Report Request managers to acknowledge or reject their direct reports’ application access. Creates a summary ticket with all responses on completion. The **Software Compliance Report** agent runs periodic software access compliance reviews. It requests managers to acknowledge or reject their direct reports' application access, then generates a summary report ticket with all responses. ![Software Compliance Report agent overview](https://1766914782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIWiU87MW3r16e1GcC8yt%2Fuploads%2Fgit-blob-97416faa2ccaaa4f68fd9b704094d01ee04cdaa6%2Fsoftware-compliance-report.png?alt=media) ### What it does * Lists employees with filters for VIP status, employment status, location, and more * Fetches application access for multiple employees * Sends messages via Slack or Teams to request manager acknowledgment - managers can approve or reject with a written note without leaving their chat tool * Tracks responses with configurable deadline and automated reminders * Generates CSV report from collected responses, enriched with employee-level data including email, job title, job description, and location, alongside manager details for each record * Creates ticket with CSV attachment for IT team review, including an employee-level summary in the ticket description for easier review ### Triggers **Schedule** - Runs at a configurable interval set in months via cron. ### Approval Managers acknowledge or reject their direct reports' access, no separate approval step for the agent itself. Each manager receives a message listing their direct reports alongside the applications they have access to, and can submit a decision with an optional written note. The agent aggregates all responses - including each manager's decision, status, and notes - into a compliance report. ### Configuration * **Run Schedule** - Frequency (daily, weekly, monthly, annually), time, timezone * **Response Deadline** - Days before request times out (e.g., 7 days) * **Reminders** - Number of reminders and frequency (e.g., 3 reminders every 24 hours) * **Ticket Destination** - Target desk (e.g., IT), priority level (low, medium, high), optional assignee ### Compliance Report Details The exported CSV includes enriched employee-level data for every record, so your IT team has full context without switching between tools. Each row includes: * Employee email, job title, job description, and location * Manager details associated with each employee * Manager decision (acknowledged or rejected) and any notes provided Compliance tickets also include an employee-level summary in the description, making it straightforward to review and act on compliance issues directly from the ticket.
Working with AI AgentsLearn how to run and monitor agentsWorking with AI Agents
Configuring AI AgentsConfigure schedule and notificationConfiguring AI Agents
# Slack Operations Agent The Slack Operations Agent is a conversational AI agent that lets you manage common Slack administrative tasks directly from your support conversation. Instead of switching between tools or submitting manual requests, you can ask the agent to perform Slack actions on your behalf, and it handles the details through a guided back-and-forth exchange. This article covers the Slack operations currently supported, how each workflow behaves, and what to expect during the conversation. *** ### Creating a Slack Channel You can ask the Harmony service agent to create a new Slack channel at any point during a support conversation. The agent collects everything it needs before taking action, so you do not need to have all the details ready when you make the request. #### How the workflow works The agent guides you through the following steps conversationally: 1. **Channel name collection and validation** - If you do not provide a channel name in your initial request, the agent asks you for one. Before proceeding, it checks whether a channel with that name already exists in your workspace, and alerts you if there is a conflict so you can choose a different name. 2. **Visibility selection** - The agent asks whether the new channel should be public or private. Public channels are visible and joinable by anyone in your workspace. Private channels are invite-only. 3. **Optional member invites** - You can specify one or more colleagues to add to the channel at the time it is created. This step is optional - if you skip it, the channel is created with you as the only member, and you can invite others later directly in Slack. 4. **Confirmation and creation** - Once the agent has all the required information, it summarises the details and asks you to confirm before creating the channel. After you confirm, the channel is created and the agent provides a direct link or confirmation message so you can navigate to it immediately. #### Example conversation > **You:** Can you create a new Slack channel for the Q3 launch project? > > **Agent:** Sure! What would you like to name the channel? > > **You:** q3-launch > > **Agent:** Got it. Should this channel be public or private? > > **You:** Private, please. > > **Agent:** Would you like to invite any team members now? If so, please share their names or email addresses. > > **You:** Add and . > > **Agent:** Here is a summary - I will create a private channel named **#q3-launch** and invite and . Shall I go ahead? > > **You:** Yes. > > **Agent:** Done! The channel **#q3-launch** has been created and your teammates have been invited. #### Things to keep in mind * Channel names must follow Slack naming rules: lowercase letters, numbers, hyphens, and underscores only, with a maximum of 80 characters. * The agent will flag any naming issues and prompt you to adjust before continuing. * If a channel with the requested name already exists, the agent will notify you and ask whether you want to use a different name or join the existing channel instead. * Member invites at creation time are optional and can always be skipped. *** ### Supported Slack Operations The table below summarises the Slack operations currently available through the conversational agent. | Operation | What the agent does | | ---------------- | -------------------------------------------------------------------------------------------- | | Create a channel | Creates a new public or private Slack channel, with optional member invites at creation time | Additional Slack operations will be added over time. If you need a Slack action that is not listed here, you can still submit a request through your normal support process. *** ### Getting Started To use the Slack Operations Agent, simply start a conversation with the Harmony service agent and describe what you want to do. For example: * "Create a new Slack channel called project-alpha." * "Set up a private Slack channel and invite my team." * "I need a new Slack channel for the design team." The agent recognises these requests and initiates the appropriate guided workflow automatically. You do not need to use any special commands or syntax. # Unused Application Monitoring The Unused Application Monitoring agent automatically scans your Identity Provider (IdP) for applications that have gone unused, then creates tickets so your team can review and act on them. By surfacing stale apps on a regular basis, you reduce your attack surface, simplify your app portfolio, and keep your IdP clean without relying on manual audits. *** ### How It Works When the agent runs, it connects to your configured IdP sources and evaluates each application against the inactivity criteria you define. Any application that meets the unused threshold is flagged, and the agent automatically opens a ticket listing those applications so your team can investigate, reassign, or decommission them. The process follows these steps: 1. The agent scans the IdP sources and application groups you specify. 2. It evaluates each application against your configured detection threshold - based on last sign-in date or number of active users. 3. Applications that meet the unused criteria are collected into a report. 4. The agent creates a ticket containing the list of unused applications for your team to review and action. *** ### Configuring the Agent #### Detection Threshold You control what counts as "unused" by setting an inactivity threshold. You can base this on either: * **Last sign-in date** - Flag any application where no user has signed in within a defined number of days. * **Active user count** - Flag any application that falls below a minimum number of active users. Choose the criterion that best fits your organization's usage patterns. For example, a stricter last-sign-in window works well for high-frequency tools, while an active-user threshold may be more appropriate for applications with periodic but legitimate use. #### Scan Targets You can define exactly which parts of your IdP the agent scans on each run: * **IdP sources** - Select one or more IdP integrations (for example, Okta, Azure AD, or other connected providers) to include in the scan. * **Application groups** - Narrow the scope further by targeting specific groups or categories of applications within those sources. Limiting the scan to relevant targets keeps results focused and avoids noise from applications that are intentionally inactive or out of scope. *** ### Ticket Creation When the agent detects unused applications, it automatically creates a ticket that includes: * The list of applications identified as unused. * The relevant inactivity data for each application, based on your configured threshold. Your team can then use the ticket to coordinate review, reach out to application owners, or begin offboarding the unused apps. No manual report generation or scheduled exports are needed - the agent handles detection and notification end to end. *** ### Enabling the Agent To enable Unused Application Monitoring: 1. Navigate to **AI Agents** in your Harmony dashboard. 2. Locate the **Unused Application Monitoring** agent under the Software Management section. 3. Select your IdP source or sources to scan. 4. Configure your detection threshold - choose between last sign-in or active user count, and set the appropriate value. 5. Optionally, specify application groups to include or exclude from the scan. 6. Save your configuration and activate the agent. Once active, the agent will run according to your configured schedule and create tickets whenever unused applications are detected. *** ### Benefits * **Reduced security risk** - Unused applications are a common source of unnecessary access and credential exposure. Regular detection helps you close those gaps faster. * **Cleaner app portfolio** - Keeping your IdP free of stale apps makes administration easier and reduces confusion for end users and IT teams alike. * **Automated, consistent coverage** - Rather than relying on periodic manual reviews, the agent provides ongoing monitoring so nothing slips through between audit cycles. * **Actionable output** - Every detection run produces a ticket, giving your team a clear, trackable item to work from rather than a raw data export to sort through. # Application Health Check: Discovered Applications The **Application Health Check: Discovered Applications** agent gives your team an automated, scheduled view of every application currently marked as Discovered in Harmony. Instead of running manual lookups to track down unreviewed or unmanaged applications, the agent surfaces all relevant details on a recurring basis so you can review, act, and stay on top of your discovered application inventory without extra effort. ### What This Agent Does This autonomous agent runs on a schedule you define and automatically monitors all applications with a Discovered status in Harmony. For each discovered application, the agent collects and surfaces the following information: * **Application details** - name, first discovered date, last seen date, owner, and all other available application metadata * **Associated users** - full user information for every user linked to each discovered application * **Associated instances** - all instance data tied to each discovered application Because the agent runs autonomously, your team receives an up-to-date picture of your discovered application landscape without anyone needing to manually query or compile the data. ### Setting Up the Agent To configure the Application Health Check: Discovered Applications agent, follow these steps: 1. Navigate to the **AI Agents** section in Harmony. 2. Locate and select **Application Health Check: Discovered Applications** from the available agent catalog. 3. Configure the schedule to define how frequently the agent should run - for example, daily, weekly, or at a custom interval that fits your review cadence. 4. Save your configuration to activate the agent. Once activated, the agent begins running automatically according to your chosen schedule. ### Reviewing Agent Output After each scheduled run, the agent surfaces its findings so your team can review the collected data. For each discovered application you will see: * A summary of application metadata, including when it was first discovered and when it was last seen * A list of users associated with the application, with full user details * Instance information linked to the application You can use this output to make informed decisions about each discovered application - such as approving it, flagging it for further review, or taking remediation steps based on your organization's policies. ### Use Cases * **Reduce manual monitoring overhead** - Eliminate recurring manual lookups by letting the agent automatically surface discovered applications on a schedule. * **Maintain application inventory hygiene** - Regularly review newly discovered or long-standing unmanaged applications before they become a compliance or security concern. * **Accelerate review workflows** - Give your team consolidated, ready-to-act information for every discovered application, including user and instance context, in a single agent output. # Device Recovery Automated device recovery with identity verification and recovery key delivery. The **Device Recovery** agent automates device recovery requests with identity verification and secure recovery key delivery to employees. The agent guides users step by step through the recovery process, handling device password resets and related asset management automatically - reducing the support load on your team while getting end users back into their devices quickly. ![Device Recovery agent overview](https://1766914782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIWiU87MW3r16e1GcC8yt%2Fuploads%2Fgit-blob-ab6e90062806d676949b20c8b4d1d00046e56c17%2Fdevice-recovery.png?alt=media) ### What it does * Triggered when a user requests device recovery * Confirms the exact issue before triggering any workflow - if a user submits a vague message like "I'm locked," the AI clarifies whether it is a device lock, an account lock, or another situation before routing to the correct flow * Verifies user identity via OTP or Okta Verify push notification before sharing any recovery key * Retrieves device recovery key from MDM integration (JAMF, Intune, JumpCloud, or Kandji) * Sends message with recovery key via Slack or Teams, with optional automatic expiry after one hour * Updates the ticket with status and outcome * Optionally performs automatic password reset when required (disabled by default) ### Triggers **Event** - Runs when agent detects Device Recovery Request made by user. ### Approval No approval required. The agent uses identity verification instead of approval workflow. ### Configuration #### Identity Verification Require users to verify their identity during device recovery. Choose from two verification methods: * **One-Time Password (OTP)** - A one-time password is sent to the user's primary email address, and secondary email if available. The user must enter this code when prompted via direct message to verify their identity. * **Okta Verify Push Notification** - Send a push notification to the user's Okta Verify app for quick and secure verification. #### Auto Password Reset Optionally enable automatic password reset for the user during the device recovery process. Automatic password reset is **disabled by default** - this reduces unintended disruption for end users who are simply recovering a device and do not need their password changed. You can enable it on a per-tenant basis through configuration if your workflow requires it. #### Recovery Key Message Expiry You can configure Harmony to automatically remove the recovery key from device recovery messages after one hour, reducing the risk of sensitive keys being exposed indefinitely in chat. When enabled, the original direct message sent to the end user is updated after 60 minutes to replace the recovery key with an expiry notice. * **Optional toggle** - The expiry behaviour is off by default and can be enabled via the `expire_recovery_key_message` setting in the Device Recovery workflow configuration. * **Automatic cleanup** - Once the ticket is resolved and the timer elapses, no trace of the key remains in the conversation. #### MDM Provider Blocks You can use dedicated MDM workflow blocks for each of your device management providers, giving the agent precise, provider-specific control over managed devices. The following providers are supported out of the box, each with their own set of blocks tailored to their capabilities: | Provider | Available Blocks | | -------------------- | --------------------------------------------------------- | | **JAMF** | Get device, list devices, get recovery key, update device | | **Microsoft Intune** | Get device, list devices, get recovery key, update device | | **JumpCloud MDM** | Get device, list devices, update device | | **Kandji** | Get device, list devices, get recovery key | These blocks connect to their respective MDM integrations and can be combined within the Device Recovery workflow to automate end-to-end recovery scenarios - such as retrieving a Personal Recovery Key from JAMF for a locked Mac, or triggering recovery actions through Intune or Kandji - without leaving Harmony. You can also retrieve a device's lock PIN directly through the Device Management API, making it easier to look up lock PIN information programmatically to support faster and more automated device management workflows. #### Tenant Access Control You can use tenant whitelist filtering to control which tenants have access to the device recovery password reset workflow template. This gives administrators precise control over which organisations can trigger password reset flows for device recovery, reducing the risk of unintended access across tenants. #### Smarter Pre-Workflow Confirmation Before triggering any recovery or reset workflow, Harmony confirms the exact issue the user is experiencing. When a user submits a vague or ambiguous message, the AI clarifies the situation before taking action: * **Device lock** - routes to the Device Recovery workflow only after confirming it is a device-related issue * **Account lock / IDP password expiration** - routes to the IDP Password Reset workflow only after confirming the lock type * **Other or unclear situations** - the AI continues to gather context before proceeding This prevents the wrong workflow from being triggered and reduces disruption caused by misclassified requests.
Working with AI AgentsLearn how to run and monitor agentsWorking with AI Agents
Configuring AI AgentsConfigure verification and deliveryConfiguring AI Agents
# Password Reset Request Automated password reset request with identity verification and temporary password delivery. The **Password Reset Request** agent automates password resets for identity provider users with identity verification and secure temporary password delivery. ![Password Reset Request agent overview](https://1766914782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIWiU87MW3r16e1GcC8yt%2Fuploads%2Fgit-blob-9e1232928189cbd2109cdfddf7a0737020210884%2Fidp-password-reset.png?alt=media) ### What it does * Triggered when a user requests an IdP password reset * Verifies user identity via OTP or Okta Verify push notification * Resets user's password to a temporary password in their identity provider * Generates a secure temporary password and requires the user to change it at next login * Terminates all active sessions for the user across configured identity providers * Sends the password reset link or OTP to the user's primary email, secondary email, or recovery email (including Microsoft Entra `otherMails` addresses) * Sends message with temporary password via Slack or Teams * Updates the ticket with status and outcome ### Triggers **Event** - Runs when agent detects IdP Password Reset Request made by user. The agent accurately distinguishes work account password reset requests from personal account requests. Gmail references are interpreted as Google Workspace work accounts only when the context clearly indicates it, preventing the workflow from triggering incorrectly for personal Gmail accounts. ### Approval No approval required. The agent uses identity verification instead of approval workflow. ### Configuration #### Identity Verification Verify the employee's identity before resetting their password. Choose from two verification methods: * **One-Time Password (OTP)** - A one-time password is sent to the user's primary email address, secondary email, or recovery email if available. The user must enter this code when prompted via direct message to verify their identity. * **Okta Verify Push Notification** - Send a push notification to the user's Okta Verify app for quick and secure verification. #### Password Reset Target Select the identity provider where the password will be reset: * **Okta** - Reset password in Okta identity provider * **Microsoft Entra ID** - Reset password in Microsoft Entra (formerly Azure AD) * **Google Workspace** - Reset password in Google Workspace * **JumpCloud** - Reset password in JumpCloud identity provider The agent supports Okta, Microsoft Entra, Google Workspace, and JumpCloud identity providers. It automatically discovers the employee's IdP integrations and terminates sessions across all configured providers. #### Account Status and IDP-Aware Guidance The agent identifies which identity provider an employee uses and tailors its guidance accordingly: * **Entra ID employees** with a locked account are guided through a Password Reset workflow, since account unlock is not available for Entra ID. * **Okta employees** with a locked account are offered both Unlock Account and Password Reset options. * **Employees with both Okta and Entra ID accounts** receive clear, per-IDP instructions so they know exactly what action is available for each account.
Working with AI AgentsLearn how to run and monitor agentsWorking with AI Agents
Configuring AI AgentsConfigure verification and deliveryConfiguring AI Agents
# IdP MFA Reset Automated MFA device reset with identity verification and re-enrollment instructions. The **MFA Device Reset** agent automates MFA resets for identity provider users with identity verification and re-enrollment instructions. ![MFA Device Reset agent overview](https://1766914782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIWiU87MW3r16e1GcC8yt%2Fuploads%2Fgit-blob-bbe81d947ab08566e3b10f71475ddf29b1c45f8f%2Fidp-mfa-reset.png?alt=media) ### What it does * Triggered when a user requests an MFA reset * Verifies user identity via one-time password (OTP) sent to the employee's email * Presents the user with an interactive list of their enrolled MFA devices so they can select only the ones to remove * Resets selected MFA factors for the user in their identity provider, leaving any unselected devices intact * Terminates all active sessions for the user across configured identity providers * Sends text notification via Slack, Teams, or email based on user preferences * Updates the ticket with status and outcome ### Triggers **Event** - Runs when agent detects MFA Reset Request made by user. ### Approval No approval required. The agent uses identity verification instead of approval workflow. ### Configuration #### Identity Verification Verify the employee's identity before resetting their MFA. The agent uses: * **One-Time Password (OTP)** - A one-time password is sent to the user's primary email address, and secondary email if available. The user must enter this code when prompted via direct message to verify their identity. #### MFA Reset Target Select the identity provider where MFA factors will be reset: * **Okta** - Reset MFA factors in Okta identity provider. After the reset, the user receives a sign-in URL to re-enroll. * **Microsoft Entra ID** - Reset MFA factors in Microsoft Entra (formerly Azure AD). Clears registered authentication methods and revokes active sessions. * **Google Workspace** - Reset MFA factors in Google Workspace. * **JumpCloud** - Reset MFA factors in JumpCloud. The agent supports the following factor types: * **TOTP (authenticator app)** - List and reset time-based one-time password devices. * **Push notifications** - List and reset push-based MFA devices. * **Combined TOTP + push** - Reset multiple factor types in a single workflow. The agent supports Okta, Microsoft Entra, Google Workspace, and JumpCloud identity providers. It automatically discovers the employee's IdP integrations and terminates sessions across all configured providers. #### Selective Device Removal When a reset is triggered, the agent sends the user an interactive notification listing all of their enrolled MFA devices. The user can select only the specific devices they want removed using a multi-select prompt delivered directly in Slack or Microsoft Teams - no need to leave their existing workflow. The agent then removes only the selected devices, leaving any others intact and reducing the risk of unnecessary disruption. #### Revoke All Sessions Optionally revoke all active user sessions after resetting MFA factors for enhanced security. This ensures that any potentially compromised sessions are immediately invalidated as part of the reset flow.
Working with AI AgentsLearn how to run and monitor agentsWorking with AI Agents
Configuring AI AgentsConfigure verification and deliveryConfiguring AI Agents
# IdP Group Management Manage group membership with approval - add or remove users from groups. The **Group Membership Management** agent manages identity provider group assignments with approval workflow for adding or removing users from groups. ![Group Membership Management agent overview](https://1766914782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIWiU87MW3r16e1GcC8yt%2Fuploads%2Fgit-blob-d859cfda898e4c78a0d0763543558a2a09c96f3c%2Fidp-group-management.png?alt=media) ### What it does * Triggered when a user requests a group membership change * Sends approval request to one or more approvers and waits for response * On approval: adds and/or removes users from an identity provider group * Updates the ticket with the outcome * Supports natural-language requests submitted through Slack, Microsoft Teams, and other connected channels * Can add or remove group owners in addition to standard members, with automatic owner resolution via email lookup * Handles requests for both standard IdP groups and email distribution lists ### Triggers **Event** - Runs when agent detects Group Membership Request made by user. ### Approval Requires approval by default. Configure approvers (e.g., Group Owner, Group Manager), approval logic (require one or all), and timeout settings. #### Assigning IdP Groups as Approvers Instead of specifying individual approvers, you can assign an identity provider group as the approver for any approval step. When a request reaches that step, Harmony resolves the group's current members on demand, and any member can approve using the configured approval logic. * **Supported providers:** Okta, Microsoft Entra ID, and Google Workspace groups are all supported as approver sources * **Entra PIM awareness:** For Microsoft Entra ID, Harmony distinguishes between *active* members (who have access right now) and *eligible* members (who can request access), so only the appropriate members are resolved as approvers #### Group Owner and Group Manager as Distinct Approver Roles Group Owner and Group Manager are now separate, selectable approver types in group membership approval steps. Previously these roles were merged together; they are now resolved independently per identity provider: * **Google Workspace** - owners and managers are resolved independently; both are included as default approvers * **Microsoft Entra ID** - the correct owner role is surfaced and routable as a distinct approver type ### Configuration #### Set approvers The Group Owner and Group Manager will be determined based on the group membership being modified. These roles are surfaced as distinct approver types, so you can route approvals to exactly the right people. Configure the approval logic: * **Approval logic** - Require approval from one of the approvers, or require all approvers to approve #### Per-IdP Enablement You can configure the agent to work with Google Workspace, Okta, or both - independently. Google and Okta group membership are managed as separate units, giving you granular control over how the agent operates across identity providers. * **Per-IdP enablement** - Choose to activate the agent for Google Workspace only, Okta only, or both simultaneously * **Independent approval flows** - When both Google and Okta are enabled, each identity provider follows its own distinct approval workflow, so approvals for one IdP do not affect the other #### Business Justification You can require requesters to provide a business justification when submitting group membership requests. When enabled, approvers receive full context before acting on an access request. * **Optional toggle** - Enable or disable the business justification requirement per workflow; it is off by default * **Automatic prompting** - If a requester does not include a justification in their initial message, the agent asks for one before the request is submitted * **Carried through to approvers** - The justification is included in the approval request so approvers have the context they need #### Execution settings * **Approval request timeout** - Days before approval request times out (e.g., 2 days) #### Notifications Toggle notifications for approval status updates. #### Identity Provider Support The agent supports group membership management across multiple identity providers: * **Okta** - Add or remove users from Okta groups * **Microsoft Entra ID** - Manage group membership in Microsoft Entra (formerly Azure AD) * **Google Workspace** - Update Google Workspace group memberships The agent automatically detects which identity provider the target group belongs to and performs the appropriate add or remove operation. Group data is sourced directly from Harmony's database, ensuring the groups shown in configuration are always accurate and up to date. ### Workflow Builder When configuring group membership blocks in the Workflow Builder, you can select multiple users at once rather than adding them one by one. This saves time when setting up or updating workflows that involve larger teams.
Working with AI AgentsLearn how to run and monitor agentsWorking with AI Agents
Configuring AI AgentsConfigure approval and IdP settingsConfiguring AI Agents
# Account Unlock Harmony's AI agent can now handle account unlock requests from start to finish, without requiring manual IT intervention. When an employee reports being locked out, the agent checks their account status in real time, identifies the cause of the lockout, and triggers the appropriate unlock workflow automatically - all within a single conversation. Account unlock support is available for both **Okta** and **Microsoft Entra ID**, covering the most common identity providers used across modern organizations. *** ### How It Works When a user submits an account unlock request through the AI agent, the following steps happen automatically: 1. The agent receives the employee's request and identifies the affected user account. 2. It queries the configured identity provider in real time to check the current account status. 3. It determines the cause of the lockout (for example, too many failed sign-in attempts or Smart Lockout enforcement). 4. It initiates the appropriate unlock workflow based on the identity provider. 5. The employee is notified once the unlock is complete or if further action is needed. No ticket routing, no manual escalation, and no waiting on an IT technician to run a query. *** ### Supported Identity Providers #### Okta Account Unlocks When an employee is locked out of their Okta account, the agent: * Detects that the account is in a locked state by checking Okta in real time. * Creates an unlock ticket to trigger the account unlock workflow directly within Okta. * Confirms the outcome back to the employee once the workflow completes. This removes the need for an IT administrator to manually locate the account in the Okta console and initiate the unlock. #### Microsoft Entra ID - Smart Lockout Detection When an employee is locked out of their Microsoft Entra ID account, the agent: * Identifies that the account has been locked via Entra's Smart Lockout mechanism. * Detects the lockout cause based on real-time account status signals. * Initiates the unlock workflow automatically to restore access. Smart Lockout in Entra ID triggers after a threshold of failed sign-in attempts, and the agent handles detection and remediation without requiring an administrator to intervene through the Azure portal. *** ### Prerequisites Before account unlock automation is available to your employees, make sure the following are in place: * Your Okta or Microsoft Entra ID integration is connected and authorized within Harmony. * The AI agent has been granted the necessary permissions to read account status and trigger unlock actions in the relevant identity provider. * Account unlock workflows are enabled in your agent configuration. Refer to the integration setup guides for [Okta](/ai-agents/access-control/account-unlock) and [Microsoft Entra ID](/ai-agents/access-control/account-unlock) for permission and scope requirements. *** ### Employee Experience From the employee's perspective, the interaction is straightforward: 1. The employee messages the AI agent describing their lockout (for example, "I can't sign in, my account is locked"). 2. The agent confirms their identity and looks up their account. 3. Within the same conversation, the agent resolves the lockout and lets the employee know they can try signing in again. There is no need to submit a support ticket, wait for an IT queue, or follow a multi-step self-service portal flow. *** ### Notes and Considerations * The agent handles unlocks only for accounts that are locked due to authentication failures or policy-triggered lockouts. Accounts that are disabled or suspended for administrative or compliance reasons are not unlocked automatically. * If the agent cannot resolve the lockout - for example, due to a permissions issue or an unsupported lockout state - it escalates the request to a human agent and informs the employee accordingly. * All unlock actions are logged for audit purposes within Harmony's activity history. # IdP Account Unlock The Automated IDP Account Unlock Workflow lets you resolve locked Identity Provider (IDP) account situations without any manual intervention. By adding the `unlock_user` block to a Harmony Workflow, you can handle the full unlock lifecycle - from verifying the requester's identity, to unlocking the account, to notifying the user and closing the associated ticket - all in a single automated flow. This article explains how the feature works, what statuses are supported, and how to configure the workflow block for your environment. *** ### How It Works When a user's IDP account is locked, the workflow is triggered automatically. The `unlock_user` block takes over and performs the following steps in sequence: 1. **Identity verification** - Confirms the requester's identity before any unlock action is taken. 2. **Unlock attempt** - Issues the unlock call to the connected IDP. 3. **Status-aware routing** - Evaluates the outcome of the unlock attempt and branches the workflow accordingly. 4. **Notification** - Sends the user a confirmation or a next-steps message depending on the outcome. 5. **Ticket resolution** - Closes or escalates the associated support ticket based on the final state. Because the routing is driven by the actual account status returned by the IDP, the workflow automatically handles edge cases without requiring separate manual rules. *** ### Supported Identity Providers #### Okta The `unlock_user` block has full support for Okta accounts. The behavior depends on the status Okta reports for the account at the time the workflow runs: | Okta Account Status | Workflow Outcome | | ------------------- | ------------------------------------------------------------------------- | | Locked out | Account is unlocked automatically and the user is notified. | | Suspended | Routed to the escalation path - agent review required. | | Deprovisioned | Routed to the escalation path - agent review required. | | Password expired | Routed to the escalation path - user is prompted to reset their password. | This status-aware routing means your team only receives escalations for situations that genuinely require human judgment. Routine lockouts are resolved end-to-end without touching the queue. *** ### Configuring the `unlock_user` Block To add the IDP account unlock capability to a workflow, follow these steps: 1. Open **Harmony Workflows** and create a new workflow or open an existing one. 2. In the workflow editor, add a new block and select **Unlock User** from the block library. 3. In the block configuration panel, set the following: * **Identity Provider** - Select the IDP connected to your environment (for example, Okta). * **Identity Verification Method** - Choose how the requester's identity should be confirmed before the unlock is attempted. * **Escalation Path** - Define which team or queue should receive escalations for statuses that cannot be resolved automatically. * **Notification Template** - Select or customize the message sent to the user after the unlock attempt. 4. Connect the block's outcome branches - typically a **success** branch for unlocked accounts and an **escalation** branch for all other statuses. 5. Save and activate the workflow. *** ### Workflow Outcome Branches The `unlock_user` block exposes the following outcome branches that you can connect to downstream steps: * **Unlocked** - The account was successfully unlocked. Use this branch to send a confirmation message and auto-resolve the ticket. * **Escalated** - The account is in a state that requires manual review (suspended, deprovisioned, or password expired). Use this branch to assign the ticket to an agent and notify the user that assistance is on the way. * **Error** - An unexpected error occurred during the unlock attempt. Use this branch to log the failure and alert your team. *** ### Benefits * **Faster resolution** - Locked-out users are unblocked immediately, without waiting for an agent to pick up the ticket. * **Reduced queue volume** - Only genuinely complex cases reach your support team. * **Consistent handling** - Every unlock request follows the same verified, auditable process. * **Status-aware escalation** - Accounts that need more than a simple unlock are automatically routed to the right place, reducing back-and-forth between agents and users. *** ### Requirements * Your IDP (for example, Okta) must be connected to Harmony as an integration before the `unlock_user` block is available in the workflow editor. * The service account or API token used for the IDP integration must have sufficient permissions to read account status and perform unlock operations. * Identity verification must be configured within the workflow to satisfy your organization's security policy before any unlock action is executed. # IdP Group Membership Query Blocks You can now query group membership information directly inside your Custom Agent workflows for all supported identity providers. Whether you need to verify access rights, audit group assignments, or drive conditional logic based on team membership, these blocks let you work with group data without leaving your workflow. The following identity providers are supported: * Okta * Microsoft Entra * Google Workspace * JumpCloud ### Available Blocks Four workflow blocks are available for group membership queries. Three are new additions, and one existing block has been enhanced. #### Check Group Membership Use this block to verify whether a specific employee is a member of a given group. This is useful for conditional branching - for example, routing a request differently depending on whether the user belongs to an admin or standard-access group. #### List User's Groups Use this block to retrieve all groups that a specific employee belongs to. The block includes full pagination support, so you can handle employees with large numbers of group memberships without missing any results. #### Get Group Details Use this block to look up information about a specific group by its ID. The response includes details such as the group's member count, making it helpful for auditing or validating group size before taking downstream actions. #### List Groups (Enhanced) The existing **List Groups** block has been updated with a `search` parameter. You can now filter the list of groups returned by a search term, making it easier to locate specific groups in large directories without retrieving the full group list first. ### Using Group Membership Blocks in a Workflow To add any of these blocks to a Custom Agent workflow: 1. Open the workflow editor for your Custom Agent. 2. Add a new block and search for the relevant group membership block by name. 3. Select your identity provider from the available options. 4. Configure the required inputs - such as the employee identifier or group ID - and connect the block's output to downstream steps as needed. Because all four blocks work consistently across Okta, Microsoft Entra, Google Workspace, and JumpCloud, you can build identity-provider-agnostic workflows or target a specific provider depending on your organization's setup. ### Common Use Cases * **Access verification** - Check whether an employee is in a specific security or access group before approving a request or granting a resource. * **Onboarding automation** - List a new employee's current group memberships to confirm provisioning steps completed correctly. * **Audit and compliance** - Retrieve group details and member counts to validate that groups stay within expected size thresholds. * **Dynamic routing** - Use group membership checks as conditions to branch your workflow logic based on a user's role or team. # Privileged Access Review Agent The Privileged Access Review agent automates the full lifecycle of elevated-access audits across your connected applications. Instead of running manual reviews on a schedule, the agent continuously monitors which users hold admin or elevated permissions in each managed application, reaches out to the right owner for a decision, and acts on that decision automatically - all without requiring you to build or maintain a separate workflow. This article explains how the agent works, how to configure it, and what happens at each stage of the review cycle. *** ### How It Works The Privileged Access Review agent runs on a recurring schedule you define. Each cycle follows these steps: 1. **Discovery** - The agent scans each connected application and identifies every user who holds admin or elevated permissions at the time of the review. 2. **Owner resolution** - For each application, the agent looks up the configured application owner. If no owner is set, your IT admin is used as the fallback recipient. 3. **Review request** - The agent sends the owner an interactive review request over Slack, Teams, or email. The request lists each flagged user along with their current role or permission level. 4. **Decision collection** - For every user on the list, the owner selects one of three actions: * **Approve** - the user retains their current access with no changes. * **Request removal** - the user's elevated access is revoked. * **Request role change** - the user's role is adjusted to a lower permission level. 5. **Execution** - The agent applies approved removal or role-change decisions directly in the connected application. 6. **Logging** - Every decision - whether approve, remove, or change - is recorded automatically in the audit log for compliance and reporting purposes. *** ### Supported Notification Channels Review requests can be delivered through any of the following channels: * **Slack** - sent as an interactive message to the application owner's Slack account. * **Microsoft Teams** - sent as an adaptive card in the owner's Teams account. * **Email** - sent as a structured email with inline action links. The channel used for a given review is determined by the notification preferences configured in your Harmony workspace. *** ### Configuring the Agent #### Prerequisites Before enabling the Privileged Access Review agent, make sure you have: * At least one application connected to Harmony through an integration. * The relevant application owners assigned within Harmony, or an IT admin fallback address configured. * Notification channel credentials set up (Slack OAuth, Teams connector, or SMTP settings). #### Setting Up a Review 1. Navigate to **AI Agents** in the Harmony console and open the **Privileged Access Review** agent. 2. Select the applications you want to include in the review scope. 3. Set the review frequency - for example, weekly, bi-weekly, or monthly. 4. Confirm or update the application owner for each selected application. Where no owner is assigned, verify that your IT admin fallback is correct. 5. Choose the notification channel through which review requests will be sent. 6. Save and activate the agent. Once activated, the agent begins its first scan at the next scheduled interval. *** ### Review Request Experience When the agent sends a review request, the recipient sees a structured list of users with elevated permissions in the application. Each entry includes: * The user's name and email address. * Their current role or permission level. * Action buttons or links to **Approve**, **Request Removal**, or **Request Role Change**. Owners can act on each user individually. The agent waits for responses and applies decisions as they come in. If a deadline or reminder policy is configured, the agent can follow up automatically with the owner if responses are pending. *** ### Access Revocation and Role Changes When an owner selects **Request Removal** or **Request Role Change** for a user, the agent executes the action directly through the connected application's integration. You do not need to intervene manually. * **Removal** deprovisions the user's elevated permissions in the target application. * **Role change** reassigns the user to the lower-privilege role specified during the decision. Both actions take effect as soon as the agent processes the owner's response. *** ### Audit Logging Every action taken by the Privileged Access Review agent is captured in the Harmony audit log. Log entries include: * The application reviewed. * The user whose access was evaluated. * The decision made (approved, removed, or role changed). * The identity of the owner who made the decision. * The timestamp of the decision and the timestamp of execution. These records are available for export and can be used to satisfy compliance requirements for privileged access management audits. *** ### Fallback Behavior If no application owner is configured for a given application, all review requests for that application are routed to the designated IT admin. This ensures no application is skipped during a review cycle, even if ownership has not yet been assigned. It is recommended that you assign a dedicated owner to each application to keep review requests targeted and reduce the volume of notifications sent to your IT admin. *** ### Best Practices * **Assign application owners explicitly** for every managed application so that review requests reach the most relevant person rather than defaulting to IT admin. * **Start with a longer review interval** (monthly) when first enabling the agent, then shorten the interval once owners are familiar with the process. * **Review the audit log after each cycle** to confirm that all removal and role-change actions were executed successfully. * **Use Slack or Teams** as your notification channel when possible - interactive messages in those platforms tend to get faster responses than email-based action links. # Unauthorized Application Monitoring Agent The Unauthorized Application Monitoring agent automatically scans your identity provider (IdP) for applications that have not been formally approved and surfaces them to your team on a recurring schedule. Instead of manually auditing your application catalog, you get a ready-made ticket, a detailed report, and a direct notification every time the agent runs - so unauthorized apps never go unnoticed. ### What the Agent Does Each time the agent runs, it performs the following actions: 1. **Scans your IdP** for any application that lacks an approved status in your catalog. 2. **Creates a ticket** that lists every unauthorized application found during that scan. 3. **Attaches a CSV report** to the ticket containing enriched details for each app, including owner, status, assigned users, first-seen date, last-seen date, and more. 4. **Notifies the IT desk owner or assignee** via Slack or Microsoft Teams so the right person can act immediately. ### Supported Identity Providers The agent works with the following IdPs: * Okta * Microsoft Entra * Google Workspace * JumpCloud ### Prerequisites Before activating the agent, make sure you have: * A connected IdP integration (Okta, Entra, Google Workspace, or JumpCloud) * A ticketing integration configured (for ticket creation) * A Slack or Microsoft Teams integration configured (for notifications) * Defined which applications in your IdP catalog are considered approved ### Setting Up the Agent 1. Navigate to **AI Agents** in the left sidebar and select **Unauthorized Application Monitoring**. 2. Choose the IdP you want the agent to scan. 3. Select your ticketing destination where new tickets should be created. 4. Choose the IT desk owner or assignee who will receive Slack or Teams notifications when the agent surfaces unauthorized apps. 5. Set the recurring schedule that controls how often the agent runs (for example, daily or weekly). 6. Save your configuration and activate the agent. Once activated, the agent will run automatically on the schedule you defined. ### Understanding the CSV Report Every ticket created by the agent includes an attached CSV report. The report contains one row per unauthorized application and includes the following fields: | Field | Description | | ---------------- | ------------------------------------------- | | Application Name | The display name of the app in your IdP | | Owner | The user or team assigned as the app owner | | Status | The current approval or provisioning status | | Assigned Users | Number of users with access to the app | | First Seen | Date the app was first detected in your IdP | | Last Seen | Most recent date the app was observed | Use this report to prioritize remediation, track repeat offenders, and maintain an auditable record of your application catalog reviews. ### Recurring Schedule The agent runs on a schedule you configure during setup. On each run: * Only applications that are currently unauthorized at the time of the scan are included. * A new ticket is created for each run so you have a clear, time-stamped history of findings. * The designated owner or assignee receives a fresh notification via Slack or Teams. Adjust the schedule at any time by returning to the agent's configuration page. ### Notifications When the agent completes a scan and finds unauthorized applications, it sends a notification to the configured IT desk owner or assignee through your connected messaging platform. The notification includes a summary of what was found and a link to the newly created ticket, so the recipient can jump directly into the details without searching for context. # Device Uptime Monitoring Automated monitoring for devices with high uptime (haven't restarted). The **Device Uptime Monitoring** agent identifies devices that have been running for an extended period without a restart. Long uptime can indicate missing restarts and security updates. You can configure thresholds, notifications, and ticket creation to match your organization's needs - and scope test runs to specific employees for faster validation. ![Device Uptime Monitoring agent overview](https://1766914782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIWiU87MW3r16e1GcC8yt%2Fuploads%2Fgit-blob-392dc43f25d703049929d7274144e5d688fa1fd6%2Fdevice-uptime-monitoring.png?alt=media) ### What it does * Runs periodic checks for devices with high uptime * Queries devices that haven't restarted within a threshold * Marks devices as NEW or existing based on entity tracking * Sends notifications to device owners about devices that haven't been restarted * Optionally excludes VIP employees from automated notification delivery * Generates CSV report with all devices meeting criteria * Creates ticket with CSV attachment for IT team review (can be toggled off) ### Triggers **Schedule** - Runs at configured frequency (e.g., daily at 08:00) via cron. ### Approval No approval required. The agent monitors and alerts, remediation is handled manually or by other workflows. ### Configuration #### Run Schedule * **Frequency** - Daily, weekly, monthly, or custom interval * **Time** - Specific time to run (e.g., 08:00) * **Timezone** - Timezone for scheduled execution (e.g., UTC+00:00) #### User Notifications Toggle to enable/disable notifications to device owners about their devices with high uptime. * **Exclude VIP employees** - Check this option to prevent VIP employees from receiving automated uptime notifications, keeping sensitive personnel out of automated outreach. #### Ticket Creation Enable or disable automatic ticket creation for devices exceeding the uptime threshold. Ticket creation is enabled by default, so existing workflows continue to behave as before with no action required. * **Create ticket after** - Days without restart before creating a ticket (e.g., 30 days) When ticket creation is turned off, the downstream steps - CSV report generation and ticket creation - are automatically disabled as well, preventing unnecessary processing. #### Ticket Destination * **Desk** - Target desk for created tickets (e.g., IT) * **Priority** - Priority level for tickets (low, medium, high) * **Assignee** - Optional assignee for created tickets #### Test Runs When triggering a test run, you can provide a target list of employee IDs to scope the check to only those individuals. This lets you validate device uptime monitoring for specific teams, roles, or individuals without running a full-scale check across your entire workforce.
Working with AI AgentsLearn how to run and monitor agentsWorking with AI Agents
Configuring AI AgentsConfigure schedule and thresholdsConfiguring AI Agents
# Low Storage Monitoring Automated monitoring for devices with critically low storage capacity. The **Low Storage Device Monitoring** agent finds devices with critically low free storage and creates tickets so IT can remediate before users are blocked. You can also configure automatic user notifications so affected employees are alerted as soon as their device crosses the configured threshold. ![Low Storage Device Monitoring agent overview](https://1766914782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIWiU87MW3r16e1GcC8yt%2Fuploads%2Fgit-blob-040647fadd50d8d456495a449c3d986614df8ef3%2Flow-storage-monitoring.png?alt=media) ### What it does * Runs periodic checks for devices with low storage * Queries devices with critically low storage capacity using flexible threshold conditions (percentage, minimum megabytes, or both) * Marks devices as NEW or existing based on entity tracking * Suppresses duplicate alerts - once a device is reported, it will not appear again until storage recovers to a healthy state * Reports all devices meeting threshold criteria, including the device owner and a clickable asset link for each flagged device * Generates CSV report with all devices * Creates ticket with CSV attachment for IT team review * Optionally notifies the affected user directly, separate from ticket creation ### Triggers **Schedule** - Runs at configured frequency (e.g., daily at 08:00 in your account's timezone) via cron. ### Approval No approval required. The agent monitors and alerts, remediation is handled manually or by other workflows. ### Configuration #### Run Schedule * **Frequency** - Daily, weekly, monthly, or custom interval * **Day** - Specific day of the week (e.g., Monday) * **Time** - Specific time to run (e.g., 08:00) * **Timezone** - Timezone for scheduled execution (e.g., UTC+00:00) #### Detection Threshold Configure the storage threshold that triggers alerts. You can set one or both conditions - an alert fires when either is met: * **Alert when remaining storage capacity is below** - Percentage threshold (e.g., 5% or the default 10%) * **Alert when remaining storage is below (MB)** - Minimum free storage in megabytes (e.g., the default 1 GB / 1024 MB) Setting both conditions means a device is flagged when free storage drops below the configured percentage **or** below the configured minimum in megabytes, whichever triggers first. #### User Notifications You can configure the agent to automatically notify the affected user when their device storage drops below the configured threshold. This notification is independent of ticket creation and can be enabled or disabled separately. * **Notify user** - Enable or disable direct notifications to the device owner * **Notification message** - Customise the message sent to the affected user #### Ticket Destination * **Desk** - Target desk for created tickets (e.g., IT) * **Priority** - Priority level for tickets (low, medium, high) * **Assignee** - Optional assignee for created tickets ### Report Details The CSV report attached to each ticket includes the following information for every flagged device: * **Device details** - Name, model, and current free storage values * **Owner** - The name of the employee assigned to each device, so you can immediately identify who to contact * **Asset link** - The Asset ID is a clickable hyperlink that takes you directly to the corresponding asset record, saving the step of a manual lookup
Working with AI AgentsLearn how to run and monitor agentsWorking with AI Agents
Configuring AI AgentsConfigure schedule and thresholdsConfiguring AI Agents
# Asset Provisioning Gap Detection Agents Keeping your asset inventory accurate is time-consuming when done manually. Two new autonomous agents continuously monitor your environment for provisioning gaps and surface them automatically, so your IT team can act without running periodic audits by hand. * **Employees with No Assigned Assets** - finds active employees in your identity provider (IdP) who have zero company-owned assets assigned to them. * **Assets with No Assigned Employees** - finds active company-owned assets that have no employee linked. When either agent detects a gap, it creates a ticket with a CSV report attached and notifies your desk admins through Slack or Microsoft Teams. ### How the Agents Work Both agents run on a configurable schedule. At each scheduled interval, an agent queries your connected IdP and asset inventory, compares the two data sets, and identifies records that do not have a corresponding match on the other side. If gaps are found, the agent automatically: 1. Creates a ticket in your helpdesk, with a CSV file attached that lists every affected employee or asset. 2. Sends a notification to your configured Slack channel or Microsoft Teams channel so desk admins are alerted in real time. If no gaps are found during a run, no ticket or notification is created. ### Employees with No Assigned Assets This agent focuses on the employee side of the gap. It scans your IdP for accounts that are marked as active and then checks whether any company-owned asset is assigned to each employee. Any active employee with zero assigned assets is included in the report. **Common follow-up actions for your IT team:** * Assign an existing unallocated asset to the employee. * Initiate a procurement or provisioning request if no suitable asset is available. * Verify whether the employee is a contractor or role that genuinely requires no hardware. ### Assets with No Assigned Employees This agent focuses on the asset side of the gap. It scans your active company-owned asset inventory and checks whether each asset is linked to at least one employee. Assets with no employee linked are included in the report. **Common follow-up actions for your IT team:** * Assign the asset to the correct employee if it was overlooked during onboarding. * Retire or mark the asset as a spare if it is no longer in use. * Investigate whether the asset was recently offboarded but not properly returned or decommissioned. ### Configuring the Agents You can configure each agent independently from the **Agents** section of your Harmony settings. For each agent, you can set: | Setting | Description | | ------------------------ | --------------------------------------------------------------------------------- | | **Schedule** | How often the agent runs (for example, daily, weekly, or a custom cron interval). | | **Notification channel** | The Slack channel or Microsoft Teams channel where desk admins receive alerts. | | **Ticket assignment** | The queue or group that newly created tickets are routed to. | Both agents can be enabled or disabled individually, so you can run only the checks that are relevant to your current workflow. ### Understanding the CSV Report Each ticket created by these agents includes a CSV file attachment. The CSV contains one row per detected gap and includes identifying details such as employee name, employee ID, asset name, and asset serial number, depending on the agent that generated it. You can download the CSV directly from the ticket to review the full list, filter by specific fields, or import it into another tool for bulk processing. ### Prerequisites Before enabling these agents, make sure the following are in place: * An IdP (such as Okta, Azure AD, or Google Workspace) is connected and syncing active employee records. * Your asset inventory is populated in Harmony with ownership and assignment data. * At least one Slack or Microsoft Teams integration is configured for notifications. --- [Next Page](/llms-full.txt/1)