Step-by-Step Usage Guide
This guide details step by step how to use AutoUpgradeTool to perform an Avanteam Process Studio version upgrade.
Process Overview
The AutoUpgradeTool assistant guides you through 6 main steps:
graph LR
A[1. Admin privileges] --> B[2. Patch selection]
B --> C[3. Instance detection]
C --> D[4. Target version]
D --> E[5. Config validation]
E --> F[6. Patch application]
Estimated duration: 15 to 45 minutes (depending on instance size and upgrade complexity)
Make sure you have performed all the checks described in the Installation and Configuration article, especially the complete backup of your environment.
Step 1: Launching in Administrator Mode
Starting the Tool
-
Navigate to the AutoUpgradeTool installation directory
C:\Avanteam\AutoUpgradeTool\ -
Right-click on
AutoUpgradeTool.exe -
Select "Run as administrator"
Privilege Management
If you haven't launched the tool in administrator mode, a warning will appear:
Available options:
| Button | Action | Recommendation |
|---|---|---|
| Yes | Relaunches the tool in administrator mode | ✅ Recommended |
| No | Continues without elevated privileges | ⚠️ Some actions will fail |
| Cancel | Closes the application | ❌ Use if you cannot obtain rights |
::: warning Actions requiring admin rights Without administrator privileges, the following operations will need to be performed manually:
- Stopping/starting Windows services (Remoting, Scheduler)
- Stopping/starting IIS pools
- Modifying certain protected system files :::
Step 2: Selecting the Directory Containing Upgrade Patches
Choose Directory Location
At startup, the assistant asks you to select the directory containing your upgrade patches.
- Click the "Browse..." button
- Navigate to the directory containing your patches (copied from Bastille)
Example:
C:\Avanteam\Patches\
Or directly from the Bastille server (if stable connection):
S:\3-PRODUIT\ReleaseUpgrades\Patches
Patch Validation
The tool automatically checks:
- ✅ File format (
.7z) - ✅ Internal patch structure
- ✅ Presence of mandatory files (
scripts/,binaries/) - ✅ Compatibility with AutoUpgradeTool version
::: danger Incompatible patch error If you see the message:
The script "xxx" from the patch is incompatible with this version of the upgrade tool.
A newer version of autoupgradetool is required.
➡️ Download the latest version of AutoUpgradeTool from the Bastille server: S:\3-PRODUIT\ReleaseUpgrades\AutoUpgradeTool\
:::
Step 3: Automatic Instance Detection
This step analyzes your Process Studio environment to automatically detect all necessary parameters.
Detected Information
At Instance Level
The tool automatically detects:
| Element | Description | Example |
|---|---|---|
| Detected version | Current version of the APS instance | 23.14 |
| Database (directory) | Connection string to the directory database | Data Source=.\SQLEXPRESS;... |
| Remoting Service | Location of the Remoting service | C:\Program Files\Avanteam\APP\PStudio.Services\Remoting-instance-APP |
At Application Level
For each detected application, the tool identifies:
| Element | Description | Example |
|---|---|---|
| Profile name | Application name (master if main application) | Application "instance APP" (master) |
| Detected version | Application version | 23.14 |
| Database (application) | Connection string to the application database | Data Source=.\SQLEXPRESS;... |
| Website | IIS website directory | C:\Program Files\Avanteam\APP\PStudio.Net.Web\app |
| Scheduler Service | Scheduler directory | C:\Program Files\Avanteam\APP\PStudio.Services\instance APP |
Rerun Detection
If the detected information is incorrect or incomplete:
- Click the "Rerun detection" button
- The tool reanalyzes your environment
- Check the displayed information again
::: info Detection in progress During detection, the button shows "Detection in progress..." and is disabled. The operation typically takes 5 to 10 seconds. :::
Information Validation
Points to check before continuing:
- The detected version matches the actual installed version
- Database connection strings are correct
- Installation directory paths are valid
- All expected applications are listed
::: warning Incomplete detection If some information is missing:
- Check that all Process Studio services are properly installed
- Check database access permissions
- Consult the Troubleshooting and FAQ article :::
Manual Modification (if necessary)
If automatic detection doesn't work correctly, you can:
- Modify paths directly in text fields
- Correct connection strings
- Adjust the detected version
Step 4: Target Version Selection
This step allows you to choose which version you want to upgrade to.
Version Choice
The "Select target version" dropdown displays all available versions based on:
- The current detected version
- Patches present in the selected archive
Examples based on current version:
| Current version | Selected patch | Available target versions |
|---|---|---|
23.14 | aps.upgrade.v23.14.v23.17.7z | 23.15, 23.16, 23.17 |
21.25 | aps.upgrade.v21.25.v23.0.7z | 23.0 |
19.25 | aps.upgrade.v19.25.v21.0.7z | 21.0 |
::: info Progressive upgrades AutoUpgradeTool automatically handles progressive upgrades.
Example: If you select version 23.17 while you're on 23.14, the tool will automatically apply intermediate patches:
23.14 → 23.15 → 23.16 → 23.17
Make sure all intermediate patches are available! :::
Compatibility Validation
The tool automatically checks:
- ✅ Availability of necessary patches
- ✅ Version consistency (no regression)
- ✅ Compatibility with current version
Possible errors:
| Error message | Cause | Solution |
|---|---|---|
| "Invalid version" | Incorrect version format | Check the detected version in step 3 |
| "Missing patch for upgrade X.X → Y.Y" | An intermediate patch is missing | Download the missing patch from Bastille |
Step 5: Configuration Validation
Before starting the upgrade, the tool performs a complete validation of the configuration.
Automatic Checks
| Check | Description | In case of error |
|---|---|---|
| Source version | Current version is valid and recognized | Correct the version in step 3 |
| Directory database | Connection string is valid | Check DB access rights |
| Application databases | All application databases are accessible | Check connections |
| Installation directories | Paths exist and are writable | Check permissions |
| Windows Services | Remoting and Scheduler services exist | Reinstall services if necessary |
| IIS Pools | Application pools exist in IIS | Check IIS configuration |
Error Correction
If errors are detected:
- Read error messages carefully displayed in red
- Fix the problems in previous steps
- Click "Previous" to return to earlier steps
- Rerun validation by clicking "Next"
The assistant will not allow you to continue until all errors are corrected. This prevents damage to your installation.
Pre-Launch Summary
Before clicking "Next", check one last time:
📋 Upgrade Summary
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Source version : 23.14
Target version : 23.17
Patches to apply : 3 (23.14→23.15, 23.15→23.16, 23.16→23.17)
Applications : 1 (instance APP - master)
Databases : 2 (directory + 1 application)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 6: Upgrade Application
This is the final step where AutoUpgradeTool automatically applies all necessary changes.
Upgrade Process
The tool executes the following operations in order:
Patch Extraction
10:33:49 | Debug | Extracting patch v23.14.v23.15
The .7z patch is extracted to a temporary directory.
README Consolidation
10:33:52 | Info | Consolidating READMEs (manual actions)
README files from each patch are merged to create an HTML document with all manual actions to perform.
Service Shutdown
10:33:53 | Info | Stopping application pool 'AppOraclePoolRoot'
10:33:53 | Info | Stopping application pool 'APPOracle_Pool'
10:33:53 | Info | Stopping application pool 'APP_Pool'
10:33:53 | Info | Stopping application pool 'APP-api-installer'
10:33:54 | Info | Stopping services
All IIS pools and Windows services are properly stopped.
File Updates
10:34:01 | Info | Applying file patch
New binaries are copied to installation directories.
Database Updates
10:34:15 | Info | Executing SQL scripts on directory database
10:34:32 | Info | Executing SQL scripts on application database
Upgrade SQL scripts are executed on all databases.
Service Restart
10:35:10 | Info | Restarting services
10:35:11 | Info | Starting application pool 'APP_Pool'
All services are restarted in the correct order.
Real-Time Monitoring
During execution:
- Progress bar: Shows overall progress
- Log console: Displays all ongoing operations
- Color coding:
- 🟦 Info: Normal information
- 🟨 Warn: Warnings (non-blocking)
- 🟥 Error: Blocking errors
"Open Logs" Button
At the bottom left, the "Open logs" button provides access to the complete log file at any time, even during execution.
Log file:
C:\Program Files\Avanteam\APP\.autoupgrade\logs\
upgrade_2024-12-30_10-33-49.log
Error Handling During Execution
If an error occurs:
Non-Critical Error (Warning)
The tool continues but alerts you:
10:34:05 | Warn | File X could not be deleted (used by another process)
➡️ Note the warning and check manually after the upgrade
Critical Error (Error)
The tool stops and offers several options:
| Option | Description | When to use |
|---|---|---|
| Retry | Attempts the failed operation again | If it was a temporary issue (network, locked DB) |
| Ignore | Proceeds to next step | If you'll handle this problem manually |
| Abort | Stops the upgrade | If the error is blocking |
::: danger Interrupted upgrade If you choose "Abort", your instance will be in an intermediate state.
Actions to perform:
- Check logs to identify the problem
- Fix the error manually
- Rerun AutoUpgradeTool which will resume where it left off
- OR restore your backup and start over :::
Finalization and Post-Upgrade Actions
Upgrade Completed
When all steps are completed successfully, a confirmation message appears:
✅ Upgrade completed successfully!
Final version: 23.17
Total duration: 15 minutes 32 seconds
README File for Manual Actions
::: warning Manual actions required Some operations cannot be automated and must be performed manually after the upgrade. :::
AutoUpgradeTool generates a README.html file listing all manual actions:
Location:
C:\Program Files\Avanteam\APP\.autoupgrade\readme\
readme_2024-12-30_10-33-49.html
How to access:
- Click the "Open manual actions" button in the interface
- OR navigate manually to the file
Example content:
## Actions to perform immediately
1. **Clear browser cache** for all users
2. **Restart IIS** completely:
iisreset /restart
3. **Test connection** to Process Studio Web
4. **Check Scheduler logs** for potential errors
## Actions to perform before next use
1. **Recompile processes** using new features
2. **Update connectors** if necessary
Post-Upgrade Checks
After the upgrade, perform these checks:
Windows Services
Get-Service | Where-Object {$_.DisplayName -like "*PStudio*"}
IIS Pools
Open the IIS Manager and verify that all Process Studio pools are started (green icon).
Process Studio Web Connection
- Open a browser
- Navigate to your Process Studio instance URL
- Log in with an administrator account
- Check the version displayed in About
Application Logs
Check Process Studio logs for potential errors:
C:\Program Files\Avanteam\APP\PStudio.Services\Logs\
C:\Program Files\Avanteam\APP\PStudio.Net.Web\Logs\
Rollback Case (Rollback)
If the upgrade causes problems and you need to roll back:
Method 1: Restore from Backup
-- 1. Stop all Process Studio services
-- 2. Restore databases
RESTORE DATABASE [APS_Directory]
FROM DISK = 'C:\Backups\APS_Directory_YYYYMMDD.bak'
WITH REPLACE;
-- 3. Restore files from backup
-- 4. Restart services
Method 2: Uninstall and Reinstall
If you don't have a backup (⚠️ not recommended), contact Avanteam support.
Multiple Upgrades (Progressive)
To go from an old version to a recent version, you may need to perform several successive upgrades.
Examples of Progressive Upgrades
Example 1: 23.10 → 23.17
Option A: Automatic with cumulative patch
If you have a cumulative patch aps.upgrade.v23.10.v23.17.7z, AutoUpgradeTool automatically handles all intermediate steps.
Option B: Manual in multiple passes If you have individual patches:
Pass 1: 23.10 → 23.12 (patch v23.10.v23.12.7z)
Pass 2: 23.12 → 23.14 (patch v23.12.v23.14.7z)
Pass 3: 23.14 → 23.17 (patch v23.14.v23.17.7z)
Example 2: 21.25 → 26.0
For a major upgrade across multiple versions:
Pass 1: 21.25 → 23.0 (major patch v21.25.v23.0.7z)
Pass 2: 23.0 → 23.18 (cumulative patch v23.0.v23.18.7z)
Pass 3: 23.18 → 26.0 (major patch v23.18.v26.0.7z)
Prefer cumulative patches available on the Bastille server for upgrades across multiple minor versions.
Check the directory S:\3-PRODUIT\ReleaseUpgrades\Patches\ to identify available patches.
End-of-Upgrade Checklist
Before considering the upgrade complete:
- All logs are green (no critical errors)
- The README file for manual actions has been consulted and actions performed
- All Process Studio Windows services are started
- All Process Studio IIS pools are started
- Connection to Process Studio Web works
- The version displayed in "About" is correct
- Application logs contain no errors
- A process creation/modification test works
- Users can reconnect
Next Steps
Now that you've mastered using AutoUpgradeTool, discover best practices:
➡️ Use Cases and Best Practices
Additional Resources
- 📖 Introduction to AutoUpgradeTool
- 🛠️ Installation and Configuration
- ❓ Troubleshooting and FAQ
- 📁 Bastille server:
S:\3-PRODUIT\ReleaseUpgrades\