Control-M Managed File Transfer Enterprise Configuration

The config mfte site service enables you to manage the setup of your integration with Control-M Managed File Transfer Enterprise, which enables file transfers to and from external users outside of your organization (such as business partners) from every Control-M MFT Enterprise site.

A site is an MFTE environment that contains either a single hub (MFT File transfer server) or a hub cluster (group of MFT file transfer servers that share the same data and settings). Each site has its own users, folders, groups, rules, settings, gateways, and processing rules.

This feature is offered in an environment with Control-M 9.0.21 or higher.

You can use API commands to configure the following areas and entities in Control-M Managed File Transfer Enterprise:

Hub Management

The following API commands are available for the management of hubs in Control-M MFT Enterprise:

config mfte:site:hub:status::get

The config mfte:site:hub:status::get command enables you to get the current status of the MFT Enterprise Hub, along with some basic information about the Hub (including details of the communication protocols used by the Hub and details regarding the associated gateways).

The Hub is the File Transfer Server that is installed with Control-M MFT, with added settings that enable it to manage external file transfers. In addition to the internal users that have access to the File Transfer Server, the Hub allows access also to external users.

To use this API command, you must have Control-M MFT Enterprise version 9.0.21 or higher installed.

This API command replaces config mft:hub:status::get, which you can still use if you have only one site, but will be deprecated in a future release.

CLI Syntax

Copy 
ctm config mfte:site:hub:status::get <siteName> <nodeId>

The following table describes the config mfte:site:hub:status::get command parameters.

Parameter

Description

siteName

Name of the site.

nodeId

ID of the host Agent of the Hub.

REST API Syntax

cURL:

Copy 
nodeId=abc-12-34
siteName=mysite
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" $endpoint/config/mfte/site/$siteName/hub/$nodeId/status

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

config mfte:site:cluster:hub::add

The config mfte:site:cluster:hub::add command enables you to add a Hub to a cluster in a High Availability (HA) environment.

The Hub is the File Transfer Server that is installed with Control-M MFT, with added settings that enable it to manage external file transfers. In addition to the internal users that have access to the File Transfer Server, the Hub allows access also to external users.

To use this API command, you must have Control-M MFT Enterprise version 9.0.21 or higher installed.

This API command replaces config mft:cluster:hub::add, which you can still use if you have only one site, but will be deprecated in a future release.

CLI Syntax

Copy 
ctm config mfte:site:cluster:hub::add <siteName> <agentName>

The following table describes the config mfte:site:cluster:hub::add command parameters.

Parameter

Description

siteName

Name of the site.

agentName

Name of the host with Agent that you want to add to the cluster.

REST API Syntax

cURL:

Copy 
agentName=myhost
siteName=mysite
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X POST "$endpoint/config/mfte/site/$siteName/cluster/hub/$agentName"

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

config mfte:site:cluster:hub::delete

The config mfte:site:cluster:hub::delete command enables you to remove a Hub from a cluster in a High Availability (HA) environment.

To use this API command, you must have Control-M MFT Enterprise version 9.0.21 or higher installed.

This API command replaces config mft:cluster:hub::delete, which you can still use if you have only one site, but will be deprecated in a future release.

CLI Syntax

Copy 
ctm config mfte:site:cluster:hub::delete <siteName> <agentname>

The following table describes the config mfte:site:cluster:hub::delete command parameters.

Parameter

Description

siteName

Name of the site.

agentName

Name of the host with Agent that you want to remove from the cluster.

REST API Syntax

cURL:

Copy 
agentName=myhost
siteName=mysite
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X DELETE "$endpoint/config/mfte/site/$siteName/cluster/hub/$agentName"

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

Gateway Management

The following API commands are available for the management of gateways in Control-M MFT Enterprise:

config mfte:site:gateway::add

The config mfte:site:gateway::add command enables you to add a Control-M MFT Enterprise Gateway.

The MFT Enterprise Gateway is a proxy server that is installed on Linux in the demilitarized zone (DMZ), also known as a perimeter network. It listens for incoming connections from external user accounts defined in the MFT Hub. The MFT Enterprise Gateway communicates with the Hub, but does not store any transfer file data.

To use this API command, you must have Control-M MFT Enterprise version 9.0.21 or higher installed.

This API command replaces config mft:gateway::add, which you can still use if you have only one site, but will be deprecated in a future release.

CLI Syntax

Copy 
ctm config mfte:site:gateway::add <siteName> <gatewayHost> <port>

The following table describes the config mfte:site:gateway::add command parameters.

Parameter

Description

siteName

Name of the site.

gatewayHost

Name of the gateway host.

port

Number of the port that the gateway listens to.

Default: 9443

REST API Syntax

cURL:

Copy 
siteName=mysite
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X POST "$endpoint/config/mfte/site/$siteName/gateway/$gatewayHost/$port"

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

config mfte:site:gateway::delete

The config mfte:site:gateway::delete command enables you to remove a Control-M MFT Enterprise Gateway.

To use this API command, you must have Control-M MFT Enterprise version 9.0.21 or higher installed.

This API command replaces config mft:gateway::delete, which you can still use if you have only one site, but will be deprecated in a future release.

CLI Syntax

Copy 
ctm config mfte:site:gateway::delete <siteName> <gatewayHost>

The following table describes the config mfte:site:gateway::delete command parameters.

Parameter

Description

siteName

Name of the site.

gatewayHost

Name of the host of the gateway that you want to delete.

REST API Syntax

cURL:

Copy 
gatewayHost=myhost
siteName=mysite
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X DELETE "$endpoint/config/mfte/site/$siteName/gateway/$gatewayHost"

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

config mfte:site:gateways::get

The config mfte:site:gateways::get command enables you to get the details of all the installed MFT Enterprise Gateways. Details for each gateway include the gateway host, port, status (OK or ERROR), and a status message.

