AWS CloudFormation Connector - Documentation (O11)

Stable version 1.1.0 (Compatible with OutSystems 11)

Uploaded

on 18 Jun (11 hours ago)

0.0

(0 ratings)

Documentation

1.1.0

This connector exposes 33 CloudFormation actions as OutSystems server actions, letting you provision, update, inspect, and tear down AWS infrastructure directly from your applications and automation logic. It spans three areas:

Single stacks — create, update, delete, and inspect individual CloudFormation stacks, with change-set support for preview-before-apply workflows.
StackSets — deploy a single template across many AWS accounts and Regions from one definition, with both self-managed and service-managed (AWS Organizations) permission models.
Organizations access — enable, disable, and inspect the trusted access required for service-managed StackSets.

All requests are signed with SigV4 and sent using the CloudFormation Query Protocol; XML responses are parsed into OutSystems structures.

Actions

Stacks

CreateStack — create a new stack from a template.
UpdateStack — update an existing stack.
DeleteStack — delete a stack.
DescribeStacks — retrieve stack details and status.
DescribeStackEvents — retrieve a stack's event history.
ListStacks — list stacks, optionally filtered by status.
ValidateTemplate — validate a template's syntax and parameters.

Change Sets

CreateChangeSet — create a change set to preview changes before applying.
DescribeChangeSet — inspect a change set's planned changes.
ExecuteChangeSet — apply a change set.
DeleteChangeSet — discard a change set.
ListChangeSets — list a stack's change sets.

StackSet Lifecycle

CreateStackSet — create a StackSet definition (template, parameters, permission model).
UpdateStackSet — update the StackSet definition and propagate to instances.
DeleteStackSet — delete an empty StackSet.
DescribeStackSet — retrieve a StackSet's full definition and aggregate drift status.
ListStackSets — list StackSets with summary information.

Stack Instances

CreateStackInstances — deploy stacks into target accounts and Regions.
UpdateStackInstances — update parameter overrides on existing instances.
DeleteStackInstances — remove instances, optionally retaining the underlying stacks.
DescribeStackInstance — retrieve a single instance, including its parameter overrides.
ListStackInstances — list instances with per-instance status and drift, with filtering.
ListStackInstanceResourceDrifts — list per-resource drift detail within an instance.

StackSet Operations

DescribeStackSetOperation — retrieve the status of an operation (the poll target for all asynchronous actions).
ListStackSetOperations — list a StackSet's operation history.
ListStackSetOperationResults — list per-account/Region results of an operation.
StopStackSetOperation — request that an in-progress operation stop.

Drift & Auto-Deployment

DetectStackSetDrift — initiate drift detection across a StackSet's instances.
ListStackSetAutoDeploymentTargets — inspect the OUs and Regions a service-managed StackSet auto-deploys to.

Import

ImportStacksToStackSet — bring existing stacks under StackSet management (up to 10 per operation) without recreating resources.

Organizations Access

ActivateOrganizationsAccess — enable trusted access between CloudFormation and AWS Organizations (prerequisite for service-managed StackSets).
DeactivateOrganizationsAccess — disable trusted access.
DescribeOrganizationsAccess — retrieve the current trusted-access status.

Authentication & Prerequisites

The connector signs every request with SigV4. You provide AWS credentials (access key ID and secret access key, and a session token if using temporary credentials) and the target Region; the connector handles the signing.

The credentials must belong to an IAM principal with the appropriate cloudformation:* permissions for the actions you call. For least privilege, grant only the specific actions in use.

For StackSets, choose a permission model:

Self-managed — create the AWSCloudFormationStackSetAdministrationRole and AWSCloudFormationStackSetExecutionRole IAM roles establishing trust between the administrator account and each target account. Suitable for any account where you can create an IAM role.
Service-managed — integrate with AWS Organizations. Call ActivateOrganizationsAccess once (from the management account) to enable trusted access, then target organizational units directly. This model supports automatic deployment to accounts as they join a target OU.

