Quick Start Guide - AL Development Collection¶

⚠️ AI-Generated Content Disclaimer: This toolkit uses GitHub Copilot and generative AI to assist in AL development. Agent responses and code generation results may vary based on context, model versions, and user inputs. Always review and test generated code thoroughly before deploying to production environments.

AI-powered AL development in 2 simple steps for Microsoft Dynamics 365 Business Central.

🚀 Quick Installation (5 minutes)¶

Option 1: VS Code Extension (Recommended)¶

1. Install from Marketplace: Search "AL Development Collection"
2. Command Palette: AL Collection: Install Toolkit to Workspace
3. Reload VS Code

Option 2: NPM¶

npm install github:javiarmesto/AL-Development-Collection-for-GitHub-Copilot
npx al-collection install

Option 3: Manual¶

git clone https://github.com/javiarmesto/ALDC-AL-Development-Collection-for-GitHub-Copilot.git
cd AL_Copilot_Collection
node install.js install [your-al-directory]

After installation: Reload VS Code (Ctrl+Shift+P → Developer: Reload Window)

📋 Two Main Tools¶

1️⃣ al-architect → Design the solution¶

Use when: You need to plan a new feature

Use al-architect mode

I need to build a sales approval system with:
- Approval levels by amount
- Email notifications
- Audit trail

Result: Complete architecture, data model, integration points

2️⃣ al-conductor → Implement with TDD¶

Use when: You have the design and want production-ready code

Use al-conductor mode

Implement the approval system designed by al-architect

Result: Complete AL code, 100% tests, automatic documentation

🎯 Basic Workflow¶

For Simple Features (🟢 1-2 objects)¶

Step 1: Describe what you need
Step 2: Copilot generates the code (with auto-guidelines)
Step 3: @workspace use al-build → Deploy

Example: "Add email validation to Customer table"

For Moderate Features (🟡 3-6 objects)¶

Step 1: Use al-architect mode → Design
Step 2: Use al-conductor mode → Implement with TDD
Step 3: @workspace use al-permissions → Permissions
Step 4: @workspace use al-build → Deploy

Example: "Customer loyalty points system"

Time: 2 hours (vs 2 days manual)

For Complex Features (🔴 7+ objects)¶

Step 1: Use al-architect mode → Complete architecture
Step 2: Use al-api mode (if APIs needed)
Step 3: Use al-conductor mode → Multi-phase implementation
Step 4: @workspace use al-performance → Validation
Step 5: @workspace use al-build → Deploy

Example: "Integration with external payment gateway (OAuth + webhooks)"

Time: 1-2 days (vs 1-2 weeks manual)

💡 What's My Complexity?¶

🟢 Simple (Directly with Copilot)¶

✅ Limited scope — isolated change
✅ Field validation or page extension
✅ Single implementation phase
✅ No integrations needed

🟡 Moderate (al-architect + al-conductor)¶

✅ Moderate scope — multiple related areas
✅ Business logic with internal workflows
✅ Internal integration events
✅ 2-3 implementation phases

🔴 Complex (al-architect + specialists + al-conductor)¶

✅ Extensive scope — broad architectural impact
✅ External APIs or services
✅ OAuth/authentication
✅ 4+ implementation phases

🛠️ Useful Commands¶

Setup Commands¶

@workspace use al-initialize    # Initialize project
@workspace use al-build         # Build and deploy
@workspace use al-permissions   # Generate permissions

Debugging Commands¶

@workspace use al-diagnose      # Complete debug
@workspace use al-performance   # Performance analysis

Specialized Modes¶

Use al-architect mode     # Architecture design
Use al-conductor mode     # TDD implementation
Use al-api mode          # REST/OData APIs
Use al-debugger mode     # Deep diagnostics
Use al-tester mode       # Testing strategy
Use al-presales mode     # Project planning & cost estimation

📖 Complete Example: Loyalty Points System¶

✅ Real validated case - This example has been fully tested (24/24 validations passed)

🎯 What We're Going to Build¶

Customer loyalty system that: - Automatically accumulates points when posting sales invoices (1% of amount) - Allows redeeming points for discounts - Shows point balance on customer card - Records point transaction history - Complexity: 🟡 MEDIUM (3-6 objects, 2-3 phases) - Time: ~2 hours (vs 2 days manual)

