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 comprehensive web application designed to streamline and enhance Power Platform Application Lifecycle Management (ALM) processes. This cloud-based tool provides solutions for common ALM challenges and automates repetitive tasks.

Browser Requirements

  • Chrome: Version 90 or later
  • Firefox: Version 88 or later
  • Safari: Version 14 or later
  • Edge: Version 90 or later
  • Internet Connection: Required for all functionality
  • JavaScript: Must be enabled

ALMWorks works with all Power Platform environments, including:

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

Configure dedicated service accounts and Personal Access Tokens (PATs) with appropriate permissions for use with ALMWorks in your production environments.

2. Accessing the Web App

ALMWorks is a web-based application that requires no downloads or installations. Access it instantly from any modern web browser.

Quick Start

  1. Open your web browser and navigate to the ALMWorks application.
  2. Click "Launch ALMWorks Web App" to access the full application.
  3. The application will load directly in your browser with all features available.

Bookmarking

For quick access, bookmark the ALMWorks application page in your browser. The application maintains your settings and preferences across sessions using cloud storage.

Automatic Updates

ALMWorks automatically receives updates whenever you access the application. No manual updates or version management required - you always have the latest features and security improvements.

Cross-Platform Access

Access ALMWorks from any device with a modern web browser:

  • Desktop computers (Windows, macOS, Linux)
  • Tablets (iPad, Android tablets)
  • Mobile devices (responsive design)
Cloud Benefits

Your settings, deployment history, and configurations are automatically saved to the cloud and synchronized across all your devices and browser sessions.

3. Settings Configuration

Configure ALMWorks to connect to your Power Platform environments and Azure DevOps organization. All settings are automatically saved to the cloud.

Power Platform Configuration

  1. Click on the "Settings" option in the sidebar navigation.
  2. In the "Power Platform Settings" section, enter your environment URLs:
    • Development URL: Your dev environment (e.g., https://yourorg-dev.crm.dynamics.com)
    • Test URL: Your test environment (e.g., https://yourorg-test.crm.dynamics.com)
    • Production URL: Your production environment (e.g., https://yourorg.crm.dynamics.com)
  3. Configure authentication credentials (Client ID, Client Secret, Tenant ID).
  4. Click "Save Settings" to store your configuration.

Azure DevOps Integration

  1. In the "Azure DevOps Settings" section, enter:
    • Organization URL: Your Azure DevOps org (e.g., https://dev.azure.com/yourorg)
    • Personal Access Token (PAT): Token with Build (read & execute) permissions
    • Project Name: Your Azure DevOps project name
  2. Click "Save Settings" to enable pipeline management features.

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.