User Guide

Comprehensive documentation to help you get the most out of ALMWorks - the Power Platform ALM Toolbox.

Back Home

1. Getting Started

ALMWorks is a desktop application designed to streamline and enhance Power Platform Application Lifecycle Management (ALM) processes. This comprehensive tool provides solutions for common ALM challenges and automates repetitive tasks.

System Requirements

  • Windows: Windows 10 or later
  • macOS: macOS 10.15 (Catalina) or later
  • Linux: Ubuntu 20.04 or equivalent
  • Memory: 4GB RAM minimum
  • Disk Space: 500MB free space
  • Internet Connection: Required for connecting to Power Platform environments

ALMWorks is designed to work with all Power Platform environments, including:

  • Power Platform Online environments
  • Dynamics 365 Customer Engagement
  • Model-driven and Canvas apps
Pro Tip

Create dedicated service accounts with appropriate permissions for use with ALMWorks in your production environments.

2. Installation

ALMWorks is distributed as a platform-specific installer for Windows, macOS, and Linux. Follow these steps to install the application:

Windows Installation

  1. Download the ALMWorks installer (.exe) from the download page.
  2. Run the installer and follow the on-screen instructions.
  3. The installer will create a desktop shortcut and add ALMWorks to your Start menu.

macOS Installation

  1. Download the ALMWorks disk image (.dmg) from the download page.
  2. Open the disk image and drag the ALMWorks icon to your Applications folder.
  3. Open the application from your Applications folder or Launchpad.

Linux Installation

  1. Download the ALMWorks AppImage from the download page.
  2. Make the AppImage executable with the command:
    chmod +x ALMWorks-x.x.x.AppImage
  3. Run the AppImage by double-clicking it or executing it from the terminal.

Auto-Updates

ALMWorks includes an automatic update system that will notify you when new versions are available. You can also check for updates manually from the Help menu.

Important Note

On first launch, the application will request permissions to connect to the internet for updates and Power Platform connectivity.

3. Connecting to Environments

ALMWorks requires connection to your Power Platform environments to perform ALM tasks. You can connect using either interactive login or service principal authentication.

Adding an Environment

  1. Click on the "Settings" gear icon in the sidebar.
  2. Select "Environments" tab.
  3. Click "Add Environment" button.
  4. Enter a display name for your environment.
  5. Enter the environment URL (e.g., https://yourorg.crm.dynamics.com).
  6. Choose an authentication method (User Account or Service Principal).
  7. Complete the authentication process.

Environment Management

Once added, you can manage your environments by:

  • Setting a default environment
  • Testing connections
  • Editing connection details
  • Removing environments
Security Note

ALMWorks securely stores your credentials in the system's secure credential store. No credentials are stored in plain text.

4. Solution Comparator

The Solution Comparator is one of the core features of ALMWorks, allowing you to compare solution files to identify differences between managed and unmanaged versions, or between different environments.

Comparing Solutions

  1. Navigate to the "Solution Comparator" plugin in the sidebar.
  2. Click "Select Files" and choose two solution zip files to compare.
  3. Alternatively, use the "Load from Environment" option to export solutions directly.
  4. Click "Compare Solutions" to start the analysis.

Understanding Comparison Results

The comparison results are displayed in several categories:

  • Components: Differences in components between the solutions
  • Properties: Property value differences for matching components
  • Missing Dependencies: Dependencies present in one solution but not the other
  • Configuration Differences: Settings, environment variables, connection references

Each difference is color-coded for easy identification:

  • Green: Added components/properties
  • Red: Removed components/properties
  • Orange: Modified components/properties

Exporting Comparison Results

You can export the comparison results in several formats:

  • HTML Report
  • Excel Spreadsheet
  • JSON Format
  • PDF Document

5. Export/Import Fixer

The Export/Import Fixer helps resolve common issues encountered during solution export and import processes in Power Platform.

Common Issues Addressed

  • Missing dependencies
  • Broken references
  • Invalid component definitions
  • Environment-specific configurations

Using the Fixer

  1. Navigate to the "Export/Import Fixer" plugin in the sidebar.
  2. Select a solution file to analyze.
  3. Click "Analyze Solution" to identify potential issues.
  4. Review the suggested fixes for each issue.
  5. Select which fixes to apply.
  6. Click "Apply Fixes" to generate a corrected solution file.
Note

The fixer creates a new solution file and does not modify the original, ensuring that your source files remain intact.

6. Azure DevOps Integration

ALMWorks integrates with Azure DevOps to streamline CI/CD pipelines for Power Platform solutions.

Connecting to Azure DevOps

  1. Navigate to the "Settings" menu.
  2. Select the "Azure DevOps" tab.
  3. Enter your Azure DevOps organization URL.
  4. Generate and enter a Personal Access Token (PAT) with appropriate permissions.
  5. Click "Test Connection" to verify.

Working with Build Pipelines

Once connected, you can:

  • View existing build pipelines
  • Create new pipelines optimized for Power Platform
  • Queue builds with custom parameters
  • Monitor build status and logs

Solution Packaging for DevOps

The Azure DevOps Packager feature helps prepare solutions for deployment through CI/CD pipelines:

  1. Navigate to the "DevOps Packager" plugin in the sidebar.
  2. Select a solution file to package.
  3. Configure deployment options (environments, connection references, etc.)
  4. Generate deployment scripts and pipeline YAML.
  5. Export the package for use in Azure DevOps.

7. Plugins & Extensions

ALMWorks features a modular plugin architecture that allows for extensibility and customization.

Built-in Plugins

The application comes with several built-in plugins:

  • Solution Comparator: Compare solution files
  • Export/Import Fixer: Fix common solution issues
  • DevOps Packager: Prepare solutions for CI/CD
  • Environment Manager: Manage Power Platform environments
  • Dependency Analyzer: Visualize and manage solution dependencies

Installing Custom Plugins

  1. Download or create a plugin package (.almplugin file).
  2. Navigate to "Settings" > "Plugins" in ALMWorks.
  3. Click "Install Plugin" and select the package file.
  4. Review the plugin permissions and click "Install".
  5. Restart ALMWorks if prompted.
Security Warning

Only install plugins from trusted sources. Plugins have access to your Power Platform environments and can perform actions on your behalf.

Developing Custom Plugins

Developers can create custom plugins using the ALMWorks SDK. Refer to the GitHub repository for documentation and examples.

8. Troubleshooting

If you encounter issues with ALMWorks, here are some common troubleshooting steps:

Connection Issues

  • Verify your internet connection.
  • Check that your Power Platform environment is accessible.
  • Confirm that your authentication credentials are valid.
  • Try clearing the application cache (Settings > Advanced > Clear Cache).

Performance Problems

  • Close unused plugins and tabs.
  • Check resource usage in Task Manager/Activity Monitor.
  • Increase application memory allowance in Settings.
  • Consider analyzing smaller solutions if working with very large files.

Application Crashes

  • Check application logs (Help > Show Logs).
  • Update to the latest version of ALMWorks.
  • Try resetting the application settings (Settings > Advanced > Reset Settings).
  • Reinstall the application if problems persist.

Getting Support

If you continue to experience issues, you can get help through the following channels:

Support the Project

ALMWorks is developed and maintained by Franck Kengne. If you find the tool useful, consider supporting the project.