Installation & Configuration Guide

This guide provides step-by-step instructions for installing and configuring IncidentAnalytix (IA) on your Microsoft Power Platform tenant. It covers environment preparation, solution installation, security role assignment, and post-installation verification.

IncidentAnalytix is delivered as a managed Microsoft Power Platform solution built on Microsoft Dataverse, designed for organizations that track incidents, allegations, contributing factors, and outcomes across safety programs.

ⓘ Audience: This guide is intended for Power Platform administrators or IT professionals responsible for deploying and managing Power Platform environments. Familiarity with the Microsoft Power Platform Admin Center and Power Apps Maker Portal is assumed.

1. Prerequisites

Before beginning installation, confirm the following are in place:

• A Microsoft 365 tenant with Power Platform enabled.
• Sufficient Power Apps or Dynamics 365 licenses for all users who will access IncidentAnalytix.
• Power Platform administrator rights (Global Admin or Power Platform Admin role) to create environments and assign security roles.
• The IncidentAnalytix solution package files provided by SystemsAnalytix: the Lookups Solution (LS) and the IncidentAnalytix Solution (IA), each in both managed and unmanaged .zip formats.
• A designated deployment account (standard user or Azure AD service principal) with System Administrator rights in each target environment. See Section 5 for setup details.

⚠ Data Sensitivity Notice: IncidentAnalytix handles sensitive safety and incident data. Before going live, confirm that your Power Platform tenant meets your organization’s data residency, privacy, and regulatory requirements.

2. Power Platform Environments

Microsoft Power Platform uses Environments as isolated containers for apps, flows, connections, and data. Each Environment includes a Dataverse database that stores the structured business data used by Model-Driven Apps.

2.1 Environment Types

Type	Purpose & Notes
Developer	Personal environment for individual building and testing. Available with a Microsoft Developer Plan. Not appropriate for shared development or production use.
Sandbox	Shared environment for development and testing. Supports backup, restore, and reset. Use for Development and Test roles in your ALM pipeline.
Production	Live environment for end users. Only managed solutions should be deployed here. Should always be a Managed Environment for enterprise governance.

2.2 Managed Environments

A Managed Environment is a governance layer applied to any environment type. It provides additional administrative controls including data loss prevention (DLP) policy enforcement, solution checker enforcement, usage analytics, and enhanced sharing restrictions.

Enabling Managed Environments is strongly recommended for production deployments of IncidentAnalytix, particularly for organizations handling sensitive or regulated incident data. Managed Environments require an additional Power Platform license.

2.3 Recommended ALM Environment Roles

ALM Role	Recommended Type	Purpose
Development	Sandbox	Where makers build and configure. Contains the unmanaged IA solution. All changes originate here.
Testing	Sandbox (Managed)	Validates managed solution packages before release. Mirrors Production configuration.
Production	Production (Managed)	Live environment for end users. Receives only tested, managed solutions.

3. Solution Architecture

3.1 Managed vs. Unmanaged Solutions

A Solution is a structured package containing all components required for an app to run: Dataverse tables, forms, views, apps, Power Automate flows, and more. IncidentAnalytix ships in two solution types:

Solution Type	Characteristics & Use
Unmanaged Dev Only	Editable. Used in the Development environment only. Components import in a draft state and must be published after import. This is your source-of-truth for all configuration and customization.
Managed Test & Prod	Read-only, locked deployment package. Used in Testing and Production. Components publish automatically on import. Removing a managed solution removes all its components from that environment.

⚠ ALM Rule: Never apply direct customizations to a managed solution in Testing or Production. All changes must be made in the Development environment’s unmanaged solution, then re-exported and re-deployed through your ALM pipeline.

3.2 Layered Solution Architecture: LS and IA

IncidentAnalytix is delivered as two layered solutions that must be installed in sequence:

Layer	Solution	Contents
1 — Base	Lookups Solution (LS)	All reference data lookup tables, forms, and views. Shared with other SystemsAnalytix applications. Must be installed first in every environment.
2 — App	IncidentAnalytix Solution (IA)	All incident tracking tables, forms, views, and the model-driven app. Depends on LS components. Installed second.

