Package Installation Guide

Kernel Dynamics 365 Integration - Installation & Setup Guide

📋 Prerequisites

  • Dynamics 365 System Administrator access in your target environment

  • Your Kernel Tenant ID & API Key

  • Microsoft 365/Azure AD admin access (for application user creation)

  • Package Version: Latest v1.0 release

🚀 Quickstart Guide

🔗 Step 1: Install the Kernel Solution

  1. Download the Solution

    • Access the installation link provided by Kernel:

    • `dynamicsurlhere`

  2. Import the Solution

    • Navigate to: Settings → Solutions

    • Click Import

    • Select the downloaded solution file: KernelDynamicsConnectedApp_1_0_0_0_managed.zip

    • Click Next

  3. Configure Installation Options

    • Install for: All Users (Recommended)

    • Enable SDK message processing: Yes

    • Review connections and dependencies

    • Click Import

  4. Wait for Installation

    • The import process typically takes 5-10 minutes

    • You'll receive a notification when complete

    • Status: "Import Complete"

  5. Verify Installation

    • Navigate to: Settings → Solutions

    • Confirm "Kernel Dynamics Connected App" appears with status Installed

    • Open Apps

    • Find and open Kernel Integration app

    • Click the Kernel Setup tab

Important: You will be prompted to grant the Kernel API access to the integration user and security role you create. This allows Kernel to sync your CRM data. Kernel only has access based on the security roles you assign.

👤 Step 2: Create Integration User

The integration user is a dedicated Application User account that Kernel uses to access your Dynamics 365 data securely.

Creating the User:

  1. Open Kernel Setup

    • In Dynamics 365, navigate to Apps → Kernel Integration

    • Click the Kernel Setup custom page

    • You'll see a loading screen with fun messages (this is normal!)

  2. Review Default Settings

    • The setup wizard will display default user information:

      • Email: [email protected]

      • First Name: Kernel

      • Last Name: Integration

      • User Type: Application User

  3. Create the Integration User

    • Click "Create Integration User"

    • The system will:

      • Create a unique application user linked to Azure AD

      • Assign the Kernel Integration Role security role

      • Send sync notification to Kernel Portal

      • Save sync status locally

  4. Success Confirmation

    • You'll see a success message: "✓ Integration user created successfully!"

    • The UI will display:

      • User full name

      • Email address

      • User status: Active

      • Sync status: Connected (green indicator)

Permission & Security Role:

The system automatically assigns the Kernel Integration Role to the integration user, which provides:

  • ✅ Read/View All access to standard entities (Account, Contact, Lead, Opportunity)

  • ✅ Read access to custom entities (as needed)

  • ✅ API access through application user context

  • ✅ Access to Kernel-specific custom entities

Alternative: You can also assign your own custom security role with specific permissions.

🔗 Step 3: Authorize Kernel Connection

Before Authorizing

You'll need your Kernel API credentials (provided by Kernel team):

  • Tenant ID: Your unique organization identifier (e.g., tenant_abc123xyz)

  • API Key: Your secure API key for authentication

Authorization Steps

  1. Verify Sync Status

    • In the Kernel Setup page, you should see:

      • Status: Connected to Kernel

      • Last Sync: Timestamp of initial sync

      • Tenant ID: Your tenant identifier

      • Integration User: Email and name

  2. Connection Established

    • Once the integration user is created, the connection is automatically established

    • The OAuth flow happens in the background using the application user credentials

    • No additional authorization window required

  3. Verify in Kernel Portal

    • Log into your Kernel Portal at https://app.kernel.ai

    • Navigate to Integrations → Dynamics 365

    • You should see your organization listed with status: Connected

    • Data sync will begin automatically

🔧 Configuration Options

Using Custom Security Roles

By default, Kernel uses the Kernel Integration Role. For custom requirements:

  1. Access Configuration

    • In Dynamics 365, navigate to: Settings → Security → Security Roles

    • Create or modify a security role with desired permissions

  2. Assign to Integration User

    • In Kernel Setup page, click "Change Integration User"

    • Select option: "Choose Existing User"

    • Select your user from the dropdown

    • The custom security role will be preserved

  3. Minimum Required Permissions

    • Read: account, contact, lead, opportunity, systemuser

    • Read: krnl_kernelsyncstatus (Kernel custom entity)

    • Execute: Custom actions (krnl_*)

    • API Access: Web API enabled

