Ares Server Addon Details
The details on this page provide background on how Server Addons operate and integrate with other Ares components such as the Ares System Manager. These notes are for reference purposes.
Information on installing and configuring Server Addons is available on Installing and Configuring Ares Server Addons.
System Manager Information
System Manager executes Addons according to the SystemManagerAddonInterval key in the Customization Manager. Addons are retrieved from the database each time this operation runs. If the LastUpdated timestamp on an Addon is newer, it will be unpackaged, and the Addon environment for that particular Addon will stop and be restarted with the new version. Any addons that are running that no longer exist in the addons table (i.e. user deleted the addon) will have the environment stop and the package directories will be cleaned up.
The System Manager will unpackage Addons to a "ServerAddons" directory that exists in the same folder as the AresSystemManager.exe. Each time the system manager starts, the directory will be cleaned up to remove old versions and allow the current versions to be unpackaged.
Inside the ServerAddons directory, each addon will have its own directory named after the unique ID of the record found in the Addons table such as "Addon-25" where 25 is the ID of the Addon in the Addons table. During the unpackaging process, the package zip file is created based on the byte array found in the Package column of the addons table. This is then unpackaged to an "Unpackaged" subdirectory. An addon environment will be started for each Addon that gets unpackaged. Unlike the client, the system manager will only start up an Addon if it was unpackaged based on results from the Addon table; i.e. users cannot create their own subdirectories of the ServerAddons directory with addon code to allow server addons to run that are not found in the Addons table.
When a new Addon version is added or a setting is changed the LastUpdated field in the Addons table is updated to a newer time stamp. The System Manager will use this indicator to restart the Addon environment for that particular Addon. This means that you will not need to restart the System Manager when updating or changing configuration settings on active Server Addons. Other Addons will still continue to function as normal and their environments will not be restarted.
If an addon package uses an external assembly, the System Manager will not be able to update the assembly because the file will be considered in use and requires a manual restart of the System Manager. When updating an Addon that uses an external assembly, a warning will alert the user the need to restart the System Manager.
Validation
When adding a new Addon or updating an Addon in the Customization Manager, the following validations will occur:
ValidatePackage
All are considered error validations which should prevent the addon from being installed
- Package contains a config file
- Package contains script files
- Package has all script files specified in the config.xml
- Name is provided in the config.xml
- Package has a version specified
- Package contains script info (This is an internal check since the config file should be loaded into ScriptInfo)
ValidateAddonUpdate
All of the default checks used by ValidatePackage are performed on the update package
The rest of the validators are warnings which should allow the addon to be updated if the user chooses to proceed
- The new addon package should have a newer version
- The new addon package should have the same name
- Warning if a previous setting is removed in the newer addon package
- Warning if a newer external assembly is found in the newer addon package
Addons Tables
The ServerAddons table (added in version 4.6) stores the following:
| Field | Description |
|---|---|
| ID | Addon ID Number |
| Name | Name of Addon |
| Addon Type | Addon Type. Currently, the only available value is Server. |
| Active | True/False |
| Package | All components of zip files uploaded through Customization Manager. |
| Settings | Only settings changed from the default settings. |
| Last Updated | Time stamp indicating when the Addon was uploaded or last change to Addon configuration. |
The Addons table is the legacy table that stored Addon information in versions previous to 4.6 and contains the following fields. It is retained in the 4.6 update just in case the conversion process should fail and it is necessary to re-install previously installed Server Addons manually.
| Field | Description |
|---|---|
| ID | Addon or ID Number |
| Name | Name of addon |
| Configuration | XML file |
| Code | Lua file |
Addons Files on the Server
When the server addons form is loaded, the database addons are retrieved. All of the addons are unpackaged to a temp directory on the local workstation to retrieve the information in the config.xml file to be displayed in the customization manager UI. This directory is typically the %AppData%\Local\Temp\CustomizationManager\Scripting directory. This will be cleaned up and removed when the customization manager closes.
All active Addons will have a folder which is named based on the ID value of the Addon in the Server Addons table. These folders are added as part of the installation process in the Customization Manager. Each folder will contain a zip file of the uploaded package and an "Unpackaged" folder containing the each file from the zip file. Folders are unpackaged each time the System Manager starts. The files are located in this directory by default: C:\Ares\Admin\SeverAddons.
Only active Addons will appear in the folder in the C:\Ares\Admin\SeverAddons directory. Deactivated Addons will automatically be removed from the folder.
Conversion Utility
When the server is updated to version 4.6, any existing Server Addons will be processed through a conversion utility which will update them to the new configuration and add necessary values to the ServerAddons table and Customization Manager. When the Conversion Utility has run, an indicator will be added to the Addons table indicating that the Addon has been converted. Any modified settings in the existing Addon will be converted as the default settings in version 4.6.
Available Commands for Ares Server Addons
The following ExecuteCommand Options are available for Ares:
| Command | Parameters |
|---|---|
| Route | ItemId (int), Target Status (string) |
| AddNoteByType | identifier (int or string), Note Type ("User" or "Item"), Note (string) |
| AddFlag | ItemId (int), Flag (string) |
| RemoveFlag | ItemId (int), Flag (string) |
| SendItemEmail | ItemId (int), Template Name (string) |
| SendUserEmail | Username (string), Template Name (string) |