File exchange

File-Exchange on MacOS has limited the access towards files for services. This means for MacOS packages the File-Exchange does not have access to the following folders and it's subfolders:

Documents
Downloads
Pictures
Movies
Music

Folders such as the following still have access:

Applications
User's Home folder (self created folders) with exclusion of the first list

The reason of this restriction from Apple can be found in there release notes here under the section Launch Daemons and Agents

Sample code uses ES6 language features such as arrow functions and promises. For compatibility with IE11, code written with these features must be either transpiled using tools like Babel or refactored accordingly using callbacks.

Introduction

The File Exchange container allows Trust1Connector to upload or download files from the filesystem to the requesting party.

The File Exchange container provides the following functionalities:

selecting a folder based on application type
listing files in selected application type
downloading one or more files into selected application type
uploading one or more files from the selected application type

An application type resolves locally to an absolute file system path.

An application can create additional folders for a given application type, those folders are relative to the absolute path which has been locally mapped on the application type.

The File Exchange container provides additionally:

optional user notification for file transfer completion
copy and move files between application types

The File-exchange payload limit is set to 50 MB. If your needs exceed this please contact support

Configuration file

The configuration file can be found in

%localappdata%\Programs\Trust1Connector\file-exchange.json

Notifications

The File Exchange container allows the application to choose whether to notify the users in the application context, or to delegate notification to the T1C. The T1C uses the underlying operating system to notify users

Context and scope

The context of a type mapping is defined by the following concepts:

applicationid (property of Type class): a string value denoting the application identifier. This is the root context for entity mapping. The application id is dervied from the Origin domain.
entity: a string value denoting the root entity for types mapping
type: a string value denoting a file typing, related to the absolute path mapped by an user, this value abstracts absolute paths from an application perspective

The following image depicts the file exchange object model:

Type Mapping

A 'Type' in the context of the File Exchange container, is a label, used by an application, to abstract the absolute path reference of the local file system. A 'Type' allows the application to perform file transfers, without the notion of the local file system organization. The File Exchange container maps the absolute path, chose by a user, on the application scoped label. We call this action a 'type mapping', this is, an absolute path, in the context of an application, is references by a label.

Type subfolders

Subfolders can be managed by the application. All subfolder are relative paths and when requested can be created, optionally recursively, by the File Exchange API. It's important to understand:

Type mapping : correlates to absolute paths on a local file system
Type subfolders: correlates to relative paths on a local file system

The File Exchange container maintains the mapping for absolute paths. Relative paths will be created when used in the specified use case. Neither absolute paths or relative paths will result in deletion on the local file system! When deleting a 'type' (aka absolute path), the type will be removed from the File Exchange container, but the references directory will still exist on the user's file system.

In the File Exchange API, the parameter relpath refers to an array of strings denoting a directory path.

Responses

The File Exchange API can be integrated using Promises or callbacks. Both are returning the same result.

Interface

