Skip to main content
Previous section

Using the MFT API for InterSystems IRIS

If the MFT business hosts do not meet your needs, you can use the MFT API, which enables you to manage connections, resources (files and directories), and users at each of the supported MFT services. This API consists of the packages %SYS.MFT.Connection and %MFT. The provided methods cover the following activities:

The %SYS.MFT.Connection package contains methods for managing network connections to MFT services. The %MFT package contains methods and properties for file and user management, in addition to service-specific functions. Both classes have subclasses for each of the supported MFT services (Box, Dropbox, and Accellion kiteworks). When creating and managing a connection, always use the connection-specific class.

Sample usages for methods are listed below. For more information about all of the items listed here, including detailed parameter specifications and return values for every method and property, see the Class Reference entries for classes in %SYS.MFT.Connection and %MFT.

Connection Management APIs

This section describes how to create a saved connection programmatically (a one-time setup), obtain a connection object, and then manage connections.

Setup Steps for Creating a Saved Connection

To create a connection to a MFT service, first complete the following one-time setup steps:

  1. Create a connection object. To do so, call the %New() method of %SYS.MFT.Connection.Box, %SYS.MFT.Connection.Dropbox, or %SYS.MFT.Connection.Kiteworks, depending on the MFT service you want to use. For example:

    set connection = ##class(%SYS.MFT.Connection.Dropbox).%New()
    Copy code to clipboard
  2. Set the following properties of this object:

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

    • Service — MFT service used for this connection.

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

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

    • URL — Root URL of the transfer service page for your organization.

    • ApplicationName — Name of the app as created on the MFT service.

    For example:

    set connection.URL = "https://companyname.kiteworks.com/"
    Copy code to clipboard
  3. Save the connection object by calling its Save() method (not %Save()). For example:

    set status = connection.Save()
    Copy code to clipboard
  4. Add the OAuth 2.0 client information. To do so, call the CreateClient() class method of the same class with the following properties as its arguments:

    • name — The name of the entry for the production, as configured at the MFT service.

    • sslConfiguration — The TLS configuration used for this MFT connection.

    • clientId — The OAuth 2.0 client ID from the MFT service.

    • clientSecret — The OAuth 2.0 client secret from the MFT service.

    For the complete signature including all optional arguments, see the Class Reference.

    For example:

    set status = ##class(%SYS.MFT.Connection.Dropbox).CreateClient(
            OAuth2AppName,
            "tlsconfig",
            clientId,
            clientSecret)}
    Copy code to clipboard

    This method adds the OAuth 2.0 client information and saves the object again. The method returns an error status if it did not successfully save the record.

These steps are equivalent to the steps described in “Creating a Managed File Transfer Connection” and “Authorizing an MFT Connection” in the chapter “Prerequisites and Configuration.”

Obtaining a Connection Object

After you have performed the setup work described in the previous section, use the GetConnection() method of the %MFT.Box, %MFT.Dropbox, or %MFT.Kiteworks class to obtain a connection object that you can use to manage connections.

GetConnection()
classmethod GetConnection(connectionName As %String, 
                          Output sc As %Status) as %SYS.MFT.Connection.Base
Copy code to clipboard

Returns a connection object for use with the given MFT service. The arguments are as follows:

  • connectionName is the name of the connection.

  • sc, which is returned by reference, is the status code that indicates whether the system retrieved the object successfully.

This method is in the class %MFT.API as well as the service-specific subclasses %MFT.Box, %MFT.Dropbox, and %MFT.Kiteworks. However, InterSystems recommends that you call GetConnection() from the appropriate service-specific class.

Sample usage:

set connection = ##class(%MFT.Box).GetConnection(connectionname,.sc)
Copy code to clipboard

Managing Connections

Once you have retrieved a connection object via GetConnection(), use the following methods to manage and retrieve information about MFT connections. Except where noted, these are instance methods within the connection object.

GetAuthorizationCodeURL()
method GetAuthorizationCodeURL(redirect As %String, 
                               scope As %String, 
                               ByRef properties As %String, 
                               Output sc As %Status) as %String
