Skip to content

We've extended the use of Tasks in PowerOn Pipelines to consider a defined configuration which is present in the repository. With this, you'll be able to define things like which PowerOns should be installed during deployments, and even what branch maps to which Sym number.

Creating the config file

In your Symitar repository, create a config.yml under a folder named .poweron-pipelines. The following example defines a global powerOnsDirectory input and sets the main branch to deploy and validate using Sym 627.

YAML
# Default inputs that apply to all tasks
inputs:
  powerOnsDirectory: REPWRITERSPECS/

# Map of branch / symNumber relationships
branchSymNumbers:
  main: 627

This will be considered by every Task within PowerOn Pipelines and the ingested values will be printed in the logs so you are always aware of what values are being used where.

Available configurations

The following are the available options for the configuration file.

inputs.powerOnsDirectory

Sets the powerOnsDirectory (which is the location of your local PowerOns) for every PowerOn Pipelines Task in the repository. This will be overwritten by individual task configurations if they explicitly set this input.

YAML
# Example: Default powerOnsDirectory which applies to all tasks
inputs:
  powerOnsDirectory: REPWRITERSPECS/

inputs.letterFilesDirectory

Sets the letterFilesDirectory (which is the location of your local LetterFiles) for every PowerOn Pipelines Task in the repository. This will be overwritten by individual task configurations if they explicitly set this input.

YAML
# Example: Default letterFilesDirectory which applies to all tasks
inputs:
  letterFilesDirectory: LETTERSPECS/

inputs.dataFilesDirectory

Sets the dataFilesDirectory (which is the location of your local DataFiles) for every PowerOn Pipelines Task in the repository. This will be overwritten by individual task configurations if they explicitly set this input.

YAML
# Example: Default dataFilesDirectory which applies to all tasks
inputs:
  dataFilesDirectory: DATAFILES/

inputs.helpFilesDirectory

Sets the helpFilesDirectory (which is the location of your local HelpFiles) for every PowerOn Pipelines Task in the repository. This will be overwritten by individual task configurations if they explicitly set this input.

YAML
# Example: Default helpFilesDirectory which applies to all tasks
inputs:
  helpFilesDirectory: HELPFILES/

branchSymNumbers

Map of Symitar repository branches to their symNumber.

YAML
# Example: Map of branch / symNumber relationships
branchSymNumbers:
  main: 627

installPowerOns

Exact PowerOn filenames eligible for installation after synchronization. By default, only listed files actually uploaded are installed; listed files deleted by mirror are uninstalled. Pull never installs or uninstalls PowerOns.

In v2.2, the task input reinstallDependentPowerOns: true also considers unchanged listed parents when a direct or nested include is deployed. This is a task input, not a new repository configuration key. It defaults to false. See dependent reinstalls.

YAML
# Example: List of PowerOn files to install
installPowerOns:
  - LB.VALID.PO

validateIgnorePowerOns

List of PowerOn filenames excluded from standalone validation. This does not suppress compiler errors during installation or errors in an include used by a selected parent.

YAML
# Example: Skip ASCII files in the PowerOn directory (which will always fail)
validateIgnorePowerOns:
  - ASCIICHAR.DATA
  - RB.SYNERGY.AP.INDEX.ASCIIDATA

preserveServerFiles

List of exact filenames or glob patterns where Symitar should remain the source of truth. Matched files are skipped during validation, preserved during push and mirror synchronization, and can be pulled back from Symitar with the pullPreservedOnly workflow.

YAML
# Example: Preserve files generated or forcibly updated by Symitar
preserveServerFiles:
  - RD.*
  - PFR.*

New in v2.2: patterns are applied in order, and the last matching rule wins. A normal pattern preserves matching files; a pattern beginning with ! removes matching files from preservation, making them eligible for normal pipeline operations. For example:

YAML
preserveServerFiles:
  - RD.*
  - '!RD.CUSTOM.PO'

Quote negated YAML patterns. In task inputs, use the comma-delimited form RD.*,!RD.CUSTOM.PO. An empty task input falls back to the repository list; it does not clear it. A preserved-only pull with no configured patterns transfers nothing.

Manage Only One Filename Prefix

CUSTOM. is a generic example; replace it with your own filename prefix. To keep legacy PowerOns on the server while managing only filenames beginning with CUSTOM., put this in .poweron-pipelines/config.yml:

YAML
preserveServerFiles:
  - '*'
  - '!CUSTOM.*'

Or supply the equivalent comma-delimited task input to both validation and synchronization:

YAML
preserveServerFiles: '*,!CUSTOM.*'

The first rule preserves everything. The second makes only CUSTOM.* eligible for validation and synchronization. These are filename wildcards, not regular expressions: * matches any sequence, ? matches one character, and other characters (including .) are literal. Matching is case-insensitive and covers the whole filename, not a repository path. This does not rename files or change the artifact's exact-casing requirements.

Filename Result
LEGACY.REPORT Preserved; not uploaded, deleted, or installed by push/mirror
CUSTOM.REPORT Eligible for normal validation and synchronization
custom.report Also eligible because matching ignores case
XCUSTOM.REPORT or CUSTOMXREPORT Preserved; neither starts with the literal CUSTOM. prefix

Eligible does not mean forced: byte-identical files remain unchanged, validateIgnorePowerOns still skips standalone validation, and installPowerOns still controls installation eligibility. Preservation is not an operating-system permission and does not stop manual changes on the host.

Choose the synchronization mode deliberately:

  • Push: upload new or changed CUSTOM.* files; leave server-only files in place.
  • Mirror: also delete server-only CUSTOM.* files absent from the artifact. Legacy files remain preserved. Use push if prefix-matching server files must not be deleted.
  • Pull with pullPreservedOnly: true: download the preserved legacy files, not the CUSTOM.* exceptions. This reverses which group transfers because the server is the source of truth for preserved files. It does not delete local-only files or install PowerOns.
  • Ordinary pull: preservation patterns do not limit downloads; pullPreservedOnly defaults to false.

Order matters. ['!CUSTOM.*', '*'] preserves everything because the final * wins. A lone !CUSTOM.* preserves nothing; it is not an allowlist on its own. Add a later positive rule such as 'CUSTOM.SPECIAL.*' to protect that subset again.

Existing positive-only lists and omitted preservation settings retain their matching behavior. Leading ! gains negation meaning in v2.2; review any older configuration containing it rather than assuming its previous literal interpretation still applies. Quote wildcard and negated values in YAML. A non-empty task input replaces the repository list rather than appending to it.

Start with isDryRun: true using the same artifact, patterns, and mode intended for release. Check the named uploads, deletions, and installation candidates before running the deployment. The deployment recomputes its plan against the host; the preview does not freeze server state. If dependent reinstalls are enabled, preserved parents remain excluded and preserved dependencies must match the artifact as described in the migration guide.