Table of Contents

Altus Copilot Field PCF Control

Note
  • This is a preview feature.
  • Preview features aren’t meant for production use and might have restricted functionality. These features are subject to change, and are available before an official release so that customers can get early access and provide feedback.
  • Licensing requirements may change before General Availability

A Power Apps Component Framework (PCF) control that integrates Microsoft Copilot AI capabilities into Dynamics 365 form fields, enabling AI-assisted content generation and editing.

Altus Copilot field

Features

  • AI-Powered Content Generation: Leverage Kusanagi (Microsoft Copilot) to automatically generate field values based on context
  • Two Integration Modes:
    • Prompt Mode: Direct integration using Xrm.Copilot.executePrompt for simple AI prompts
    • Event Mode: Advanced integration using Xrm.Copilot.executeEvent to trigger Copilot Studio topics with dynamic context
  • Dynamic Context Loading:
    • Load context functions from web resources at runtime via contextLibraryResource property
    • Automatic 10-second polling (100ms intervals) to wait for context functions to become available
    • Flexible, reusable context gathering functions accessible via dot notation (e.g., SenseiProject.Copilot.getProjectContext)
  • Auto-Summarization: Optionally auto-populate fields when creating new records (if field is empty and Kusanagi is available)
  • Inline Editing:
    • Always-visible textarea for immediate editing
    • Hover-triggered sparkle button (✨) for AI generation
    • Manual edits disable automatic field synchronization
  • Graceful Degradation: Falls back to plain textarea when Kusanagi is unavailable
  • Accessibility: Full WCAG compliance with ARIA labels, keyboard navigation, and screen reader support
  • Responsive Design: Adapts to control's rowSpan configuration; works seamlessly across desktop and mobile devices
  • Telemetry Integration: Built-in Application Insights logging via shared LoggingService and Kusanagi telemetry infrastructure

Configuration Properties

Field Value (Required)

  • Type: Bound text field (SingleLine.Text or Multiple Lines of Text)
  • Description: The field that will display and store the AI-generated content. Supports both single-line and multi-line text fields.

Mode

  • Type: Enum (prompt | event)
  • Default: prompt
  • Description: Determines how the control interacts with Copilot
    • prompt: Uses simple prompt-based generation
    • event: Triggers Copilot Studio topics with context

Prompt

  • Type: Multiple-line text
  • Description: The prompt sent to Copilot (used in both modes - as the direct prompt in prompt mode, or as part of context in event mode)

Event Name (Event Mode Only)

  • Type: Single-line text
  • Description: The name of the Copilot Studio event/topic to trigger
  • Required when: Mode is event

Context Function Name (Optional)

  • Type: Single-line text
  • Description: Fully qualified name of a JavaScript function that returns additional context data. The function is dynamically resolved from the global scope (e.g., window.MyNamespace.getProjectContext). Used in both prompt and event modes to enhance the Copilot request with dynamic data.
  • Example: SenseiProject.Copilot.getProjectContext
  • Function Signature: async function(pcfContext?): Promise<string | Record<string, unknown>>
  • Resolution: Uses dot notation to navigate the window object tree at runtime. The control polls for up to 10 seconds for the function to become available, checking every 100ms.

Context Library Resource (Optional)

  • Type: Single-line text
  • Description: Web resource name containing the context handler function (e.g., sensei_Kusanagi.bundle.js). If specified, the control will dynamically load this web resource before executing the context function.
  • Example: sensei_Kusanagi.bundle.js

Auto-Summarize on New

  • Type: Boolean
  • Default: true
  • Description: Automatically trigger summarization when creating a new record

Usage Examples

Example 1: Simple Prompt Mode

Configure the control to summarize a project description:

Properties:
- fieldValue: new_projectsummary
- mode: prompt
- prompt: "Create a concise 2-3 sentence summary of this project based on its objectives, timeline, and expected outcomes."
- autoSummarizeOnNew: true

Example 2: Event Mode with Context

Configure the control to use a Copilot Studio topic with dynamic context:

Properties:
- fieldValue: new_statusupdate
- mode: event
- prompt: "Generate a status update for this project"
- eventName: "GenerateProjectStatus"
- contextFunctionName: "SenseiProject.Copilot.getProjectContext"
- contextLibraryResource: "sensei_Kusanagi.bundle.js"
- autoSummarizeOnNew: false

Context function example (add to form's web resource and expose on global namespace):

// In your web resource
window.SenseiProject = window.SenseiProject || {};
window.SenseiProject.Copilot = window.SenseiProject.Copilot || {};

window.SenseiProject.Copilot.getProjectContext = async function(pcfContext) {
    const formContext = pcfContext?.page?.getFormContext?.() || Xrm.Page;
    
    // Return structured data for event mode
    return {
        projectName: formContext.getAttribute("new_name")?.getValue(),
        projectId: formContext.data.entity.getId(),
        phase: formContext.getAttribute("new_phase")?.getValue(),
        riskLevel: formContext.getAttribute("new_risklevel")?.getValue(),
        budget: formContext.getAttribute("new_budget")?.getValue()
    };
    
    // Or return a string for simpler prompt mode enhancement
    // return JSON.stringify({ projectName: "...", phase: "..." });
};

Auto-Summarize Behavior

When autoSummarizeOnNew is enabled (default: true):

  1. The control checks if it's on a new form (no entity ID in context)
  2. If Kusanagi is available and no configuration errors exist
  3. If the field is empty or contains only whitespace
  4. The control automatically triggers AI generation on mount
  5. Auto-summarization only happens once per control instance to prevent repeated API calls

If Kusanagi is not available, the control falls back to editingFallback state regardless of the autoSummarizeOnNew setting.

User Interface

The control displays different states based on the field value, user actions, and Kusanagi availability:

Editing State (Primary)

  • Displays a textarea for viewing and editing content
  • On hover, shows a sparkle (✨) button in the top-right corner to trigger AI generation
  • After AI generation, displays an AI disclaimer below the textarea: "✨ Review AI content before use. See terms"
  • The textarea adapts its minimum height based on the control's rowSpan configuration
  • Users can manually edit content at any time; once manually edited, the control stops syncing with external field updates

Viewing State (Read-Only)

  • Displays the field content as read-only text when the control is disabled or the field is not editable
  • No AI generation button is shown

Editing Fallback State

  • Shown when Kusanagi is not available (not configured, not published, or user lacks required security role)
  • Displays a plain textarea without the AI sparkle button
  • Allows manual editing only
  • Also shown when certain Copilot API errors occur (e.g., "required field is not set")

Loading State

  • Displays skeleton loading indicators during:
    • Initial control initialization
    • AI content generation
  • Number of skeleton rows matches the control's rowSpan configuration

Accessibility Features

  • ARIA labels on all interactive elements
  • Keyboard navigation support
  • Screen reader announcements
  • High contrast mode support
  • Responsive design for various screen sizes
Edit this page