To use this API command, you must have Control-M MFT Enterprise version 9.0.21 or higher installed.

This API command replaces config mft:gateways::get, which you can still use if you have only one site, but will be deprecated in a future release.

CLI Syntax

Copy 
ctm config mfte:site:gateways::get <siteName>

Where siteName is the name of the site.

REST API Syntax

cURL:

Copy 
siteName=mysite
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" "$endpoint/config/mfte/site/$siteName/gateways"

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

Virtual Folder Management

The following API commands are available for the management of virtual folders in Control-M MFT Enterprise:

config mfte:site:virtualfolder::add

The config mfte:site:virtualfolder::add command enables you to create a new virtual folder based on folder settings that you define through a Folder Properties file.

Virtual folders are used to transfer incoming and outgoing files between external and internal users. Authorizations applied at the folder level determine which external and internal users can access the folders. Folders can be configured to define a maximum retention period, and can generate email notifications to associated users when new files are available.

To use this API command, you must have Control-M MFT Enterprise version 9.0.21 or higher installed.

This API command replaces config mft:virtualfolder::add, which you can still use if you have only one site, but will be deprecated in a future release.

CLI Syntax

Copy 
ctm config mfte:site:virtualfolder::add <siteName> <folderName> [-f <folderPropertiesData.json>]

The following table describes the config mfte:site:virtualfolder::add command parameters.

Parameter

Description

siteName

Name of the site.

folderName

Name of the virtual folder that you want to create.

folderPropertiesData

Full path and name of a .json payload file that contains definitions for the virtual folder, as described in Folder Properties Data File.

REST API Syntax

cURL:

Copy 
siteName=mysite
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -F "[email protected]"
-X POST $endpoint/config/mfte/site/$siteName/virtualfolder

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

config mfte:site:virtualfolder::update

The config mfte:site:virtualfolder::update command enables you to update an existing virtual folder based on folder settings that you define through a Folder Properties file.

To use this API command, you must have Control-M MFT Enterprise version 9.0.21 or higher installed.

This API command replaces config mft:virtualfolder::update, which you can still use if you have only one site, but will be deprecated in a future release.

Besides applying all settings that are explicitly defined in the Folder Properties file, the Update process also sets all remaining settings to default values. Therefore, as a best practice, perform the following sequence of steps:

  1. Obtain ALL current settings of the virtual folder by running the config mfte:site:virtualfolders::get command.

  2. Use the current definitions of the relevant virtual folder (from the output of the previous step) to create your Folder Properties file, a .json file.

  3. In the Folder Properties file, change the specific settings that you want to update, and keep all other content in the file.

    For full details about all folder settings, see Folder Properties Data File.

  4. Proceed with running the Update command.

CLI Syntax

Copy 
ctm config mfte:site:virtualfolder::update <siteName> <folderName> [-f <folderPropertiesData.json>]

The following table describes the config mfte:site:virtualfolder::update command parameters.

Parameter

Description

siteName

Name of the site.

folderName

Name of the virtual folder that you want to update.

folderPropertiesData

Full path and name of a .json payload file that contains definitions for the virtual folder, as described in Folder Properties Data File.

REST API Syntax

cURL:

Copy 
folderName=folder3
siteName=mysite
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -F "[email protected]"
-X POST "$endpoint/config/mfte/site/$siteName/virtualfolder/$folderName"

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

config mfte:site:virtualfolder::delete

The config mfte:site:virtualfolder::delete command enables you to delete an existing virtual folder.

To use this API command, you must have Control-M MFT Enterprise version 9.0.21 or higher installed.

This API command replaces config mft:virtualfolder::delete, which you can still use if you have only one site, but will be deprecated in a future release.

CLI Syntax

Copy 
ctm config mfte:site:virtualfolder::delete <siteName> <folderName>

The following table describes the config mfte:site:virtualfolder::delete command parameters.

Parameter

Description

siteName

Name of the site.

folderName

Name of the virtual folder that you want to delete.

REST API Syntax

cURL:

Copy 
folderName=folder5
siteName=mysite
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X DELETE "$endpoint/config/mfte/site/$siteName/virtualfolder/$folderName"

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

config mfte:site:virtualfolders::get

The config mfte:site:virtualfolders::get command enables you to get the details of defined virtual folders.

The output is returned in JSON format. You can use this output as a template for your own Folder Properties files when creating new virtual folders or editing existing virtual folders. For more information about the syntax of virtual folder definitions, see Folder Properties Data File.

To use this API command, you must have Control-M MFT Enterprise version 9.0.21 or higher installed.

This API command replaces config mft:virtualfolders::get, which you can still use if you have only one site, but will be deprecated in a future release.

CLI Syntax

Copy 
ctm config mfte:site:virtualfolders::get <siteName> [-s <search query>]

The following table describes the config mfte:site:virtualfolders::get command parameters.

Parameter

Description

siteName

Name of the site.

search query

Optional parameter that runs a search and filters the output based on folder name.

For multiple values, use wildcards (* or ?) or commas.

-s "name=a*"

REST API Syntax

cURL:

Copy 
siteName=mysite
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" "$endpoint/config/mfte/site/$siteName/users/virtualfolders"
                     
curl -H "$AuthHeader" "$endpoint/config/mfte/site/$siteName/users/virtualfolders?name=a*"

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

config mfte:site:virtualfolder:user::add

The config mfte:site:virtualfolder:user::add command enables you to add an external user or a user group to an existing virtual folder's list of authorized users and groups.

To use this API command, you must have Control-M MFT Enterprise version 9.0.21 or higher installed.

This API command replaces config mft:virtualfolder:user::add, which you can still use if you have only one site, but will be deprecated in a future release.

CLI Syntax

Copy 
ctm config mfte:site:virtualfolder:user::add <siteName> <folderName> <userOrGroup>

