S3 storage

Availability

[SINCE Orbeon Forms 2024.1.1, 2025.1]

Introduction

When sending an email using the email action, you can store attachments into an S3 bucket. This is done by setting the s3-store parameter to true and providing the s3-config and s3-path parameters to the action.

Similarly, form definition and data attachments can be stored into an S3 bucket instead of the database. This is done by using an S3 attachment provider (i.e. setting the oxf.fr.persistence.provider.*.*.*.attachments property to s3).

Amazon Simple Storage Service (S3) is a cloud storage service provided by Amazon Web Services (AWS), but any S3-compatible service can be used, such as MinIO, Backblaze B2, Wasabi, and many others.

Email action parameters

The following email action parameters are specific to S3 storage:

• s3-store: If true, email attachments are stored in an S3 bucket in addition to being sent via email. If false or absent, attachments are only sent via email.

• s3-config: Specifies the name of the S3 configuration to use. The S3 configuration properties are described below.

• s3-path: Defines the XPath expression used to determine the storage path for attachments. The path is relative to the root of the S3 bucket. It is evaluated against the XML data of the form. If the XPath expression evaluates to an empty string, attachments are stored at the root of the S3 bucket. This expression has the same constraints as the PDF, TIFF and XML attachments filenames.

Fallback behavior

• If s3-config or s3-path are not provided as parameters, the properties oxf.fr.email.s3-config.*.* or oxf.fr.email.s3-path.*.* are used instead.

• If a property is not found for the S3 configuration name, default is used as the S3 configuration name.

• A default value for the oxf.fr.email.s3-path.*.* property is provided, which uses the app name, form name, etc. to generate a path. It is however recommended to provide a custom path that fits your needs.

Bucket configuration

An S3 configuration consists of a set of properties that follow the naming convention:

oxf.fr.s3.[configuration-name].[s3-property]

• [configuration-name]: The name of the S3 configuration.

• [s3-property]: One of the following properties:

  • endpoint: The S3 endpoint (default: s3.amazonaws.com)

  • region: The AWS region (e.g. eu-south-1 or us-east-1)

  • bucket: The name of the S3 bucket.

  • accesskey: The access key for authentication.

  • secretaccesskey: The secret access key for authentication.

No default S3 configuration is provided. You must define at least one S3 configuration to use the s3-store parameter.

Example

Your S3 configuration properties could define an S3 configuration named form-submissions-bucket that looks as follows:

<property as="xs:string"  name="oxf.fr.s3.form-submissions-bucket.endpoint"        value="s3.amazonaws.com"/>
<property as="xs:string"  name="oxf.fr.s3.form-submissions-bucket.region"          value="us-east-1"/>
<property as="xs:string"  name="oxf.fr.s3.form-submissions-bucket.bucket"          value="form-submissions"/>
<property as="xs:string"  name="oxf.fr.s3.form-submissions-bucket.accesskey"       value="YYDLE3Z65JK7SZLB5RXB"/>
<property as="xs:string"  name="oxf.fr.s3.form-submissions-bucket.secretaccesskey" value="1csA5grUiF/TcAD7lOkWd0KBrYLDhQtK5sWl163U"/>

You then reference the form-submissions-bucket configuration in an email action, which might look as the example below. This example uses the default value for s3-path; if that default works for you, you can skip this parameter. This example includes only S3-specific parameters, but you may want to add other parameters documented on the Form Runner email action page.

email(
    s3-store  = "true",
    s3-config = "form-submissions-bucket",
    s3-path   =
      "concat(
          fr:app-name(),      '/',
          fr:form-name(),     '/',
          fr:form-version(),  '/',
          current-dateTime(), '-',
          fr:document-id()
      )"
)

With the example path above, the S3 objects would be stored with keys such as:

• my-app/my-form/1/2025-03-12T03:43:43.334-07:00-175279c65b1cc95d1b027f3c92c3beebc85c05aa/My form.xml

• my-app/my-form/1/2025-03-12T03:43:43.334-07:00-175279c65b1cc95d1b027f3c92c3beebc85c05aa/My form.pdf

• my-app/my-form/1/2025-03-12T03:43:43.334-07:00-175279c65b1cc95d1b027f3c92c3beebc85c05aa/user-attachment.jpg

• my-app/my-form/1/2025-03-12T03:43:43.334-07:00-175279c65b1cc95d1b027f3c92c3beebc85c05aa/user-attachment.doc

Access and secret access keys

This is a general description of how to get access and secret access keys for AWS. The process will be different for other S3-compatible services.

You will typically define a policy in AWS Identity and Access Management (IAM) that allows access to the S3 bucket. You then create a user in IAM, attach the policy to the user, and generate a new pair of access and secret access keys under "Security credentials" > "Access keys". You can then use these keys in the S3 configuration properties. Alternatively, you can also attach the policy to a user group or a role, and then assign the user to the group or the role.

A simple policy that restricts access to a single bucket might look like the following:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "s3:*",
            "Resource": [
                "arn:aws:s3:::form-submissions",
                "arn:aws:s3:::form-submissions/*"
            ]
        }
    ]
}

Note that bucket names need to be unique across all of AWS.

See also

• Form Runner email action
• Persistence configuration properties