interface AbstractFileExchange {
    download(entity: string, type: string, file: Blob, fileName: string, relPath?: [string], implicitCreationType?: boolean, notifyOnCompletion?: boolean, callback?: (error: T1CLibException, data: FileListResponse) => void): Promise<DataResponse>;
    upload(entity: string, type: string, fileName: string, rel_path?: [string], notifyOnCompletion?: boolean, callback?: (error: T1CLibException, data: FileListResponse) => void): Promise<Blob>;
    listTypes(entity?: string, page?: Page, callback?: (error: T1CLibException, data: TypeListResponse) => void): Promise<TypeListResponse>;
    listType(entity: string, type: string, callback?: (error: T1CLibException, data: TypeResponse) => void): Promise<TypeResponse>;
    listTypeContent(entity: string, type: string, relPath?: [string], page?: Page, callback?: (error: T1CLibException, data: FileListResponse) => void): Promise<FileListResponse>;
    listContent(entity: string, page?: Page, callback?: (error: T1CLibException, data: FileListResponse) => void): Promise<FileListResponse>;
    existsType(entity: string, type: string, callback?: (error: T1CLibException, data: BoolDataResponse) => void): Promise<BoolDataResponse>;
    existsFile(entity: string, type: string, relPath: [string], callback?: (error: T1CLibException, data: BoolDataResponse) => void): Promise<BoolDataResponse>;
    getAccessMode(entity: string, type: string, relPath?: [string], callback?: (error: T1CLibException, data: DataResponse) => void): Promise<DataResponse>;
    createDir(entity: string, type: string, relPath: [string], recursive?: boolean, callback?: (error: T1CLibException, data: FileResponse) => void): Promise<FileResponse>;
    copyFile(entity: string, fromType: string, toType: string, fileName: string, newfileName: string, fromrelPath?: [string], toRelPath?: [string], callback?: (error: T1CLibException, data: FileResponse) => void): Promise<FileResponse>;
    moveFile(entity: string, fromType: string, toType: string, fileName: string, fromrelPath?: [string], toRelPath?: [string], callback?: (error: T1CLibException, data: FileResponse) => void): Promise<FileResponse>;
    renameFile(entity: string, type: string, fileName: string, newfileName: string, relPath?: [string], callback?: (error: T1CLibException, data: FileResponse) => void): Promise<FileResponse>;
    getFileInfo(entity: string, type: string, fileName: string, relPath?: [string], callback?: (error: T1CLibException, data: FileResponse) => void): Promise<FileResponse>;
    createType(entity: string, type: string, initPath?: [string], modal?: boolean, timeout?: number, callback?: (error: T1CLibException, data: TypeResponse) => void): Promise<TypeResponse>;
    createTypeDirs(entity: string, type: string, rel_path: [string], modal?: boolean, timeout?: number, callback?: (error: T1CLibException, data: FileListResponse) => void): Promise<FileListResponse>;
    updateType(entity: string, type: string, timeout?: number, callback?: (error: T1CLibException, data: TypeResponse) => void): Promise<TypeResponse>;
    deleteType(entity: string, type: string, callback?: (error: T1CLibException, data: boolean) => void): Promise<boolean>;
}

Objects

Enums

The following enumerators have been exported by the File Exchange container:

enum FileSort {ASC, DESC}
enum TypeStatus {MAPPED,UNMAPPED}

Enum

Values

Description

FileSort

ASC, DESC

Used for sorting files. ASC = ascending, DESC = descending

TypeStatus

MAPPED, UNMAPPED

Use to inform the application if a Type has been mapped to an absolute path by the user.

Classes

class T1CResponse {
    constructor(public success: boolean, public data?: any) {}
}

class ListFilesRequest {
    constructor(public path: string, public extensions: string[]) {}
}

export class File {
    constructor(public extension: string,
                public name: string,
                public path: string,
                public relPath: string[],
                public type: string,
                public entity: string,
                public size: number,
                public lastModificationTime: string,
                public isDir: boolean,
                public access: string) {}
}

class FileListResponse extends T1CResponse {
    constructor(public data: FileList, public success: boolean) {
    super(success, data);
    }
}

class FileList {
    constructor(public files: File[], public total: number) {}
}

class FileResponse extends T1CResponse {
    constructor(public data: File, public success: boolean) {
        super(success, data);
    }
}

class TypeListResponse extends T1CResponse {
    constructor(public data: TypeList, public success: boolean) {
        super(success, data);
    }
}

class TypeResponse extends T1CResponse {
    constructor(public data: Type, public success: boolean){
        super(success, data);
    }
}

class Type {
    constructor(public entity: string, public type: string, public path: string, access: string, status: TypeStatus, public files: number, public appid?: string) {}
}

class TypeList{
    constructor(public types: Type[], public total: number) {}
}

class Page {
    constructor (public start: number, public size: number, public sort: FileSort) {}
}

class DataArrayResponse extends T1CResponse {
    constructor(public data: string[], public success: boolean) {
        super(success, data);
    }
}

