Copilot Mapping Suggestions - Setup & Processing Guide
Overview
The Copilot features in the Linc Third Party Transactions extension use Azure OpenAI to propose mappings that would otherwise be entered by hand. Copilot only ever proposes: every proposal is shown in a review dialog, and nothing reaches your mapping tables until you choose Keep.
Two capabilities are available. Both are in Preview.
| Capability | What it does | Where to start it |
|---|---|---|
| Mapping suggestions | Proposes a Third Party Mapping for each imported value (item, G/L account, customer, location, etc.) that validation could not resolve | Suggest mappings on the Third Party Transactions page or the Third Party Setup Card |
| Excel mappings | Reads a spreadsheet and proposes which transaction field each column should be imported into | Suggest Excel mappings on the Third Party Setup list or Third Party Setup Card |
Key Components
- Third Party Copilot Setup (Page 71112712): Azure OpenAI credentials and the monthly token limit for the company
- Third Party Setup: Per-third-party opt-in for each capability
- Copilot & AI Capabilities: Environment-level on/off switch for each capability (Business Central standard page)
- Suggest Third Party Mappings with Copilot (Page 71112710) and Suggest Excel Mappings with Copilot (Page 71112713): the review dialogs
- Output: Third Party Mappings (Third Party Transaction Maps) or Excel import mappings (Third Party Excel Import Maps)
Prerequisites
1. Azure OpenAI Resource
- Your own Azure OpenAI resource with a chat model deployment. The resource is billed to you directly (the capabilities are registered as Custom Billed). No Microsoft-managed resource is used.
- The resource endpoint, the name you gave the chat model deployment, and an API key
2. Extension Setup
- Linc Third Party Transactions extension installed, with Linc Extension Access (subscription) active
- Users hold the extension permission set (PS_THI_LINC), which includes the Copilot objects
- An administrator who can switch capabilities on in Copilot & AI Capabilities
Step-by-Step Setup Instructions
Step 1: Enter the Azure OpenAI Credentials
- Search for Third Party Copilot Setup (Page 71112712)
- Under Credentials, enter:
- Endpoint: Your Azure OpenAI endpoint (
https://<resource name>.openai.azure.com) - Deployment: The name of your chat model deployment
- Key: The API key for the resource
- Endpoint: Your Azure OpenAI endpoint (
- Confirm that Credentials Stored is switched on
The three values are write-only. They are held in Isolated Storage, never stored on the setup record, and the fields stay blank after entry. To change one, type the new value over the blank field. Use Clear Credentials to remove all three.
Step 2: Switch the Capabilities On
- On the Third Party Copilot Setup page, check Copilot Capabilities under Status. It should read Both registered and switched on.
- If a capability is switched off, an administrator chooses Copilot & AI Capabilities and switches on Mapping suggestions and/or Excel mappings.
Registration happens automatically on install and upgrade, and when the Copilot & AI Capabilities page is opened.
Step 3: Set the Monthly Token Limit (optional)
On the Third Party Copilot Setup page, under Token Usage:
- Monthly Token Limit: Maximum tokens the company may use per calendar month across both capabilities. A run that would exceed the limit is not sent. Leave blank for no limit.
- Tokens Used This Month: Estimated usage (text sent plus answer received). It is an estimate, not an invoice.
- Token Usage Month: The month the count belongs to. The count restarts automatically on the first run of a new month.
- Reset Token Count: Sets the count back to zero without changing the limit.
Step 4: Opt In Per Third Party
- Open the Third Party Setup Card for the configuration
- Under the General section, switch on:
- Enable Copilot Mapping Suggestions: for value mapping suggestions. Use Mapping must also be on for the action to appear, because suggestions are pointless if validation never consults the mappings.
- Enable Copilot Column Mapping: for Excel column mapping suggestions. Use Mapping is not required, as the Excel import always reads its column mappings.
A Copilot action shows only when all three gates are on: the Linc subscription, the capability in Copilot & AI Capabilities, and the third party's own opt-in.
Mapping Suggestions
When to use it
Use it when validation flags transactions as Error because a value from the third party (for example a product code or an account description) has no Third Party Mapping.
Supported mapping types
G/L Account, Item, Fixed Asset, Customer, Vendor, Location, Resp. Center, FA Maintenance, Shortcut Dimension 1-8 Code, Salesperson/Purchaser, VAT Prod. Posting Group, Payment Terms Code, Payment Method Code and Shipment Method Code.
Processing
- On the Third Party Transactions page, select the rows to look at (or open the Third Party Setup Card, which uses all transactions for that third party with a validation status of Error)
- Choose Suggest mappings, then Suggest mappings in the dialog
- Copilot looks at every reference that could not be resolved automatically and proposes one record for each. Each run handles up to 25 references; run it again for the next batch.
- Review the Proposed Mappings list:
| Column | Description |
|---|---|
| Keep | Ticked by default on rows that have something to create. Untick any you do not want. |
| Status | Suggested, No Match or Created. Only Suggested rows can be created. |
| Third Party Reference No. | The value exactly as imported |
| Reference Context | Surrounding text from the transaction given to Copilot |
| Mapping Type / Mapping No. / Mapping Description | The proposed Business Central record. Correct Mapping No. with the lookup if Copilot chose wrongly. |
| Variant Code / Unit of Measure Code | Editable for item mappings |
| Confidence | High, Medium, Low, or Fuzzy Search (found by searching Business Central; Copilot was not asked) |
| Reason | Why the record was proposed, or why nothing could be |
| Occurrence Count | How many selected transactions carry this value |
- Choose Try again to discard the proposals and ask again, Discard to close without creating anything, or Keep to create a Third Party Mapping for every ticked row
- After Keep, the affected transactions are validated again so the new mappings take effect
Copilot may only choose a record from the candidates it was given. A code that is not on that list is rejected. For small master tables the complete list is sent; for tables with more than 2,000 rows Copilot chooses from a shortlist found by searching.
Excel Mappings
When to use it
Use it when setting up an Excel import for a new third party, before running Import Transactions from Excel File.
Processing
- On the Third Party Setup list or card, choose Suggest Excel mappings
- Upload the
.xlsxfile and, if the workbook has more than one sheet, choose the sheet - Choose Suggest Excel mappings in the dialog. Copilot reads the headings from the first row, together with up to 20 rows of values (a few distinct values per column), for up to 60 columns.
- Review the Proposed Excel mappings list. Each column shows its heading, sample values, the proposed target field, a confidence and a reason. A mapping is either:
- Field: the column is imported into the proposed field on every row
- Fixed Value: one value is written to every imported row. This is proposed only when every value in the column is identical, or for a setting the file implies but does not carry as a column (for example Credit Memo for a file of credit notes).
- Fields the import needs that the file does not cover appear as rows where you type the value to use on every row, then keep the row
- Untick anything you do not want and choose Keep. Fields that are already mapped for this third party are left alone.
Application area and third party code are taken from the setup record on every imported row, so no column is needed for them. If the third party treats amounts as unit prices, the dialog reminds you that line amounts are multiplied by the quantity after import.
Data Sent to Azure OpenAI
- Mapping suggestions: the unresolved reference values, their context text from the transaction, and candidate Business Central records (code and description) for the mapping type
- Excel mappings: column headings and a sample of the values only. The file itself is not sent.
- Imported content is marked as data, not instructions, and Copilot is told to ignore any instructions found inside it
- Credentials stay in Isolated Storage
Troubleshooting
| Message / Symptom | Cause and resolution |
|---|---|
| Action not visible | One of the three gates is off: subscription, capability in Copilot & AI Capabilities, or the third party's opt-in. Mapping suggestions also need Use Mapping. |
| Copilot has no Azure OpenAI resource to call | Enter the endpoint, deployment and key on the Third Party Copilot Setup page |
| Azure refused the credentials | Check the endpoint, deployment name and key |
| Your Azure OpenAI resource has no capacity left | Try again later, or raise the quota on the deployment in Azure |
| This company has reached its monthly Copilot limit | Raise or clear the limit, or reset the token count, on the Third Party Copilot Setup page |
| This Copilot capability has been switched off | An administrator switches it on in Copilot & AI Capabilities |
| None of the selected transactions have an unresolved reference | Nothing needs mapping, or the selection contains no transactions with an unresolved value |
| This file could not be read as a spreadsheet | Check the file is .xlsx, the right sheet is chosen, and it is not password protected |
| The header row of this sheet has no headings | The import reads headings from row 1 |
| No Match on a row | The master data may not exist. Create it, or map the value by hand. |
Best Practices
- Check every proposal against the imported value before choosing Keep, particularly rows with Low or Medium confidence
- Run mapping suggestions on a representative selection rather than the whole backlog, as each run handles 25 references
- Start with a sandbox environment while the capabilities are in Preview