The following table describes the config mfte:site:virtualfolder:user::add command parameters.

Parameter

Description

siteName

Name of the site.

folderName

Name of the virtual folder.

userOrGroup

Name of external user or user group.

REST API Syntax

cURL:

Copy 
folderName=folder5
siteName=mysite
userOrGroup=userA
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X POST "$endpoint/config/mfte/site/$siteName/virtualfolder/$folderName/user/$userOrGroup"

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

config mfte:site:virtualfolder:user::delete

The config mfte:site:virtualfolder:user::delete command enables you to remove an external user or user group from an existing virtual folder's list of authorized users and groups.

To use this API command, you must have Control-M MFT Enterprise version 9.0.21 or higher installed.

This API command replaces config mft:virtualfolder:user::delete, which you can still use if you have only one site, but will be deprecated in a future release.

CLI Syntax

Copy 
ctm config mfte:site:virtualfolder:user::delete <siteName> <folderName> <userOrGroup>

The following table describes the config mfte:site:virtualfolder:user::delete command parameters.

Parameter

Description

siteName

Name of the site.

folderName

Name of the virtual folder.

userOrGroup

Name of external user or user group.

REST API Syntax

cURL:

Copy 
folderName=folder5
siteName=mysite
userOrGroup=userA
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X DELETE "$endpoint/config/mfte/site/$siteName/virtualfolder/$folderName/user/$userOrGroup"

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

Folder Properties Data File

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

Copy 
{
    "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:

The following table describes the File Properties Data file 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.

Valid Values:

  • true

  • false

Default: false

deleteFilesAfterDownloadByExternalUsers

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

Valid 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.

Valid 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.

Define the following settings on each folder:

  • name: Defines the Sub-folder name.

  • accessLevel: Determines the access level for all files in the sub-folder, which overrides thevirtual folder access level, as described 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) 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) 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.

External User Management

The following API commands are available for the management of external users in Control-M MFT Enterprise:

config mfte:site:externaluser::add

The config mfte:site:externaluser::add command enables you to create a new external user based on user definitions that you provide through the command or through an External User Data file.

To use this API command, you must have Control-M MFT Enterprise version 9.0.21 or higher installed.

This API command replaces config mft:externaluser::add, which you can still use if you have only one site, but will be deprecated in a future release.

CLI Syntax

Copy 
ctm config mfte:site:externaluser::add <siteName> <userName> <email> <companyName> [password] [-f <ExternalUserData.json>] [-p]

The following table describes the config mfte:site:externaluser::add command parameters.

Parameter

Description

siteName

Name of the site.

userName

Name of the external user that you want to create.

The name must be unique and not in use by any other external user or user group.

email

Email address of the external user.

companyName

Name of the company with which the external user is associated.

password

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.

ExternalUserData

Full path and name of a .json payload file that contains definitions for the external user, as described in External User Data File.

Specifying the password through the command is optional, because you have the following alternatives:

  • Provide a password or predefined secret through the External User Data file.

  • Use the -p (or -prompt) option through the CLI. With this option, you do not need to enter the password in the command. Instead, you are prompted for the password (twice) after you enter the command.

    If you use both the password parameter and the -p option, the password that you enter through the command prompt overrides the password that you specify in the command.

REST API Syntax

cURL:

Copy 
siteName=mysite
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -F "[email protected]"
-X POST $endpoint/config/mfte/site/$siteName/externalUserData

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

config mfte:site:externaluser::update

The config mfte:site:externaluser::update command enables you to update an existing external user based on user definitions that you provide through an External User Data file.

This API command replaces config mft:externaluser::update, which you can still use if you have only one site, but will be deprecated in a future release.

To use this API command, you must have Control-M MFT Enterprise version 9.0.21 or higher installed.

Besides applying all settings that are explicitly defined in the External User Data file, the Update process also sets all remaining settings to default values. Therefore, as a best practice, perform the following sequence of steps:

  1. Obtain ALL current settings of the external user by running the config mfte:site:externalusers::get command.

  2. Use the current definitions of the relevant external user (from the output of the previous step) to create your External User Data file, a .json file.

  3. In the External User Data file, change the specific settings that you want to update, and keep all other content in the file.

    For full details about all user definitions, see External User Data File.

  4. Proceed with running the Update command.

CLI Syntax

Copy 
ctm config mfte:site:externaluser::update <siteName> <userName> <-f ExternalUserData.json> [-p]

The following table describes the config mfte:site:externaluser::update command parameters.

Parameter

Description

siteName

Name of the site.

userName

Name of the external user that you want to update.

ExternalUserData

Full path and name of a .json payload file that contains definitions for the external user, as described in External User Data File.

If you do not want to specify the user's password through the External User Data file, you can include the -p (or -prompt) option in the CLI command. With this option, you are prompted for the password (twice) after you enter the command.

REST API Syntax

cURL:

Copy 
userName=user3
siteName=mysite
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -F "[email protected]"
-X POST "$endpoint/config/mfte/site/$siteName/externaluser/$username"

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

config mfte:site:externaluser::delete

The config mfte:site:externaluser::delete command enables you to delete an existing external user.

To use this API command, you must have Control-M MFT Enterprise version 9.0.21 or higher installed.

This API command replaces config mft:externaluser::delete, which you can still use if you have only one site, but will be deprecated in a future release.

CLI Syntax

Copy 
ctm config mfte:site:externaluser::delete <siteName> <userName>

The following table describes the config mfte:site:externaluser::delete command parameters.

Parameter

Description

siteName

Name of the site.

userName

Name of the external user that you want to delete.

REST API Syntax

cURL:

Copy 
username=user5
siteName=mysite
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X DELETE "$endpoint/config/mfte/site/$siteName/externaluser/$username"

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

config mfte:site:externalusers::get

The config mfte:site:externalusers::get command enables you to get the details of defined external users.

