File exchange

Introduction

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

• 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.

A user can chose to 'persist' the Type mapping, or can decide to assign an absolute path for each individual transaction.

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.

Implicit Consent using Clipboard

Interface

interface AbstractFileExchange {
    download(entity: string, type: string, file: ArrayBuffer, 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<ArrayBuffer>;
    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[]) {}
}

class File {
    constructor(public extension: string,
                public name: string,
                public path: string,
                public relPath: 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 appid?: string, public entity?: string, public type?: string, public path?: string, access?: string, status?: TypeStatus, public files?: number) {}
}

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.

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:

Code	Description	Info
800	FileExchangeException	General File exchange exception
801	IoException	Exception regarding file IO
803	AccessException	Exception regarding access towards a file/folder
804	Type Exception	Exception regarding a Type
805	Entity exception	Exception regarding a Entity
806	Configuration exception	Exception regarding the configuration file