Installing and upgrading
Backups
Security
User management
Advanced user group options
Customising ResourceSpace
Plugins
StaticSync
Configuring ResourceSpace
Integrations

StaticSync - keep your files in situ

 

StaticSync is intended for the case where there is an operational reason why you still need your existing resources to remain in a standard folder structure.

Via the ingest mode it is also an alternative import mechanism, sometimes referred to as hot folders.

It is not intended as a way to store resources externally in order to increase your storage capability. This should be done by mapping drive(s) to the filestore folder at an operating system level.

Files that are deleted from the filestore will be archived within ResourceSpace rather than deleted so that metadata is not lost. This process is not reversed when the file is replaced - instead a new resource is created.

Staticsync.php should be configured as a nightly cron job and is designed to run from the command line rather than via the web/apache (e.g. 'php pages/tools/staticsync.php').

Resource types are automatically selected based on the file's extension.

When using StaticSync as an import mechanism via the ingest option the file is moved into ResourceSpace's own filestore, just as if the file had been uploaded directly to ResourceSpace. Furthermore, metadata can be extracted from the file's path via multiple path/metadata mappings to assist with metadata entry. In other words different parts of the tree structure can map to metadata fields so that project codes and similar metadata can be determined automatically without the uploading user needing to edit resources manually via ResourceSpace.

Configuration options

StaticSync is configured via include/config.php. All settings are described in include/config.default.php.

  • $syncdir - The synchronised folder.
  • $staticsync_userref - User ID to use for StaticSync actions
  • $nogo - Folders that must be avoided when synchronising. Each folder name is enclosed in square brackets e.g. "[IgnoredFolderA][IgnoredFolderB]".
  • $staticsync_whitelist_folders - Allow the system to specify the exact folder paths under the $syncdir that need to be synced/ ingested in ResourceSpace. When using $staticsync_whitelist_folders and $nogo configs together, ResourceSpace is going to first check the folder is in the $staticsync_whitelist_folders folders and then look in the $nogo folders. See an example of how the configuration for it would look like:
$syncdir = '/var/Projects';
$staticsync_whitelist_folders = array(
    'projectA/documentation',
    'projectB/events',
    'templates'
);
  • $staticsync_autotheme - Should themes automatically be created based on the folder structure? The first level will become the theme category and the second level will become the theme (collection) name.
  • $resource_type_extension_mapping_default - The resource type will be determined from the file's extension. For file extensions that have no configured mapping, this value determines the resource type ID that will be used. The resource type ID can be found by clicking on the resource type in System Setup. If the system has already been configured with $staticsync_extension_mapping_default, then this will take precedence instead.
  • $resource_type_extension_mapping - configures a mapping between a resource type and a series of file extensions used to automatically determine the correct resource type. If the system has already been configured with $staticsync_extension_mapping, then this will take precedence instead. You will need one instance of this line for every resource type. The format is:
resource_type_extension_mapping[resource type ID]=array("extension 1","extension 2");
  • $staticsync_title_includes_path - The title automatically contains the filename. If this option is set to yes, the title will also contain the path to that file.
  • $staticsync_ingest - if set to 'yes' then the files discovered by StaticSync will be moved to ResourceSpace's own filestore folder. In other words StaticSync becomes another import method.
  • $staticsync_ingest_force - Force ingest of existing files into filestore if switching from $staticsync_ingest=false to $staticsync_ingest=true;
  • $autorotate_no_ingest - Try to rotate images automatically when not ingesting resources? If set to TRUE you must also set $imagemagick_preserve_profiles=true;
  • $autorotate_ingest - Try to rotate images automatically when ingesting resources? If set to TRUE you must also set $imagemagick_preserve_profiles=true;
  • $staticsync_defaultstate - The default workflow state for imported files (-2 = pending submission, -1 = pending review, etc.)
  • $staticsync_deleted_state - Archive state to set for resources where ResourceSpace discovers that files have been deleted/moved from syncdir (when $staticsync_ingest=false;)
  • staticsync_revive_state - Related to $staticsync_deleted_state. If this is set then deleted items that later reappear will be moved to this archive state
  • $staticsync_ignore_deletion_states - Optional array of archive states for which missing files will be ignored and not marked as deleted
  • $staticsync_max_files - Maximum number of files to process in each run of staticsync
  • $staticsync_file_minimum_age - Optionally set this to ignore files that aren't at least this many seconds old
  • $staticsync_prefer_embedded_title - TRUE by default. If this is set to false then the system will always synthesize a title from the filename and path, even if an embedded title is found in the file. If true, the embedded title will be used.
  • $staticsync_allow_syncdir_deletion -Do we allow deletion of files located in $syncdir through the UI? Only relevant if $staticsync_ingest=false;
  • $staticsync_mapfolders - configures a mapping between part of the sync folder path and a metadata field. For example, if you added a mapping for '/projects/' and specified that the second level should be 'extracted' means that 'ABC' would be extracted as metadata into the specified field if you added a file to '/projects/ABC/'. Hence meaningful metadata can be specified by placing the resource files at suitable positions within the static folder hierarchy. You need one line for each mapping. An example mapping is as follows:
$staticsync_mapfolders[]=array
   (
   "match"=>"/projects/",
   "field"=>10,
   "level"=>2
   );

The options are as follows:

    • match - the path subsection to match in order to activate this rule. This can occur anywhere within the path. This restricts the action of the import to specific places within the sync folder structure.
    • field - the ID of the field to write the extracted metadata to
    • level - the depth of the extracted folder within the sync folder structure. For the example given above, where '/projects/' is the match string and '/projects/ABC' is a typical subfolder, specifiying level two would extract the value 'ABC'. Hence any files placed in the ABC folder would have the value ABC placed in the appropriate field automatically.

This is very flexible and with sensible folder design and multiple mappings can eliminate the need to enter metadata directly into ResourceSpace when uploading files. A user need only place the file to upload in the correct location in the tree and the appropriate metadata will be added automatically.

Additional options for alternative files

There are a number of options for adding alternative files automatically using staticsync

Option 1 - Use a subfolder with the same name as the primary resource file*

If staticsync finds a folder in the same directory matching the name of the file being processed but with this suffix appended, any files in the folder will be treated as alternative files for the given file.

For example if this option is set as below

$staticsync_alternatives_suffix="_alternatives";

...then the folder/file structure might look like this

/staticsync_folder/myfile.jpg
/staticsync_folder/myfile.jpg_alternatives/alternative1.jpg
/staticsync_folder/myfile.jpg_alternatives/alternative2.jpg
/staticsync_folder/myfile.jpg_alternatives/alternative3.jpg

Option 2 - add files in same folder with multiple defined string suffixes

With this option alternative files are located in same directory as the primary file but are identified by various defined string suffixes which determine the name used for the alternative file.

To use this set options similar to below. Any file with the same name as the primary file but with a suffix matching the array key will be created as an alternative file with the name of the value for that key

$staticsync_alt_suffixes = true;
$staticsync_alt_suffix_array =array (
   '_orig' => "Original Scan",
   '_tp' => "Title Page",
   '_cov' => "Cover",
   '_scr' => "Inscription"
    );

This would support adding alternative files as in the example below

/staticsync_folder/myfile.jpg
/staticsync_folder/myfile_scr.jpg       (alt file named 'Inscription')
/staticsync_folder/myotherfile.jpg
/staticsync_folder/myotherfile_orig.jpg (alt file named 'Original Scan')

In addition you can extend this so that multiple alternative files of each type can be created by checking for the same suffixes but with numeric value attached

Adding the following option

$numeric_alt_suffixes = 5;

This would support extra alternative files as in the example below

/staticsync_folder/myfile.jpg
/staticsync_folder/myfile_scr.jpg        (alt file named 'Inscription')
/staticsync_folder/myfile_scr2.jpg       (alt file named 'Inscription')
/staticsync_folder/myfile_scr3.jpg       (alt file named 'Inscription')
/staticsync_folder/myfile_scr4.jpg       (alt file named 'Inscription')
/staticsync_folder/myfile_scr5.jpg       (alt file named 'Inscription')
/staticsync_folder/myotherfile.jpg
/staticsync_folder/myotherfile_orig.jpg (alt file named 'Original Scan')

Note that in this example the following file would become a separate resource because it is outside the range of defined alternatives

/staticsync_folder/myfile_scr6.jpg

Option 3 - add files in same folder with a defined string suffix*

With this option alternative files are located in same directory as the primary file but identified by a defined string suffix. A more powerful option is to use $staticsync_alt_suffix_array as described above

For example if this option is set as below

#$staticsync_alternative_file_text="_alt_";

then the folder/file structure might look like this

/staticsync_folder/myfile.jpg
/staticsync_folder/myfile_alt_.jpg
/staticsync_folder/myotherfile.jpg
/staticsync_folder/myotherfile_alt_.jpg
  • Requires $staticsync_ingest to be enabled.

Troubleshooting

If you find that files with non-ASCII filenames are not being processed correctly please check your PHP locale settings. Adding a line similar to the one below in the relevant php.ini files (including for the cli versions) may fix some issues on lInux servers.

intl.default_locale = 'en_GB.UTF-8'