The output is returned in JSON format. You can use this output as a template for your own External User Data files when creating new external users or editing existing external users. For more information about the syntax of user definitions, see External User Data File.

To use this API command, you must have Control-M MFT Enterprise version 9.0.21 or higher installed.

This API command replaces config mft:externalusers::get, which you can still use if you have only one site, but will be deprecated in a future release.

CLI Syntax

Copy 
ctm config mfte:site:externalusers::get  <siteName> [-s <search query>]

The following table describes the config mfte:site:externalusers::get command parameters.

Parameter

Description

siteName

Name of the site.

search query

Optional parameter that filters results by running a search using the query string format:

"field1=criteria1&field2=criteria2&field3=criteria3"

The following fields are available for use in the search query:

  • name

  • email

  • description

  • company

  • phoneNumber

For multiple values, use wildcards (* or ?) or commas.

REST API Syntax

cURL:

Copy 
siteName=mysite
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" $endpoint/config/mfte/site/$siteName/externalusers
                     
curl -H "$AuthHeader" "$endpoint/config/mfte/site/$siteName/externalusers?name=a*&email=b*"

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

config mfte:site:externaluser:virtualfolders::get

The config mfte:site:externaluser:virtualfolders::get command enables you to get a list of virtual folders that a specific external user is authorized to access.

To use this API command, you must have Control-M MFT Enterprise version 9.0.21 or higher installed.

This API command replaces config mft:externaluser:virtualfolders::get, which you can still use if you have only one site, but will be deprecated in a future release.

CLI Syntax

Copy 
ctm config mfte:site:externaluser:virtualfolders::get <siteName> <userName>

The following table describes the config mfte:site:externaluser:virtualfolders::get command parameters.

Parameter

Description

siteName

Name of the site.

userName

Name of the external user.

REST API Syntax

cURL:

Copy 
userName=user5
siteName=mysite
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" $endpoint/config/mfte/site/$siteName/externaluser/$username/virtualfolders

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

config mfte:site:externaluser::lock

The config mfte:site:externaluser::lock command enables you to lock an external user, which blocks this user from logging into Control-M MFT Enterprise or performing actions related to file transfers.

To use this API command, you must have Control-M MFT Enterprise version 9.0.21 or higher installed.

This API command replaces config mft:externaluser::lock, which you can still use if you have only one site, but will be deprecated in a future release.

CLI Syntax

Copy 
ctm config mfte:site:externaluser::lock <siteName> <userName>

The following table describes the config mfte:site:externaluser::lock command parameters.

Parameter

Description

siteName

Name of the site.

userName

Name of the external user.

REST API Syntax

cURL:

Copy 
userName=user5
siteName=mysite
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X POST $endpoint/config/mfte/site/$siteName/externaluser/$user/lock

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

config mfte:site:externaluser::unlock

The config mfte:site:externaluser::unlock command enables you to unlocks an external user that is currently locked out of Control-M MFT Enterprise / For example, a user that you previously locked manually, or a user that was locked out due to a period of inactivity, repeated failed login attempts, or password expiration.

To use this API command, you must have Control-M MFT Enterprise version 9.0.21 or higher installed.

This API command replaces config mft:externaluser::unlock, which you can still use if you have only one site, but will be deprecated in a future release.

CLI Syntax

Copy 
ctm config mfte:site:externaluser::unlock <siteName> <userName>

The following table describes the config mfte:site:externaluser::unlock command parameters.

Parameter

Description

siteName

Name of the site.

userName

Name of the external user.

REST API Syntax

cURL:

Copy 
userName=user5
siteName=mysite
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X POST $endpoint/config/mfte/site/$siteName/externaluser/$user/unlock

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

config mfte:site:externalusers::unlock

The config mfte:site:externalusers::unlock command enables you to unlock all external users that are currently locked out of Control-M MFT Enterprise .

To use this API command, you must have Control-M MFT Enterprise version 9.0.21 or higher installed.

This API command replaces config mft:externalusers::unlock, which you can still use if you have only one site, but will be deprecated in a future release.

CLI Syntax

Copy 
ctm config mfte:site:externalusers::unlock <siteName>

Where siteName is the name of the site.

REST API Syntax

cURL:

Copy 
siteName=mysite
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X POST $endpoint/config/mfte/site/$siteName/externalusers/unlock

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

config mfte:site:externalusers:locked::get

The config mfte:site:externalusers:locked::get command enables you to get a list of external users who are currently locked including the reason for each locked user.

To use this API command, you must have Control-M MFT Enterprise version 9.0.21 or higher installed.

This API command replaces config mft:externalusers:locked::get, which you can still use if you have only one site, but will be deprecated in a future release.

CLI Syntax

Copy 
ctm config mfte:site:externalusers:locked::get <siteName>

Where siteName is the name of the site.

REST API Syntax

cURL:

Copy 
siteName=mysite
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" $endpoint/config/mfte/site/$siteName/externalusers/locked

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

External User Data File

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

Copy 
{ 
   "name": "username1",
   "email": "[email protected]",
   "description": "description",
   "company": "companyName",
   "phoneNumber": "44-16-5555555",
   "password": "********",
   "homeFolder": "vfolder1",
   "sshKey": "key",
   "as2Key": {
      "id": "as2KeyId",
      "partnersCertificateAlias": "partner_certificate",
      "destinationFolder": "folder_dest1"
   }
}

The following table describes the External User Data file 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.

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.

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.

Group Management

The following API commands are available for the management of groups in Control-M MFT Enterprise:

config mfte:site:usergroup::add

The config mfte:site:usergroup::add command enables you to create a new group of users (external users or ldap users) based on group settings that you define through a User Group Properties file.

To use this API command, you must have Control-M MFT Enterprise version 9.0.21 or higher installed.

This API command replaces config mft:usergroup::add, which you can still use if you have only one site, but will be deprecated in a future release.

