Overview

In Workflows, node properties are always created in code (typically in the node's init() function via addProperty(), addEncryptedProperty(), etc.).

The purpose of the node defaults XML file is to define the default values used by the Node Preferences / Node Defaults system. These values are typically applied when a new instance of the node is created, allowing users to customize defaults globally without modifying the Python node implementation.

File locations and naming

Node defaults are stored as one XML file per node.

Typical locations:

SGO AppData/shared/users/nodeId.xml
Some installations may store user-specific preferences under a subfolder such as: SGO AppData/shared/users/<UserName>/nodeId.xml

Naming rules:

The file base name is usually the node id (lowercase and without spaces), for example: asperain.xml, amberscript.xml.
Inside the file, the node element name usually matches the node class name (often CamelCase / PascalCase), for example: <AsperaIn>, <Amberscript>.

If the node defaults XML file is missing, Workflows falls back to the defaults defined in code, and the node may not appear in Node Preferences as configurable defaults.

Minimal file structure

A node defaults XML file typically uses this structure:

<?xml version="1.0" encoding="UTF-8"?>
<nodeCommonRoot>
  <MyNodeClassName>
    <objectName>MyNodeClassName</objectName>
    <color>#005a50</color>
    <someProperty>defaultValue</someProperty>
    <anotherProperty/>
  </MyNodeClassName>
</nodeCommonRoot>

Notes:

nodeCommonRoot is the standard root for node defaults.
The child element (MyNodeClassName) identifies the node.
Each property is stored as an XML element whose tag name matches the property id defined in code (for example, addProperty("someProperty")).

How XML maps to properties

Property id matching

Each element name inside the node section maps to a property id created by the node code. For example, if the node code creates:

self.addProperty("language", "en")

self.addEncryptedProperty("pwd")

then the defaults file may contain:

Optional grouping elements

Some nodes group properties using nested XML elements (often mirroring the nested categories used in the node XSD schema). For example:

<Config>
  <apiKey/>
</Config>

In this case, Config is a grouping element and apiKey is the actual property id. Grouping elements are used for organization and do not change the property id; the property id is still the leaf element name (apiKey).

Important:

Avoid using the same property id in multiple groups (leaf tag names should remain unique).
Grouping is optional: for simple nodes you can place all properties directly under the node element.

Value formats (common cases)

The value is stored as the text content of the element.

Empty / unset values

Empty values are typically represented as either:

or:

Both mean an empty string.

Booleans

Booleans are typically stored as true or false:

<bypassEnabled>false</bypassEnabled>

<nodeLocked>false</nodeLocked>

Numbers

Integer/float properties are stored using their textual numeric representation:

List-like properties

Many list-like properties are stored as a single string (for example, comma-separated values):

The exact separator and parsing rules depend on the node implementation.

Paths and Universal Paths

Path-like properties are typically stored as plain strings:

<localFilePath>C:/Temp/input.mov</localFilePath>

<remoteFilePath>ascp://demo.asperasoft.com/Upload</remoteFilePath>

If a property represents a Universal Path, it is still commonly stored as a string. The node code determines how the string is interpreted (local path, URL, protocol path, etc.).

Encrypted properties

Properties created with addEncryptedProperty() are stored encrypted and are not shown in clear text in the UI (they are typically displayed as a masked/password field).

In the defaults XML, the value is stored as an encrypted string:

<pwd>AwXuliKmoo85evIH4nZ/mVCVUTfoJLkADyzmtCPMTzv5lXl9ePFxzMP2n7He</pwd>

Recommendations:

Avoid manually editing encrypted values. Prefer using the GUI to set them.
Leaving the element empty (<pwd/>) is often safer than pasting unknown encrypted strings.

Multiline text and XML escaping

Properties may contain multiline text. The XML stores the literal newline characters.

If the text contains reserved XML characters such as < or >, they must be escaped as XML entities (<, >, &).

Example (a text field that includes embedded template code):

<body>Put Your Text Here
&amp;lt;?py
print("Hello")
?&amp;gt;</body>

Note:

Workflows typically writes the correct escaping when saving defaults from the GUI.
If you hand-edit the XML, ensure it remains valid UTF-8 XML.

Precedence and lifecycle

A typical precedence model is:

1) The node code defines an initial/default value when creating the property. 2) If a node defaults XML entry exists for that property, Workflows uses it as the default for new node instances and for Node Preferences display.

If you remove a property from the node code, it may remain present in the defaults XML. Such stale entries are harmless but may confuse users; clean them up when you deprecate properties.

Troubleshooting

If a node does not appear in Node Preferences, or defaults do not apply:

Verify the node has a corresponding defaults file under the expected users/ folder.
Verify the XML file name matches the node id used by Workflows.
Verify the node element name inside the XML matches the node class name (as used by the schema).
Verify the property tags match property ids created by the node code (exact spelling).
Ensure the XML is valid and encoded in UTF-8.