Skip to main content
Version: Current (v17+)

Handlers

In uSync, a Handler manages the reading and writing of the uSync settings from the folder of the Umbraco installation.

Handlers don't do the actual importing or exporting of items, that work is done by the Serializers.

Handler Groups​

Handlers are enabled in the default group by default. Generally you do not need to add handlers individually to the config:

The most common action is to turn content on or off. This can be done with the ExportAtSave option, see our guide on turning off content edition.

Disable Individual Handlers​

If you want to turn individual handlers off you can add them to the list of disabled handlers.

"uSync" : {
    "Sets" :{
        "Default" : {
            "DisabledHandlers" : ["DictionaryHandler"]
        }
    }
}

Handler Sets

A handler set defines the behaviour of a group of handlers. uSync and the uSync dashboard already use a set called 'default' automatically. You can create your own sets, but you will need to build it in code.

Enabled​

Is this handler set enabled?

HandlerGroups​

List of groups handlers can belong to.

DisabledHandlers​

List of disabled handlers.

IsSelectable​

Is this handler selectable? For handlers to appear in the drop down on the dashboard, they have to be selectable.

Handler Defaults​

All handlers have their own settings, which you can set individually (see below). You can set default settings for all the handlers in the config.

"uSync": {
    "Sets" : {
        "Default" : {
            "HandlerDefaults" :{
                "Enabled": true,
                "Actions": "All", 
                "UseFlatStructure": true,
                "FailOnMissingParent": false,
                "Group": "",
                "Settings": {
                    // handler specific settings go here
                }
            }
        }
    }
}

Enabled​

Turns a handler on or off.

Actions​

What actions the handlers will work for.

UseFlatStructure​

Saves the files in a single folder or use a folder structure to represent the layout in Umbraco.

GuidNames​

Items should be saved with their guid/key value as the filename.

FailOnMissingParent​

If set to true the import will fail if the parent item cannot be found. If set to false the import process will attempt to find the closest possible parent item and import the item into that location.

Group​

Override the group the handler belongs to.

CreateClean​

Create a corresponding _clean file for this export. This clean file will only be created if the item in question has children.

Settings​

See handler specific settings below.

Handler settings​

Handler settings allow you to have more control over the behaviour of a handler. There are a number of settings all handlers share, and some that only work for certain handlers.

appsettings.json
"uSync": {
    "Sets" : {
        "Default" : {
            "HandlerDefaults" :{
                "Settings": {
                    "Content/Media" : "",
                    "CreateOnly": false, 
                    "CreateOnlyDelete": false,
                    "DataTypes" : "", 
                    "DoNotSerialize" : "", 
                    "Exclude" : "",
                    "ExcludeContentTypes" : "",
                    "ExportTrashed" : true,
                    "IgnoreAliases" : "",
                    "ImportTrashed" : true,
                    "IncludeContentTypes" : "",
                    "NoConfigEditors" : "",
                    "RulesOnExport" : false,
                }
            }
        }
    }
}

CreateOnly​

Items are created if they do not exist, but existing items are not synced.

"Settings": {
  "CreateOnly": false, 
 }

CreateOnlyDelete​

Items are created if they do not exist, and items are deleted if they have been deleted, but existing items are not synced.

"Settings": {
  "CreateOnlyDelete": false, 
 }

IgnoreAliases​

List of aliases of items that you don't want the handler to import.

"Settings": {
  "IgnoreAliases" : "",
}

Handler Specific Settings​

Some handlers have additional settings

Content/Media​

Path to a content item include.

"Settings": {
  "Content/Media" : "", 
 }

DataTypes​

List of datatypes by name that you don't want to import the configuration for.

"Settings": {
  "DataTypes" : "", 
 }

DoNotSerialize​

Names of content/media properties not to serialize as part of a sync.
(Added uSync 9.1+ #289)

"Settings": {
  "DoNotSerialize" : "", 
 }

Exclude​

Path to a content item to exclude.

"Settings": {
  "Exclude" : "", 
 }

ExcludeContentTypes​

List of content types to exclude. When using this setting all other content types are synced and any in this list are ignored.
(Added uSync 10.3+ #419)

"Settings": {
  "ExcludeContentTypes" : "", 
 }

ExportTrashed​

Export items that are in the Trashed state.

"Settings": {
  "ExportTrashed" : true, 
 }

ImportTrashed​

Import items that are in the Trashed state.

"Settings": {
  "ImportTrashed" : true, 
 }

IncludeContentTypes​

List of content types to include. When this value is set ONLY these content types will be included in any sync.
(Added uSync 10.3+ #419)

"Settings": {
  "IncludeContentTypes" : "", 
 }

NoConfigEditors​

List of editor aliases of items you don't want the configuration to be imported for.

"Settings": {
  "NoConfigEditors" : "", 
 }

RulesOnExport​

Run the rules during an export.

"Settings": {
  "RulesOnExport" : false, 
 }

For Example...​

Handler specific settings are often set on individual handlers. For example, the configuration below would not import trashed items, and exclude any content in the the Home/Testing content tree.

appsettings.json
"uSync" :{
    "Sets": {
        "Default": {
            "Handlers": {
                "ContentHandler" : {
                    "Settings" : {
                        "ImportTrashed": false,
                        "Exclude": "Home/Testing"
                    }
                }
            }
        }
    }
}
tip

uSync.Publisher uses a diffrent content handler called PublishedContentHandler, if you want settings to apply to only that handler you need to use the different name.