class DataResponse extends T1CResponse {
    constructor(public data: string, public success: boolean) {
        super(success, data);
    }
}

class RestException {
    constructor(public status: number, public code: string, public description: string, public client?: GCLClient) {
        ObjectUtil.removeNullAndUndefinedFields(this);
    }
}

Function Descriptions

The following functions are available in the T1C-JS library:

JavaScript API

Function

Input

Output

Description

download

entity, type, file, filename, relpath, implicitCreationType, notifyOnCompletion

success value

Creates a file named filename at the type location, optionally in relative folder denoted by relpath, with file contents file. Optionally notifies user upon completion.

upload

entity, type, filename, relpath, notifyOnCompletion

array buffer

Uploads a file named filename, from the type location, optionally in relative folder denoted with relpath. Optionally notifies user upon completion.

listTypes

entity, page

list of type objects

Returns a list of existing types. The type object contains information about the mapping of absolute paths. Paging can be used optionally by using the page parameter.

listType

entity, type

type object

Returns the targeted type object.

listTypeContent

entity, type, relpath, page

list of file objects

Returns a list of file objects for the targeted type. A file can be a directory or a binary file. The relpath refers to the directory path where files should be searched for.

listContent

entity, page

list of file objects

Returns a list of file objects for all known types. The list will contain all files that are present in defined types.

existsType

entity, type

boolean

Verifies if type exists. Be aware that a type can exist, but no mapping has been persisted by the user.

existsFile

entity, type, relpath

boolean

Verifies if a file exists on the local file system.

getAccessMode

entity, type, relpath, filename

access mode

Returns the access mode for a file or directory. The param relpath can be used to target a nested file or directory.

createDir

entity, type, relpath, recursive

file object

Returns the created file object (which in this use case is always a directory). When recursive is set to true, the all subfolders will be created.

copyFile

entity, fromType, toType, filename, newfilename, fromrelpath, torelpath

file object

Copy a file or directory on the local file system.

moveFile

entity, fromType, toType, filename, fromrelpath, torelpath

file object

Move a file or directory on the local file system.

renameFile

entity, type, filename, newfilename, relpath

file object

Rename a file or directory

getFileInfo

entity, type, filename, relpath

file object

Returns the targeted file information

createType

entity, type, timeoutInSeconds, initabspath

type object

Creates a new type mapping, with optional initial path (migration support). When the path is not found on the local system, the user will be prompted with a file chooser.

createTypeDirs

entity, type, relpath, showModal, timeoutInSeconds

type object

Creates new subfolders for a type mapping. If the type mapping is not existing, the user will be prompted with a file chooser.

updateType

entity, type, timeoutInSeconds

type object

Prompt the user to force renewal of type mapping. The user will be presented with file chooser, even when the mapping exists already.

deleteType

entity, type

boolean

Removes the type mapping, but does not delete

directories or files from the local system.

Detailed Function Overview

Paging (Page interface)

The File Exchange container uses paging for the endpoints:

listTypes
listContent

The page-parameter can be optionally provided and contains the following properties:

start: start index
size: number of items on a page
sort: ordering of file and directory names ascending or descending

When used, the resulting response returns an 'total' property with the total item count for the requested resource.

download

Creates a file named filename at the type location in the context of entity, optionally in relative folder denoted by relpath, with file content file. Optionally notifies user upon completion.. When notifications are disabled, the application is assumed to handle user notifications.

The optional relpath provided, will be created when not existing, this in a recursive manner.

Interface

download(entity: string, type: string, file: Blob, fileName: string, relPath?: [string], implicitCreationType?: boolean, notifyOnCompletion?: boolean, callback?: (error: T1CLibException, data: FileListResponse) => void): Promise<DataResponse>;

Parameters

entity: the entity context where the type mapping is persisted
type: location for the newly created file
file: Blob containing binary data to be put in the file
filename: name to be given to the file
relpath: optional relative path (array of strings), when provided will implicitly create the missing directories.
implicitCreationType: In case the type mapping doesn’t exist, a prompt will be shown to the user for creating the Type before performing the download.
notifyOnCompletion: show modal info form operating system to user upon completion