Copy code to clipboard

Returns the URL to use for obtaining authorization from the MFT service. The arguments are as follows:

  • redirect is the redirect URL.

  • scope is the OAuth 2.0 scope.

  • properties is a multidimensional array of properties.

  • sc, which is returned by reference, is the status code that indicates whether the system was successful in obtaining the URL.

IsAuthorized()
method IsAuthorized(Output errorMessage As %String) as %Boolean
Copy code to clipboard

Checks the authorization status of the connection. There is one argument:

  • errorMessage, which is returned as output, contains any error messages returned by the MFT service.

RevokeToken()
method RevokeToken() as %Status
Copy code to clipboard

Revokes the token for the connection and returns a %Status value to indicate success or failure of this operation.

DeleteId()
classmethod DeleteId(name As %String) as %Status
Copy code to clipboard

Deletes the connection object and returns a %Status value to indicate success or failure of this operation. There is one argument:

  • name is the name of the connection object.

This method is in each of the classes %SYS.MFT.Connection.Box, %SYS.MFT.Connection.Dropbox, and %SYS.MFT.Connection.Kiteworks. Although all these classes inherit from %SYS.MFT.Connection.Base, InterSystems recommends that you call DeleteId() from the appropriate service-specific class.

Directory and File Management APIs

This section lists the methods you can use to manage directories and files at an MFT service. These methods are in the service-specific subclasses %MFT.Box, %MFT.Dropbox, and %MFT.Kiteworks. Unlike the connection management methods, InterSystems recommends that you call the directory and file management methods from the parent class %MFT.API; for example, use %MFT.API.CreateFolder() instead of %MFT.DropBox.CreateFolder(). InterSystems IRIS automatically processes all calls as the appropriate service-specific version whenever methods are called from the parent class. If a call does not exist for a particular service, then InterSystems IRIS skips that step and continues to the next one.

Important:

To manage directories and files on Dropbox, you must use a connection based on a Dropbox User application with Full Dropbox permission.

Managing Folder Access

Use the following methods for creating, deleting, and sharing folders at an MFT service.

CreateFolder()
classmethod CreateFolder(connection As %SYS.MFT.Connection.Base, 
                         folderPath As %String, 
                         Output itemInfo As %MFT.ItemInfo) as %Status
Copy code to clipboard

Creates a folder and returns a %Status value to indicate success or failure of this operation. This method has the following arguments:

  • connection is a connection object for an MFT service, obtained via GetConnection().

  • folderPath is the full path of the folder to create.

  • itemInfo, which is returned as output, is an instance of %MFT.ItemInfo that provides a handle for the new folder. See %MFT.ItemInfo Details.

Sample usage:

set status = ##class(%MFT.API).CreateFolder(connection,"/NewDir",.itemInfo)
Copy code to clipboard
DeleteFolder()
classmethod DeleteFolder(connection As %SYS.MFT.Connection.Base, 
                         path As %String
                         permanent as %Boolean = 0) as %Status
Copy code to clipboard

Deletes a folder and returns a %Status value to indicate success or failure of this operation. This method has the following arguments:

  • connection is a connection object for an MFT service, obtained via GetConnection().

  • path is the full path of the folder. You can instead specify this argument as a string of the form "id:id_from_iteminfo" where id_from_iteminfo is an ID from a %MFT.ItemInfo object.

  • permanent specifies whether the deletion is permanent. If permanent is 0, the MFT service moves the folder to the trash folder. If permanent is 1, the MFT service deletes the folder permanently. Note that this method does not currently support permanent folder deletion for DropBox.

Sample usage:

set status = ##class(%MFT.API).DeleteFolder(connection,"/DirToDelete")
Copy code to clipboard
ShareFolder()
classmethod ShareFolder(connection As %SYS.MFT.Connection.Base, 
                        path As %String, 
                        accessLevel As %String = "viewer", 
                        users As %List) as %Status
Copy code to clipboard

