Configuration reference for file transfers to or from external users

9.0.20.000 This page provides information for creating payload JSON files that are required for the configuration of file transfers to and from external users.

For each type of object involved in file transfers — external user, virtual folder, and group (of users) —  a separate type of JSON file is required.

External User Data file

The following code sample demonstrates how to define an external user in the JSON file:

{
   "name": "username1",
   "email": "aaa@bbb.com",
   "description": "description",
   "company": "companyName",
   "phoneNumber": "44-16-5555555",
   "password": "********",
   "homeFolder": "vfolder1",
   "sshKey": "key",
   "as2Key": {
      "id": "as2KeyId",
      "partnersCertificateAlias": "partner_certificate",
      "destinationFolder": "folder_dest1"
   }
}

The External User Data file contains the following properties for each external user:

Property

Description

name

Defines the name of the external user.

The name must be unique, that is, not used by any other external user or user group.

email

Defines the Email address of the user.

description

(Optional) Defines a textual description of the user.

company

Defines the name of the company with which the user is associated.

phoneNumber

(Optional) Defines the user's phone number.

password

Defines a password that controls the external user's access to the file transfer mechanism.

Valid values:

  • Plain text
  • Secret:<secretKey>: Uses a predefined secret
  • KEEP_EXISTING: Keeps the existing password. Use this option when you update an existing external user and do not want to change the password.
  • GENERATE_PASSWORD: Sends a temporary unique password to the external user's email address, which must be changed within 24 hours. Use this option only when you add a new external user.

Note: If you specify a password, you do not need to specify an SSH key (the next property).

homeFolder

Determines whether the default folder for the external user to upload and download files is the B2B Home folder or one of the virtual folders. 

The user is automatically authorized to the selected folder.

To keep the default value (the B2B Home folder), do not include this parameter or leave its value empty (""). 

sshKey

Defines a key and passphrase for an SSH connection to a remote host

Note: If you specify an SSH key, you do not need to specify a password (the previous property).

as2Key

Defines specifications of a key for an Applicability Statement 2 (AS2) connection, which you can use to transfer Electronic Data Interchange (EDI) messages.

AS2 key specifications are optional when updating the definitions of an existing external user.

Do NOT include AS2 key specifications when defining a new external user.

    as2Id

Unique AS2 identification (ID)

    certificate

Name of the AS2 certificate

    destinationFolder

A destination folder to use in AS2 connections, one of the virtual folders associated with this external user

Folder Properties Data file

The following code sample demonstrates how to define a virtual folder in the JSON file:

{
   "name": "folder_1",
   "authorizedInternalUsers": [ "username1","username2"],
   "deleteFilesAfterDownload": true,
   "deleteFilesAfterDownloadByExternalUsers": true,
   "notifyByEmailWhenFileArrive" : true,
   "accessLevel" : "Write only",
   "fixedSubFolders": [
       {
           "name": "incoming",
           "accessLevel": "Full control",
           "operation": "",
           "originalName": ""
       },
       {
           "name": "outgoing",
           "accessLevel": "Read only",
           "operation": "",
           "originalName": ""
       }
    ],
   "authorizedExternalUsersAndGroupsExtended": [
      {
          "name": "user1",
          "accessLevel": "Read only"
      },
      {
          "name": "group1",
          "accessLevel": "Write only"
      }
    ],
   "retentionPolicy": 10,
   "sizeLimit": 100,
   "allowedFilePattern":"*.zip",
   "blockedFilePattern":"*.exe"
}

The Folder Properties Data file contains the following properties for each virtual folder:

Property

Description

name

Defines a logical name for the virtual folder.

authorizedInternalUsers

Defines the names of internal users that you want to have access to this folder.

For all internal users, use the * wildcard.

deleteFilesAfterDownload

Determines whether to delete the file after an internal user has downloaded it.

Values: true|false

Default: false

deleteFilesAfterDownloadByExternalUsers

Determines whether to delete the file after an external user has downloaded it.

Values: true|false

Default: false

notifyByEmailWhenFileArrive

Determines whether to send an email of notification to allowed users when a new file arrives and is ready for download.

Values: true|false

Default: false

accessLevel

Determines one of the following access levels for the virtual folder:

  • Full control: Enables external users to upload, download, rename, and delete files and sub-folders.
  • Read only: Enables external users to view and download files and sub-folders.
  • Write only: Enables external users to only upload files and sub-folders. Users cannot view.

fixedSubFolders

Defines sub-folders within the virtual folder. For each sub-folder, you define the following settings:

  • name of sub-folder
  • accessLevel to all files in the sub-folder, to override the access level of the virtual folder (see above)
  • operation to perform if you are updating the sub-folder, required only if you want to perform one of the following operations:
    • deleteDefinition: Delete a sub-folder from within the virtual folder, but keep its contents
    • deleteContent: Delete a sub-folder and all its contents
    • rename: Rename a sub-folder
  • originalName of the sub-folder that you want to rename (only for the rename operation)

authorizedExternalUsersAndGroupsExtended

Defines external users and user groups that are authorized to access this folder. For each user or group, you define the following settings:

  • name of user or group
  • accessLevel granted to the user or group

If there is a conflict between a user and a group to which it is associated, the access level with more authorizations takes precedence.

If there is a conflict between the access level of the user or group and the access level of the virtual folder or sub-folder, the access level with less authorizations takes precedence.

retentionPolicy

Determines the maximum number of hours to keep the file, before it is automatically deleted.

If you do not want to limit the retention time, specify a value of 0.

Default: 0

sizeLimit

Determines the maximum number of gigabytes allowed in the virtual folder before file uploading is blocked for external and internal users.

For unlimited file uploading, specify a value of 0.

Default: 0

allowedFilePattern

(Optional) Defines a file pattern for the files that external users are allowed to upload to this virtual folder. Include the * wildcard in the specified pattern.

By default, all files are allowed in the folder. Use this property to limit the allowed files by whitelisting a specific pattern.

blockedFilePattern

(Optional) Defines a file pattern for files that external users are NOT allowed to upload to this virtual folder. Include the * wildcard in the specified pattern.

By default, all files are allowed in the folder. Use this property to blacklist certain files based on a file pattern.

User Group Properties Data file and User Group Details Data file

The following code sample demonstrates how to define a new user group in the UserGroupPropertiesData JSON file:

{
"name": "group1",
"externalUsers": ["user1", "user2"],
"ldapGroups": ["ldapGroup1","ldapGroup2"]
}

If you are updating an existing user group, you use a UserGroupPropertiesData JSON file, in which you do NOT specify the name of the group:

{
"externalUsers": ["user1", "user2"],
"ldapGroups": ["ldapGroup1","ldapGroup2"]
}

These data files contain the following properties for each group of users:

Property

Description

name

(Only if adding a new user group) Name of the user group

externalUsers

Any number of external users to include in the group

ldapGroups

Any number of LDAP groups to include in the group

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*