CLI Syntax

Copy 
ctm config mfte:site:usergroup::add <siteName> <groupName> [-f <UserGroupPropertiesData.json>]

The following table describes the config mfte:site:usergroup::add command parameters.

Parameter

Description

siteName

Name of the site.

groupName

Name of the group that you want to create.

UserGroupPropertiesData

Full path and name of a .json payload file that contains definitions for the group, as described in User Group Properties Data File and User Group Details Data File.

REST API Syntax

cURL:

Copy 
siteName=mysite
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -F "[email protected]"
-X POST $endpoint/config/mfte/site/$siteName/usergroup

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

config mfte:site:usergroup::update

The config mfte:site:usergroup::update command enables you to update an existing group of users (external users or ldap users) based on group settings that you define through a User Group Properties file.

To use this API command, you must have Control-M MFT Enterprise version 9.0.21 or higher installed.

This API command replaces config mft:usergroup::update, which you can still use if you have only one site, but will be deprecated in a future release.

CLI Syntax

Copy 
ctm config mfte:site:usergroup::update <siteName> <groupName> [-f <UserGroupPropertiesData.json>]

The following table describes the config mfte:site:usergroup::update command parameters.

Parameter

Description

siteName

Name of the site.

groupName

Name of the group that you want to update.

UserGroupPropertiesData

Full path and name of a .json payload file that contains definitions for the group, as described in User Group Properties Data File and User Group Details Data File.

This file is similar to the properties file that you use when adding a new user group. However, in the file used for updating an existing user group, you do NOT specify the name of the group.

REST API Syntax

cURL:

Copy 
groupName=group4
siteName=mysite
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -F "[email protected]"
-X POST "$endpoint/config/mfte/site/$siteName/usergroup/$usergroup"

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

config mfte:site:usergroup::delete

The config mfte:site:usergroup::delete command enables you to delete an existing group of users.

To use this API command, you must have Control-M MFT Enterprise version 9.0.21 or higher installed.

This API command replaces config mft:usergroup::delete, which you can still use if you have only one site, but will be deprecated in a future release.

CLI Syntax

Copy 
ctm config mfte:site:usergroup::delete <siteName> <groupName>

The following table describes the config mfte:site:usergroup::delete command parameters.

Parameter

Description

siteName

Name of the site.

groupName

Name of the group that you want to delete.

REST API Syntax

cURL:

Copy 
groupName=group6
siteName=mysite
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X DELETE "$endpoint/config/mfte/site/$siteName/usergroup/$groupname"

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

config mfte:site:usergroups::get

The config mfte:site:usergroups::get command enables you to get the details of defined groups.

The output is returned in JSON format. You can use this output as a template for your own User Group Properties files when creating new groups or editing existing groups. For more information about the syntax of group definitions, see User Group Properties Data File and User Group Details Data File.

To use this API command, you must have Control-M MFT Enterprise version 9.0.21 or higher installed.

This API command replaces config mft:usergroups::get, which you can still use if you have only one site, but will be deprecated in a future release.

CLI Syntax

Copy 
ctm config mfte:site:usergroups::get <siteName> [-s <search query>]

The following table describes the config mfte:site:usergroups::get command parameters.

Parameter

Description

siteName

Name of the site.

search query

Optional parameter used to filter results by running a search using the query string format:
"field1=criteria1&field2=criteria2&field3=criteria3"

The following fields are available for use in the search query:

  • name

  • externalUsers

  • ldapGroups

For multiple values, use wildcards (* or ?) or commas.

cURL:

Copy 
siteName=mysite
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" "$endpoint/config/mfte/site/$siteName/usergroups"
                     
curl -H "$AuthHeader" "$endpoint/config/mfte/site/$siteName/usergroups?name=a*&externalUsers=b*"

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

config mfte:site:usergroup:user::add

The config mfte:site:usergroup:user::add command enables you to add an external user to an existing group.

To use this API command, you must have Control-M MFT Enterprise version 9.0.21.100 or higher installed.

CLI Syntax

Copy 
ctm config mfte:site:usergroup:user::add <siteName> <groupName> <userName>

The following table describes the config mfte:site:usergroup:user::add command parameters.

Parameter

Description

siteName

Defines the name of the site.

groupName

Defines the name of the existing group that you want to add to.

userName

Defines the name of the user that you want to add to the existing group.

REST API Syntax

cURL:

Copy 
siteName=mysite
groupName=Group1
userName=John
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X POST $endpoint/config/mfte/site/$siteName/groupName/$groupName/userName/$userName

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

config mfte:site:usergroup:user::delete

The config mfte:site:usergroup:user::delete command enables you to delete an external user from an existing group.

To use this API command, you must have Control-M MFT Enterprise version 9.0.21.100 or higher installed.

CLI Syntax

Copy 
ctm config mfte:site:usergroup:user::delete <siteName> <groupName> <userName>

The following table describes the config mfte:site:usergroup:user::delete command parameters.

Parameter

Description

siteName

Defines the name of the site.

groupName

Defines the name of the existing group that you want to delete from.

userName

Defines the name of the user that you want to delete from the existing group.

REST API Syntax

cURL:

Copy 
siteName=mysite
groupName=Group1
userName=John
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X DELETE $endpoint/config/mfte/site/$siteName/groupName/$groupName/userName/$userName

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

config mfte:site:usergroup:ldapGroup::add

The config mfte:site:usergroup:ldapGroup::add command enables you to add an LDAP group to an existing group.

To use this API command, you must have Control-M MFT Enterprise version 9.0.21.100 or higher installed.

CLI Syntax

Copy 
ctm config mfte:site:usergroup:ldapGroup::add <siteName> <groupName> <ldapGroupName>

The following table describes the config mfte:site:usergroup:ldapGroup::add command parameters.

Parameter

Description

siteName

Defines the name of the site.

groupName

