Connect Dynamics 365 X++ to Copilot Studio via Custom APIs

Core Concept: X++ Classes as Copilot Tools

Dynamics 365 X++ business logic can be exposed as tools to Copilot Studio agents by implementing the ICustomAPI interface and registering them as Power Apps APIs. This allows agents to call backend business operations directly within agentic instructions.

Purchase Order Workflow Example

The demo agent (named 'purchase man') orchestrates a complete PO lifecycle: gathering details, optionally submitting to workflow, confirming, and receiving. Each step calls a distinct X++ tool and passes parameters forward automatically without manual coding.

Purchase order agent workflow steps

Preview Feature: Custom API Generation

In Dynamics 365 Finance & Operations, enable the 'preview custom API generation' feature. This is a prerequisite for exposing X++ classes as APIs.

Three Required Components per Class

Each X++ class must (1) implement the ICustomAPI interface, (2) be decorated with AIPluginOperation and DataContract attributes specifying the plugin name and activity description, and (3) contain a Run() method with the business logic.

Example: PO Workflow Submission Class

Takes purchase ID and comment as input parameters. The Run() method calls the workflow template and passes the comment, triggering workflow processing automatically.

Example: PO Confirmation Class

Accepts purchase ID as input. The Run() method verifies the document is not already approved, then calls purchase order form data and confirmation processing class.

Example: PO Receipt Class

Takes purchase ID and packing slip ID as inputs. The Run() method calls the standard purchase order receipt class with UpdateAll option (or partial receipt if needed).

Menu Items and Security Setup

Create menu items with the same name as each class. Then create privileges and security roles for each menu item to control access.

Build and Deploy Process

Compile the X++ code, go to Extensions, select the model, ensure both 'Deploy' and 'DB sync' are checked, and deploy to the online environment. This process takes significant time; the environment will come back online when complete.

Create Solution and Publisher

In make.powerapps.com, create a new solution with a custom publisher and prefix (e.g., CR666). Record the prefix—it is essential for later identification of your APIs.

Add Custom API Objects

In the solution, navigate to Custom API (under More > Others) and create one entry per X++ class. Fill in: unique name, display name, description, and plugin type (must be 'microsoft.dynamics.fno.copilotplugins.invokefno.customapi').

Add Custom API Request Parameters

For each input parameter (e.g., purchase ID, comment, packing slip ID), create a Custom API Request Parameter entry. Specify the parameter name, display name, description, data type (string, etc.), and whether it is optional.

Critical: Plugin Type Must Match

The plugin type must exactly be 'microsoft.dynamics.fno.copilotplugins.invokefno.customapi'. If incorrect, Copilot Studio tools will not recognize the API.

Use Microsoft Dataverse Connector

In Copilot Studio, add a tool by selecting Connectors > Microsoft Dataverse > 'Perform an unbound action in a Power Platform environment'. This is the method to wire custom APIs as tools.

Configure Tool Details

For each tool: (1) Choose the correct connection, (2) Set a display name and description, (3) In Input section, select 'Custom' and choose your environment (or use 'Current' for dynamic selection), (4) Select the custom action name from the refreshed list of available APIs.

Map Input Parameters

After selecting the action, click to enable parameter selection. Add each input parameter (e.g., purchase ID, comment) and provide a description for each. Description is mandatory.

Critical: Set Completion to Specific Outputs

In the Completion section (Advanced), select 'Specific' outputs, not 'All'. Choosing 'All' causes infinite response times. This is a commonly forgotten but crucial step.

Instruction Syntax and Tool References

In Copilot Studio agent instructions, reference tools by typing '/' to see available tools. Instructions can specify step-by-step logic (e.g., 'ask user for PO details, then call PO submission tool, then confirm'). Parameters flow automatically from one step to the next without manual passing.

Automatic Parameter Forwarding

Unlike traditional X++ or C# code, agentic instructions automatically pass output from one step (e.g., purchase order number from step 1) to subsequent steps (e.g., step 2 confirmation). No explicit parameter passing code is needed.

Conditional Logic in Instructions

Instructions can include conditionals (e.g., 'if change management is disabled, skip workflow submission; otherwise, ask user to submit'). This allows the agent to adapt behavior based on system configuration.

Agent Creates PO from Natural Language

User provides a single prompt: 'Create a purchase order for vendor X, legal entity Y, item Z, quantity Q.' The agent parses this, calls the PO creation tool, and generates the purchase order in Dynamics 365.

Agent Asks for Additional Lines

After creating the initial PO, the agent prompts the user: 'Would you like to add more lines?' User can respond yes or no, and the agent adapts accordingly.

Agent Checks Approval Status

The agent checks if the PO requires workflow approval (based on change management settings). In the demo, change management is disabled, so the PO is auto-approved and the agent skips the submission step.

Agent Confirms PO

The agent calls the PO confirmation tool, automatically retrieving the PO number generated in step 1 and confirming it. The PO state changes to 'Confirmed' in Dynamics 365.

Agent Receives PO with Packing Slip

The agent asks the user for a packing slip ID, then calls the PO receipt tool. The purchase order is marked as 'Received' and product receipt records are created in Dynamics 365.

Verification in Dynamics 365

After the agent completes all steps, the speaker navigates to Accounts Payable > All Purchase Orders, filters by the generated PO number, and confirms the PO is in 'Confirmed' state with receipt records created.

Prefix Recording is Critical

When creating a custom publisher in Power Apps, record the prefix (e.g., CR666). This prefix is used to identify your custom APIs in the Copilot Studio tool selection list.

Plugin Type Validation

The plugin type 'microsoft.dynamics.fno.copilotplugins.invokefno.customapi' must be exact. Typos or incorrect values prevent Copilot Studio from recognizing the API.

Automatic Parameter Flow Advantage

Unlike traditional development, agentic instructions pass parameters implicitly between steps. This eliminates boilerplate parameter-passing code and makes workflows more readable.

Completion Output Selection Impact

Selecting 'All' outputs in tool completion causes infinite response times. Always select 'Specific' outputs to return only necessary data.