Migrating from conventional project to packaged project

This document describes the steps required to migrate an existing SAMO 9 installation to SAMO 10. It covers database migration, application server updates, and configuration adjustments necessary for a successful transition.

Conventional projects (non-packaged)

The previous versions of SAMO (up to version 10+) allowed for two types of project deployments: conventional (non-packaged) and packaged projects. In conventional projects, the project files were stored in one single configuration directory and each component (like LIDS Application Server, SAMO Gateway, etc.) had their own configuration property defined by {componentName}.configuration_path (e.g. lids.configuration_path for LIDS Application Server). In SAMO 10+ the packaged project is refered to using the samo_packages_root property that points to the root directory containing all SAMO packages.

In SAMO 10, the only supported project type is the packaged project. Therefore, conventional projects need to be migrated to packaged projects during the upgrade process.

Packaged projects

Packaged projects store all project files (metadata, resources, etc.) in SAMO packages. These packages can be versioned and have basic dependency management.

Package structure

A typical SAMO packaged project follows this structure:

packages/
 ├── package-name/
 │   ├── dynamic-app/
 │   │   └── {app-name}/
 │   │       ├── configuration/
 │   │       │   ├── application/
 │   │       │   ├── metadata/
 │   │       │   └── map/
 │   │       └── resources/
 │   ├── lids-as/
 │   │   ├── business-service/
 │   │   ├── browser/
 │   │   ├── resources/
 │   │   ├── extensions/
 |   |   ├── model.xml
 |   |   └── config.xml
 │   ├── gateway/
 │   │   ├── proxies/
 │   │   ├── applications/
 |   │   ├── clients/    
 |   ├── package.json  <-- Important file defining the package
 |   └── {Other SAMO components}...
 └── package-name-2/
     ├── lids-as/ ...
     └── package.json  <-- Each package has its own package.json

package.json file

The package.json file is a manifest that describes the package, its version, dependencies, and other metadata. A typical package.json file looks like this:

{
  "name": "@samo-demo/eam",
  "version": "9.0.0",
  "configurationPackage": true,
  "dependencies": {
    "@samo/samo-base": "~11.11.0",
    "@samo-protocols/protocol-base": "8.3.0",
    "@samo-demo/lids-demo": "9.0.0"
  }
}

Here we can see that the package is named @samo-demo/eam, has version 9.0.0, and depends on other packages like @samo/samo-base and @samo-demo/lids-demo which are required for the package to load and function correctly.

Migration Steps

1. Prepare Your Environment

Before starting the migration, ensure you have:

• Backup of your existing SAMO 9 configuration directory
• SAMO 10 platform installed and ready
• Access to all configuration files

2. Create Package Structure

Create a new packages directory for your packaged project:

mkdir packages
cd packages
mkdir my-project-name
cd my-project-name

3. Migrate LIDS Application Server Configuration

Transform the conventional structure into the packaged lids-as directory:

3.1 Create LIDS-AS Directory Structure

mkdir lids-as
cd lids-as

To Packaged:

packages/my-project/lids-as/
 ├── business-service/
 ├── browser/
 ├── extensions/
 ├── resources/
 ├── ... (other necessary folders)
 ├── config.xml        
 ├── model.xml         
 ├── option.xml       
 ├── presentation.xml  
 ├── resource.xml      
 ├── thematization.xml 
 ├── tool.xml
 └── ... (other necessary XML files)        

4. Migrate Dynamic App Configuration

If your project includes Dynamic App components:

4.1 Create Dynamic App Structure

mkdir dynamic-app
cd dynamic-app
mkdir my-app-name
cd my-app-name

4.2 Migrate Dynamic App Metadata

Same as above, migrate the files into the new structure:

packages/my-project/dynamic-app/my-app-name/
 ├── configuration/
 │   ├── application/
 │   ├── metadata/
 │   │   ├── entities/
 │   │   │   ├── features/
 │   │   │   ├── codelists/
 │   │   │   └── groups/
 │   ├── map/
 │   └── ... (other necessary folders)
 └── resources/
     └── ... (resource files like icons, templates, etc.)

5. Migrate Gateway Configuration

If you are using SAMO Gateway, migrate its configuration in a similar manner:

• Application definitions → gateway/applications/
• OAuth clients → gateway/clients/
• API proxies → gateway/proxies/

packages/my-project/gateway/
 ├── applications/
 ├── clients/
 ├── proxies/
 └── ... (other necessary folders)

6. Create package.json

Create package.json with the following content:

{
  "name": "@my-organization/my-project",
  "version": "10.0.0",
  "description": "Migrated from SAMO 9 conventional project",
  "configurationPackage": true,
  "dependencies": {
    "@samo/samo-base": "~11.11.0",
    "@any-other-required-packages": "x.x.x"
  }
}

7. Update Configuration Properties

Update your SAMO 10 configuration files to use the new packaged structure:

Remove old properties:

lids.configuration_path=C:\old-path\configuration
dynamic-app.configuration_path=C:\old-path\configuration
gateway.configuration_path=C:\old-path\configuration

Add new property:

samo_packages_root=C:\samo-10\packages

8. Validation and Testing

After migration, perform thorough testing:

8.1 Validate Package Structure

Ensure all required files are in place:

• package.json exists in package root
• All necessary component directories and files are correctly migrated
• The property samo_packages_root points to the correct location
• SAMO 10 Application Server starts and successfully loads the configuration
• There is no difference in functionality compared to the previous SAMO 9 setup

9. Common Migration Issues and Solutions

Issue: Missing Dependencies

Symptom: Package fails to load with dependency errors

Solution:

• Check package.json dependencies
• Ensure all required SAMO base packages are listed and present in the samo_packages_root directory
• Verify version compatibility

Issue: Resource Files Not Found

Symptom: Icons, reports, or templates not loading

Solution:

• Verify resource paths in resource.xml
• Ensure resources are in correct lids-as/resources/ subdirectories
• Check file permissions

Issue: Custom Scripts Failing

Symptom: Business logic errors in logs

Solution:

• Review script imports and module paths
• Update any hardcoded configuration paths
• Check for API changes between SAMO 9 and 10

10. Migration Checklist

Use this checklist to track your migration progress:

Backup created for all SAMO 9 configuration

New package directory structure created

LIDS Application Server files migrated lids-as/

Core XML files (config.xml, model.xml, etc.)

Directories with resources, extensions, business services, etc. migrated

Dynamic App files migrated dynamic-app/

Gateway configuration migrated gateway/

Other SAMO components migrated (if applicable)

package.json created with correct dependencies

Configuration properties updated samo_packages_root

File paths updated in configuration files

Application server started successfully

Package loading verified in logs

Core functionality, business logic and DynamicApp tested

Performance validated

Now that your project is packaged, consider using version control:

cd packages/my-project
git init
git add .
git commit -m "Initial migration from SAMO 9 conventional project"

Package Versioning

Follow semantic versioning for your packages:

• Major version (10.x.x) - Breaking changes
• Minor version (x.1.x) - New features, backwards compatible
• Patch version (x.x.1) - Bug fixes

Modular Architecture

Consider splitting large packages into smaller, focused packages:

• Core business entities in one package
• Extensions in separate packages
• Shared resources in a common package

This improves maintainability and allows for independent versioning.

Documentation

Document your package structure:

• Create a README.md in your package
• Document custom scripts and business logic
• Maintain a changelog for version updates
• Document dependencies and their purposes