Alternative: Choose Existing User

If you prefer to use an existing application user:

  1. In Kernel Setup, click "Choose Existing User"

  2. Select from dropdown of active application users

  3. Click "Choose"

  4. System will:

    • Assign required security roles

    • Send sync notification to Kernel

    • Update sync status

🔒 Security & Compliance

OAuth & Authentication

The Kernel Connected App uses:

  • Azure AD Application Registration for secure authentication

  • Application User context (no password, service principal-based)

  • HMAC-SHA256 signatures for API request verification

  • Organization ID as the secret key for signature generation

API Scopes & Permissions

The integration requires these permissions:

  • Dynamics 365 Web API Access - Read and manage your data

  • Offline Access - Perform requests continuously

  • Organization Context - Access organization-level settings

Data Access & Security

  • ✅ Access is logged and auditable in Audit Summary View

  • ✅ All API calls use encrypted HTTPS (TLS 1.3)

  • ✅ Data transmission is encrypted end-to-end

  • ✅ Integration user follows principle of least privilege

  • ✅ Supports Azure AD conditional access policies

🚨 Troubleshooting

Common Issues and Solutions

❌ "Plugin Execution Failed"

Problem: Plugin throws an error during user creation

Solutions:

  1. Verify you have System Administrator role

  2. Check that Azure AD application is properly registered

  3. Review plugin trace logs:

    • Navigate to: Settings → System → System Jobs

    • Filter by: Status = Failed

    • Review error message and stack trace

  4. Contact Kernel support with System Job ID

❌ "Invalid Signature" Error

Problem: API calls fail with 401 Unauthorized

Solutions:

  1. Verify remote site settings:

    • Navigate to: Settings → Security → Remote Site Settings

    • Confirm https://api.kernel.ai is present and active

  2. Check organization ID in trace logs

  3. Ensure system time is synchronized (NTP)

  4. Contact Kernel support for signature verification

❌ "Sync Status Not Updating"

Problem: UI shows "Not Connected" even after user creation

Solutions:

  1. Refresh the page (Ctrl+F5 or Cmd+Shift+R)

  2. Check custom entity permissions:

    • Navigate to: Settings → Security → Security Roles

    • Verify Kernel Integration Role has Read/Write to krnl_kernelsyncstatus

  3. Review plugin trace logs for errors

  4. Try "Change Integration User" and recreate

❌ "Cannot Create Application User"

Problem: User creation fails with Azure AD error

Solutions:

  1. Verify Azure AD application registration:

    • Check application exists in Azure Portal

    • Verify client ID matches plugin configuration

    • Ensure API permissions are granted with admin consent

  2. Check your role permissions:

    • Must have System Administrator in Dynamics

    • Must have Application Administrator in Azure AD

  3. Review Azure AD audit logs for failures

❌ Custom Page Shows Blank Screen

Problem: Kernel Setup page doesn't load

Solutions:

  1. Clear browser cache and cookies

  2. Try different browser (Chrome, Edge recommended)

  3. Check browser console for JavaScript errors (F12)

  4. Verify solution is fully imported and published

  5. Re-publish all customizations:

    • Settings → Solutions → Publish All Customizations

⚠️ Connection Working But No Data Syncing

Problem: Integration connected but data not appearing in Kernel

Solutions:

  1. Check security role permissions:

    • Integration user must have Read access to all relevant entities

    • Verify field-level security permissions

  2. Review sync logs in Kernel Portal

  3. Verify business unit access:

    • Integration user must have access to correct business unit

  4. Check if data meets sync criteria (e.g., record ownership)

🔄 Managing the Integration

Deactivating the Integration User

To temporarily disconnect:

  1. In Kernel Setup:

    • Click "Deactivate User"

    • Confirm action

    • User status changes to: Inactive

    • Sync status cleared

  2. Manual Deactivation:

    • Navigate to: Settings → Security → Users

    • Find the Kernel Integration user

    • Click Deactivate

    • Confirm action

Effect: Kernel will no longer be able to access your Dynamics data. Sync will stop.

Reactivating the Connection