Shares the given folder with specific users (granting them a specific access level) and returns a %Status value to indicate success or failure of this operation. This method has the following arguments:

  • connection is a connection object for an MFT service, obtained via GetConnection().

  • path is the full path of the folder.

  • accessLevel specifies the access level to give. The default is view-only access. Refer to the documentation from the MFT service for the different levels of access.

  • users is a %List of user names.

Sample usage:

set status = ##class(%MFT.API).ShareFolder(connection,"/SharedDir/","editor",ListOfUsers))
Copy code to clipboard
UnshareFolder()
classmethod UnshareFolder(connection As %SYS.MFT.Connection.Base, 
                          path As %String, 
                          user As %String) as %Status
Copy code to clipboard

Removes a given user from those authorized to access a folder and returns a %Status value to indicate success or failure of this operation. This method has the following arguments:

  • connection is a connection object for an MFT service, obtained via GetConnection().

  • path is the full path of the folder.

  • user is a user name.

Sample usage:

set status = ##class(%MFT.API).UnshareFolder(connection,"/FolderToUnshare","mwinters")
Copy code to clipboard
UnshareFolderAll()
classmethod UnshareFolderAll(connection As %SYS.MFT.Connection.Base, 
                             path As %String) as %Status
Copy code to clipboard

Prevents the folder from being shared with any user and returns a %Status value to indicate success or failure of this operation. This method has the following arguments:

  • connection is a connection object for an MFT service, obtained via GetConnection().

  • path is the full path of the folder.

Sample usage:

set status = ##class(%MFT.API).UnshareFolderAll(connection,"/FolderToUnshare")
Copy code to clipboard
MountFolder()
classmethod MountFolder(connection As %SYS.MFT.Connection.Base, 
                        folderName As %String) as %Status
Copy code to clipboard

For Dropbox only: Mounts the folder if it has been shared by the owner and returns a %Status value to indicate success or failure of this operation. This method has the following arguments:

  • connection is a connection object for an MFT service, obtained via GetConnection().

  • folderName is the full path of the folder.

Sample usage:

set status = ##class(%MFT.DropBox).MountFolder(connection,"MyFolder")
Copy code to clipboard
UnmountFolder()
classmethod UnmountFolder(connection As %SYS.MFT.Connection.Base, 
                          folderName As %String) as %Status
Copy code to clipboard

For Dropbox only: Unmounts the folder folderName and returns a %Status value to indicate success or failure of this operation. This method has the following arguments:

  • connection is a connection object for an MFT service, obtained via GetConnection().

  • folderName is the full path of the folder.

Sample usage:

set status = ##class(%MFT.DropBox).UnmountFolder(connection,"FolderName")
Copy code to clipboard
SetCurrentFolder()
classmethod SetCurrentFolder(connection As %SYS.MFT.Connection.Base, 
                             folderPath As %String) as %Status
Copy code to clipboard

Establishes the given folder as the current working folder in the production and returns a %Status value to indicate success or failure of this operation. This method has the following arguments:

  • connection is a connection object for an MFT service, obtained via GetConnection().

  • folderName is the full path of the folder.

Sample usage:

set status = ##class(%MFT.API).SetCurrentFolder(connection,"/a/b/c")
Copy code to clipboard

Getting Folder Information

Use the following methods and properties to obtain information about folders at the MFT service named in connection:

GetCurrentFolder()
classmethod GetCurrentFolder(connection As %SYS.MFT.Connection.Base, 
                             Output folderPath As %String) as %Status
Copy code to clipboard

Eetrieves the full pathname of the current working folder and returns a %Status value to indicate success or failure of this operation. This method has the following arguments:

  • connection is a connection object for an MFT service, obtained via GetConnection().

  • folderName, which is returned as output, is the full path of the current working folder for the given connection.

Sample usage:

set status = ##class(%MFT.API).GetCurrentFolder(connection,.path)
Copy code to clipboard
GetFolderInfo()
classmethod GetFolderInfo(connection As %SYS.MFT.Connection.Base, 
                          path As %String, 
                          Output itemInfo As %MFT.ItemInfo) as %Status
Copy code to clipboard

