Reference Model Management

Reference Model Management allows teams to break large, complex projects down into manageable files while maintaining a single source of truth.

By linking project files, multiple users can collaborate on separate diagrams and models simultaneously. You can import files being actively developed by teammates as read-only assets, allowing you to build your own models in context by safely referencing external work – completely eliminating the risk of accidental modifications or overwriting.

When a shared reference model is updated, those changes can be synchronized across all dependent project files, ensuring the entire team stays perfectly aligned.

How to Import a Reference Model

1. Navigate to [File] – [Reference Model Management].
   
   
   
2. When the [Reference Model Management] dialog box appears, click the [Add] button.
   
   
   
   
3. Select your preferred Path Type (Absolute Path or Relative Path), then select the Astah project file (.asta) you wish to import.
   
   
   
4. A progress bar will appear. Once it reaches 100%, click the [Close] button.
   
   
   
5. You will be redirected back to the main [Reference Model Management] window, where you can verify that the reference model has been successfully added to the project tree.
   
   
6. The reference models are added strictly as read-only assets to preserve the integrity of the original file.
   
   
   
7. You can drag the model to diagram and connect with local models…etc. But when you attempt to modify reference models, you will be getting an alert.
   
   

Managing Updates & Hierarchical Dependencies

Real-Time Update Notifications

When you open a project file that contains out-of-date assets (e.g., a teammate has updated a referenced file), Astah will automatically alert you with a synchronization prompt.

Synchronizing Your Models

If you click [OK] to the window shown above, the [Reference Model Management] window will display your project hierarchy. Any project file names displayed in orange text indicate that the source file has been modified externally and your local project is out-of-date..

Select the specific project file name highlighted in orange and click [Update].


A confirmation dialog will appear. Click [Yes] to proceed with updating the the reference models.

If multiple projects requires synchronization, click the [Update All] button to updated all the project files.


A confirmation dialog will appear. Click [Yes] to proceed with updating the the reference models.

Updating Reference Projects via Command Line

You can trigger reference updates via .bat (Windows) or .sh (mac/Linux) scripts.

1. Smart Updates (Based on Timestamp)

Use the update-all command to scan a specified directory. Astah will look at the system file timestamps and only update .asta files that have actually been modified.
If you prefer to check project-internal metadata rather than system file timestamps, add the use-builtin-timestamp (or ubt) flag.

Windows

call astah-run.bat "astah_directory_path" update-all
e.g.
call astah-run.bat "C:\\Program Files\\astah-professional" update-all

mac/Linux

astah-run.sh "astah_directory_path" update-all
e.g.
astah-run.sh "/home/tanaka/astah-professional" update-all

• You can find “astah-run.bat” or “astah-run.sh” in Astah Installation folder.
• It exports log files as yyyyMMdd_HHmm_astah_convert_command.log in the directory.

2. Forced Batch Updates

Use the update-all-force command to completely bypass timestamp checks and force a total synchronization of every single reference model inside all .asta files within the target directory.

Windows

call astah-run.bat "asta_directory_path" update-all-force
e.g.
call astah-run.bat "C:\\Program Files\\astah-professional" update-all-force

mac/Linux

astah-run.sh "astah_directory_path" update-all-force
e.g.
astah-run.sh "/home/tanaka/astah-professional" update-all-force

How to Merge Reference Models

When a referenced subsystem’s design is finalized and you want to permanently integrate it into your master project as fully editable elements, you can merge it.

1. Navigate to [File] – [Reference Model Management].
   
   
   
2. Select the reference file you want to absorb from the hierarchy tree and click the [Clear] button.
   
   

System Preferences

You can customize system preferences for reference models by navigating to: [Tools] – [System Properties] – [Reference Model].