XMPro Deployment Manager

Application

The XMPro Deployment Manager provides comprehensive deployment capabilities for managing XMPro solutions across environments through Git repository integration. The application consists of two main components:

Export Wizard

The export functionality allows users to package and deploy XMPro solutions to Git repositories with intelligent optimization.

Import Wizard

The import functionality enables seamless import of packaged solutions from Git repositories with comprehensive dependency management.

Core Architecture Components

Key Features

Category-Based Package Optimization

The deployment manager uses a sophisticated algorithm to group components by their categoryId and by category type (Application/Datastream, Recommendation, and Recommendation Form):

Algorithm Benefits:

• Minimized Package Count: Intelligent grouping reduces the total number of deployment packages
• Category Consistency: Ensures cross-environment category mapping integrity
• API Efficiency: Reduces deployment API calls through batched component processing
• Conflict Prevention: Prevents category mismatches during environment promotion

Azure DevOps Integration

Repository Structure:

https://{your-organization}.visualstudio.com/{your-project}/_git/{repository-name}
├── {branch}/
│   └── {solution}/
│       ├── {tag-1}/
│       │   ├── package-contents.json
│       │   ├── applications/
│       │   ├── datastreams/
│       │   └── recommendations/
│       ├── {tag-2}/
│       └── {tag-N}/

Dependency Resolution Engine

The import wizard includes a comprehensive dependency resolution system:

Resolution Categories:

Non-Blocking (Import can proceed):

• Collection Mapping: Collection assignment for imported Data Streams
• Category Mapping: Flexible category assignment for imported components
  • Collection and Category mapping appears for all package items but only applies to new items
  • Existing items inherit their current category/collection and create new versions
  • All package entities must have a category option selected before import

Blocking (Must resolve to import):

• Missing or Version Incompatible Agents: Detection and resolution required
• Missing or Version Incompatible Connectors: Manual resolution required
• Server Variables: Identification of missing configuration variables
  • Import cannot proceed until all blocking dependencies are resolved. Version mismatches between agents or connectors used during development and those in the target environment can cause runtime failures or unexpected behavior in production

Steps to Deploy

1. Configure Git Repository Access

Set up Azure DevOps Personal Access Token with appropriate permissions:

• Scope: Full Access permission recommended
• Organization: User Defined
• Expiration: Recommended 90 days for development environments
• Storage: Securely stored as XMPro Server Variable

2. Execute SQL Setup Scripts

Before importing the application, execute the required SQL scripts in the target AD (Application Designer) database:

Script 1: Create_Synonym_Tables_for_Category_Lookup.sql

This script creates cross-database external tables to enable the Deployment Manager to query category information from the DS and SM databases.

Update the following variables before execution:

Note: The script includes built-in validation to prevent execution with placeholder values. Ensure all ChangeMe- prefixes are removed.

Script 2: sp_AppExport.sql

This script creates the stored procedure used by the Export Wizard to format application, data stream, and recommendation metadata for Git deployment. No variable configuration is required - execute as-is in the AD database.

3. Configure Server Variables

Ensure the following variables are available for SQL connectivity and Git integration:

Important: Variable names must match exactly as shown above. The application relies on these specific names for lookups—using different names will cause lookups to fail. If you must use different variable names, you will need to remap them in both the SQL datasources and the metablock value mapping sections.

4. Import the Application Package

• Import the XMPro Deployment Manager application
• Check for data source errors the export and import pages after import

6. Verify Export Functionality

Test the export wizard:

• Navigate to the Export Wizard page
• Select Applications, Data Streams, and/or Recommendations
• Configure solution name and base version tag
• Verify Git credentials auto-validation
• Select Import Uploads and Appfiles where appropriate
• Execute deployment to test Git integration

7. Approve Pull Request in Git

Navigate to your Git Repository:

• Identify your specific Pull Request by matching Solution and Base Version Name
• Select the Pull Request, click Complete, leave the default selections checked, then click Complete Merge
• Repeat this process for all packages in the solution
• The exported solution will now be available in the main branch to select in the Import Wizard

8. Verify Import Functionality

Test the import Wizard:

• Navigate to the Import Wizard page
• Browse Git repository branches and solution. The default branch will be main, but non-merged branches are still selectable
• Select the solution for import
• Resolve any missing dependencies
• Assign or create categories as required
  • Note: Category assignment will only reassign new entities. Existing entities are matched by Universal ID and version, retaining their current category/collection assignment. The category field is still required as there is no current way to tell what exists in the target env
• Configure collection mapping
• Execute import to test full workflow

API Configuration

Import Size Limits

The application enforces a 200MB size limit on imports to prevent timeout issues and ensure reliable import operations.

Export Timeout Settings

Export operations include a configurable database timeout of 1 minute (3600ms) to handle large application exports. This timeout is set at the database command level to prevent export failures when processing complex applications with extensive dependencies.

Troubleshooting

Common Export Issues

Common Import Issues

Performance Considerations

Advanced Configuration

Custom Category Creation

The Import Wizard supports dynamic category creation:

// Category types supported:
- applications - datastreams (shared namespace)
- recommendations (separate namespace)
- recommendationforms (separate namespace)

Package Optimization Algorithm

Core Principle: Components are grouped by categoryId to minimize total packages while respecting category constraints.

Algorithm Flow:

1. Package Initialization: Start with first unassigned component
2. Greedy Consolidation: Add components with matching categories
3. Optimization Pass: Fill remaining slots with compatible single items
4. Validation: Ensure package integrity and category consistency

Environment Promotion Pipeline

Non-Prod Environment → Git Repository → Production Environment
    ↓                        ↓              ↓
Export Wizard          Package Storage    Import Wizard
Category Grouping      Version Control    Dependency Resolution
Git Integration        Branch Management  Collection Mapping

This deployment manager provides enterprise-grade capabilities for managing XMPro solutions across environments while maintaining integrity, consistency, and optimal performance.