Skip to main content

Prerequisites and Configuration

An InterSystems IRIS® production can include business hosts that communicate directly with Managed File Transfer (MFT) services. Before adding these business hosts, perform the following prerequisites:

InterSystems IRIS supports the following MFT services:

Preparing the MFT Service Account

Before you can use an MFT service with InterSystems IRIS, you must perform the following tasks:

The following subsections provide details.

Setting Up Accounts

For each MFT service you intend to use, you must create two types of accounts:

  • One main administrative account, which manages all users and all directories

  • Multiple subaccounts, as needed for the end users

An end user account is needed for each person (or organization) expected to send and receive files. These end users can access only the files in their own folders or in folders to which they have explicitly been granted access, either by the actual owner or by an administrator. Consult the documentation for the MFT service for instructions on how to create these subaccounts, and how to set and verify permissions.

When you create the main account, make a note of the root URL that is meant for use in transferring files (for this account). You will need this information later (to use as the Base URL for the connection to the account).

Also choose an administrator for the account and make a note of the email address of that person.

Creating a Custom Application

After creating accounts at the MFT service, you must create a custom application within the main account, for use by the InterSystems IRIS production. Within this custom application, specify the following details:

  • A unique name.

  • The redirect URL for the InterSystems IRIS server. This URL has the following form:

    https://<baseURL>/prefix/csp/sys/oauth2/OAuth2.Response.cls
    

    Where:

    • <baseURL> is the base URL for the instance

    • prefix is an optional prefix if needed by the Web Gateway configuration.

    See Creating a Managed File Transfer Connection.

  • A pair of generated values (an OAuth 2.0 client ID/client secret pair), for use in authorizing the connection. The MFT services each use different names for these values:

    MFT Service Name for the OAuth 2.0 client ID Name for the OAuth 2.0 client secret
    Box Client ID Client Secret
    Dropbox App key App secret
    kiteworks Client Application ID Client Secret Key
    Important:

    When the transfer service generates this information, record it immediately and keep it in a secure location. The client secret, in particular, is meant to be held privately.

Setting Up the Directory Structure

You must also set up a directory structure so that each subaccount has a designated area for sending files and for receiving files.

InterSystems recommends using one parent “Incoming” and one parent “Outgoing” directory at the top level of the account, with individual incoming and outgoing subdirectories for the subaccounts within those directories. This organization makes it easier for the InterSystems IRIS production to locate all files that need to be transferred in either direction.

If you are already using an MFT service, then you may already be using a different directory structure. If so, and you do not wish to modify the directory structure, then you might need to add multiple MFT business services and operations to the production, each configured to find or place files in different directories.

Creating Configuration Items in InterSystems IRIS

In addition to preparing the MFT account, you need to create specific configuration items on the InterSystems IRIS server. Specifically, you must:

The following subsections describe the details.

Creating a TLS Configuration

InterSystems IRIS uses TLS to connect to an MFT service, so you must create a TLS configuration to use. InterSystems recommends that you create a separate configuration to use only for MFT connections, even if it uses default settings.

For details on creating a new TLS configuration, see About Configurations.

Creating a Managed File Transfer Connection

A managed file transfer (MFT) connection is a configuration item that the production can use to connect securely to an MFT service. If you have multiple productions running on a single InterSystems IRIS server, create a separate MFT connection for each production. In each case, the MFT connection must contain the OAuth 2.0 information you received from the MFT service.

To create an MFT connection:

  1. From the Management Portal, go to the Managed File Transfer Connections page (System Administration > Security > Managed File Transfer Connections).

  2. Click Create Connection to bring up the configuration page.

  3. Specify values for the fields as follows, and then click Save:

    • Connection Name — Name for this connection for use within the production.

    • File management service — MFT service used for this connection.

    • SSL/TLS configuration — Name of the TLS configuration to use for this connection.

    • Email address — Email address of the administrator of the MFT account.

    • Base URL — Root URL meant for use in transferring files (specific to your account).

    • OAuth 2.0 application name — Name of the custom application created within the MFT service.

    • OAuth 2.0 client ID — The application identifier as provided by the MFT service. Each MFT service uses a different name for this item:

      • Box: Client ID

      • Dropbox: App key

      • kiteworks: Client Application ID

    • OAuth 2.0 client secret — The password that the MFT service provided. Each MFT service uses a different name for this item:

      • Box: Client Secret

      • Dropbox: App secret

      • kiteworks: Client Secret Key

    • OAuth 2.0 redirect URL — URL used by the MFT service to connect to InterSystems IRIS. Enter the following values to automatically generate this URL:

      • Use TLS/SSL — Whether to use TLS to connect to the MFT service. In general, you should select this option.

      • Host name — The fully qualified domain name (FQDN) or IP address of the InterSystems IRIS server. See <baseURL>.

      • Port — The web server port specified in the Web Gateway configuration, if any.

      • Prefix — Typically blank. Specify this if needed to accommodate any changes in the Web Gateway configuration.

  4. Verify that the generated redirect URL has the following form:

    https://hostname:port/prefix/csp/sys/oauth2/OAuth2.Response.cls
    

    Or (less common):

    https://hostname/prefix/csp/sys/oauth2/OAuth2.Response.cls
    

    If you omit Prefix, there is only one slash before csp.

    This URL must match the one you supplied to the MFT service when creating the custom application for the production.

  5. If the generated URL does not match what you had provided to the MFT service, then log in to the MFT service and edit the app definition to use the generated URL.

Authorizing an MFT Connection

The next step is to authorize the newly created MFT connection. To do so, obtain and save an access token from the Managed File Transfer Connections page (System Administration > Security > Managed File Transfer Connections), as follows:

  1. Click the Get Access Token link for the connection you want to authorize.

    When you do so, the Management Portal displays the login page for the MFT service.

  2. Log in with the credentials for the administrative account.

    Once the MFT service has authenticated the credentials, you see a page that displays the authorization request from the MFT service, listing the types of access that are to be granted to the production.

  3. Click Grant Access to authorize the access. This redisplays the Connections list, and the MFT connection is now listed as Authorized.

FeedbackOpens in a new tab