⚠ Dependency Enforcement: If the IncidentAnalytix Solution (IA) is imported before the Lookups Solution (LS), the platform will abort the import with a dependency error. Always install LS first.

4. Installation Sequence at a Glance

The table below summarizes the full installation sequence across all three environments. Complete all steps for each environment in order.

#	Environment	Action	Solution Type
1	Lookups Dev	Import LS	Unmanaged
2	Lookups Dev	Export LS for downstream use	Managed export
3	IA Dev	Import LS	Managed
4	IA Dev	Import IA	Unmanaged
5	IA Dev	Publish All Customizations	—
6	IA Test	Import LS	Managed
7	IA Test	Import IA	Managed
8	IA Production	Import LS	Managed
9	IA Production	Import IA	Managed

5. Prerequisite: Deployment Account Setup

Before installing solutions, set up a dedicated account to own the deployment process. This prevents tying solution ownership to an individual’s personal account — a risk when personnel changes occur.

5.1 Option A: Standard User Account

1. In the Microsoft 365 Admin Center, create a new user (e.g., [email protected]). Assign a Power Apps Per User or Dynamics 365 license.
2. In the Power Platform Admin Center, navigate to each environment. Under Settings › Users + Permissions › Users, add this account and assign the System Administrator security role.
3. Secure the account credentials and restrict sign-in to authorized personnel only.

5.2 Option B: Service Principal (Recommended for ALM Pipelines)

1. In Microsoft Entra ID (Azure AD), register a new application. Note the Application (Client) ID and create a Client Secret.
2. In the Power Platform Admin Center, for each environment, go to Settings › Users + Permissions › Application users. Click New app user, select your registered application, and assign the System Administrator security role.
3. A service principal does not consume a Power Apps user license. However, if the solution includes Power Automate flows using premium connectors, a Power Automate license may be required.

ⓘ For step-by-step guidance, see the Microsoft Learn article: Manage application users in the Power Platform admin center.

6. Development Environment Setup

The Development environment is where the IncidentAnalytix unmanaged solution is installed and maintained. All configuration, lookup data customization, and future changes originate here.

6.1 Set Up the Lookups Development Environment

A dedicated environment for the Lookups solution maintains clean separation from the IA solution and supports reuse across other SystemsAnalytix applications.

1. In the Power Platform Admin Center, create a new Sandbox environment named (e.g., Lookups Dev). Provision a Dataverse database. Add the deployment account from Section 5 as a System Administrator.
2. Sign in to the Power Apps Maker Portal and switch to the Lookups Dev environment.
3. Go to Solutions and click Import. Select the Lookups Solution Unmanaged .zip file. Complete the import wizard.
4. After import, click Publish All Customizations to activate all components.
5. Verify that the expected lookup tables, forms, and views are present in the solution.
6. Export the Lookups Solution as a Managed .zip file. This managed export is imported into all downstream environments (IA Dev, Test, Production).

6.2 Set Up the IncidentAnalytix Development Environment

1. Create a new Sandbox environment named (e.g., IncidentAnalytix Dev). Provision a Dataverse database. Add the deployment account as a System Administrator.
2. In the Maker Portal, switch to the IncidentAnalytix Dev environment.
3. Go to Solutions › Import. Select the Lookups Solution Managed .zip file (from step 6.1.6). Complete the import. Managed solutions publish automatically.
4. Verify the Lookups solution appears and its components are accessible.
5. Click Import again. Select the IncidentAnalytix Solution Unmanaged .zip file. Complete the import wizard.
6. After the IA import completes, click Publish All Customizations. This step is required for unmanaged solutions to activate all imported components.
7. Verify that the IncidentAnalytix model-driven app opens, incident tables are accessible, and lookup fields correctly resolve to values from the Lookups solution.

✓ The Development environment now holds the Lookups Solution (managed) and the IncidentAnalytix Solution (unmanaged). Use this environment for all configuration work, lookup data customization, and schema changes.

