docs.intersystems.com
Home  /  Application Development: Using Adapters and Gateways in Productions  /  Enabling Productions to Use Managed File Transfer Services  /  Using the MFT API for InterSystems IRIS


Enabling Productions to Use Managed File Transfer Services
Using the MFT API for InterSystems IRIS
[Back] 
InterSystems: The power behind what matters   
Search:  


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()
  2. Set the following properties of this object:
    For example:
    set connection.URL = "https://companyname.kiteworks.com/"
  3. Save the connection object by calling its Save() method (not %Save()). For example:
    set status = connection.Save()
  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:
    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 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
Returns a connection object for use with the given MFT service. The arguments are as follows:
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)
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
Returns the URL to use for obtaining authorization from the MFT service. The arguments are as follows:
IsAuthorized()
method IsAuthorized(Output errorMessage As %String) as %Boolean
Checks the authorization status of the connection. There is one argument:
RevokeToken()
method RevokeToken() as %Status
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
Deletes the connection object and returns a %Status value to indicate success or failure of this operation. There is one argument:
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
Creates a folder and returns a %Status value to indicate success or failure of this operation. This method has the following arguments:
Sample usage:
set status = ##class(%MFT.API).CreateFolder(connection,"/NewDir",.itemInfo)
DeleteFolder()
classmethod DeleteFolder(connection As %SYS.MFT.Connection.Base, 
                         path As %String
                         permanent as %Boolean = 0) as %Status
Deletes a folder and returns a %Status value to indicate success or failure of this operation. This method has the following arguments:
Sample usage:
set status = ##class(%MFT.API).DeleteFolder(connection,"/DirToDelete")
ShareFolder()
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 %Status value to indicate success or failure of this operation. This method has the following arguments:
Sample usage:
set status = ##class(%MFT.API).ShareFolder(connection,"/SharedDir/","editor",ListOfUsers))
UnshareFolder()
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 %Status value to indicate success or failure of this operation. This method has the following arguments:
Sample usage:
set status = ##class(%MFT.API).UnshareFolder(connection,"/FolderToUnshare","mwinters")
UnshareFolderAll()
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 %Status value to indicate success or failure of this operation. This method has the following arguments:
Sample usage:
set status = ##class(%MFT.API).UnshareFolderAll(connection,"/FolderToUnshare")
MountFolder()
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 %Status value to indicate success or failure of this operation. This method has the following arguments:
Sample usage:
set status = ##class(%MFT.DropBox).MountFolder(connection,"MyFolder")
UnmountFolder()
classmethod UnmountFolder(connection As %SYS.MFT.Connection.Base, 
                          folderName As %String) as %Status
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:
Sample usage:
set status = ##class(%MFT.DropBox).UnmountFolder(connection,"FolderName")
SetCurrentFolder()
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 %Status value to indicate success or failure of this operation. This method has the following arguments:
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:
GetCurrentFolder()
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 %Status value to indicate success or failure of this operation. This method has the following arguments:
Sample usage:
set status = ##class(%MFT.API).GetCurrentFolder(connection,.path)
GetFolderInfo()
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 %Status value to indicate success or failure of this operation. This method has the following arguments:
Sample usage:
set status = ##class(%MFT.API).GetFolderInfo(connection,"/dirname",.itemInfo)
GetFolderContents()
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 %Status value to indicate success or failure of this operation. This method has the following arguments:
Sample usage:
set status = ##class(%MFT.API).GetFolderContents(connection,"",IsRecursive,.contents)
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
Deletes a file and returns a %Status value to indicate success or failure of this operation. This method has the following arguments:
Sample usage:
set status = ##class(%MFT.API).DeleteFile(connection,"/dirname/filetodelete.txt")
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
Uploads a file and returns a %Status value to indicate success or failure of this operation. This method has the following arguments:
Sample usage:
set status = ##class(%MFT.API).UploadFile(connection,localdir_"file.txt","/uploadDir/file.txt",,.itemInfo)
DownloadFile()
classmethod DownloadFile(connection As %SYS.MFT.Connection.Base,
                         filePath As %String, 
                         localFilePath As %String) as %Status
Downloads a file and returns a %Status value to indicate success or failure of this operation. This method has the following arguments:
Sample usage:
set status = ##class(%MFT.API).DownloadFile(connection,"/DownloadDir/file.txt",localdir_"file.txt")
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
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:
Sample usage:
set status = ##class(%MFT.API).UploadStream(connection,stream,"/uploadDir/newfile.txt",0,.itemInfo)
DownloadStream()
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 %Status value to indicate success or failure of this operation. This method has the following arguments:
Sample usage:
set status = ##class(%MFT.API).DownloadStream(connection,"/DownloadDir/file.txt",.resultstream)
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
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:
Sample usage:
set status = ##class(%MFT.API).GetFileInfo(connection,"filename.txt",.itemInfo)
%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
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
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
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:
DeleteUserById()
classmethod DeleteUserById(connection As %SYS.MFT.Connection.Base, userid As %String) as %Status
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:
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
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:
Sample usage:
set status = ##class(%MFT.API).GetUser(connection,"User ToGet",.user)
GetUsername()
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 %Status value to indicate success or failure of this operation. This method has the following arguments:
Sample usage:
set status = ##class(%MFT.API).GetUsername(connection,itemInfo.UserID,.username)
GetUserById()
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 %Status value to indicate success or failure of this operation. This method has the following arguments:
Sample usage:
set status = ##class(%MFT.API).GetUserById(connection,itemInfo.ModifiedBy,.user)
GetUserList()
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 %Status value to indicate success or failure of this operation. This method has the following arguments:
Sample usage:
set status = ##class(%MFT.API).GetUserList(connection,.userList)
%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.