T1C-API
Search…
File Exchange API
File management, file up and download using an operating system abstraction layer. Allows the consuming application to work with OS independent directory and file aliases.

Introduction

The File Exchange container allows Trust1Connector to manage files and directories, to upload or download files to/from the filesystem from/to the requesting party (especially for web application). The user of the device must give a consent prior of file operations.
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
    creating sub directories in 'mapped' folders (application types)
The Trust1Connector does NOT allow the deletion of folders or files residing on the user's device.
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. This means that the web application can ask the user to create subdirectories in an application type which has been already mapped.
The File Exchange container provides additionally:
    optional user notification for file transfer completion
    copy and move files between application types
    user consent to allow the consuming application to perform file operations
    application/domain scoped, application types are bound to the application domain
    OS native files and directory chooser dialogs
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
1
%localappdata%\Trust1Connector\file-exchange.json
Copied!

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. The type of notification supported by the T1C is system modal information (message, error, warning dialogs).

Context and scope

The context of a type mapping is defined by the following concepts:
    application_id (property of Type class): a string value denoting the application identifier. This is the root context for entity mapping. The application id is derived from the Origin domain and acts as an application scope for all defined mappings
    entity: a string value denoting the root entity/owner for types mapping. This can be called the root for al 'aliases' or 'type mappings' which will be created.
    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 as it acts as an alias, referencing a file or directory based on the configured absolute path.
The following image depicts the file exchange object model:
File Exchange Object Model

Type Mapping

A 'Type' in the context of the File Exchange container, is an alias or 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 organisation. The File Exchange container maps the absolute path, chosen 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 an alias or label (=Type).
A conceptual example, a mapping of
1
[Windows]
2
"C:\Users\userA\t1t\coda"
3
[OSX]
4
"/Users/userA/t1t/coda"
Copied!
can be mapped on:
1
application_id: mywebapp.com //domain
2
entity: Trust1Team //root context
3
type: Coda
Copied!
When the example mapping has been done, the consuming application does not need to worry about the underlying operating system, and can just target the folder or file using the tuple (entity, type) bounded implicitly by the operating domain (mywebapp.com).

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 and MUST reside in a type mapping/definition.
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, within a type mapping.

Responses

The File Exchange API can be integrated using any REST client. When an application want to integrate using a Javascript client, especially for web applications, please visit the T1C-SDK-JS:

Bulk File Transfer

The File Exchange container allows for bulk file transfer. The individual methods are stateless requests to the T1C-GCL service, and allows to up- or download one or more files from a user perspective. The progress information can be retrieved by the application for each file separately or for all the actions running on the T1C-GCL service.

Language

The language, used for OS modals, is determined the web application. The title and message properties can be provided, which will be used in the underlying OS modal/dialog. For OSX, there is no title of message for the file or directory chooser. In OSX you can only pass through the title and message using system modals (error, warn, info messages and PIN dialog).

Interface

TODO: Insert YAML file with OpenAPI specification

Objects

Enums

The following enumerators have been exported by the File Exchange container:
1
enum FileSort {ASC, DESC}
2
enum TypeStatus {MAPPED,UNMAPPED}
Copied!
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.

Function Descriptions

The following functions are available in the T1C-API module:
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.

CreateType

Let's start by creating a new 'type mapping' and see how this works. For all use cases, it is not required to enter operating system specific path input, except for this use case, where you can optionally provide a system specific path construct. When given, the interface will validate that the folder exists, that the folder is readable and will execute the binding. When the conditions are not fulfilled, a modal will pop-up for the user to choose a folder. The additional modal property can override the implicit type mapping behaviour, by using the given initPath, and open the folder by default in the directory chooser modal.
The initPath parameter denotes an initial path proposal from the application. Example values:

Windows

1
initPath: [ "C:\", "Users", "user1", "Desktop", "folder1" ];
2
initPath: [ "C:\Users", "user1", "Desktop", "folder1" ];
3
initPath: [ "C:\Users\user1\Desktop\folder1" ];
Copied!

macOS

1
initPath: [ "/Users", "user1", "Desktop", "folder1" ];
2
initPath: [ "/Users/user1/Desktop/folder1" ];
Copied!

Linux

1
initPath: [ "/home", "user1", "Desktop", "folder1" ];
2
initPath: [ "/home/user1/Desktop/folder1" ];
Copied!
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) using the prompt to the end user even if the initPath exists or not. This parameter forces the prompt of the directory 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 (user's home folder).
    when the initPath is provided and modal is set to false: the initabspath is used implicitly 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 dir-chooser is shown when the mapping doesn't exist.
    when the initPath is not provided and modal is set to false: the dir-chooser is shown as we don't want the use case to fail. The modal is implicitly set to true.

Example Request

Let's create a new type mapping for 'entity': T1T (our category or virtual label), with 'type name' or 'alias': doc
1
curl --location --request POST 'https://t1c.t1t.io:51884/v3/modules/fileexchange/apps/file/create-type' \
2
--header 'X-CSRF-Token: t1c-js' \
3
--header 'origin: localhost' \
4
--header 'Content-Type: application/json' \
5
--data-raw '{
6
"entity": "T1T",
7
"type": "doc",
8
"modal": true,
9
"initPath": ["/Users","michallis","_doc"]
10
}'
Copied!

