afFolioFileSyncExt

Enable development processes with GIT and other Source Code Management (SCM) tools.

Git (like any other superior Source Control Management (SCM) system), needs to synchronise and version files on the file system.

This is a problem for SkySpark developers working in Axon, because Axon functions are held in the Folio database and not on the file system!

This is where Folio File Sync comes in!

Contents

• Features
• All our software works together!
• Usage - Git
• Usage - Folio File Sync
  • Sync'ing from Folio to Files
  • Sync'ing from Files to Folio
• Settings
• Licensing
  • Evaluation mode
• Disclaimer
• Special mentions

Features

This extension provides two-way synchronisation from Folio records in SkySpark, to .trio files on the file system; enabling developers to utilise GIT with Axon functions, Apps, Views, Defs, Rules, and other Folio records.

Folio File Sync enables GIT and Source Code Management development processes to be used with SkySpark.

Folio File Sync features:

• Sync Folio records to .trio files
• Sync .trio files to Folio records
• Customise directories and file naming conventions
• Import / export settings for easy configuration
• Ready-made Axon functions for scripting synchronisations

Folio File Sync is FREE to download and evaluate for ONE SkySpark project.

We were inspired to create this extension after writing our featured Fantom Factory article:

How To := Axon + Git

Note: This extension has been developed for SkySpark v3.1.3 or later.

All our software works together!

Folio File Sync works hand in hand with the rest of Fantom Factory's software range, such as:

Use it with Easy Conn to work on team Axon functions for developing SkySpark Connectors.

Use it with Pod Builder to package up your new Axon connector or SkySpark rules.

Use it with Axon Encryptor to protect your Axon source code.

Usage - Git

After installing Folio File Sync, every time you create, change, or delete an Axon function to Folio, the changes will be automatically saved to a .trio file on the file system.

These files can then be committed to Git (or another SCM) in the usual fashion.

Conversely, if Git updates the file system, these changes can be synchronised through to Folio.

Thus enabling a true development workflow when working with SkySpark.

Usage - Folio File Sync

Upon initial install, Folio File Sync is configured with a suite of defaults.

These defaults should be either updated, or overridden by importing a settings file from a colleague.

By default, Folio File Sync will:

• save .trio files to the SkySpark project's io/afFolioFileSync/ directory.
• only sync Folio records with the afFolioFileSync tag.

This is so everyone has access to view the synced files, and an initial sync will only save very specific records - and not every func, view, and def record!

It is anticipated that the top level directory will be manually updated to somewhere more convenient / easily accessible, and the afFolioFileSync tag be either removed or replaced in the Settings View.

Note that the Folio File Sync "Settings" View and all related Axon functions are accessible to su users only.

Syncing from Folio to Files

Syncing occurs automatically as records are edited and committed.

• Creating a new record creates a new .trio file.
• Updating a record updates the .trio file.
• Deleting a record deletes the .trio file.

Only records that match a sync subscription (see Settings) are synced to the file system.

Syncing from Files to Folio

Syncing is manual, triggered by clicking the "Sync to Folio" button in the Settings View.

• Creating a new .trio file creates a new Folio record.
• Updating a .trio file updates the Folio record with the same id.
• Deleting a .trio file does NOT delete any Folio records.

Note that Folio IDs are deemed globally unique enough to avoid clashes between different SkySpark instances.

New .trio files MUST contain a afFolioFileSyncRec tag for it to be synced to Folio, but this tag is NOT committed to Folio. This allows non Folio File Sync .trio files to co-exist in the same directory structure.

Settings

Folio File Sync uses Haxall Observables to be notified of changes to the Folio database. It then saves these changes as a record in a .trio file.

This means that synchronising Folio records to the file system is automatic. For example, as soon as you save an Axon function in the Code App, it is automatically saved to the file system in its own .trio file.

To configure which records are to be saved, and where, visit the "Folio File Sync View" in the "Settings App".

Each row in the table defines a set of records to be observed / synchronised from Folio; a Haxall subscription. A row describes a filter of Folio records, a subdirectory they are to be saved in, and macro to generate the file name with.

File name macros are similar to SkySpark navName tags and other disMacros. See the Axon macro() function for details.

Note that if multiple filters overlap, then multiple files will be created from a single record. Conversely, if multiple subscriptions resolve to the same file name then one will overwrite the other.

The top-level directory, under which all .trio files are saved, is typically set in the general "Settings" dialogue. The directory may be located anywhere on the file system, and is not limited to the SkySpark project's io/ directory (unlike most Axon applications!).

If a new source has been pulled by Git, the "Sync to Folio" button may be used to copy the new changes from the file system, back into Folio.

The list of observables and related settings, may be imported and exported from the general "Settings" dialogue. This allows project configurations to be easily copy / pasted between developers and their SkySpark instances.

Licensing

Folio File Sync is a commercial product and requires a licence to be purchased to run in its entirety.

Licences for Folio File Sync are tied to a SkySpark installation / host ID. This means to use Folio File Sync on multiple SkySpark installations will require multiple licences; one per installation. Be sure to enter your SkySpark licence ID when purchasing, see Where is my SkyArc Installation ID? for details.

Purchased licences are available from the My Licences page on StackHub and should be downloaded to the /var/lic/ directory of your SkySpark installation.

Minor updates to Folio File Sync may be provided free of charge, but major updates will require a new licence to be purchased.

The End-User License Agreement ("EULA") is contained with the downloaded .pod file.

For support and comments, please email -------------------------.

Evaluation mode

If Folio File Sync does not find a valid licence, it enters into an evaluation mode whereby it is valid for use in ONE SkySpark project. Attempts to use Folio File Sync in evaluation mode in more that one project will result in a licence fault.

Evaluation mode is designed for developers to try out various features of Folio File Sync to assess its suitability for purpose.

Disclaimer

The software is provided "AS IS" and the author disclaims all warranties with regard to this software including all implied warranties of merchantability and fitness. In no event shall the author be liable for any special, direct, indirect, or consequential damages or any damages whatsoever resulting from loss of use, data or profits, whether in an action of contract, negligence or other tortious action, arising out of or in connection with the use or performance of this software.

Special mentions

Special thanks go to Henry Chatwin of our very own Fantom Factory Tech Team for putting in the time, effort, and quality code required to produce this SkySpark extension.