Defines the name of the existing group that you want to add to.

ldapGroupName

Defines the name of the LDAP group that you want to add to the existing group.

REST API Syntax

cURL:

Copy 
siteName=mysite
groupName=Group1
ldapGroupName=LDAP_Group1
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X POST $endpoint/config/mfte/site/$siteName/groupName/$groupName/ldapGroupName/$ldapGroupName

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

config mfte:site:usergroup:ldapGroup::delete

The config mfte:site:usergroup:ldapGroup::delete command enables you to delete an LDAP group from an existing group.

To use this API command, you must have Control-M MFT Enterprise version 9.0.21.100 or higher installed.

CLI Syntax

Copy 
ctm config mfte:site:usergroup:ldapGroup::delete <siteName> <groupName> <ldapGroupName>

The following table describes the config mfte:site:usergroup:ldapGroup::delete command parameters.

Parameter

Description

siteName

Defines the name of the site.

groupName

Defines the name of the existing group that you want to delete from.

ldapGroupName

Defines the name of the LDAP group that you want to delete from the existing group.

REST API Syntax

cURL:

Copy 
siteName=mysite
groupName=Group1
ldapGroupName=LDAP_Group1
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X DELETE $endpoint/config/mfte/site/$siteName/groupName/$groupName/ldapGroupName/$ldapGroupName

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

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:

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

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

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

The following table describes the User Group 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.

ldapUsers

Any number of LDAP users to include in the group.

Processing Rule Management

The following API commands are available for the management of processing rules in Control-M MFT Enterprise:

config mfte:site:processingRule::add

The config mfte:site:processingRule::add command enables you to add a new processing rule based on rule settings that you define through a Rule Properties file.

MFT Enterprise Processing Rules enable you to automate specific actions to files that were uploaded or downloaded by external or internal users to specific virtual folders. These actions are based on specific conditions that you define for each rule, such as filename, size, or user. After (or before for download) an external or internal user uploads or downloads a file from the Hub, it is processed based on defined rules such as moving the file to another location and sending alert email messages.

To use this API command, you must have Control-M MFT Enterprise 9.0.21.200 or higher installed.

CLI Syntax

Copy 
ctm config mfte:site:processingRule::add <siteName> <rulePropertiesFile>

The following table describes the config mfte:site:processingRule::add command parameters.

Parameter

Description

siteName

Defines the name of the site.

rulePropertiesFile

Defines the full path and name of a .json payload file that contains definitions for the processing rule, as described in Rule Properties File.

REST API Syntax

cURL:

Copy 
siteName=mysite
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -F "[email protected]"
-X POST $endpoint/config/mfte/site/$siteName/processingRule

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

config mfte:site:processingRule::update

The config mfte:site:processingRule::update command enables you to update an existing processing rule based on rule settings that you define through a Rule Properties file.

To use this API command, you must have Control-M MFT Enterprise 9.0.21.200 or higher installed.

Besides applying all settings that are explicitly defined in the Rule Properties file, the Update process also sets all remaining settings to default values. Therefore, as a best practice, do the following:

  1. Obtain ALL current settings of the rule by running the config mfte:site:processingRules::get command.

  2. Use the current definitions of the relevant rule (from the output of the previous step) to create your Rule Properties file, a .json file.

  3. In the Rule Properties file, change the specific settings that you want to update, and keep all other content in the file.

    For full details about all rule settings, see Rule Properties File.

  4. Proceed with running the Update command.

CLI Syntax

Copy 
ctm config mfte:site:processingRule::update <siteName> <ruleName> <rulePropertiesFile>

The following table describes the config mfte:site:processingRule::update command parameters.

Parameter

Description

siteName

Defines the name of the site.

ruleName

Defines the name of the processing rule that you want to update.

rulePropertiesFile

Defines the full path and name of a .json payload file that contains definitions for the processing rule, as described in Rule Properties File.

REST API Syntax

cURL:

Copy 
ruleName=rule3
siteName=mysite
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -F "[email protected]"
-X POST "$endpoint/config/mfte/site/$siteName/ruleName/$ruleName"

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

config mfte:site:processingRule::delete

The config mfte:site:processingRule::delete command enables you to delete an existing processing rule.

To use this API command, you must have Control-M MFT Enterprise 9.0.21.200 or higher installed.

CLI Syntax

Copy 
ctm config mfte:site:processingRule::delete <siteName> <ruleName>

The following table describes the config mfte:site:processingRule::delete command parameters.

Parameter

Description

siteName

Defines the name of the site.

ruleName

Defines the name of the processing rule that you want to delete.

REST API Syntax

cURL:

Copy 
ruleName=rule5
siteName=mysite
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X DELETE "$endpoint/config/mfte/site/$siteName/ruleName/$ruleName"

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

config mfte:site:processingRules::get

The config mfte:site:processingRules::get command enables you to get the details of defined processing rules.

The output is returned in JSON format. You can use this output as a template for your own Rule Properties files when you create new processing rules or editing existing rules. For more information about the syntax of rule definitions, see Rule Properties File.

To use this API command, you must have Control-M MFT Enterprise 9.0.21.200 or higher installed.

CLI Syntax

Copy 
ctm config:mfte:site:processingRules::get <siteName> [-s <search query>]

The following table describes the config mfte:site:processingRules::get command parameters.

Parameter

Description

siteName

Defines the name of the site.

search query

(Optional) Defines a search to filter the output based on any combination of the following fields:

  • name

  • description

  • priority

  • status

The format for the query string is "field1=criteria1&field2=criteria2".

Use * (asterisks) or ? (question marks) for wildcards. Use , (commas) to specify multiple field criteria.

name=myRule&description=a*

REST API Syntax

cURL:

Copy 
siteName=mysite
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token
                 
curl -H "$AuthHeader" "$endpoint/config/mfte/site/$siteName/processingRules?name=myRule&description=a*"

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