Output

{
    data: string
    success: boolean
}

Use Cases

The use cases are the followings with the concerned parameters :

Use Case 1

download with existing Type (whatever the value true or false of the flag ‘implicitCreationType’)
- The user launches the download process with a relpath.
- The application uses the T1C function download with as parameter a relpath.
- The file is downloaded to the directory of the path + relpath (recursive creation).

Use Case 2 – download with non existing Type and parameter ‘implicitCreationType’ = false

The user launches the download process.
The application uses the T1C function download with as parameter a relpath.
The exception 356 is raised due the fact the Type doesn’t exist.
End

Use Case 3 – download with non existing Type and parameter ‘implicitCreationType’ = true

The user launches the download process.
The application uses the T1C function download with as parameter a relpath.
The user will see the prompt for the Type creation with a default path.
The user selects the directory and cancels or validates the creation:
- Cancellation of the creation.
- Validation of the creation.
  - The Type is created.
  - The file is downloaded to the directory of the path + relpath (recursive creation).

upload

Uploads a file named filename, from the type location, optionally in relative folder denoted with relpath. Optionally notifies the user upon completion.. When the notifications are disabled, the application is assumed to handle user notifications.

The optional relpath provided, will be created when not existing, this in a recursive manner.

Interface

upload(entity: string, type: string, fileName: string, relPath?: [string], notifyOnCompletion?: boolean, callback?: (error: T1CLibException, data: Blob) => void): Promise<Blob>;

Parameters

entity: the entity context where the type mapping is persisted
type: location for the file to upload
filename: name of the file to be uploaded
relpath: optional relative path (array of strings)
notifyOnCompletion: show modal info form operating system to user upon completion

Output

Returns a Blob object

listTypes

Retrieve a list of current persisted mappings given an optional entity.

Interface

listTypes(entity?: string, page?: Page, callback?: (error: T1CLibException, data: TypeListResponse) => void): Promise<TypeListResponse>;

Parameters

entity: the entity context where the type mapping is persisted. Optional.
page: apply a paging to the result. Optional.

Output

{
    data: TypeList
    success: boolean
}

listType

Retrieve a list of current mappings given an entity type context.

Interface

listType(entity: string, type: string, callback?: (error: T1CLibException, data: TypeResponse) => void): Promise<TypeResponse>;

Parameters

entity: the entity context where the type mapping is persisted.
type: the entity type mapping context

Output

{
    data: Type
    success: boolean
}

listTypeContent

List all the content for a mapping.

Interface

listTypeContent(entity: string, type: string, relPath?: [string], page?: Page, callback?: (error: T1CLibException, data: FileListResponse) => void): Promise<FileListResponse>;

Parameters

entity: the entity context where the type mapping is persisted.
type: the entity type mapping context
relpath: specify a relative path to retrieve the files
page: apply a paging to the result. Optional.

Output

{
    data: FileList
    success: boolean
}

listContent

List all the content for a mapping given an entity context..

Interface

listContent(entity: string, page?: Page, callback?: (error: T1CLibException, data: FileListResponse) => void): Promise<FileListResponse>;

Parameters

entity: the entity context where the type mapping is persisted.
page: apply a paging to the result. Optional.

Output

{
    data: FileList
    success: boolean
}

existsType

Verify if a context mapping exists.

Interface

existsType(entity: string, type: string, callback?: (error: T1CLibException, data: BoolDataResponse) => void): Promise<BoolDataResponse>;

Parameters

entity: the entity context where the type mapping is persisted.
type: the entity type mapping context

Output

{
    data: boolean
    success: boolean
}

existsFile

Verify if a file exists in a context mapping.

Interface

existsFile(entity: string, type: string, relPath: [string], callback?: (error: T1CLibException, data: BoolDataResponse) => void): Promise<BoolDataResponse>;