7. Testing Environment Setup

The Testing environment receives managed solution packages and is used to validate IncidentAnalytix before promoting changes to Production. No development work should occur here.

1. Create a new Sandbox environment named (e.g., IncidentAnalytix Test). Provision a Dataverse database. Add the deployment account as a System Administrator.
2. In the Maker Portal, switch to the Test environment.
3. Import the Lookups Solution Managed .zip file. Managed solutions publish automatically — no additional publish step required.
4. Verify the Lookups solution is present and components are available.
5. Import the IncidentAnalytix Solution Managed .zip file. The platform detects the LS dependency is satisfied and completes the import.
6. Perform functional verification: open the model-driven app, create a sample incident record, confirm lookup fields resolve correctly, and verify Power Automate flows are active.
7. Any issues discovered should be resolved in the Development environment. Do not make direct changes to managed components in the Test environment.

8. Production Environment Setup

The Production environment hosts the live application for end users. Only thoroughly tested managed solution packages should be deployed here.

1. Create a Production-type environment named (e.g., IncidentAnalytix Production). Enable it as a Managed Environment. Provision a Dataverse database. Add the deployment account as a System Administrator.
2. In the Maker Portal, switch to the Production environment.
3. Import the Lookups Solution Managed .zip file.
4. Verify the Lookups solution is present.
5. Import the IncidentAnalytix Solution Managed .zip file.
6. Perform go-live verification: confirm the app opens correctly, security roles are assigned to all users (see Section 10), and sample data entry works end-to-end.

⚠ ALM Discipline: Future changes must follow the Dev → Test → Production cycle. Never import unmanaged solutions or make direct customizations in the Production environment.

9. Automating Deployments with Power Platform Pipelines

Power Platform Pipelines automate the export-and-import cycle across your Dev → Test → Production environments. Once configured, a maker can promote a new solution version to Testing or Production with a few clicks, eliminating manual file handling and reducing deployment errors.

9.1 Install the Pipelines App

1. Create a dedicated Pipelines Host environment (Sandbox or Production type, Managed). This hosts the pipeline configuration app separately from your solution environments.
2. In the Pipelines Host environment, go to Resources › Dynamics 365 Apps and install Power Platform Pipelines. This adds the Deployment Pipeline Configuration model-driven app.
3. Ensure the deployment account has the Deployment Pipeline Administrator role in the Pipelines Host environment.

9.2 Configure the Pipeline

Open the Deployment Pipeline Configuration app and create a new pipeline:

• Name the pipeline (e.g., IncidentAnalytix Deployment Pipeline).
• Add the IncidentAnalytix Dev environment as the Development (source) stage.
• Add the IncidentAnalytix Test environment as Stage 1 (target).
• Add the IncidentAnalytix Production environment as Stage 2 (target).
• Optionally, configure delegated deployment using the service principal from Section 5.2 as the stage owner for Test and Production. This ensures solution component ownership is not tied to an individual’s account.

9.3 Running a Deployment

• In the Development environment, open the IncidentAnalytix unmanaged solution and click Deploy (pipeline option in the command bar).
• Select the configured pipeline and target stage (Testing). The pipeline automatically exports a managed artifact from Dev and imports it into Test.
• After successful validation in Test, promote the same artifact to Production. Pipelines reuse the tested artifact rather than re-exporting from Dev, ensuring what was tested is exactly what ships.

ⓘ Reference: Overview of pipelines in Power Platform and Set up pipelines on Microsoft Learn.

10. Security Roles Setup

IncidentAnalytix uses a layered security architecture built on Microsoft Dataverse security roles. This design follows the principle of least privilege, remains future-proof against Microsoft platform updates, and provides clear role assignment for administrators.

Upon the initial installation you need to use the Built-in Security Roles that come with the app. These should be used for initial installation only so testers can open and review the app. For actual deployment you must create your own Security Roles using the built-in IA Security Role Templates as a sample. See Security Fundamentals for more information.

Required Role Assignment — All Are Mandatory