To reconnect after deactivation:

  1. In Kernel Setup:

    • You'll see the deactivated user

    • Click "Reactivate User"

    • System sends lifecycle event to Kernel

    • Sync status restored

  2. Manual Reactivation:

    • Navigate to: Settings → Security → Users

    • Find the Kernel Integration user

    • Click Activate

    • Return to Kernel Setup and verify sync status

Changing the Integration User

If you need to switch to a different user:

  1. In Kernel Setup:

    • Click "Change Integration User"

    • Choose an option:

      • Create New User - Creates fresh application user

      • Choose Existing User - Assigns existing user

  2. What Happens:

    • Previous user is NOT deactivated (just unlinked)

    • Previous sync status is cleared

    • New user receives security roles

    • New sync notification sent to Kernel

    • Tenant binding updated

Updating API Credentials

If your Kernel API credentials change:

  1. Obtain new credentials from Kernel support

  2. In Dynamics Kernel Setup:

    • Click "Disconnect" (if connected)

    • The integration user remains but sync stops

  3. Contact Kernel support to update tenant binding

  4. Click "Reactivate User" to re-establish connection

Revoking Access Completely

To completely remove Kernel integration:

  1. Deactivate Integration User (see above)

  2. Delete Custom Entities (Optional):

    • Navigate to: Settings → Customizations

    • Delete krnl_kernelsyncstatus entity (removes sync history)

  3. Uninstall Solution:

    • Navigate to: Settings → Solutions

    • Select Kernel Dynamics Connected App

    • Click Delete (this removes all components)

  4. Notify Kernel Support to remove organization from portal

📊 Monitoring & Maintenance

View Sync Activity

  1. In Dynamics 365:

    • Navigate to: Settings → System → System Jobs

    • Filter by: Regarding = Kernel

    • Review execution logs and timestamps

  2. In Kernel App:

    • Log into https://app.kernel.ai

    • Navigate to: Settings → CRM Integrations → Dynamics 365

    • View sync history and status

Performance Monitoring

  • Plugin execution time: < 2 minutes (typical < 30 seconds)

  • API response time: < 5 seconds

  • Sync frequency: Real-time (on record create/update)

Audit Trail

All integration activity is logged:

  • Settings → Auditing → Audit Summary View

  • Filter by: User = Kernel Integration

  • Review: Create, Update, Read operations

📞 Support

Getting Help

Include in Your Support Request:

  1. Organization Information:

    • Organization ID (found in Settings → Customizations → Developer Resources)

    • Environment URL (e.g., https://yourorg.crm.dynamics.com)

    • Environment type (Production / Sandbox)

  2. Integration User Details:

    • Username

    • Email address

    • User GUID (from user settings)

  3. Error Information:

    • Complete error messages

    • System Job IDs (for plugin errors)

    • Screenshots of error

    • Trace logs (from System Jobs)

  4. Sync Information:

    • Tenant ID

    • Last successful sync timestamp

    • Sync job IDs (from Kernel Portal)

📦 Package Components Reference

What Gets Installed

Component
Type
Purpose

KernelUserController

Plugin

Manages integration user lifecycle

KernelPermissionReporter

Plugin

Reports security role assignments

Kernel Setup

Custom Page

User interface for configuration

krnl_kernelsyncstatus

Custom Entity

Stores synchronization state

krnl_kernelsetting

Custom Entity

Stores configuration settings

Kernel Integration Role

Security Role

Provides API and data access

Custom Actions

Workflows

API endpoints for user management

Remote Site Settings

Configuration

Enables API callouts to Kernel

Solution Details

  • Publisher: Kernel

  • Prefix: krnl

  • Type: Managed (Production) / Unmanaged (Sandbox)

  • Dependencies: None

🔐 Privacy & Data Handling

What Data is Synced?

By default, Kernel syncs:

  • Standard Entities: Account, Contact, Lead, Opportunity, User

  • Fields: All fields accessible by integration user's security role

  • Metadata: Entity schemas, relationships, field definitions

What Data is NOT Synced?

  • Passwords or authentication credentials

  • System audit logs (unless explicitly configured)

  • Attachment file contents (only metadata)

  • Data outside integration user's security scope

PreviousDynamics integrationNextInbound API

Last updated