Parameters

entity: the entity context where the type mapping is persisted.
type: the entity type mapping context
relpath: a relative path based on the context root folder

Output

{
    data: boolean
    success: boolean
}

getAccessMode

Get the access mode of a folder or file in a context mapping.

Interface

getAccessMode(entity: string, type: string, fileName: string, relPath?: [string], callback?: (error: T1CLibException, data: DataResponse) => void): Promise<DataResponse>;

Parameters

entity: the entity context where the type mapping is persisted.
type: the entity type mapping context
filename: an optional filename, if not specified the folder access mode will be returned
relpath: an optional relative path based on the context root folder

Output

{
    data: string ("rwx")
    success: boolean
}

createDir

Create a directory in a context mapping.

Interface

createDir(entity: string, type: string, relPath: [string], recursive?: boolean, callback?: (error: T1CLibException, data: FileResponse) => void): Promise<FileResponse>;

Parameters

entity: the entity context where the type mapping is persisted.
type: the entity type mapping context
relpath: a relative path based on the context root folder
recursive: indicate whether the directory should be created recursively. If not and the parent directories do not exist, an error will be thrown.

Output

{
    data: File
    success: boolean
}

copyFile

Copy a file from one context mapping to another.

Interface

copyFile(entity: string, fromType: string, toType: string, fileName: string, newfileName: string, fromrelPath?: [string], toRelPath?: [string], callback?: (error: T1CLibException, data: FileResponse) => void): Promise<FileResponse>;

Parameters

entity: the entity context where the type mapping is persisted.
fromType: the originating entity type mapping context
toType: the destination entity type mapping context
filename: the name the of the to copy
newfilename: the new destination file name
fromrelpath: an optional originating relative path based on the context root folder
torelpath: an optional destination relative path based on the context root folder

Output

{
    data: File
    success: boolean
}

moveFile

Move a file from one context mapping to another.

Interface

moveFile(entity: string, fromType: string, toType: string, fileName: string, fromrelPath?: [string], toRelPath?: [string], callback?: (error: T1CLibException, data: FileResponse) => void): Promise<FileResponse>;

Parameters

entity: the entity context where the type mapping is persisted.
fromType: the originating entity type mapping context
toType: the destination entity type mapping context
filename: the name the of the to copy
fromrelpath: an optional originating relative path based on the context root folder
torelpath: an optional destination relative path based on the context root folder

Output

{
    data: File
    success: boolean
}

renameFile

Rename a file in a context mapping.

Interface

renameFile(entity: string, type: string, fileName: string, newfileName: string, relPath?: [string], callback?: (error: T1CLibException, data: FileResponse) => void): Promise<FileResponse>;

Parameters

entity: the entity context where the type mapping is persisted.
fromType: the originating entity type mapping context
toType: the destination entity type mapping context
filename: the name the of the to copy
relpath: an optional relative path based on the context root folder

Output

{
    data: File
    success: boolean
}

getFileInfo

Get file information of a file in a context mapping.

Interface

getFileInfo(entity: string, type: string, fileName: string, relPath?: [string], callback?: (error: T1CLibException, data: FileResponse) => void): Promise<FileResponse>;

Parameters

entity: the entity context where the type mapping is persisted.
type: the originating entity type mapping context
filename: the name the of the to copy
relpath: an optional relative path based on the context root folder

Output

{
    data: File
    success: boolean
}

createType

The initPath parameter denotes an initial path proposal from the application. Example values:

Windows