config mfte:site:processingRule::disable

The config mfte:site:processingRule::disable command enables you to temporarily disable a processing rule (without deleting the rule).

To use this API command, you must have Control-M MFT Enterprise 9.0.21.200 or higher installed.

CLI Syntax

Copy 
ctm config mfte:site:processingRule::disable <siteName> <ruleName>

The following table describes theconfig mfte:site:processingRule::disable command parameters.

Parameter

Description

siteName

Defines the name of the site.

ruleName

Defines the name of the processing rule that you want to disable.

REST API Syntax

cURL:

Copy 
ruleName=rule5
siteName=mysite
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X POST "$endpoint/config/mfte/site/$siteName/ruleName/$ruleName/disable"

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

config mfte:site:processingRule::enable

The config mfte:site:processingRule::enable command enables you to re-enable a processing rule that was previously disabled.

To use this API command, you must have Control-M MFT Enterprise 9.0.21.200 or higher installed.

CLI Syntax

Copy 
ctm config mfte:site:processingRule::enable <siteName> <ruleName>

The following table describes the config mfte:site:processingRule::enable command parameters.

Parameter

Description

siteName

Defines the name of the site.

ruleName

Defines the name of the processing rule that you want to enable.

REST API Syntax

cURL:

Copy 
ruleName=rule5
siteName=mysite
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X POST "$endpoint/config/mfte/site/$siteName/ruleName/$ruleName/enable"

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

Rule Properties File

The following code sample demonstrates how to define a processing rule in the JSON file:

Copy 
{
    "name": "ruleAllConditionsAndActions",
    "description": "Rule All Conditions And Actions",
    "priority": 2,
    "ruleType": "Pull",
    "status": "Enabled",
    "conditions": {
        "fileNamePatternCondition": {
            "caseSensitive": false,
            "excludeFiles": false,
            "isRegex": false,
            "pattern": "myPattern.txt"
        },
        "fileSizeCondition": {
            "maxSize": 100.0,
            "maxUnits": "GB",
            "minSize": 20.0,
            "minUnits": "KB"
        },
        "userCondition": {
            "companyNames": [
                "bmc"
            ],
            "userOrGroupNames": [
                "user1"
            ]
        },
        "virtualFolderCondition": {
            "caseSensitive": false,
            "isRegex": false,
            "subDirectory": "",
            "virtualFolderNames": [
                "folder2"
            ],
            "virtualFolderPatterns": [
                "folder1.*"
            ]
        }
    },
    "postActions": [
        {
            "actionType": "AddEventAction",
            "addEventActionData": {
                "actionFailsBehaviour": {
                    "deleteFile": false,
                    "nextActionBehaviour": "Abort"
                },
                "eventName": "event2",
                "eventDate": "ODAT"
            }
        },
        {
            "actionType": "RunFolderJobAction",
            "runFolderJobActionData": {
                "actionFailsBehaviour": {
                    "deleteFile": true,
                    "nextActionBehaviour": "Abort"
                },
                "folderName": "myFolder",
                "hold": true,
                "jobName": "myJob",
                "orderNow": true,
                "placeInFolder": "New",
                "variables": [
                    {
                        "key": "FILE_NAME",
                        "value": "12"
                    }
                ]
            }
        },
        {
            "actionType": "EmailNotificationAction",
            "emailNotificationActionData": {
                "actionFailsBehaviour": {
                    "deleteFile": false,
                    "nextActionBehaviour": "Abort"
                },
                "emailMessage": "This message is important.",
                "emailSubject": "Important",
                "notifyTo": [
                    "[email protected]"
                ]
            }
        },
        {
            "actionType": "FileOperationAction",
            "fileOperationActionData": {
                "actionFailsBehaviour": {
                    "deleteFile": false,
                    "nextActionBehaviour": "Skip"
                },
                "operator": "Move",
                "renameDestinationFile": "renameDest.txt",
                "targetDirectory": "/folder2/",
                "fileLocationType": "Relative"
            }
        },
        {
            "actionType": "RunCommandAction",
            "runCommandActionData": {
                "actionFailsBehaviour": {
                    "deleteFile": false,
                    "nextActionBehaviour": "Abort"
                },
                "commandPath": "echo 10",
                "successfulReturnCodes": "0"
            }
        }
    ],
    "preActions": [
        {
            "actionType": "RunCommandAction",
            "runCommandActionData": {
                "actionFailsBehaviour": {
                    "deleteFile": false,
                    "nextActionBehaviour": "Abort"
                },
                "commandPath": "echo 10",
                "successfulReturnCodes": "0"
            }
        }
    ]
}

The following table describes the Rule Properties file properties for each processing rule.

Property

Description

name

 Defines the name of the rule.

description

 Describes the purpose of the rule.

priority

Determines the priority level for this rule.

If you define a higher priority level, this rule will be processed before other matching rules.

Valid Values: 1 (highest priority)–10 (lowest priority)

ruleType

Determines the rule type, as follows:

  • Upload: The rule is processed after the file is uploaded by an external user.

  • Download: The rule is processed before or after the file is downloaded by an external user.

  • Push: The rule is processed after the file is uploaded by an internal user.

  • Pull: The rule is processed before or after the file is downloaded by an internal user.

Default: Upload

status

Determines the activation status of the rule:

  • Enabled

  • Disabled

Default: Enabled

conditions

Defines conditions that must be met for the rule to be applied.

For more information about the types of conditions and the properties that you use to define them, see the table below.

postActions

Defines the actions to perform after the file is uploaded or downloaded, provided that the defined conditions were met.

You can define various types of actions, using the actionType property.

For more information about the types of actions and the properties that you use to define them, see the table below.

preActions

Defines the actions to perform before the file is downloaded, provided that the defined conditions were met.

