Manage S3 Service Connection

Audience: System/Security Administrators

Skill Prerequisites: Amazon S3, AWS IAM

Creates, reads, updates or deletes an Amazon S3 storage connection (folder type). A storage connection links a portal folder to an S3 bucket, so that files saved in the folder are stored in S3. See Amazon S3 Storage Integration for how S3 storage works.

This action does from a form or workflow what you would otherwise do by hand in Manage Folder Types. The connection's ID is returned as a token, so it can be passed straight to Get or Create Folder to create an S3-backed folder.

note

This action requires the Amazon S3 Storage Integration feature to be licensed and installed.

Typical Use Cases

• Automatically set up a separate S3 bucket, or a separate base path, for each new customer or tenant
• Rotate AWS access keys on existing connections
• Read a connection's settings to check or display its bucket and region

Don't use it to

• Create the S3 bucket itself. The bucket must already exist in AWS.
• Upload or delete individual files in S3. Save files into a folder that uses the connection instead.

Related Actions

Action Name	Description
Get or Create Folder	Creates a folder that uses the storage connection, by passing [<OutputTokenName>:ConnectionId] as Storage Connection.
Alter Folder Permissions	Sets permissions on the new folder.

Input Parameter Reference

Parameter	Description	Supports Tokens	Default	Required
CRUD Mode	What to do: Create, Read, Update or Delete a storage connection. In expression mode, use create, read, update or delete.	Yes	Create	Yes
Storage Connection Name	Create and Update. A unique name for the connection. If empty when creating, the name is S3 <BucketName>. The action fails if another connection already uses the name. Avoid using the bucket name on its own.	Yes	S3 <BucketName>	No
Storage Connection ID	Read, Update and Delete. The ID of the connection to act on. It must be an existing S3 connection.	Yes	empty string	Yes
AWS AccessKey	Create and Update. The access key ID of an IAM user that can access the bucket.	Yes	empty string	Yes
AWS SecretKey	Create and Update. The secret access key for the access key.	Yes	empty string	Yes
AWS Region	Create and Update. The bucket's region as its system name, for example us-east-1, eu-central-1 or us-west-2.	Yes	empty string	Yes
AWS Bucket Name	Create and Update. The name of an existing S3 bucket.	Yes	empty string	Yes
Base Path Inside Bucket	Create and Update. Optional. A folder path inside the bucket that the connection starts from, for example customers/acme. Leave empty to use the root of the bucket.	Yes	empty string	No
Map Path Structure	Create and Update. How portal folders are mapped to paths in the bucket. Relative to Portal Root (1): the bucket mirrors the portal's folder structure from the root. Relative to Folder (2): files and folders are added directly under the bucket and base path.	Yes	Relative to Portal Root	No

info

When updating, enter all the connection settings again, including the name, access key, secret key, region and bucket. Settings you leave empty aren't kept from the existing connection: an empty name or base path is saved as empty, and empty required settings make the action fail.

Output Parameters Reference

Parameter	Description
Output Token Name	The name of the token that stores the connection details. Tokens are set in every mode. For Delete, they describe the connection that was deleted.

If Output Token Name is S3, the following tokens are created:

Token	Description
[S3:ConnectionId]	The storage connection ID. Pass it to Storage Connection in Get or Create Folder.
[S3:Name]	The connection name.
[S3:Region]	The AWS region.
[S3:BucketName]	The bucket name.
[S3:BasePathInsideBucket]	The base path inside the bucket.
[S3:MapPathStructure]	1 (Relative to Portal Root) or 2 (Relative to Folder).
[S3:AwsAccessKey]	The access key, decrypted.
[S3:AwsSecretKey]	The secret key, decrypted.

danger

The AwsAccessKey and AwsSecretKey tokens contain the credentials in plain text. Never show them on a page, write them to logs or send them in emails.

Considerations

• The bucket is checked. On create and update, the action connects to AWS with the credentials you provide and checks that the bucket exists. If it doesn't, or if the credentials can't see it, the action fails. The error message says AWS S3 Bucket ... already exists, but it means the bucket wasn't found.
• Credentials are encrypted when they're saved in the connection settings.
• Deleting a connection. Move or delete any folders that use the connection before deleting it. Files already in the bucket aren't deleted from S3.
• Connection type. Read, update and delete only work on S3 connections. The action fails if the ID belongs to a different type of folder connection.
• IAM permissions. Give the IAM user access only to the buckets it needs, rather than full S3 access.

Examples

tip

To understand how to use the below examples, please see Running Examples.

1. Create a storage connection and an S3-backed folder for a customer

The first action creates a connection named S3 <Company> that stores files under customers/<CustomerCode> in the acme-app-files bucket. The AWS keys come from the AwsKey and AwsSecret tokens. The second action creates the folder Customers/<Company>/ using the new connection.

[
    {
        "Title": "Manage S3 Service Connection",
        "ActionType": "PlantAnApp.ManageS3ServiceConnection",
        "Description": "Create the customer's storage connection",
        "Condition": null,
        "Parameters": {
            "CRUDMode": {
                "Expression": "",
                "Value": "create",
                "IsExpression": false,
                "Parameters": {}
            },
            "Name": "S3 [Company]",
            "FolderMappingId": "",
            "AwsAccessKey": "[AwsKey]",
            "AwsSecretKey": "[AwsSecret]",
            "AwsRegion": "us-east-1",
            "BucketName": "acme-app-files",
            "BasePathInsideBucket": "customers/[CustomerCode]",
            "MapPathStructure": {
                "Expression": "",
                "Value": "2",
                "IsExpression": false,
                "Parameters": {}
            },
            "OutputTokenName": "S3"
        }
    },
    {
        "Title": "Get or Create Folder",
        "ActionType": "GetOrCreateFolder",
        "Description": "Create the customer's S3-backed folder",
        "Condition": null,
        "Parameters": {
            "FolderPath": {
                "Expression": "Customers/[Company]",
                "Value": "",
                "IsExpression": true,
                "Parameters": {}
            },
            "FolderMappingConnection": {
                "Expression": "[S3:ConnectionId]",
                "Value": "",
                "IsExpression": true,
                "Parameters": {}
            },
            "OutputTokenName": "CustomerFolder"
        }
    }
]

Revised 09/25/2026