AWS::Transfer::Agreement

Creates an agreement. An agreement is a bilateral trading partner agreement, or partnership, between an AWS Transfer Family server and an AS2 process. The agreement defines the file and message transfer relationship between the server and the AS2 process. To define an agreement, Transfer Family combines a server, local profile, partner profile, certificate, and other attributes.

The partner is identified with the PartnerProfileId, and the AS2 process is identified with the LocalProfileId.

Note

Specify eitherBaseDirectory or CustomDirectories, but not both. Specifying both causes the command to fail.

Syntax

To declare this entity in your AWS CloudFormation template, use the following syntax:

JSON

{
  "Type" : "AWS::Transfer::Agreement",
  "Properties" : {
      "AccessRole" : String,
      "BaseDirectory" : String,
      "CustomDirectories" : CustomDirectories,
      "Description" : String,
      "EnforceMessageSigning" : String,
      "LocalProfileId" : String,
      "PartnerProfileId" : String,
      "PreserveFilename" : String,
      "ServerId" : String,
      "Status" : String,
      "Tags" : [ Tag, ... ]
    }
}

YAML

Type: AWS::Transfer::Agreement
Properties:
  AccessRole: String
  BaseDirectory: String
  CustomDirectories: 
    CustomDirectories
  Description: String
  EnforceMessageSigning: String
  LocalProfileId: String
  PartnerProfileId: String
  PreserveFilename: String
  ServerId: String
  Status: String
  Tags: 
    - Tag

Properties

AccessRole

Connectors are used to send files using either the AS2 or SFTP protocol. For the access role, provide the Amazon Resource Name (ARN) of the AWS Identity and Access Management role to use.

For AS2 connectors

With AS2, you can send files by calling StartFileTransfer and specifying the file paths in the request parameter, SendFilePaths. We use the file’s parent directory (for example, for --send-file-paths /bucket/dir/file.txt, parent directory is /bucket/dir/) to temporarily store a processed AS2 message file, store the MDN when we receive them from the partner, and write a final JSON file containing relevant metadata of the transmission. So, the AccessRole needs to provide read and write access to the parent directory of the file location used in the StartFileTransfer request. Additionally, you need to provide read and write access to the parent directory of the files that you intend to send with StartFileTransfer.

If you are using Basic authentication for your AS2 connector, the access role requires the secretsmanager:GetSecretValue permission for the secret. If the secret is encrypted using a customer-managed key instead of the AWS managed key in Secrets Manager, then the role also needs the kms:Decrypt permission for that key.

For SFTP connectors

Make sure that the access role provides read and write access to the parent directory of the file location that's used in the StartFileTransfer request. Additionally, make sure that the role provides secretsmanager:GetSecretValue permission to AWS Secrets Manager.

Required: Yes

Type: String

Pattern: arn:.*role/.*

Minimum: 20

Maximum: 2048

Update requires: No interruption

BaseDirectory

The landing directory (folder) for files that are transferred by using the AS2 protocol.

Required: No

Type: String

Pattern: ^(|/.*)$

Maximum: 1024

Update requires: No interruption

CustomDirectories

A CustomDirectoriesType structure. This structure specifies custom directories for storing various AS2 message files. You can specify directories for the following types of files.

• Failed files

• MDN files

• Payload files

• Status files

• Temporary files

Required: No

Type: CustomDirectories

Update requires: No interruption

Description

The name or short description that's used to identify the agreement.

Required: No

Type: String

Pattern: ^[\u0021-\u007E]+$

Minimum: 1

Maximum: 200

Update requires: No interruption

EnforceMessageSigning

Determines whether or not unsigned messages from your trading partners will be accepted.

• ENABLED: Transfer Family rejects unsigned messages from your trading partner.

• DISABLED (default value): Transfer Family accepts unsigned messages from your trading partner.

Required: No

Type: String

Allowed values: ENABLED | DISABLED

Update requires: No interruption

LocalProfileId

A unique identifier for the AS2 local profile.

Required: Yes

Type: String

Pattern: ^p-([0-9a-f]{17})$

Minimum: 19

Maximum: 19

Update requires: No interruption

PartnerProfileId

A unique identifier for the partner profile used in the agreement.

Required: Yes

Type: String

Pattern: ^p-([0-9a-f]{17})$

Minimum: 19

Maximum: 19

Update requires: No interruption

PreserveFilename

Determines whether or not Transfer Family appends a unique string of characters to the end of the AS2 message payload filename when saving it.

• ENABLED: the filename provided by your trading parter is preserved when the file is saved.

• DISABLED (default value): when Transfer Family saves the file, the filename is adjusted, as described in File names and locations.

Required: No

Type: String

Allowed values: ENABLED | DISABLED

Update requires: No interruption

ServerId

A system-assigned unique identifier for a server instance. This identifier indicates the specific server that the agreement uses.

Required: Yes

Type: String

Pattern: ^s-([0-9a-f]{17})$

Minimum: 19

Maximum: 19

Update requires: Replacement

Status

The current status of the agreement, either ACTIVE or INACTIVE.

Required: No

Type: String

Allowed values: ACTIVE | INACTIVE

Update requires: No interruption

Tags

Key-value pairs that can be used to group and search for agreements.

Required: No

Type: Array of Tag

Maximum: 50

Update requires: No interruption

Return values

Ref

Fn::GetAtt

The Fn::GetAtt intrinsic function returns a value for a specified attribute of this type. The following are the available attributes and sample return values.

For more information about using the Fn::GetAtt intrinsic function, see Fn::GetAtt.

AgreementId

The unique identifier for the AS2 agreement, returned after the API call succeeds.