Silver Action Flow YAML Specification

This document defines the YAML format accepted and generated by ActionFlowCompiler. It describes specification version 1, the graph shape, variables, parameters, conditions, and every currently supported typed action configuration.

The YAML format is a semantic representation of an IAction graph. Runtime identifiers such as action IDs, parameter IDs, graph positions, and incoming variable metadata are generated by the compiler and are deliberately excluded from YAML.

1. Serialization rules

• Property and enum names use camelCase.
• Indentation is spaces; generated YAML uses two spaces per level.
• null values, default values, and empty collections are omitted from canonical YAML.
• An omitted property therefore normally means its documented .NET default.
• Canonical YAML uses LF line endings and ends with one newline.
• Maximum accepted YAML length is 1,000,000 characters.
• The semantic hash is the lowercase SHA-256 hash of canonical YAML.
• A node must contain exactly one configuration block matching its type.
• Collection order is meaningful except for branches and option dictionaries, which are emitted in ordinal key order.

For example, false, 0, an empty list, and an enum's first value may be absent from generated YAML even though they remain valid when written explicitly.

2. Document structure

version: 1
scope: solution
root:
  type: user
  name: Example
  description: Optional description
  outputs: []
  user: {}
  branches: {}
  next: null

scope describes ownership and portability. It does not itself alter runtime execution.

3. Action node

Every node has this common shape:

type: alert
name: ShowResult
description: Show the result to the user.
outputs:
- source: success
  alias: WasSuccessful
  type: boolean
  scope: cascaded
alert:
  message:
    value: Done
next:
  type: refresh
  name: RefreshPage
  refresh: {}
branches:
  cancel:
    type: alert
    name: Cancelled
    alert: {}

Supported typed node types are:

user, input, setVariable, if, alert, methodCaller, updateEntity, createEntityForm, refresh, and webService.

runtime is also supported as a compatibility representation for the remaining allow-listed ActionHandler action types.

3.1 Continuations and branches

next becomes IAction.Action, the normal exit. Named branches become an action-specific secondary exit:

Unsupported branch names cause compilation to fail. A missing continuation ends that path.

4. Outputs, aliases, and variable scope

outputs:
- source: result
  alias: CreatedCustomer
  type: businessEntity
  scope: cascaded

Supported output types are text, textArray, number, numberArray, data, file, oledbImage, fileCollection, dataRow, dataTable, json, jsonArray, xml, xmlArray, boolean, dateTime, html, csv, excel, word, businessEntity, businessEntityList, and businessEntityProperty.

All actions may expose common semantic sources such as name, description, success, and error when those locals exist. Important action-specific sources include:

The source must map to a real local variable on that action. Changing type does not convert the value. For example, a businessEntity source cannot be declared as oledbImage to extract an image.

4.1 Consuming an alias

Parameters can consume an output without embedding generated IDs:

value:
  alias: CreatedCustomer

During compilation the alias is resolved to the appropriate runtime variable ID or token. An alias must have been published by an earlier reachable action.

5. Silver parameter

The following reusable structure represents a SilverParameter:

name: Authorization
value: Bearer $$Secret:ApiToken$$
alias: ExistingOutput
parameterType: dynamicVariable
intValue: 10
doubleValue: 10.5
dateTimeValue: 2026-08-06T12:00:00Z

Supported parameterType values are incomingVariables, businessEntityList, sbelList, businessEntity, security, constant, basementCall, dynamicVariable, path, and entryParameter.

Do not specify both alias and a meaningful value. Use alias for generated runtime references and value for literal values or expressions.

5.1 Dynamic expressions

Dynamic values may contain placeholders:

$$Local:Result$$
$$Parameter:InvoiceId$$
$$Cascaded:CustomerId$$
$$Index:Index$$
$$Security:<name>$$
$$Roles:<name>$$
$$Env:<name>$$
$$AppEnv:<name>$$
$$Secret:<name>$$
$$System:NewGuid$$

Local, Parameter, Cascaded, and Index refer to action variables. Security and Roles use the current user/security context. Env, AppEnv, and Secret resolve configured values. System invokes a built-in expression. Secrets should always be references; never store secret values in YAML.

6. Buttons

button:
  text: Save
  icon: fas fa-save
  iconFirst: true
  iconOnly: false
  cssClass: btn btn-primary

The same structure is used by user, input, alert, confirm, and cancel buttons.

7. Conditions

A condition compares left and right. An all collection is logical AND; an any collection of groups is logical OR.

any:
- all:
  - name: IsAdministrator
    left:
      value: $$Roles:UserRole$$
    operator: contains
    right:
      value: Admin
      parameterType: constant
    dataType: text

Operators: equal, notEqual, greaterThan, greaterThanOrEqual, lessThan, lessThanOrEqual, contains, notContains, and startsWith.

