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:
-
Create a connection object. To do so, call the %New() method of %SYS.MFT.Connection.BoxOpens in a new tab, %SYS.MFT.Connection.DropboxOpens in a new tab, or %SYS.MFT.Connection.KiteworksOpens in a new tab, depending on the MFT service you want to use. For example:
set connection = ##class(%SYS.MFT.Connection.Dropbox).%New()
-
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/"
-
-
Save the connection object by calling its Save() method (not %Save()). For example:
set status = connection.Save()
-
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)}
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.
Obtaining a Connection Object
After you have performed the setup work described in the previous section, use the GetConnection() method of the %MFT.BoxOpens in a new tab, %MFT.DropboxOpens in a new tab, or %MFT.KiteworksOpens in a new tab class to obtain a connection object that you can use to manage connections.
classmethod GetConnection(connectionName As %String,
Output sc As %Status) as %SYS.MFT.Connection.Base
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.APIOpens in a new tab as well as the service-specific subclasses %MFT.BoxOpens in a new tab, %MFT.DropboxOpens in a new tab, and %MFT.KiteworksOpens in a new tab. However, InterSystems recommends that you call GetConnection() from the appropriate service-specific class.
Sample usage:
set connection = ##class(%MFT.Box).GetConnection(connectionname,.sc)
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.
method GetAuthorizationCodeURL(redirect As %String,
scope As %String,
ByRef properties As %String,
Output sc As %Status) as %String
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.
method IsAuthorized(Output errorMessage As %String) as %Boolean
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.
method RevokeToken() as %Status
Revokes the token for the connection and returns a %StatusOpens in a new tab value to indicate success or failure of this operation.
classmethod DeleteId(name As %String) as %Status
Deletes the connection object and returns a %StatusOpens in a new tab 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.BoxOpens in a new tab, %SYS.MFT.Connection.DropboxOpens in a new tab, and %SYS.MFT.Connection.KiteworksOpens in a new tab. Although all these classes inherit from %SYS.MFT.Connection.BaseOpens in a new tab, 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.BoxOpens in a new tab, %MFT.DropboxOpens in a new tab, and %MFT.KiteworksOpens in a new tab. Unlike the connection management methods, InterSystems recommends that you call the directory and file management methods from the parent class %MFT.APIOpens in a new tab; 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.
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.
classmethod CreateFolder(connection As %SYS.MFT.Connection.Base,
folderPath As %String,
Output itemInfo As %MFT.ItemInfo) as %Status
Creates a folder and returns a %StatusOpens in a new tab 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.ItemInfoOpens in a new tab that provides a handle for the new folder. See %MFT.ItemInfo Details.
Sample usage:
set status = ##class(%MFT.API).CreateFolder(connection,"/NewDir",.itemInfo)
classmethod DeleteFolder(connection As %SYS.MFT.Connection.Base,
path As %String
permanent as %Boolean = 0) as %Status
Deletes a folder and returns a %StatusOpens in a new tab 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.ItemInfoOpens in a new tab 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")
classmethod ShareFolder(connection As %SYS.MFT.Connection.Base,
path As %String,
accessLevel As %String = "viewer",
users As %List) as %Status
Shares the given folder with specific users (granting them a specific access level) and returns a %StatusOpens in a new tab 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 %ListOpens in a new tab of user names.
Sample usage:
set status = ##class(%MFT.API).ShareFolder(connection,"/SharedDir/","editor",ListOfUsers))
classmethod UnshareFolder(connection As %SYS.MFT.Connection.Base,
path As %String,
user As %String) as %Status
Removes a given user from those authorized to access a folder and returns a %StatusOpens in a new tab 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")
classmethod UnshareFolderAll(connection As %SYS.MFT.Connection.Base,
path As %String) as %Status
Prevents the folder from being shared with any user and returns a %StatusOpens in a new tab 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")
classmethod MountFolder(connection As %SYS.MFT.Connection.Base,
folderName As %String) as %Status
For Dropbox only: Mounts the folder if it has been shared by the owner and returns a %StatusOpens in a new tab 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")
classmethod UnmountFolder(connection As %SYS.MFT.Connection.Base,
folderName As %String) as %Status
For Dropbox only: Unmounts the folder folderName and returns a %StatusOpens in a new tab 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")
classmethod SetCurrentFolder(connection As %SYS.MFT.Connection.Base,
folderPath As %String) as %Status
Establishes the given folder as the current working folder in the production and returns a %StatusOpens in a new tab 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")
Getting Folder Information
Use the following methods and properties to obtain information about folders at the MFT service named in connection:
classmethod GetCurrentFolder(connection As %SYS.MFT.Connection.Base,
Output folderPath As %String) as %Status
Eetrieves the full pathname of the current working folder and returns a %StatusOpens in a new tab 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)
classmethod GetFolderInfo(connection As %SYS.MFT.Connection.Base,
path As %String,
Output itemInfo As %MFT.ItemInfo) as %Status
Retrieve a specified folder and returns a %StatusOpens in a new tab 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.ItemInfoOpens in a new tab 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)
classmethod GetFolderContents(connection As %SYS.MFT.Connection.Base,
folderPath As %String,
recursive As %Boolean = 0,
Output folderContents As %MFT.FolderContents) as %Status
Retrieves the contents of a specified folder and returns a %StatusOpens in a new tab 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.FolderContentsOpens in a new tab that provides a handle to the folder contents (if GetFolderContents() returns success).
Sample usage:
set status = ##class(%MFT.API).GetFolderContents(connection,"",IsRecursive,.contents)
An instance of the class %MFT.FolderContentsOpens in a new tab has the following properties:
A list of the contents of the folder, each one in an instance of %MFT.ItemInfoOpens in a new tab.
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:
classmethod DeleteFile(connection As %SYS.MFT.Connection.Base,
path As %String) as %Status
Deletes a file and returns a %StatusOpens in a new tab 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")
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
Uploads a file and returns a %StatusOpens in a new tab 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.ItemInfoOpens in a new tab 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)
classmethod DownloadFile(connection As %SYS.MFT.Connection.Base,
filePath As %String,
localFilePath As %String) as %Status
Downloads a file and returns a %StatusOpens in a new tab 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")
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
Uploads the contents of the given stream, creating a file within the transfer service, and returns a %StatusOpens in a new tab 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.ItemInfoOpens in a new tab 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)
classmethod DownloadStream(connection As %SYS.MFT.Connection.Base,
filePath As %String,
ByRef stream As %BinaryStream) as %Status
Downloads a file, creating a stream object, and returns a %StatusOpens in a new tab 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)
Getting File Information
The %MFT.ItemInfoOpens in a new tab 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.APIOpens in a new tab, %MFT.BoxOpens in a new tab, %MFT.DropboxOpens in a new tab, or %MFT.KiteworksOpens in a new tab class:
classmethod GetFileInfo(connection As %SYS.MFT.Connection.Base,
path As %String,
Output itemInfo As %MFT.ItemInfo) as %Status
Retrieves information about the given file and returns a %StatusOpens in a new tab 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.ItemInfoOpens in a new tab 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)
%MFT.ItemInfo Details
An instance of the class %MFT.ItemInfoOpens in a new tab has the following method and properties:
method GetPath(trailingSlash As %Boolean = 1) as %String
Returns the path of the file, as a string. The argument trailingSlash specifies whether the path should include a trailing slash.
Contains information about the file. This property is an instance of %DynamicObjectOpens in a new tab.
Contains the internal identifier for the item, as a string.
Indicates the item’s time of creation in UTC, as a %Timestamp.
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.
Contains the name of the item, as a string.
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.BoxOpens in a new tab, %MFT.DropboxOpens in a new tab, and %MFT.KiteworksOpens in a new tab. Unlike the connection management methods, InterSystems recommends that you call the user management methods from the parent class %MFT.APIOpens in a new tab; 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.
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.
classmethod CreateUser(connection As %SYS.MFT.Connection.Base, userInfo As %MFT.UserInfo) as %Status
Creates a user and returns a %StatusOpens in a new tab 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().
-
userInfo is an instance of %MFT.UserInfoOpens in a new tab that contains information about the user to create. See %MFT.UserInfo Details.
classmethod DeleteUser(connection As %SYS.MFT.Connection.Base, username As %String) as %Status
Given a username, deletes the user and returns a %StatusOpens in a new tab 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.
classmethod DeleteUserById(connection As %SYS.MFT.Connection.Base, userid As %String) as %Status
Given a user ID, deletes the user and returns a %StatusOpens in a new tab 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:
classmethod GetUser(connection As %SYS.MFT.Connection.Base,
username As %String,
Output userInfo As %MFT.UserInfo) as %Status
Given a username, retrieves information about the user and returns a %StatusOpens in a new tab 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.UserInfoOpens in a new tab that contains information about the user. See %MFT.UserInfo Details.
Sample usage:
set status = ##class(%MFT.API).GetUser(connection,"User ToGet",.user)
classmethod GetUsername(connection As %SYS.MFT.Connection.Base,
internalId As %String,
Output username As %String) as %Status
Given a user ID, retrieves the username and returns a %StatusOpens in a new tab 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)
classmethod GetUserById(connection As %SYS.MFT.Connection.Base,
userid As %String,
Output userInfo As %MFT.UserInfo) as %Status
Given a user ID, retrieves information about the user and returns a %StatusOpens in a new tab 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.UserInfoOpens in a new tab that contains information about the user. See %MFT.UserInfo Details.
Sample usage:
set status = ##class(%MFT.API).GetUserById(connection,itemInfo.ModifiedBy,.user)
classmethod GetUserList(connection As %SYS.MFT.Connection.Base, Output userList As %MFT.UserList) as %Status
Retrieves a list of all the users for the account and returns a %StatusOpens in a new tab 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.UserListOpens in a new tab that contains information about the users. The %MFT.UserListOpens in a new tab object includes the property Users, which is a list of %MFT.UserInfoOpens in a new tab objects.
Sample usage:
set status = ##class(%MFT.API).GetUserList(connection,.userList)
%MFT.UserInfo Details
The CreateUser() method uses an instance of the class %MFT.UserInfoOpens in a new tab as input. Other methods return instances of this class as output.
An instance of the class %MFT.UserInfoOpens in a new tab has the following properties:
A %DynamicObjectOpens in a new tab that contains information about the user.
The (descriptive) name of the named user, as a string.
An internal identifier for the named user, as a string.
The unique name (login) of the user (typically the user’s email address), as a string.