Copy Fields Between Work Items

Copy Fields Between Work Items is a configurable Visual Workflow action that moves selected data from one work item to another without requiring workflow authors to build a chain of custom HTTP calls.

It is designed for practical workflow automation scenarios where a new item is spawned, an existing item is synchronised, or staged forms on the same item need to share data. In one action, authors can copy:

• FormBuilder-style work-item attributes
• Core work-item fields such as title, description, reference, category, and priority
• Aspect data paths using a safe read-merge-write approach

Why it matters

Workflow authors often need to carry forward important context from an intake, enquiry, parent matter, or source record into a destination record. Historically, that could mean several separate nodes: one for attributes, another for title or reference, and another custom integration step for aspect data.

This action consolidates that work into one mapped step. Authors choose the source and destination work-item identifiers, define the fields to copy, and let the action route each mapping to the correct Sharedo public API.

Business benefits

• Fewer workflow nodes — replace multiple update steps with one configurable copy action.
• Clearer workflow design — mappings are visible in the action designer instead of hidden in custom script.
• Safer data movement — strict and lenient modes let teams decide whether missing source data should stop the workflow or be skipped.
• Better authoring experience — Mapping Studio and work-type pickers help authors find and map fields visually.
• Flexible transformation — simple transforms and Excel-style expressions support common formatting and composition needs.
• Public API alignment — the action uses Sharedo public work-item endpoints rather than private tenant-specific hooks.

Typical use cases

Intake to instruction

Copy intake data from a source work item into a newly created destination work item. For example:

• Caller name and contact details as attributes
• Destination title from a mapped scope field
• Priority or summary into aspect data

Parent to child work item

When a child item is created from a parent, copy selected values such as reference, category, priority, and structured case overview fields.

Same-work-item form prefill

Use the same work-item id as both source and destination to copy values between forms or stages on the same work item.

Computed references and titles

Use expressions to build values such as:

• A destination reference based on the source reference
• A title composed from multiple source fields
• A cleaned or formatted description

What can be copied

Mappings are routed by the destination key:

Bare destination keys are treated as attributes for backwards compatibility.

Transform and expression support

Single-source mappings can apply common transforms:

• Trim whitespace
• Uppercase
• Lowercase
• Date only
• Null if empty

Expression mappings can combine values using a small Excel-style language. Examples include:

• concat({firstName}, " ", {lastName})
• uppercase({matterCode})
• default({preferredName}, {firstName})
• format-date({createdOn}, "YYYY-MM-DD")
• concat({core:reference}, "-SOW")

Expressions can reference attributes, core fields, and aspect paths.

Operating modes

Strict mode

Strict mode is the default. If a required single-source mapping is missing from the source item, the action routes to failed and does not write partial data.

Use strict mode when copied data is mandatory for downstream workflow steps.

Lenient mode

Lenient mode skips missing single-source mappings, writes the remaining values, and routes to partial when anything was skipped.

Use lenient mode when source data is optional or tenant forms vary by scenario.

Outputs

The action provides three workflow outlets:

• success — all requested mappings were copied and all writes succeeded
• partial — lenient mode skipped one or more missing source fields, but remaining writes succeeded
• failed — required data was missing in strict mode, or a read/write API call failed

Important limitations

• Auto-map applies to attributes only; it does not automatically copy core fields or aspect data.
• Single-source mappings read from source attributes only. Use expression mode for source core or aspect references.
• Complex values such as option sets, ODS entities, participants, rich text, or multi-select values may copy verbatim. Authors should verify that the destination field accepts the same shape.
• Core work-item writes are limited to the public API field whitelist supported by the platform.
• Aspect writes use read-merge-write to preserve sibling fields, but tenant-specific aspect handlers should still be tested.

Technical notes

Component identity

• System name: AltCopyFieldsBetweenWorkTypes
• Designer widget: Alt.CopyFieldsBetweenWorkTypesDesigner
• Kind: Visual Workflow action
• Category: Alterspective
• Icon: fa-copy
• Source path: src/vw-actions/copy-fields-between-work-types
• Foundry-backed: No
• Runtime dependency style: Native TypeScript action template using Sharedo workflow runtime globals and public HTTP APIs

Runtime purpose

The action copies mapped values from a source work item to a destination work item. Version 1.6 expands the original attribute-copy behaviour into multi-category routing:

• Attributes via /attributes
• Core work-item fields via workItem body
• Aspect data via aspectData body

Routing is determined per mapping from the destination key prefix.

Public APIs used

The template uses public Sharedo work-item endpoints:

• GET /api/v1/public/workItem/{sourceId}/attributes
• GET /api/v1/public/workItem/{sourceId} when expressions reference source core: or aspect: data
• GET /api/v1/public/workItem/{destinationId} when aspect writes require read-merge-write
• PUT /api/v1/public/workItem/{destinationId} for core fields and aspect data
• POST /api/v1/public/workItem/{destinationId}/attributes for attribute writes

Writes are sequential. Core/aspect PUT is performed before attribute POST.

If the core/aspect write succeeds but the later attribute write fails, the destination may be partially updated; the failure log explicitly notes this.

Configuration shape

The persisted step config is represented by StepConfig:

interface StepConfig {
  sourceWorkItemIdVariable: string;
  destinationWorkItemIdVariable: string;
  sourceWorkType: string;
  destinationWorkType: string;
  fieldMap: FieldMapEntry[];
  mode: "strict" | "lenient";
  autoMap: boolean;
  ignorePrefixes: string[];
}

sourceWorkType and destinationWorkType are design-time hints only. Runtime reads and writes by work-item id.

Field mapping model

Each mapping has a destination and either a source key or expression:

interface FieldMapEntry {
  destination: string;
  source?: string;
  transform?: "trim" | "uppercase" | "lowercase" | "dateOnly" | "nullIfEmpty";
  expression?: string;
}

Expression mode wins when both source and expression are present.

Route classification

Implemented in route-classifier.ts.

Destination conventions:

Unknown prefixes are treated as literal attribute keys, not errors.

Core field whitelist

Only these core: fields are accepted:

• title
• titleIsUserProvided
• userTitle
• description
• categoryId
• reference
• referenceIsUserProvided
• externalReference
• priorityId

When core:title is mapped and core:titleIsUserProvided is not explicitly supplied, the mapper injects titleIsUserProvided: true.

When core:reference is mapped and core:referenceIsUserProvided is not explicitly supplied, the mapper injects referenceIsUserProvided: true.

Aspect write behaviour

Aspect writes are handled as path patches:

1. Classify destinations such as aspect:case-overview.summary.
2. Read existing destination work item when aspect patches exist.
3. Clone existing aspectData.
4. Apply patches using setNested.
5. PUT merged aspectData.

Utilities live in aspect-merge.ts:

• getNested
• setNested
• deepMerge
• applyPatches

Arrays are replaced, not concatenated or element-merged. undefined is treated as no-op in deep merge; null explicitly clears.

Mapper flow

Implemented in mapper.ts.

High-level flow:

1. Build explicit pairs from fieldMap.
2. If autoMap is enabled, append same-name attribute pairs for source attributes not ignored and not already covered by explicit single-source entries.
3. Resolve source values.
4. Apply transforms.
5. Partition into:

• toWrite
• skipped
• missing
• warnings

1. Bucket toWrite by route:

• attributes
• coreFields
• aspectPatches
• unroutable

Strict mode fails before writing if any single-source mapping is missing. Lenient mode skips missing single-source mappings.

Expression mappings do not fail just because an internal field reference resolves empty. Parse, arity, or unknown-function errors are treated as missing-source failures.

Expression language

Implemented in expression-evaluator.ts and expression-functions.ts.

The evaluator is a small recursive-descent parser and does not use eval or Function.

Supported atoms:

• String literals: "text"
• Integer literals: 123, -1
• Field references: {firstName}, {core:title}, {aspect:case-overview.summary}
• Function calls

Built-in functions:

• concat(...)
• uppercase(value)
• lowercase(value)
• trim(value)
• default(...)
• format-date(value, format?)
• substring(value, start, end?)
• replace(value, find, replacement)

Expression source references support the same prefixes as destinations:

The template analyses expressions before runtime reads. It only fetches the source work item when an expression references core: or aspect:.

Designer

The designer consists of:

• factory.ts — creates Knockout observables, validation, outlets, and selector models
• designer.ts — designer widget behaviour and blade integration
• templates/CopyFieldsBetweenWorkTypesDesigner.html — node properties UI
• work-type-picker-component.ts — custom work-type picker component
• Mapping Studio integration via Alt.Widgets.VW.MappingStudio

Designer features include:

• Source and destination work-item id variable selectors
• Source and destination work-type pickers
• Data Composer deep links for selected work types
• Manual mapping table
• Mapping Studio launch
• Strict/lenient mode controls
• Auto-map and ignored-prefix configuration
• Three outlets: success, partial, failed

The custom work-type picker loads /api/sharedoTypes/tree once per page and provides list search, tree browsing, abstract-type toggle, selected-state display, and keyboard navigation.

Validation

Factory-level validation requires:

• Source work-item id variable
• Destination work-item id variable

Mapping rows with empty destination are filtered out on save. Rows must have either:

• destination + source, or
• destination + expression

Logging and failure behaviour

The runtime logs:

• Source and destination variable names and resolved ids
• Mode, auto-map setting, mapping counts, ignored prefixes
• Source attribute read count
• Multi-source expression read activity
• Mapping resolution counts
• Structured-value warnings
• Write buckets
• Unroutable mappings
• Skipped lenient mappings
• Completion outlet and duration

Failure routes to the failed outlet when connected. If no failed outlet is connected, the template throws an error so the workflow engine can handle it.

Test coverage

Behaviour is covered by unit tests for:

• Aspect merge utilities
• Composer path extraction
• Expression parser/evaluator
• Expression functions
• Mapper behaviour
• Source/destination GraphBrowser pick pairing
• Route classification

The pure logic is intentionally separated from Sharedo runtime globals for testability.

Known technical limitations

• Auto-map only copies source attributes.
• Single-source mapping mode only reads source attributes; source core/aspect values require expression mode.
• Complex typed values are copied as returned by the source API and may require destination-specific verification.
• Unknown destination prefixes are treated as literal attribute names.
• Core field support depends on the platform public PUT contract.
• Aspect writes preserve existing sibling data, but aspect handlers with strict validation can still reject a merged payload.

How it's built

Git is the single source of truth — the component lives at src/vw-actions/copy-fields-between-work-types. Deployment is to the Sharedo IDE; the manifest defines how the platform loads it.

User guide

When to use this action

Use Copy Fields Between Work Items when a workflow needs to copy selected data from one work item to another.

Common examples:

• Copy intake fields into a newly created item.
• Copy parent item details into a child item.
• Copy values between forms on the same work item.
• Set a destination title, reference, priority, or aspect field from source data.
• Build a computed destination value from several source fields.

Before you start

Create or identify two workflow variables of type Work Item Identifier:

1. A variable containing the source work-item id.

2.

How to use it

In the Visual Workflow editor, find Copy Fields Between Work Items in the toolbox under the Alterspective category and drag it onto a step. Configure its inputs/outlets in the node's designer panel.

For the authoritative configuration fields and behaviour, see the component's designer help panel and the source linked in the footer.