Data types: text, integer, boolean, float, dateTime, date, time, guid, and oledbImage.

Both sides must be present. A parameter object with no value is still an empty value; it is not a wildcard.

8. Typed action configurations

8.1 user

User-triggered entry point exposed on a controller.

type: user
name: CreateCustomer
user:
  target: Customer
  published: true
  group: Administration
  displayLabel:
    value: Create customer
  button:
    text: Create
  visibility: always
  enabled: always
  visibleWhen:
    all: []
  enabledWhen:
    all: []
  allowBulk: false
  singleRun: true
  allowCancel: false
  cancelOnError: false
  runType: single

Method-based visibility/enabling from legacy UserAction cannot be represented by the typed converter.

8.2 input

Displays an input dialog. next is confirm; branches.cancel is discard.

input:
  label: { value: Details }
  cssClass: row
  title: { value: Create customer }
  message: { value: Enter the details. }
  confirmButton: { text: Save }
  cancelButton: { text: Cancel }
  confirmLabel: On Confirm
  cancelLabel: On Discard
  cancelOnError: false
  fields: []

Each field supports:

Input types are label, text, email, maskedText, password, integer, decimal, dateTime, checkbox, switch, file, radioButton, tags, dropdown, combobox, richText, colorPicker, colorPickerTextBox, iconPicker, and iconPickerTextBox.

Numeric settings:

Text settings:

Date settings contain dynamicMinimum, minimum, dynamicMaximum, maximum, allowEdit, and showWeekNumber.

Source settings:

File settings contain extensions, size, and multiple.

8.3 setVariable

Creates or updates typed variables.

setVariable:
  cancelOnError: false
  items:
  - type: text
    name: FullName
    input:
      value: $$Cascaded:FirstName$$ $$Cascaded:LastName$$
    update: false
    targetAlias: null
    booleanValue: null
    dateTimeInputType: incomingVariable
    operations:
    - operation: Trim
      arguments: []

Item properties:

Text operations: Replace, ToLower, ToUpper, Trim, TrimStart, TrimEnd. Number operations: RoundUp, RoundDown, Decimal. Date/time operations: AddSecond, AddMinute, AddHour, AddDay, AddMonth, AddYear, Date, Hour, Day, Week, Month, Year. Operation names are parsed case-insensitively.

8.4 if

Evaluates OR groups of AND conditions. next is true and branches.false is false.

if:
  trueLabel: "True"
  falseLabel: "False"
  any:
  - all:
    - left: { alias: Total }
      operator: greaterThan
      right: { intValue: 0, parameterType: constant }
      dataType: integer

The legacy third IfAction branch is not supported.

8.5 alert

Displays a message and then follows next.

alert:
  title: { value: Completed }
  message: { value: The operation completed. }
  confirmButton: { text: OK }

title and message are evaluated parameters. confirmButton uses the common button structure.

8.6 methodCaller

Calls a published MethodAction.

methodCaller:
  methodId: method-id
  methodName: CalculateTotal
  isActive: true
  preSetupBreakpoint: false
  postSetupBreakpoint: false
  cancelOnError: false
  requiredParameters: []
  returnParameters: []

Required parameter properties are name, type (default text), isRequired, businessEntityName, and parameter. Return parameter properties are name, type (default text), isRequired, localName, and businessEntityName.

8.7 updateEntity

Updates one business entity and follows next.

updateEntity:
  target: Customer
  identifier: { alias: CustomerId }
  parameters:
  - name: Status
    value: Active
    parameterType: constant
  suppressNotification: false
  suppressError: false
  postSetupBreakpoint: false
  cancelOnError: false

The entity result can be exported with source result.

8.8 createEntityForm

Opens a create form. next is submit and branches.cancel is cancel.

createEntityForm:
  target: Customer
  parameters: []
  upsertOnConfirm: true
  submitLabel: On Submit
  cancelLabel: On Cancel
  suppressNotification: false
  suppressError: false
  cancelOnError: false

The submitted entity can be exported with source result.

8.9 refresh

Requests a host UI refresh and follows next. It has no action-specific properties:

type: refresh
name: RefreshPage
refresh: {}

8.10 webService

Evaluates and submits an HTTP request.

webService:
  method: post
  navigation:
    value: /api/customers
    parameterType: constant
  headers:
  - name: Authorization
    value: Bearer $$Secret:ApiToken$$
  requestContentType: applicationJson
  responseContentType: applicationJson
  body:
  - name: payload
    value: '{"name":"$$Cascaded:CustomerName$$"}'
  timeoutDelay: 30
  numberOfRetryOnFail: 2
  postSetupBreakpoint: false
  cancelOnError: true

Request content types: applicationJson, applicationXml, textXml, applicationXWwwFormUrlEncoded, multipartFormData, applicationOctetStream, applicationGraphql, and applicationNdJson.