The CallAs input on StackSet actions selects the caller context: SELF (management account or self-managed) or DELEGATED_ADMIN (a registered delegated administrator account). When polling or describing an operation, use the same CallAs value used to start it.

Working with the Connector

Synchronous vs. asynchronous actions

Most StackSet instance and update actions are asynchronous: they return an OperationId rather than a final result. To track completion, poll DescribeStackSetOperation with that ID until the status reaches a terminal state:

Non-terminal: RUNNING, QUEUED, STOPPING
Terminal: SUCCEEDED, FAILED, STOPPED

Asynchronous actions include CreateStackInstances, UpdateStackInstances, DeleteStackInstances, UpdateStackSet, DetectStackSetDrift, and ImportStacksToStackSet. By contrast, CreateStackSet, DeleteStackSet, and the describe/list actions return immediately.

A typical deployment flow: CreateStackSet (synchronous) → CreateStackInstances (returns OperationId) → poll DescribeStackSetOperation until terminal.

Targeting accounts and Regions

Instance actions deploy to the cross-product of the targeted accounts and the supplied Regions — the Region list is applied to every targeted account. Specify accounts via the Accounts list (self-managed) or the DeploymentTargets object (service-managed), but never both.

Pagination

List actions return up to MaxResults items plus a NextToken. To retrieve all results, repeat the call passing the returned NextToken until it comes back empty.

Drift detection workflow

Drift is a layered drill-down: DetectStackSetDrift initiates a check (poll the returned operation to completion) → DescribeStackSet reports aggregate counts → ListStackInstances (filtered by drift status) identifies which instances drifted → ListStackInstanceResourceDrifts reports the specific resources and property-level differences.

Error handling

Any error returned by CloudFormation surfaces as an OutSystems exception from the action. Wrap calls in exception handlers and inspect the message for the underlying cause (for example, an operation already in progress, a non-empty StackSet on delete, or an invalid parameter combination).

Notes

