# Package Installation 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:** <integration@kernel.ai>
     * **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

* **Email:** <support@kernel.ai>

#### 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.kernel.ai/integrations/dynamics-integration/package-installation-guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.