inittabspath = [ "C:\", "Users", "user1", "Desktop", "folder1" ];
inittabspath = [ "C:\Users", "user1", "Desktop", "folder1" ];
inittabspath = [ "C:\Users\user1\Desktop\folder1" ];

macOS

initPath = [ "Users", "user1", "Desktop", "folder1" ];
initPath = [ "/Users/user1/Desktop/folder1" ];

Linux

initPath = [ "home", "user1", "Desktop", "folder1" ];
initPath = [ "/home/user1/Desktop/folder1" ];

The optional parameter modal is by default set to true.

When createType is called upon an existing type mapping, the file-chooser shown to the user is defaults to the existing absolute path provided for the type.

The showModal flag is used to propose (or not) the prompt to the end user even if the initPath exists or not. This parameter forces the prompt of the file chooser:

when the initPath is provided and showModal is set to true: the initPath is pre-selected in the file-chooser shown to the user if existing, or the file-chooser is shown with a default path.
when the initPath is provided and modal is set to false: the initabspath is used when mapping exists, otherwise the file-chooser is shown to the user in order to select a valid absolute path.
when the initPath is not provided and modal is set to true: the file-chooser is shown when the mapping doesn't exist.
when the initPath is not provided and modal is set to false: a type exception is thrown when the type mapping doesn't exist

Interface

createType(entity: string, type: string, initPath: [string], modal?: boolean, timeout?: number, callback?: (error: T1CLibException, data: TypeResponse) => void): Promise<TypeResponse>;

Parameters

entity: the entity context where the type mapping is persisted.
type: the entity type mapping context
modal: indicate if the folder dialog must be shown
timeout: optional timeout in seconds before the folder dialog is discarded)
initPath: the optional initial root context path for the new type

Output

{
    data: Type
    success: boolean
}

Use Cases

The use cases are the followings with the concerned parameters:

Use Case 1

createType with an existing initPath and parameter showModal = true
- The user will create a type mapping.
- The application uses the T1C function createType with as parameter an existing initabspath and the modal set to true.
- A prompt must appear with the value set to initPath.
- The user selects (or not) a directory and cancels or validates the creation:
- Cancellation of the creation.
  - The exception is raised due the fact it has been aborted.
- Validation of the creation.
  - The Type is created.
- End
Use Case 2
- createType with an existing initabspath and parameter modal = false
  - The user will create a Type
- The application uses the T1C function createType using as parameter an existing initPath and the modal set to false.
- No prompt will be proposed to the end user but the Type is created.
- End
Use Case 3
- createType with a non existing initPath (whatever the value true or false of the flag modal)
  - The user will create a Type.
- The application uses the T1C function createType with as parameter a non existing initPath.
- A prompt must appear with default value.
- The user selects (or not) a directory and cancels or validates the creation:
  - Cancellation of the creation.
    The exception is raised due the fact it has been aborted.
  - Validation of the creation.
    The Type is created.
- End

createTypeDirs

Create directories for a context mapping.

Interface

createTypeDirs(entity: string, type: string, relPath: [string], modal?: boolean, timeout?: number, callback?: (error: T1CLibException, data: FileListResponse) => void): Promise<FileListResponse>;

Parameters

entity: the entity context where the type mapping is persisted.
type: the entity type mapping context
relpath: a relative path based on the context root folder
modal: indicate if the folder dialog must be shown
timeout: optional timeout in seconds before the folder dialog is discarded)

Output

{
    data: FileList
    success: boolean
}

updateType

Update a context mapping. A folder dialog will be opened and a new root context path can be choosen.

Interface

updateType(entity: string, type: string, timeout?: number, callback?: (error: T1CLibException, data: TypeResponse) => void): Promise<TypeResponse>;

Parameters

entity: the entity context where the type mapping is persisted.
type: the entity type mapping context
timeout: timeout in seconds before the folder dialog is discarded)

Output

{
    data: Type
    success: boolean
}

deleteType

Delete a context mapping.

Interface

deleteType(entity: string, type: string, callback?: (error: T1CLibException, data: boolean) => void): Promise<boolean>;

Parameters

entity: the entity context where the type mapping is persisted.
type: the entity type mapping context

Output

{
    data: boolean
    success: boolean
}

Error Responses

The error codes mentioned are added to the File Exchange container. The exception handling follows the framework exception handling and are extensions of status codes mentioned on:

Status codes / error handeling

PreviousCrelan NextRemote loading

Last updated 3 years ago