agility workflows

agility workflows (alias agility workflow) runs a workflow operation (publish, unpublish, approve, decline or request approval) on content items and pages in the target of an earlier sync. It finds the items through that sync's mapping files, or you can name target IDs directly.

Checked against @agility/cli 1.1.0. For the options every command shares, sign-in and exit codes, see the CLI command reference.

Usage

agility workflows --sourceGuid=<source> --targetGuid=<target> --locales=<locale> --operationType=<operation> [options]

From agility workflows --help:

agility workflows

Perform workflow operations (publish, unpublish, approve, decline,
requestApproval) on content and pages from existing mappings.

Choosing the operation: --operationType

Value	Also accepted	What it does on the target
publish	pub	Publishes. Only items that are published in the source are published; staging-only items are skipped
unpublish	unpub	Unpublishes every matched item
approve	app	Approves every matched item
decline	dec	Declines every matched item
requestApproval	request-approval, request_approval, req	Requests approval for every matched item

Other spellings of the option: --operation-type, --OperationType, --OPERATION_TYPE, --op and --type. Values are not case-sensitive.

Options

Option	Default	What it does
--sourceGuid	from .env	The source of the earlier sync. Used to find the mapping files and to check what is published in the source
--targetGuid	from .env	The instance the operation runs on
--locales		The locale to work in. The operation runs in the first locale you list, so run the command once per locale. Always pass it
--operationType	publish	See above
--contentIDs	none	Comma-separated target content IDs. Skips the mapping lookup, for example --contentIDs=121,1221,345
--pageIDs	none	Comma-separated target page IDs. Skips the mapping lookup, for example --pageIDs=12,11,45
--list	false	Lists the source and target pairs that have mapping files in agility-files/mappings/, with their locales and item counts, then exits. Doesn't sign in or change anything
--token, --headless, --verbose		As for every command. See the command reference

--contentIDs and --pageIDs are only read by workflows. Earlier documentation listed them under sync; sync ignores them.

The other shared options in --help (--elements, --models, --pages, --preflight and so on) don't affect this command.

What it acts on

• From mappings (default): every content item and page recorded in agility-files/mappings/{sourceGuid}-{targetGuid}/ for the locale. Run it from the folder that holds those files. If there are none, it prints No mappings found to process. and stops.
• From IDs: with --contentIDs or --pageIDs, only those target items. For publish, the CLI still uses the mappings to check which of them are published in the source, and skips the rest.

Items are processed in batches through Agility's batch workflow API. After a publish, the mapping files are updated with the newly published versions.

Examples

# Which source/target pairs have mappings here?
agility workflows --list

# Publish everything that is published in the source (en-us)
agility workflows --sourceGuid="A-u" --targetGuid="B-u" --locales="en-us" --operationType="publish"

# Same for a second locale: one run per locale
agility workflows --sourceGuid="A-u" --targetGuid="B-u" --locales="fr-ca" --operationType="publish"

# Request approval for two specific target items
agility workflows --sourceGuid="A-u" --targetGuid="B-u" --locales="en-us" \
  --operationType="requestApproval" --contentIDs="121,1221"

# Unpublish two target pages
agility workflows --sourceGuid="A-u" --targetGuid="B-u" --locales="en-us" \
  --operationType="unpublish" --pageIDs="12,45"

If you only want to publish what you just synced, agility sync --autoPublish does it in the same run. See sync and push.

Exit behavior

• Exits 1 when any item fails, and 0 when the operation finishes without failures (including when there was nothing to process).
• --list exits 0.
• In 1.1.0, if sign-in fails or a required setting is missing, the command stops without setting a failing exit code. In CI, check the output for the COMPLETE summary.

Related

• sync and push
• CLI CI/CD Integration Guide: a sync-then-publish pipeline