Retrieve a specified folder and returns a %Status value to indicate success or failure of this operation. This method has the following arguments:

  • connection is a connection object for an MFT service, obtained via GetConnection().

  • path is the full path of the folder.

  • itemInfo, which is returned as output, is an instance of %MFT.ItemInfo that provides a handle to the given folder (if GetFolderInfo() returns success). For details, see “%MFT.ItemInfo Details.”

Sample usage:

set status = ##class(%MFT.API).GetFolderInfo(connection,"/dirname",.itemInfo)
Copy code to clipboard
GetFolderContents()
classmethod GetFolderContents(connection As %SYS.MFT.Connection.Base,
                              folderPath As %String,
                              recursive As %Boolean = 0,
                              Output folderContents As %MFT.FolderContents) as %Status
Copy code to clipboard

Retrieves the contents of a specified folder and returns a %Status value to indicate success or failure of this operation. This method has the following arguments:

  • connection is a connection object for an MFT service, obtained via GetConnection().

  • folderPath is the full path of the folder.

  • recursive controls whether to recursively obtain subfolders.

  • folderContents, which is returned as output, is an instance of %MFT.FolderContents that provides a handle to the folder contents (if GetFolderContents() returns success).

Sample usage:

set status = ##class(%MFT.API).GetFolderContents(connection,"",IsRecursive,.contents)
Copy code to clipboard

An instance of the class %MFT.FolderContents has the following properties:

Contents

A list of the contents of the folder, each one in an instance of %MFT.ItemInfo.

Recursive

A Boolean value indicating whether or not %MFT.FolderContents.Contents is a recursive listing.

Managing Files

Use the following methods for managing files at the MFT service named in connection:

DeleteFile()
classmethod DeleteFile(connection As %SYS.MFT.Connection.Base, 
                       path As %String) as %Status
Copy code to clipboard

Deletes a file and returns a %Status value to indicate success or failure of this operation. This method has the following arguments:

  • connection is a connection object for an MFT service, obtained via GetConnection().

  • path is the full pathname of the file.

Sample usage:

set status = ##class(%MFT.API).DeleteFile(connection,"/dirname/filetodelete.txt")
Copy code to clipboard
UploadFile()
classmethod UploadFile(connection As %SYS.MFT.Connection.Base, 
                       localFilePath As %String, 
                       filePath As %String, 
                       replace As %Boolean = 0, 
                       Output itemInfo As %MFT.ItemInfo) as %Status
Copy code to clipboard

Uploads a file and returns a %Status value to indicate success or failure of this operation. This method has the following arguments:

  • connection is a connection object for an MFT service, obtained via GetConnection().

  • localFilePath is the full pathname of the file on the local system.

  • filePath is the full target pathname of the file within the transfer service.

  • replace specifies whether to replace any existing file that has the same name.

  • itemInfo, which is returned as output, is an instance of %MFT.ItemInfo that provides a handle to the newly uploaded file (if UploadFile() returns success). For details, see “%MFT.ItemInfo Details.”

Sample usage:

set status = ##class(%MFT.API).UploadFile(connection,localdir_"file.txt","/uploadDir/file.txt",,.itemInfo)
Copy code to clipboard
DownloadFile()
classmethod DownloadFile(connection As %SYS.MFT.Connection.Base,
                         filePath As %String, 
                         localFilePath As %String) as %Status
Copy code to clipboard

Downloads a file and returns a %Status value to indicate success or failure of this operation. This method has the following arguments:

  • connection is a connection object for an MFT service, obtained via GetConnection().

  • filePath is the full pathname of the file within the transfer service.

  • localFilePath is the full target pathname of the file on the local system.

Sample usage:

set status = ##class(%MFT.API).DownloadFile(connection,"/DownloadDir/file.txt",localdir_"file.txt")
Copy code to clipboard
UploadStream()
classmethod UploadStream(connection As %SYS.MFT.Connection.Base, 
                         stream As %BinaryStream, 
                         filePath As %String, 
                         replace As %Boolean = 0, 
                         Output itemInfo As %MFT.ItemInfo) as %Status
Copy code to clipboard