Parameters

    entity: the entity context where the type mapping is persisted.
    type: the entity type mapping context or alias for the type mapping
    modal: indicate if the folder dialog must be shown
    initPath: the optional initial root context path for the new type

Example Response

The output denotes a valid mapping, this means that the application can interact with the folder: "/Users/michallis/_doc" by using the (entity, type) identifiers.
1
{
2
"success": true,
3
"data": {
4
"entity": "T1T",
5
"type": "doc",
6
"absPath": "/Users/michallis/_doc",
7
"accessMode": "drw",
8
"total": 0,
9
"appId": "localhost"
10
}
11
}
Copied!

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 initPath and the modal set as 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

listTypes

Retrieve a list of current persisted mappings given an optional entity. When the entity property is not provided in the body, all entities will be returned for the given domain (domain of the requesting application). The domain is determined by the header field: 'origin' and is defined as the 'application identifier'.
All types created and actions executed are always bound to the 'application identifier' context.

Example

1
curl --location --request POST 'https://t1c.t1t.io:51884/v3/modules/fileexchange/apps/file/list-types?start=1&size=5&sort=ASC' \
2
--header 'X-CSRF-Token: t1c-js' \
3
--header 'origin: localhost' \
4
--header 'Content-Type: application/json' \
5
--data-raw '{
6
"entity": "T1T"
7
}'
Copied!

Parameters

    entity [optional]: the optional entity context where the type mapping is persisted
    page [optional query parameter]: apply a paging to the result. Optional

Output

1
{
2
"success": true,
3
"data": {
4
"types": [
5
{
6
"appId": "localhost",
7
"entity": "T1T",
8
"type": "doc",
9
"path": "/Users/michallis/_doc",
10
"access": "drw",
11
"status": "MAPPED",
12
"total": 224400
13
}
14
],
15
"total": 1
16
}
17
}
Copied!

listType

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

Interface

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

Parameters

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

Output

1
{
2
data: Type
3
success: boolean
4
}
Copied!

listTypeContent

List all the content for a mapping.

Interface

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

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

1
{
2
data: FileList
3
success: boolean
4
}
Copied!

listContent

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

Interface

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

Parameters

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

Output

1
{
2
data: FileList
3
success: boolean
4
}
Copied!

existsType

Verify if a context mapping exists.

Interface

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

Parameters

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

Output

1
{
2
data: boolean
3
success: boolean
4
}
Copied!

existsFile

Verify if a file exists in a context mapping.

Interface

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

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

1
{
2
data: boolean
3
success: boolean
4
}
Copied!

getAccessMode

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

Interface

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

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

1
{
2
data: string ("rwx")
3
success: boolean
4
}
Copied!

createDir

Create a directory in a context mapping.

Interface

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

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

1
{
2
data: File
3
success: boolean
4
}
Copied!

copyFile

Copy a file from one context mapping to another.

Interface

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

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

1
{
2
data: File
3
success: boolean
4
}
Copied!

moveFile

Move a file from one context mapping to another.

Interface

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

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

1
{
2
data: File
3
success: boolean
4
}
Copied!

renameFile

Rename a file in a context mapping.

Interface

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

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

1
{
2
data: File
3
success: boolean
4
}
Copied!

getFileInfo

Get file information of a file in a context mapping.

Interface

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

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

1
{
2
data: File
3
success: boolean
4
}
Copied!

createTypeDirs

Create directories for a context mapping.

Interface

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

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

1
{
2
data: FileList
3
success: boolean
4
}
Copied!

updateType

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

Interface

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

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

1
{
2
data: Type
3
success: boolean
4
}
Copied!

deleteType

Delete a context mapping.

Interface

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

Parameters

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

Output

1
{
2
data: boolean
3
success: boolean
4
}
Copied!

Download File

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

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

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

1
{
2
data: string
3
success: boolean
4
}
Copied!

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

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

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
Last modified 14d ago