Every user of IncidentAnalytix must be assigned all 3 role layers. The application will not function correctly if any layer is missing.

• Layer 1 Required – Microsoft Basic User Role: this is a built-in Microsoft Role that provides core functionality to the app. Without this role the user cannot start the app
• Layer 2 Required – IA Generic (Platform Features) Security Role: Grants access to basic backend workflows and scheduled processes.
• Layer 3 Required – At least one IncidentAnalytix Security Role: Controls access to IA custom tables based on job responsibility. Without at least one IA Security Role, the app will open, but the user will not have access to any of the tables, basically it would be just an empty shell.

10.1 Layer 1: Basic User Role

Basic User is a Microsoft-built security role that provides the minimum platform privileges required to open and run any model-driven app in Dataverse. Microsoft maintains and updates this role automatically as the platform evolves.

⚠ The Microsoft Basic User Role must be assigned to all users.

10.2 Layer 2: IA Generic (Platform Features)

The IA Generic (Platform Features) role is a platform utility role that grants Power Automate flow execution rights and workflow activation privileges necessary for IncidentAnalytix automated processes. It does not grant any Dataverse entity permissions — all entity-level access remains at None. This role should be combined with functional data-access roles for most users. It ensures that workflows and scheduled processes can execute on behalf of users who trigger them.

Feature Area	Privileges Included
Timeline, Notes & Activities	Create, Read, Update, Delete on Activity-related tables (Notes, Phone Calls, Tasks, Emails) used by the Timeline control on all IA forms.
SharePoint Document Management	Privileges required to link to and view SharePoint document libraries from within IncidentAnalytix records.
Excel Export and Import	Permissions allowing users to export Dataverse data to Excel and import updated data back via the standard model-driven app Export/Import commands.

⚠ The IA Generic (Platform Features) role must be assigned to each user.

10.3 Layer 2: IncidentAnalytix Security Roles

Security Roles control what incident data a user can create, read, update, and delete. IA ships with a number of Security Role Templates. These are sample templates only and are locked to prevent editing. Future updates to IA may add new permissions to these templates which is why they should/cannot be changed by customers.

⚠ At least one of your Organization Security Roles must be assigned to each user.

Build your own Security Roles: Copy the existing IA Security Roles and save them with a name for your organization. Use a Prefix unique to your organization to make them easier to locate. Edit the copies as needed to meet your needs.

Example Security Role	Intended User & Capabilities
IA Admin	Full read/write/delete access to all IncidentAnalytix tables, security role management, and configuration. Reserved for system administrators and solution owners.
IA Risk Manager	Full read/write access across all incidents and related records within their assigned Business Unit. Can view and edit all incidents submitted by staff in their unit. Cannot delete records.
IA Risk Manager	Can create and edit incidents and related records. Read access to peer records within the Business Unit. Typically assigned to program supervisors or lead staff.
IA Incident Reporter	Can create new incident records and edit their own submissions. Read-only access to incidents they are associated with. Typical role for front-line staff reporting incidents.
IA Read Only	Read-only access to all incident records within scope. No create, update, or delete privileges. Appropriate for auditors, reviewers, or leadership requiring visibility without edit rights.

⚠ At least one of your Organization Security Roles must be assigned to each user.

ⓘ Review the full list of included IA Security Roles and permissions on each table.

10.4 Assigning Security Roles to Users

Security roles are assigned per environment. Roles assigned in Testing do not carry over to Production. Roles must be assigned in every environment where users need access.

Via the Power Platform Admin Center (recommended for bulk assignments)

1. Go to admin.powerplatform.microsoft.com and sign in as an administrator.
2. Select Environments and choose the target environment (e.g., IncidentAnalytix Production).
3. Go to Settings › Users + permissions › Users.
4. Select the user(s) and click Manage security roles.
5. Select all three required roles: App Opener, IncidentAnalytix – Generic, and the appropriate IA Data Role.
6. Click Save. Roles take effect immediately.

Via the Power Apps Maker Portal (individual user management)