Only the RunCommandAction action type is available (through the actionType property) for Pre actions. For more information about this action type and its properties, see the description in the table below.

The following table lists the types of conditions that you can define and the properties for each type:

Condition Type

Description
fileNamePatternCondition

Applies the rule on condition that the filename matches (or does not match) a specific pattern.

The following properties are available for this condition type:

  • pattern: Defines the pattern to compare the filename with.

  • caseSensitive: Determines whether the pattern is case-sensitive.

    Valid Values:

    • true

    • false

    Default: false

  • isRegex: Determines whether the pattern is a regular expression.

    Valid Values:

    • true

    • false

  • excludeFiles: Determines whether the specified pattern is used to include files in the condition (a value of false) or to exclude files from the condition (a value of true). The default is false.
fileSizeCondition

Applies the rule on condition that the file matches a certain size.

The following properties are available for this condition type:

  • maxSize: Defines the maximum measurement in a file size range.

  • maxUnits: Determines one of the following units for the maximum measurement:

    • B: Bytes

    • KB: Kilobytes

    • MB: Megabytes

    • GB: Gigabytes

  • minSize: Defines the minimum measurement in a file size range.

  • minUnits: Determines the unit for the minimum measurement.
userCondition

Applies the rule on condition that the file was sent by specific users, groups, or companies.

The following properties are available for this condition type:

  • companyNames: Defines an array of company names.

  • userOrGroupNames: Defines an array of user or group names.
virtualFolderCondition

Applies the rule on condition that the file arrives in a specific virtual folder (and optionally a subdirectory within it).

The following properties are available for this condition type:

  • virtualFolderNames: Defines an array of specific folder names.

  • virtualFolderPatterns: Defines an array of patterns to compare the folder name with.

  • subDirectory: Defines the name of a subdirectory within the virtual folder.

  • caseSensitive: Determines whether the folder patterns are case-sensitive.

    Valid Values:

    • true

    • false

    Default: false

  • isRegex: Determines whether the folder patterns are regular expressions.

    Valid Values:

    • true

    • false

    Default: false

The following table lists the types of actions that you can define (through the actionType property) and the properties for each type.

Action Type

Description
AddEventAction

Adds an event after the file is uploaded or downloaded, provided that the defined conditions are met. This triggers jobs that are waiting for this event to start executing.

Action definitions go under the addEventActionData object, with the following available properties:

  • eventName: Defines the name of the event to add.

  • eventDate: Determines the date scheduled for the event, with the following options:

    • A date in MMDD format.

    • ODAT: The current Control-M order date.

    • STAT: An indication that the event is not date-specific.

    Default: ODAT

  • actionFailsBehaviour: Defines the behavior when the current action fails, as described in the table below.

RunFolderJobAction

Runs a folder and job after the file is uploaded or downloaded, provided that the defined conditions are met.

Action definitions go under the runFolderJobActionData object, with the following available properties:

  • folderName: Defines the name of the folder to run.

  • jobName: Defines the name of the job to run.

  • hold: Determines whether to pause the job from executing.

    Valid Values:

    • true

    • false

    Default: false

  • orderNow: Determines whether to order the job immediately, disregarding scheduling definitions.

    Valid Values:

    • true

    • false

    Default: false

  • placeInFolder: (Optional) Determines how to order jobs or Sub Folders that belong to a SMART Folder:

    • New: Insert jobs into a new folder.

    • Recent: Insert jobs into a recent folder.

    • Standalone: Insert the jobs into a regular folder.

    Default: New

  • variables: Defines job variables as an array, with a key and value for each variable.

  • actionFailsBehaviour: Defines the behavior when the current action fails, as described in the table below.

EmailNotificationAction

Sends a notification email after the file is uploaded or downloaded, provided that the defined conditions are met.

Action definitions go under the emailNotificationActionData object, with the following available properties:

  • emailMessage: Defines the message text to send by email.

  • emailSubject: Defines the subject line for the email message.

  • notifyTo: Defines the email addresses of the recipients (as an array).

  • actionFailsBehaviour: Defines the behavior when the current action fails, as described in the table below.

FileOperationAction

Enables you to perform operations on the file after it is uploaded or downloaded, provided that the defined conditions are met. You can move or copy the file to another directory, or you can rename or delete the file.

Action definitions go under the fileOperationActionData object, with the following available properties:

  • operator: Defines the type of operation to perform on the file:

    • Move

    • Copy

    • Rename

    • Delete

  • renameDestinationFile: Defines a new name for the file, either for the original file in a Rename operation or for the destination file in a Copy or Move operation.

  • targetDirectory: Defines the path to a target directory for a Copy or Move operation.

  • fileLocationType: Determines whether the defined target directory (for a Copy or Move operation) is a relative path or absolute path.

    Valid values: Relative|Absolute

  • actionFailsBehaviour: Defines the behavior when the current action fails, as described in the table below.

RunCommandAction

Runs an executable command or script after the file is uploaded or downloaded or before the file is downloaded, provided that the defined conditions are met.

Action definitions go under the runCommandActionData object, with the following available properties:

  • commandPath: Defines a command or a path to an executable command or script.

  • successfulReturnCodes: Defines the return codes for successful execution. Separate multiple return codes with commas.

  • actionFailsBehaviour: Defines the behavior when the current action fails, as described in the table below.

The following table lists the options under the actionFailsBehaviour property to control the behavior of rule processing when a defined action (of any type) fails.

Property

Description

deleteFile

Determines whether to delete the file if the action fails.

Valid Values:

  • true

  • false

Default: false

nextActionBehaviour

Determines how to handle subsequent actions and rules when the current action fails.

Valid Values:

  • Abort: Abort all actions in this rule and stop processing rules. In the case of a Pre action, file download is aborted, as well.

  • Skip: Stop processing this rule and skip to the next rule.

  • Continue: Continue processing any additional defined actions within the rule (and any subsequent rules).