The endpoint is regional (for example, https://cloudformation.us-east-1.amazonaws.com/); set the Region to match where your stacks and StackSets live.
Some resources, such as ACM certificates for CloudFront, must be created in us-east-1 regardless of your primary Region.
A StackSet must be emptied (all instances deleted) before it can be deleted.
Deleting stack instances offers a retain option, letting you remove instances from StackSet management without destroying the underlying resources.
Complex inputs (parameters, tags, deployment preferences, deployment targets, filters) are modeled as OutSystems structures.

Support & Feedback

Issues, feature requests, and contributions are welcome. Please use the component's support channel on Forge to report problems or suggest improvements, including the action name and the relevant request details (with credentials redacted).

1.0.1

Prerequisites:

Use a pair of client/secret keys of AWS credentials with the following IAM permissions:

cloudformation:ValidateTemplate
cloudformation:CreateStack
cloudformation:UpdateStack
cloudformation:DeleteStack
cloudformation:DescribeStacks
cloudformation:DescribeStackEvents
cloudformation:ListStacks
cloudformation:CreateChangeSet
cloudformation:DescribeChangeSet
cloudformation:ExecuteChangeSet
cloudformation:DeleteChangeSet
cloudformation:ListChangeSets

Actions available:

AWSCloudFormationConnector_ValidateTemplate

Validates the syntax and structure of a CloudFormation template without creating any resources. Returns the declared parameters, required capabilities, and any transforms. Use as a pre-flight check before calling CreateStack or UpdateStack.

Key inputs: TemplateBody or TemplateURL

Key outputs: Parameters list, Capabilities list, Description, DeclaredTransforms

Important: the returned Capabilities list should be stored and passed directly to CreateStack or UpdateStack. If a template requires CAPABILITY_NAMED_IAM and it is not passed at deploy time, the stack creation will fail with InsufficientCapabilitiesException.

AWSCloudFormationConnector_CreateStack

Creates a new CloudFormation stack from a template. Asynchronous — returns immediately with a StackId. Poll DescribeStacks until a terminal status is reached.

Key inputs: StackName, TemplateBody or TemplateURL, Parameters, Capabilities, OnFailure, TimeoutInMinutes, EnableTerminationProtection

Key outputs: StackId

Error to handle: AlreadyExistsException — switch to UpdateStack when received.

Recommended OnFailure values:

ROLLBACK — default, undoes all changes on failure
DO_NOTHING — leaves failed resources in place for debugging
DELETE — rolls back and deletes the stack entirely

AWSCloudFormationConnector_UpdateStack

Applies a new template or updated parameter values to an existing stack. Asynchronous — returns immediately with a StackId. Poll DescribeStacks until a terminal status is reached.

Key inputs: StackName, TemplateBody, TemplateURL, or UsePreviousTemplate, Parameters, Capabilities

Key outputs: StackId

Errors to handle:

ValidationError with message No updates are to be performed. — treat as success, the stack is already in the desired state
ValidationError with message containing ROLLBACK_COMPLETE — stack must be deleted and recreated, it cannot be updated
ValidationError with message does not exist — switch to CreateStack

Note on UsePreviousValue: use this on sensitive parameters (NoEcho: true) to avoid having to re-pass secrets on every update. Pass UsePreviousValue=true for any parameter whose value you do not want to change.

Note on tags: tags do not support UsePreviousValue. Always pass the complete desired tag set — omitting tags will remove them from the stack.

AWSCloudFormationConnector_DeleteStack

Initiates deletion of a stack and all its resources. Asynchronous — returns immediately with an empty response. Poll DescribeStacks until a ValidationError with "does not exist" is returned, which confirms full deletion.

Key inputs: StackName, ClientRequestToken, RetainResources

Key outputs: none (empty response)

Errors to handle:

ValidationError with termination protection message — call SetTerminationProtect to disable protection before retrying
DELETE_FAILED stack status — call DescribeStackEvents to identify the blocking resource, resolve the dependency, then retry DeleteStack

Note on RetainResources: only valid when retrying a DELETE_FAILED stack. Pass the logical resource IDs of resources that cannot be deleted so CloudFormation skips them and completes the stack deletion, leaving those resources orphaned in AWS.

AWSCloudFormationConnector_DescribeStacks

Returns the current status, parameters, outputs, and metadata for a stack. The primary polling action after CreateStack, UpdateStack, and ExecuteChangeSet.

Key inputs: StackName (name or ARN)

Key outputs: StackStatus, StackStatusReason, Outputs, Parameters, Tags, EnableTerminationProtection, DriftInformation

Terminal statuses — stop polling:

Status	Outcome
`CREATE_COMPLETE`	Success
`UPDATE_COMPLETE`	Success
`UPDATE_ROLLBACK_COMPLETE`	Update failed, rolled back — call `DescribeStackEvents` for cause
`ROLLBACK_COMPLETE`	Create failed, rolled back — stack can only be deleted
`CREATE_FAILED`	Failed with rollback disabled
`DELETE_FAILED`	Deletion failed
`ROLLBACK_FAILED`	Rollback failed — manual intervention required
`UPDATE_ROLLBACK_FAILED`	Update rollback failed — call `ContinueUpdateRollback` to recover

Note on deletion polling: after DeleteStack, DescribeStacks will eventually return ValidationError with "does not exist" rather than DELETE_COMPLETE. Treat this specific error as a successful deletion confirmation, not a real error.

AWSCloudFormationConnector_DescribeStackEvents

Returns the event log for a stack in reverse chronological order (newest first). Most useful for diagnosing failures — filter for events where ResourceStatus ends in _FAILED and read ResourceStatusReason for the root cause.

Key inputs: StackName (name or ARN), NextToken

Key outputs: list of events with ResourceType, LogicalResourceId, PhysicalResourceId, ResourceStatus, ResourceStatusReason, Timestamp

Failure diagnosis pattern: when DescribeStacks returns a failed terminal status, immediately call DescribeStackEvents and filter for ResourceStatus values ending in _FAILED. The ResourceStatusReason on those events contains the actual AWS error message.

AWSCloudFormationConnector_ListStacks

Returns a summary list of stacks filtered by one or more status values. Does not require a stack name. Can return deleted stacks. Does not return outputs, parameters, or tags — use DescribeStacks for full detail on a specific stack.

Key inputs: StackStatusFilter list, NextToken

Key outputs: list of stack summaries with StackName, StackId, StackStatus, CreationTime, LastUpdatedTime, DeletionTime, DriftInformation

Note: DELETE_COMPLETE stacks are excluded from results unless explicitly included in StackStatusFilter. This is the only status excluded by default.

AWSCloudFormationConnector_CreateChangeSet

Calculates the changes that would result from applying a new template or parameter values to an existing stack, without executing them. Asynchronous — poll DescribeChangeSet until Status reaches CREATE_COMPLETE before reading results or calling ExecuteChangeSet.

Key inputs: StackName, ChangeSetName, ChangeSetType, TemplateBody or TemplateURL or UsePreviousTemplate, Parameters, Capabilities, Description

Key outputs: Id (change set ARN), StackId

Note on ClientToken: this action uses ClientToken for idempotency, not ClientRequestToken as used by other actions. Passing the wrong key name will not produce an error but will not deduplicate requests.

Note on naming: change set names must be unique among active change sets for a stack. A reliable pattern is appending a timestamp, e.g. my-alb-cs-20240115-103000.

AWSCloudFormationConnector_DescribeChangeSet

Returns the status and full list of calculated resource changes for a change set. Poll until Status=CREATE_COMPLETE before reading changes or calling ExecuteChangeSet.

Key inputs: ChangeSetName (name or ARN), StackName, IncludePropertyValues, NextToken

Key outputs: Status, ExecutionStatus, StatusReason, Changes list, Parameters, Tags, Capabilities

ExecutionStatus values to act on:

ExecutionStatus	Action
`AVAILABLE`	Safe to call `ExecuteChangeSet`
`OBSOLETE`	Another change set was executed first — call `DeleteChangeSet`
`UNAVAILABLE`	Calculation not yet complete — keep polling
`EXECUTE_COMPLETE`	Already executed — change set will be gone from `ListChangeSets`

The most important field in the Changes list is Replacement:

False — resource updated in-place, no interruption
True — resource will be destroyed and recreated — flag this prominently in any UI
Conditional — replacement depends on runtime values — treat with the same caution as True

No-changes case: when CreateChangeSet was submitted with no differences, DescribeChangeSet returns Status=FAILED with StatusReason of The submitted information didn't contain changes. and an empty Changes list. Treat this as a success with a no-op result.

AWSCloudFormationConnector_ExecuteChangeSet

Applies a previously reviewed and approved change set to its target stack. Asynchronous — returns immediately with an empty response. Poll DescribeStacks until a terminal status is reached.

Key inputs: ChangeSetName (name or ARN), StackName, ClientRequestToken, DisableRollback

Key outputs: none (empty response)

Pre-flight check: always verify ExecutionStatus=AVAILABLE from DescribeChangeSet before calling this action. Any other ExecutionStatus will result in InvalidChangeSetStatusException.

Note on automatic deletion: after successful execution, the change set is automatically deleted by CloudFormation. Do not treat its absence from ListChangeSets as an error in post-execution checks.

Note on failure: if execution fails and the stack rolls back, the change set is NOT automatically deleted. You can retry execution after resolving the underlying issue, or delete it and create a new one.

AWSCloudFormationConnector_ListChangeSets

Returns a summary of all change sets for a given stack. Does not return the full changes list — use DescribeChangeSet for full detail on a specific change set.

Key inputs: StackName, NextToken

Key outputs: list of change set summaries with ChangeSetName, ChangeSetId, Status, ExecutionStatus, CreationTime, Description

Typical usage pattern: call ListChangeSets to populate a list of available change sets, then call DescribeChangeSet when the user selects one to review before deciding to execute or discard it.

Known Limitations

TemplateBody has a maximum size of 51,200 bytes. For larger templates, upload the template to S3 and pass TemplateURL instead.
This connector does not include S3 upload functionality. A separate S3 connector is needed for TemplateURL support.
Stack Sets (multi-account / multi-region deployments) are not covered by this connector.