1. Go to make.powerapps.com and switch to the target environment.
2. Go to Settings › Advanced settings › Security › Users.
3. Select the user and click Manage Roles in the command bar.
4. Check Basic User, IncidentAnalytix – Generic, and the appropriate IA Data Role. Click OK.

⚠ Common Access Error: If a user can sign in to Power Apps but receives an “Insufficient Permissions” error when opening IncidentAnalytix, verify that both role layers are assigned. The most common cause is a missing IA Role or a missing Basic User role.

10.5 Security Roles for App Customization

Depending on your Environment Configuration, there should be at least one user assigned as the internal Microsoft Power Apps System Administrator Role which provides full control over the application and all aspects of configuration and deployment. This should be a limited role assigned only to experienced Power Platform developers and/or high-level IT staff.

For ‘day-to-day’ customization and modification, a user would need the Microsoft Power Apps Environment Maker Rols and the System Customizer Role. These should be granted only to those with experience building and managing Power Apps.

Environment Maker role is what allows a user to:

• See the environment in make.powerapps.com
• Create/manage apps, flows, and solutions
• Act as a “maker persona” in the portal

System Customizer role is required to:

• Create or modify Dataverse tables, columns, relationships
• Edit forms, views, command bars, and other schema-level artifacts
• Actually create unmanaged customizations

11. Post-Installation Configuration

After solution installation and security role assignment, complete the following tasks before opening IncidentAnalytix to end users.

11.1 Loading Core Lookup Data — Configuration Migration Tool

IncidentAnalytix ships with a set of pre-built core lookup values that populate the reference data dropdowns used throughout the application. These values cover standard categories such as Anatomical Locations, Countries, States/Provinces, Illnesses, Injuries, and more. They are delivered as a Configuration Migration Tool data package — a .zip file produced by the Microsoft Power Platform Configuration Migration tool. Importing this data gets your application ready to run quickly.

There are additional Lookup Tables that you will need to customize with your own organization values before starting to use the application (e.g. Activity Types, Severity Level, etc.). See section 11.6.

This package must be imported into every environment (Development, Testing, and Production) after the LS and IA solutions are installed. Without this step the application is functional, but all lookup dropdowns will be empty and incident records cannot be properly classified.

11.2 What the Package Contains

The Configuration Migration Tool package contains the core static lookup records for the Lookups Solution tables. These are the seed values that SystemsAnalytix maintains as the baseline dataset for all IncidentAnalytix deployments. They include:

• Anatomical Location for Injuries and Illnesses
• Injury and Illness Types
• Countries, States / Provinces
• Weather and Wind categories
• Equipment Category, Condition, and Performance values

These values are a starting point. Your organization can add, rename, or suppress lookup values after import to match your operational terminology.

11.3 Prerequisites

Before importing the data package, confirm the following:

• The Lookups Solution (LS) and IncidentAnalytix Solution (IA) are both fully installed and published in the target environment
• The Microsoft Power Platform Configuration Migration tool is installed on your workstation. It is available as part of the Power Platform Tools package from the Microsoft Power Platform Tools download page
• The deployment account from Section 5 has System Administrator rights in the target environment

11.4 Importing the Data Package

Repeat these steps for each environment — Development first, then Testing, then Production.

1. Launch the Configuration Migration tool (DataMigrationUtility.exe) on your workstation.
2. On the main screen, select Import data and click Continue.
3. On the login screen, select your deployment type (Office 365) and enter the credentials for the deployment account from Section 5. Click Login.
4. Select the target environment from the list of available organizations and click Login.
5. On the Import Configuration Data screen, click the folder icon next to the data file field and browse to the Configuration Migration Tool .zip file provided by SystemsAnalytix.
6. Click Import Data. The tool will process all lookup tables in dependency order. This means that if Table B (e.g. State/Province) depends on Table A (Country), the Table B import will be paused until Table A has been imported and then Table B will be imported in a second pass. Progress is shown per-table as the import runs.
7. When the import completes, review the summary screen for any errors or warnings. A fully successful import shows all tables with a green status and zero failures.
8. Click Finish.