Response content types: textPlain, textHtml, textCss, textJavascript, applicationJson, applicationXml, textXml, applicationYaml, applicationGraphql, applicationOctetStream, imagePng, imageJpeg, imageGif, applicationPdf, applicationZip, videoMp4, audioMpeg, applicationJavascript, applicationVndApiJson, and applicationNdJson.

Runtime body behavior:

• get sends no body.
• post, put, and patch send a body.
• delete sends no body, although the current preprocessing path can still access the first body parameter.
• multipartFormData processes every body parameter. Incoming file/data variables become binary form parts; other parameters become text parts.
• Non-multipart requests send only the first body parameter as UTF-8 text.
• JSON remains a string inside the parameter because Silver expressions must be evaluated before the HTTP body is created.

Current response conversion is implemented for JSON/plain/XML text and for octet-stream/PNG/JPEG/GIF/PDF/ZIP bytes. Other advertised response types may produce no response value. HTTP 4xx/5xx status codes are not automatically turned into exceptions by the current handler.

Web-service outputs can use response, responseCode, exceptionMessage, and dataType.

9. Runtime compatibility nodes

Actions without a curated typed converter use:

type: runtime
name: Delay
runtime:
  actionType: DelayAction
  configurationJson: '{"Seconds":2}'

Currently allow-listed runtime types are:

EventAction, MethodAction, BackgroundAction, GetEntityAction, GetEntityListAction, GetLookupAction, UpdateEntityListAction, DeleteEntityListAction, LoadFileAction, DataParserAction, ConvertorAction, ExportAction, ToastAction, NavigationAction, DelayAction, ReloadAction, CreateEntityAction, UpdateEntityFormAction, DeleteEntityAction, WhileLoopAction, LoopAction, BreakLoop, ContinueLoop, DownloadAction, SendMailAction, LoadingAction, SaveFileAction, ReturnAction, and ConfirmAction.

The JSON schema is the corresponding action model's serializable properties. Runtime nodes are safe only for known allow-listed types; arbitrary CLR type activation and JSON type-name handling are disabled.

10. Compilation and validation

Compilation performs these stages:

1. Parse YAML into the compact specification.
2. Validate document version, scope, root, node names, and graph shape.
3. Select exactly one converter for every node type.
4. Generate action IDs and graph positions.
5. Resolve parameters and semantic aliases.
6. Create local/outgoing variable metadata.
7. Connect next and named branches.
8. Run the action model's recursive validation.
9. Produce the compiled IAction graph and canonical YAML/hash metadata.

A graph may contain at most 512 nodes and have a maximum nesting depth of 64. Cycles and reuse of the same YAML node object are rejected.

Decompilation performs the reverse operation. It rejects runtime graphs that cannot be represented semantically, for example an incoming variable ID with no available alias or a legacy action feature unsupported by its typed converter.

Compiler failures are written as one JSON file per failure under ActionFlowLogs, named:

ActionCompilerErrorLog-yyyyMMdd-HHmmss-fffffff.json

The log contains the serialized action where available, error details, compiler operation, timestamp, and diagnostic context.

11. Complete example

version: 1
scope: solution
root:
  type: user
  name: AskForEmail
  outputs:
  - source: businessEntity
    alias: BusinessEntity:Customer
    type: businessEntity
    scope: cascaded
  user:
    target: Customer
    published: true
    displayLabel:
      value: Update email
    button:
      text: Update email
    visibility: always
    enabled: always
    singleRun: true
  next:
    type: input
    name: ReadEmail
    outputs:
    - source: Email
      alias: Email
      type: text
      scope: cascaded
    input:
      title:
        value: Email address
      fields:
      - name: Email
        required: true
        type: email
    branches:
      cancel:
        type: alert
        name: Cancelled
        alert:
          message:
            value: No changes were made.
    next:
      type: updateEntity
      name: SaveEmail
      updateEntity:
        target: Customer
        identifier:
          value: $$Cascaded:BusinessEntity:Customer.PrimaryKey$$
        parameters:
        - name: Email
          alias: Email
      next:
        type: refresh
        name: RefreshCustomer
        refresh: {}

12. Authoring checklist

Before saving or publishing YAML:

1. Use version: 1 and a non-unknown scope.
2. Give every node a non-empty and preferably unique name without spaces.
3. Match type with exactly one configuration block.
4. Publish only real semantic sources and assign compatible types.
5. Declare an alias before consuming it; keep aliases unique in scope.
6. Use parameterType: constant for literal values when evaluation is not wanted.
7. Keep credentials as $$Secret:<name>$$ references.
8. Use only branch names supported by that node type.
9. Account explicitly for cancel and error paths.
10. Compile and perform a semantic YAML round trip before publication.