Uploads the contents of the given stream, creating a file within the transfer service, and returns a %Status value to indicate success or failure of this operation. This method has the following arguments:

  • connection is a connection object for an MFT service, obtained via GetConnection().

  • stream is the stream whose contents are to be uploaded.

  • filePath is the full target pathname of the file within the transfer service.

  • replace specifies whether to replace any existing file that has the same name.

  • itemInfo, which is returned as output, is an instance of %MFT.ItemInfo that provides a handle to the new file (if UploadStream() returns success). For details, see “%MFT.ItemInfo Details.”

Sample usage:

set status = ##class(%MFT.API).UploadStream(connection,stream,"/uploadDir/newfile.txt",0,.itemInfo)
Copy code to clipboard
DownloadStream()
classmethod DownloadStream(connection As %SYS.MFT.Connection.Base, 
                           filePath As %String, 
                           ByRef stream As %BinaryStream) as %Status
Copy code to clipboard

Downloads a file, creating a stream object, and returns a %Status value to indicate success or failure of this operation. This method has the following arguments:

  • connection is a connection object for an MFT service, obtained via GetConnection().

  • filePath is the full pathname of the file within the transfer service.

  • stream, which is returned by reference, is the stream object that contains the file contents (if DownloadStream() returns success).

Sample usage:

set status = ##class(%MFT.API).DownloadStream(connection,"/DownloadDir/file.txt",.resultstream)
Copy code to clipboard

Getting File Information

The %MFT.ItemInfo class provides an API for information about files. The GetFolder(), UploadFile(), and UploadStream() methods (listed in previous sections) each return an instance of this class as output. You can also obtain an instance of this class by calling the GetFileInfo() method of the %MFT.API, %MFT.Box, %MFT.Dropbox, or %MFT.Kiteworks class:

GetFileInfo()
classmethod GetFileInfo(connection As %SYS.MFT.Connection.Base, 
                        path As %String, 
                        Output itemInfo As %MFT.ItemInfo) as %Status
Copy code to clipboard

Retrieves information about the given file and returns a %Status value to indicate success or failure of this operation. This method has the following arguments:

  • connection is a connection object for an MFT service, obtained via GetConnection().

  • path is the full pathname of the file within the transfer service.

  • itemInfo, which is returned by reference, is an instance of %MFT.ItemInfo that contains information about the file (if GetFileInfo() returns success). See “%MFT.ItemInfo Details.”

Sample usage:

set status = ##class(%MFT.API).GetFileInfo(connection,"filename.txt",.itemInfo)
Copy code to clipboard

%MFT.ItemInfo Details

An instance of the class %MFT.ItemInfo has the following method and properties:

%MFT.ItemInfo.GetPath() method
method GetPath(trailingSlash As %Boolean = 1) as %String
Copy code to clipboard

Returns the path of the file, as a string. The argument trailingSlash specifies whether the path should include a trailing slash.

Details property

Contains information about the file. This property is an instance of %DynamicObject.

ItemId property

Contains the internal identifier for the item, as a string.

Modified property

Indicates the item’s time of creation in UTC, as a %Timestamp.

ModifiedBy property

Contains the internal identifier (UserId) of the user who last modified the item, as a string. Use %MFT.API.GetUsername() on the returned value to get the external username.

Name property

Contains the name of the item, as a string.

Type property

Indicates whether the item is a file (1) or a folder (2).

User Management APIs

This section lists the methods you can use to manage users at an MFT service. These methods are in the service-specific subclasses %MFT.Box, %MFT.Dropbox, and %MFT.Kiteworks. Unlike the connection management methods, InterSystems recommends that you call the user management methods from the parent class %MFT.API; for example, use %MFT.API.CreateUser() instead of %MFT.DropBox.CreateUser(). InterSystems IRIS automatically processes all calls as the appropriate service-specific version whenever methods are called from the parent class. If a call does not exist for a particular service, then InterSystems IRIS skips that step and continues to the next one.

Important:

To manage users on Dropbox, you must use a connection based on a Dropbox Business application with Team Member Management permission.

Creating and Deleting Users

Use the following methods to create and delete users.

