Mapping Component (sys-mappings)

The Mapping component turns script mapping code into reusable, versioned helpers. Repeated transformation/utility code (JSON serialization, crypto, formatting, etc.) is defined once and referenced from many components. Via the plugin capability it can also embed third-party libraries/DLLs (assemblies) into the script context, removing the need for separate "utility APIs" in business cases.

Schema: vnext-schema/mapping-definition.schema.json · Flow: sys-mappings

A Mapping component is consumed in two ways:

1. scripts.helpers[] — the helper class is included into the consuming component's script context and called directly (e.g. JsonHelper.Serialize(...)).
2. encoding: "REF" — a mapping object's code becomes a reference to this component instead of an inline string.

Definition JSON Example

{
  "key": "json-helper",
  "version": "1.0.0",
  "flow": "sys-mappings",
  "domain": "core",
  "flowVersion": "1.0.0",
  "tags": ["helper", "json"],
  "attributes": {
    "name": "JsonHelper",
    "location": "./src/JsonHelper.csx",
    "code": "using Newtonsoft.Json; public static class JsonHelper { public static string Serialize(object v) => JsonConvert.SerializeObject(v); }",
    "encoding": "NAT"
  }
}

Properties

attributes

Field	Type	Required	Default	Description
name	string	Yes	—	Helper/class name (e.g. JsonHelper), minLength: 1
location	string	No	—	Code file path (pattern ^\./.*\.csx$)
code	string	Yes	—	Mapping code content (may be empty when sourced from location)
encoding	string	No	B64	B64 (Base64) or NAT (native C#)

sys-mappings cannot be REF

A Mapping component's encoding may only be B64 or NAT. REF is not allowed — the sys-mappings component is itself the reference target and cannot reference itself.

Scripts: Helper References and Allowed Assemblies

Other components reference this component as a helper through the scripts object on their mapping objects (and on workflow flow-level attributes):

"scripts": {
  "helpers": [
    { "key": "json-helper", "version": "1.0.0", "domain": "core", "flow": "sys-mappings" }
  ],
  "allowedAssemblies": ["Newtonsoft.Json"]
}

Field	Type	Description
helpers	array	References to sys-mappings components (key, version, domain, flow: "sys-mappings")
allowedAssemblies	string[]	Allowed .NET assemblies for the script context (added to the sandbox allow-list)

For the allow-list and the default ban list, see Scripting / Sandbox. For a flow-wide helper/assembly, use workflow attributes.scripts.

REF Encoding

A mapping/scriptCode object can reference a sys-mappings component instead of carrying inline code. When encoding: "REF", code is a reference object:

"mapping": {
  "encoding": "REF",
  "code": { "key": "initial-mapping", "version": "1.0.0", "flow": "sys-mappings", "domain": "core" }
}

• code is a mappingRef: key, version, domain, flow: "sys-mappings".
• sys-mappings itself cannot be REF (no self-reference).
• In Forge Studio, selecting REF opens a pickup dialog listing existing sys-mappings components (select / clear / create), like other reference fields (see Forge Studio).

REF is valid in all mapping objects: transition mapping, rule, timer, viewRule, subflow mapping, task/extension/function mapping.

Example Components

Example	What it does	Allowed assembly
json-helper	JsonHelper.Serialize(...) (Newtonsoft.Json)	Newtonsoft.Json
rsa-crypto	RsaCryptoHelper.Encrypt/Decrypt (RSA OAEP-SHA256)	System.Security.Cryptography
initial-mapping	ITransitionMapping start transition input mapping (REF target)	—

Component Tree and Configuration

Mapping components live under the domain's Mappings/ folder; vnext.config.json adds mappings to paths and exports.

Related

• Mapping Guide — inline mapping, ScriptContext, ScriptBase
• Interfaces — IMapping, ITransitionMapping, IOutputHandler
• Scripting / Sandbox — allowedAssemblies, sandbox, ban list
• Schema source: vnext-schema (GitHub)