NOTE: The import is additive — it will not overwrite or delete records that already exist in the target environment. If you have previously added custom lookup values, they are preserved.

IMPORTANT: Do not close the Configuration Migration tool or disconnect from the network during an import. A partial import will leave some lookup tables populated and others empty. If an import is interrupted, re-run it from the beginning — the additive behavior means duplicate records will not be created for rows that already imported successfully.

11.5 Verifying the Import

After import, open the IncidentAnalytix model-driven app in the target environment and create a test incident record. Confirm that the following fields populate with dropdown options:

• Incident Category
• Severity Level
• Type of Incident
• Activity Type
• Contributing Factor (via the Contributing Factors child table)

If any of these dropdowns are empty, check the Configuration Migration tool summary log for errors on the corresponding lookup table and re-run the import.

11.6 Configure Lookup Data for your Organization

IncidentAnalytix allows organizations to customize lookup values for categories such as Incident Type, Severity Level, Activity Type, etc. Review and customize these lookup tables in the Development environment to align with your organization’s terminology. Lookup tables are provided as Microsoft Excel seed data files. Import the customized lookup data into your Production environment using the Excel Import feature within the model-driven app. See Microsoft Learn – Import Data From Excel.

11.7 Configure Organization Reference Data

Set up your organization’s reference structure before creating incident records. These values appear in dropdowns throughout the application:

• Organization Branch — geographic branches of an organization.
• Organization Site Location — physical locations where programs operate
• Organization Facility — sub-locations within a Site Location.
• Organization Program Type — program structure as applicable.
• Organization Course Type — program course type as applicable.
• Organization Person to Notify — individuals in your notification escalation chain.
• Organization Notification Levels — notification levels in your organization.

11.8 Dataverse Auditing

Dataverse table auditing is disabled by default across all IncidentAnalytix tables. If your organization has regulatory, accreditation, or compliance requirements mandating a change audit trail, you must enable auditing manually after installation.

To enable: in the Power Platform Admin Center, navigate to the environment settings, go to Audit and Logs › Audit Settings, and enable auditing at the environment level. Then enable auditing on each individual table through the table’s managed properties in the solution. Auditing can then be enabled for individual tables and/or for individual columns within a table.

⚠ Storage Impact: Enabling auditing on all 85+ IncidentAnalytix tables will increase Dataverse storage consumption and may affect performance in high-volume environments. Enable auditing only on tables that require it for specific compliance obligations.

11.9 Business Unit Structure

If your organization requires record-level data isolation between departments, regions, or program areas, configure Dataverse Business Units before adding end users. Security roles and record ownership interact with the Business Unit structure to determine data visibility scope. Contact SystemsAnalytix support for guidance on multi-Business Unit deployments.

12. Best Practices & ALM Notes

• Always install LS before IA in any environment. The platform enforces this dependency and will abort an IA import if LS is missing.
• Treat Testing and Production as read-only deployment targets. All changes — including lookup data additions and schema customization — originate in the Development environment’s unmanaged solution.
• Use a dedicated service account or service principal for all deployments. Individual accounts tied to an employee create ownership risk when that employee leaves.
• Assign BOTH security role layers (Basic User and one IA Data Role) to every user. Partial role assignment is the most common cause of access errors.
• Enable Managed Environments on Production (and optionally Testing) for DLP policy enforcement, solution checker requirements, and usage insights.
• Maintain PITR checkpoint records before each major solution upgrade in Production, particularly when the upgrade includes schema changes to existing tables.

13. Reference Documentation

Topic	Microsoft Learn Link
Solution concepts (Managed vs Unmanaged)	solution-concepts-alm
Create and manage environments	create-environment
Manage application users	manage-application-users
Add users and assign security roles	add-users-to-environment
Import solutions	import-update-export-solutions
Pipelines overview	pipelines
Set up pipelines	set-up-pipelines
Run pipelines	run-pipeline
Delegated deployments (service principal)	delegated-deployments-setup

---

Questions? Contact SystemsAnalytix Support at support.systemsanalytix.com