📋 Step 1: Design with al-architect (20 min)¶

Open VS Code in your AL project and run:

Use al-architect mode

Design a customer loyalty points system with these requirements:

FUNCTIONALITY:
- Customers accumulate points when posting sales invoices (1% of amount)
- Points can be redeemed for discounts
- Show point balance on customer card
- Record all point transactions

BUSINESS RULES:
- 1 point = 1% of sales amount
- Minimum redemption: 100 points
- Points don't expire
- Complete audit trail

TECHNICAL CONSIDERATIONS:
- Use events (don't modify BC base objects)
- AL-Go structure (App vs Test)
- 100% test coverage

Al-architect will respond with:

📐 ARCHITECTURE: Loyalty Points System

🗂️ DATA MODEL:
1. Table 50100 "Loyalty Point Entry"
   - Entry No., Customer No., Points, Transaction Type, Sales Document No.

2. TableExtension 50100 "Customer Ext" extends Customer
   - "Loyalty Points Balance" (Calculated FlowField)
   - "Loyalty Points Enabled" (Boolean)

🔗 INTEGRATION:
- Event Subscriber: OnAfterPostSalesInvoice → Calculate and assign points
- Codeunit 50100 "Loyalty Management" → Calculation and redemption logic

📄 UI:
- PageExtension 50100 "Customer Card Ext" → Show balance
- Page 50100 "Loyalty Point Entries" → History

🧪 TESTING:
- Test for OnAfterPostSalesInvoice
- Test for points calculation
- Test for redemption
- Test for FlowField

✅ Architecture ready → Automatically saved in .github/plans/architecture.md

🎭 Step 2: TDD Implementation with al-conductor (90 min)¶

Now switch to al-conductor to implement:

Use al-conductor mode

Implement the loyalty points system designed by al-architect

Al-conductor will automatically orchestrate:

📊 Planning Phase (5 min)¶

Planning subagent analyzes the project
Identifies existing BC objects
Proposes 7 implementation phases

🔴 Phase 1: Loyalty Point Entry Table (RED → GREEN → REFACTOR)¶

RED (2 min):
- Implement: AL Implementation Subagent creates failing test
- Test: "Insert Loyalty Point Entry with required fields"

GREEN (3 min):
- Implement: Table with minimum fields
- Test: ✅ PASS

REFACTOR (2 min):
- Review: AL Code Review Subagent validates structure
- Result: Clean and efficient code

🔴 Phase 2: Customer Extension (RED → GREEN → REFACTOR)¶

RED: Test FlowField calculation
GREEN: TableExtension + FlowField
REFACTOR: SetLoadFields optimization

🔴 Phase 3: Loyalty Management Codeunit (RED → GREEN → REFACTOR)¶

RED: Test points calculation (1% of $1000 = 10 points)
GREEN: AddPoints + CalcPoints functions
REFACTOR: Extract constants

🔴 Phase 4: Event Subscriber (RED → GREEN → REFACTOR)¶

RED: Test OnAfterPostSalesInvoice integration
GREEN: Event subscriber calling AddPoints
REFACTOR: Error validation

🔴 Phase 5: Points Redemption (RED → GREEN → REFACTOR)¶

RED: Test RedeemPoints with validations
GREEN: Function with 100 points minimum validation
REFACTOR: Descriptive error messages

🔴 Phase 6: Customer Card Extension (RED → GREEN → REFACTOR)¶

RED: Test UI shows balance
GREEN: PageExtension with field
REFACTOR: Format and design

🔴 Phase 7: Loyalty Entries Page (RED → GREEN → REFACTOR)¶

RED: Test navigation and filtering
GREEN: List page with filters
REFACTOR: Actions and DrillDown

Final Result:

✅ 10 AL objects created
✅ 63 tests implemented (100% passing)
✅ Documentation in .github/plans/
✅ Code reviewed and validated
✅ Production ready

🔒 Step 3: Permissions and Deployment (10 min)¶

# Generate permissions automatically
@workspace use al-permissions

# Build and deploy
@workspace use al-build

📦 Generated Objects¶

App/
├── Tables/
│   └── LoyaltyPointEntry.Table.al (50100)
├── TableExtensions/
│   └── CustomerExt.TableExtension.al (50100)
├── Codeunits/
│   ├── LoyaltyManagement.Codeunit.al (50100)
│   └── SalesEventSubscriber.Codeunit.al (50101)
├── Pages/
│   └── LoyaltyPointEntries.Page.al (50100)
├── PageExtensions/
│   └── CustomerCardExt.PageExtension.al (50100)
└── Permissions/
    └── LoyaltySystem.PermissionSet.al (50100)

Test/
└── LoyaltyTests.Codeunit.al (63 test functions)

🧪 Generated Tests (Examples)¶

[Test]
procedure TestAddPointsFromSales()
begin
    // [GIVEN] Customer with no points
    CreateCustomer(Customer);

    // [WHEN] Post sales invoice of $1000
    CreateAndPostSalesInvoice(Customer, 1000);

    // [THEN] Customer has 10 points (1% of 1000)
    Assert.AreEqual(10, GetLoyaltyPoints(Customer), 'Points calculation');
end;

[Test]
procedure TestRedeemPoints_Minimum()
begin
    // [GIVEN] Customer with 50 points
    SetCustomerPoints(Customer, 50);

    // [WHEN] Tries to redeem
    asserterror RedeemPoints(Customer, 50);

    // [THEN] Error: minimum 100 points
    Assert.ExpectedError('Minimum redemption is 100 points');
end;

📊 Measurable Results¶

Metric	Manual	With Orchestra
Total time	2 days	2 hours
Objects created	10	10
Tests written	0-10	63 (100%)
Production bugs	3-5	0
Documentation	Manual	Automatic
Code review	Manual	Automatic

🎓 What You Learned¶

✅ Design before code → al-architect plans everything
✅ Automatic TDD → al-conductor implements with tests first
✅ Event-driven → Don't modify BC base objects
✅ Guaranteed quality → Automatic review in each phase
✅ Documentation included → Everything in .github/plans/

🔄 Reproduce the Complete Example¶

Detailed step-by-step guide: REPRODUCIBLE-EXAMPLE.md

Quick summary (from scratch in your project):

Design:

Use al-architect mode

[Copy requirements from example]

Implement with TDD:

Use al-conductor mode

Implement the design from al-architect

Deploy:

@workspace use al-permissions
@workspace use al-build

Total time: ~2 hours from zero to production ✨

Complete documentation with troubleshooting: See reproducible guide →

✨ Auto-Guidelines (Working in Background)¶

While coding, these rules apply automatically:

✅ al-code-style → Format and structure
✅ al-naming-conventions → PascalCase names
✅ al-performance → SetLoadFields, early filtering
✅ al-error-handling → TryFunctions, error labels
✅ al-events → Event-driven pattern
✅ al-testing → AL-Go structure

You don't need to ask for them, they just work.

🎓 Tips for Maximum Performance¶

✅ Do This¶

Always start with al-architect to design before coding
Use al-conductor to implement with automatic TDD quality
Provide rich context → Describe requirements, business rules, considerations
Trust auto-guidelines → They work in the background, don't ask for them manually
Follow the Loyalty Points example → It's the validated reference

❌ Avoid This¶

Don't skip architectural design (for medium/complex features)
Don't implement without tests (al-conductor does it automatically)
Don't modify BC base objects (always use events and extensions)
Don't ignore automatic code reviews from AL Code Review Subagent

🔧 Quick Troubleshooting¶

"I don't see Copilot suggestions"¶

Verify Copilot is enabled
Reload VS Code
Open a .al file

"Modes don't appear"¶

Check files in .github/copilot/agents/
Reload VS Code
Verify they have .agent.md extension

"Validation fails"¶

npm install
npm run validate

📚 Complete Documentation¶

Collection Guide - Detailed technical guide
Instructions - Auto-guidelines
Workflows - Available commands
Modes - Specialists

🎯 Next Step¶

If you're new to AL:¶

@workspace use al-initialize

If you have a feature to build:¶

Use al-architect mode

[Describe your feature here]

If you have a bug:¶

Use al-debugger mode

[Describe the problem]

Version: 2.11.0
Reference Model: AI Native-Instructions Architecture
Last Updated: 2026-02-06

⚠️ AI Assistant Reminder: This content is generated with assistance from AI tools. Results, code suggestions, and agent responses may vary depending on multiple factors including input quality, context, and AI model behavior. Always validate, test, and review AI-generated content before production use.