CreateUser()
classmethod CreateUser(connection As %SYS.MFT.Connection.Base, userInfo As %MFT.UserInfo) as %Status
Copy code to clipboard

Creates a user and returns a %Status value to indicate success or failure of this operation. This method has the following arguments:

DeleteUser()
classmethod DeleteUser(connection As %SYS.MFT.Connection.Base, username As %String) as %Status
Copy code to clipboard

Given a username, deletes the user and returns a %Status value to indicate success or failure of this operation. This method has the following arguments:

  • connection is a connection object for an MFT service, obtained via GetConnection().

  • username is the name of the user.

DeleteUserById()
classmethod DeleteUserById(connection As %SYS.MFT.Connection.Base, userid As %String) as %Status
Copy code to clipboard

Given a user ID, deletes the user and returns a %Status value to indicate success or failure of this operation. This method has the following arguments:

  • connection is a connection object for an MFT service, obtained via GetConnection().

  • userid is the ID of the user.

Getting a User Object

Use the following methods to get user information from the MFT service named in connection:

GetUser()
classmethod GetUser(connection As %SYS.MFT.Connection.Base, 
                    username As %String, 
                    Output userInfo As %MFT.UserInfo) as %Status
Copy code to clipboard

Given a username, retrieves information about the user and returns a %Status value to indicate success or failure of this operation. This method has the following arguments:

  • connection is a connection object for an MFT service, obtained via GetConnection().

  • username is the name of the user.

  • userInfo, which is returned as output, is an instance of %MFT.UserInfo that contains information about the user. See “%MFT.UserInfo Details.”

Sample usage:

set status = ##class(%MFT.API).GetUser(connection,"User ToGet",.user)
Copy code to clipboard
GetUsername()
classmethod GetUsername(connection As %SYS.MFT.Connection.Base, 
                        internalId As %String, 
                        Output username As %String) as %Status
Copy code to clipboard

Given a user ID, retrieves the username and returns a %Status value to indicate success or failure of this operation. This method has the following arguments:

  • connection is a connection object for an MFT service, obtained via GetConnection().

  • internalId is the ID of the user.

  • username, which is returned as output, is the name of the user.

Sample usage:

set status = ##class(%MFT.API).GetUsername(connection,itemInfo.UserID,.username)
Copy code to clipboard
GetUserById()
classmethod GetUserById(connection As %SYS.MFT.Connection.Base,  
                        userid As %String,  
                        Output userInfo As %MFT.UserInfo) as %Status
Copy code to clipboard

Given a user ID, retrieves information about the user and returns a %Status value to indicate success or failure of this operation. This method has the following arguments:

  • connection is a connection object for an MFT service, obtained via GetConnection().

  • userid is the ID of the user.

  • userInfo, which is returned as output, is an instance of %MFT.UserInfo that contains information about the user. See “%MFT.UserInfo Details.”

Sample usage:

set status = ##class(%MFT.API).GetUserById(connection,itemInfo.ModifiedBy,.user)
Copy code to clipboard
GetUserList()
classmethod GetUserList(connection As %SYS.MFT.Connection.Base, Output userList As %MFT.UserList) as %Status
Copy code to clipboard

Retrieves a list of all the users for the account and returns a %Status value to indicate success or failure of this operation. This method has the following arguments:

  • connection is a connection object for an MFT service, obtained via GetConnection().

  • userList, which is returned as output, is an instance of %MFT.UserList that contains information about the users. The %MFT.UserList object includes the property Users, which is a list of %MFT.UserInfo objects.

Sample usage:

set status = ##class(%MFT.API).GetUserList(connection,.userList)
Copy code to clipboard

%MFT.UserInfo Details

The CreateUser() method uses an instance of the class %MFT.UserInfo as input. Other methods return instances of this class as output.

An instance of the class %MFT.UserInfo has the following properties:

Details

A %DynamicObject that contains information about the user.

Name

The (descriptive) name of the named user, as a string.

UserId

An internal identifier for the named user, as a string.

UserName

The unique name (login) of the user (typically the user’s email address), as a string.