170 lines
4.7 KiB
Markdown
170 lines
4.7 KiB
Markdown
# Flow Spec Schema
|
|
|
|
The YAML spec format for declarative ST AR flow definitions.
|
|
|
|
## Top-Level Structure
|
|
|
|
```yaml
|
|
version: "1.0" # Spec format version
|
|
meta: # Human-readable metadata
|
|
name: <string>
|
|
description: <string>
|
|
application: ... # AR Application definition
|
|
subscription: ... # Subscription definition
|
|
routes: ... # Route definitions (simple, template, composite)
|
|
prerequisites: ... # Resources that must exist before deploy
|
|
```
|
|
|
|
## application
|
|
|
|
```yaml
|
|
application:
|
|
name: <string> # AR application name (must be unique in ST)
|
|
type: AdvancedRouting # Always AdvancedRouting for AR flows
|
|
```
|
|
|
|
## subscription
|
|
|
|
```yaml
|
|
subscription:
|
|
account: <string> # ST account name that owns the subscription
|
|
folder: /<path> # Upload folder that triggers routing (absolute path)
|
|
application: <string> # AR application name (must match application.name)
|
|
post_transmission_actions:
|
|
ptaOnSuccessDoInAdvancedRoutingWildcardPull: true
|
|
submitFilenamePatternExpression: "*" # "*" = trigger on any file
|
|
submitFilterType: FILENAME_PATTERN
|
|
triggerFileOption: fail
|
|
triggerOnSuccessfulWildcardPull: true
|
|
```
|
|
|
|
Note: `submitFilenamePatternExpression` here only affects server-initiated pulls.
|
|
For client-uploaded files, use route-level `condition` to filter by file type.
|
|
|
|
## routes.simple — Steps
|
|
|
|
Steps are applied in array order. Each step sees all files in the route payload
|
|
unless `usePrecedingStepFiles: true` is set.
|
|
|
|
### Compress step
|
|
|
|
```yaml
|
|
- type: Compress
|
|
conditionType: ALWAYS # Required. ALWAYS or EL.
|
|
actionOnStepFailure: PROCEED # PROCEED = non-matching files continue
|
|
fileFilterExpression: "*.txt" # GLOB or REGEX
|
|
fileFilterExpressionType: GLOB
|
|
usePrecedingStepFiles: false # false = see all route files
|
|
singleArchiveEnabled: false # false = one ZIP per file; true = bundle all
|
|
compressionMode: ZIP # ZIP (default) or GZIP
|
|
```
|
|
|
|
Output filename: `<original>.zip`
|
|
|
|
### PgpEncryption step
|
|
|
|
```yaml
|
|
- type: PgpEncryption
|
|
conditionType: ALWAYS
|
|
actionOnStepFailure: PROCEED
|
|
fileFilterExpression: "*.md"
|
|
fileFilterExpressionType: GLOB
|
|
usePrecedingStepFiles: false
|
|
encryptKeyExpression: <cert-alias> # The cert name in ST cert store
|
|
encryptKeyExpressionType: ALIAS # ALIAS or EXPRESSION_WILDCARD only
|
|
encryptKeyOwnerExpression: <account-name> # Account that owns the cert
|
|
encryptKeyOwnerExpressionType: NAME
|
|
compressionType: "0" # "0" = no PGP compression
|
|
useAsciiArmour: false # false = binary; true = ASCII armored
|
|
signKeyExpression: null # Optional: signing key alias
|
|
signKeyExpressionType: null
|
|
signKeyOwnerExpression: null
|
|
signKeyOwnerExpressionType: null
|
|
```
|
|
|
|
Output filename: `<original>.pgp`
|
|
|
|
**Cert requirements:** `accessLevel: PUBLIC`, `account: <owner-account>` (not null).
|
|
`encryptKeyExpressionType` only accepts `ALIAS` or `EXPRESSION_WILDCARD` — not `NAME`.
|
|
|
|
### SendToPartner step
|
|
|
|
```yaml
|
|
- type: SendToPartner
|
|
conditionType: ALWAYS
|
|
actionOnStepFailure: FAIL
|
|
fileFilterExpression: "*"
|
|
fileFilterExpressionType: GLOB
|
|
usePrecedingStepFiles: false
|
|
partnerName: <partner-account> # ST partner account name
|
|
partnerSite: <partner-site-name> # ST partner site name
|
|
```
|
|
|
|
### ExternalScript step
|
|
|
|
```yaml
|
|
- type: ExternalScript
|
|
conditionType: ALWAYS
|
|
actionOnStepFailure: PROCEED
|
|
fileFilterExpression: "*"
|
|
fileFilterExpressionType: GLOB
|
|
usePrecedingStepFiles: false
|
|
scriptPath: /path/to/script.sh
|
|
outputFileExpression: "${basename}.out"
|
|
```
|
|
|
|
## routes.template
|
|
|
|
```yaml
|
|
template:
|
|
name: <string>
|
|
conditionType: MATCH_ALL # Always MATCH_ALL for templates
|
|
```
|
|
|
|
## routes.composite
|
|
|
|
```yaml
|
|
composite:
|
|
name: <string>
|
|
conditionType: MATCH_ALL # Always MATCH_ALL for composites
|
|
```
|
|
|
|
## prerequisites
|
|
|
|
Resources validated by `st_env_snapshot.py` before any deploy:
|
|
|
|
```yaml
|
|
prerequisites:
|
|
accounts:
|
|
- name: <account-name>
|
|
type: individual | partner
|
|
partner_accounts:
|
|
- name: <account-name>
|
|
partner_sites:
|
|
- name: <site-name>
|
|
partner: <partner-account-name>
|
|
certificates:
|
|
- name: <cert-alias>
|
|
type: pgp | ssh | x509
|
|
usage: partner | local | private
|
|
account: <owner-account>
|
|
accessLevel: PUBLIC | PRIVATE
|
|
```
|
|
|
|
If any prerequisite is missing, `st_deploy.py` exits with code 2 before making any changes.
|
|
|
|
## EL Conditions (route-level filtering)
|
|
|
|
To filter which files enter a route by extension:
|
|
|
|
```yaml
|
|
routes:
|
|
simple:
|
|
conditionType: EL
|
|
condition: "${transfer.target.matches('.*\\.txt')}"
|
|
```
|
|
|
|
- `transfer.target` = full file path
|
|
- Use Java regex with double-escaped dot (`\\.` not `\.`)
|
|
- Single-escape throws AR0045 at runtime
|