IafFileSvc

Use the IafFileSvc API to manage files, file containers, and their versions on the platform.

addFile

Uploads a file to one or more namespaces.

Parameter	Required	Type	Description
file	Yes	Object	Pass a File or ReadStream object.
namespaces	Yes	(Array<String> | String)	Pass a namespace or that you want to upload a file to.
parents	Yes	String	Pass a parent folder you want to add the file to. If you pass the "undefined" value, the file uploads to the root folder.
tags	No	Array<String>	Pass any metadata tags you want to add to the file in an array.
ctx	No	Ctx	Context, such as namespaces and authentication token information.
options	No	FileOptions	Pass a FileOptions object with your file options as properties, such as "headers", "nodeFormData", and "filename". File uploads work in Node.js 24+ only when nodeFormData is set to true.

Returns

Promise<Array<File>> - Returns a promise with an array with your uploaded file as a File class object

Examples

// Upload gzip in root folder
let options = {'headers':{'Content-Encoding': 'gzip'}, 'filename': 'gzipFile.gzip'};

// For backend nodejs 24+
options.nodeFormData = true

let uploadedFile = await IafFileSvc.addFile(fileStream, project._namespaces, undefined, tags, ctx, options);

addFileResumable

Uploads a file as a File class object that resumes after upload interruptions. You can invoke this method later to resume the file upload from where the upload stopped. The method wraps initiateFileUpload and resumeUpload.

Parameter	Required	Type	Description
file	Yes	Object	Pass either a File or ReadStream object.
namespaces	Yes	(Array<String> | String)	Pass a namespace or an array of namespaces. The namespaces must be present in nsfilter property in the ctx or browser session storage.
parents	Yes	String	Pass a parent folder you want to add the file to. If you pass the "undefined" value, the file uploads to the root folder.
tags	Yes	Array<String>	Pass any tags you want to add to the file in an array.
ctx	No	Ctx	Context, such as namespaces and authentication token information.
options	Yes	ResuambleFileUploadProps	Pass a ResuambleFileUploadProps object to add a filename, tags, and callback functions for success, progress and failure.

Returns

Promise<File> - A promise for the created File object

Examples

let file = fs.createReadStream(filePath);
let uploadProps = { filename: 'projectAModel.bimpk' };

uploadProps.onComplete = (file) =>  console.log('upload success');

uploadProps.onProgress = (bytesUploaded, bytesTotal) => {
 let percentage = (bytesUploaded / bytesTotal * 100).toFixed(2);
 console.log(fileInfo._name, bytesUploaded, bytesTotal, percentage + "%");
}

uploadProps.onError = (error) => console.log('Failed to upload:',uploadUrl,error)

const resumableFile = await IafFileSvc.addFileResumable(file, namespaces, undefined, tags, ctx, uploadProps);

addFolder

Creates a new folder in one or more namespaces.

Parameter	Required	Type	Description
folderName	Yes	String	Pass a name for the folder.
namespaces	Yes	(Array<String> | String)	Pass a namespace or an array of namespaces. Namespaces must be present in nsfilter property in the ctx or browser session storage.
parents	Yes	String	Pass a parent folder you want to add the file to. If you pass the "undefined" value, the file uploads to the root folder.
ctx	No	Ctx	Context, such as namespaces and authentication token information.

Returns

Promise<File> - A promise with your created folder

Examples

const folder = await IafFileSvc.addFolder(
  "example_folder", 
  app._namespaces[0], 
  rootFolder, 
  ctx
);

addFolderWithTags

Creates a new folder under the parents and namespaces you declare.

Parameter	Required	Type	Description
folderName	Yes	String	Folder name
namespaces	Yes	(Array<String> | String)	Namespaces to be uploaded. Please note that these namespaces must be present in nsfilter.
parents	No	String	Parent folder id. root folder would be taken if not provided
tags	No	JSON	Pass any tags you want to add to the folder.
ctx	No	Ctx	Context storage that contains data, such as authorization token requirements, namespaces, or session storage.

Returns

Promise<File> - The created folder as a File object

Examples

const folder = await IafFileSvc.addFolderWithTags(
  "folder_name",
  project.namespaces,
  rootContainer,
  ["demo_folder"],
  ctx
);

cancelFileUpload

Aborts a resumable file upload.

Parameter	Required	Type	Description
fileId	Yes	String	Pass the file's id.
ctx	No	Ctx	Context, such as namespaces and authentication token information.

Returns

String - ok:204 response

Examples

const response = await IafFileSvc.cancelFileUpload(fileId);

createPermissions

Creates permissions for File Service resources.

Parameter	Required	Type	Description
permissions	Yes	Array<Permission>	Pass a Permissions array.
ctx	No	Ctx	Context storage that contains data, such as authorization token requirements, namespaces, or session storage.

Returns

Promise<CreatePermissionsResponse> - Returns a response object with an array of successful permissions and an array of failed permissions

Examples

// Permissions with mandatory fields
const permissions = [{
  _actions: [  IafPermission.PermConst.Action.Read, IafPermission.PermConst.Action.Share, IafPermission.PermConst.Action.Delete ],
  _namespace: "ProjA_HEpftR8X",
  _resourceDesc:{
    _irn: "filesvc:file:*"
  },
  _user:{
    _id: "75b2a3d6-a3e8-498d-99dc-23538bc9a389", // Either user or usergroup, specify respective _type
    _type: IafPermission.PermConst.UserType.User // Either user or usergroup, specify respective _id
  }
}];

const result = IafFileSvc.createPermissions(permissions, ctx);

// Permissions with criteria
const permissions = [{
  _actions: [ IafPermission.PermConst.Action.Read, IafPermission.PermConst.Action.Share, IafPermission.PermConst.Action.Delete ],
  _namespace: "ProjA_HEpftR8X",
  _resourceDesc:{
    _irn: "filesvc:file:*", // Refer {Permission} for more valid irns
    _criteria: {
      filetype: "bimpk"
    }
  },
  _user:{
    _id: "75b2a3d6-a3e8-498d-99dc-23538bc9a389", // Either user or usergroup, specify respective _type
    _type: IafPermission.PermConst.UserType.User // Either user or usergroup, specify respective _id
  }
}];

const result = IafFileSvc.createPermissions(permissions, ctx);

deleteFile

Deletes a File class object.

Parameter	Required	Type	Description
fileId	Yes	String	Pass the file's UUID.
ctx	No	Ctx	Context, such as namespaces and authentication token information.

Returns

String - ok:204 response

Examples

const res = await IafFileSvc.deleteFile(item._id);

deleteFiles

Delete many files by Ids

Parameter	Required	Type	Description
fileIds	Yes	Array<String>	file ids to delete
ctx	No	Ctx	Context, such as namespaces and authentication token information.
options	No	Object	additional options if any

deleteFileVersion

Deletes a FileVersion when you pass its id. If you delete tip version then next latest version will be the tip version.

Parameter	Required	Type	Description
fileId	Yes	String	Pass the file's UUID.
vId	Yes	String	Pass the file version's UUID.
ctx	No	Ctx	Context, such as namespaces and authentication token information.

Returns

Promise<String> - ok:204 response

Examples

const response = await IafFileSvc.deleteFileVersion(file._id, selectedVersion);

deletePermission

Deletes a Permission class object when you pass its id.

Parameter	Required	Type	Description
id	Yes	String	Pass the Permission object's id.
ctx	No	Ctx	Context storage that contains data, such as authorization token requirements, namespaces, or session storage.

Returns

Promise<String> - ok:204 response

Examples

const response = await IafFileSvc.deletePermission(permission._id);

getAllFilesInTree

Gets all the File class objects from all folders in a tree.

Parameter	Required	Type	Description
criteria	Yes	FileCriteria	Pass a FileCriteria object with your filter options.
ctx	No	Ctx	Context, such as namespaces and authentication token information.
options	Yes	GetFileOptions	Pass an Options object with your response pagination options, such as "_offset", and "_pageSize".

Returns

Promise<Array<File>> - An array of File class objects

Examples

const criteria = { _parents: file._parents[0] };
const options = { _offset: "3", _pageSize: "100" };

const fileTree = await IafFileSvc.getAllFilesInTree(criteria, ctx, options);

getFile

Gets a File class object when you pass it's id.

Parameter	Required	Type	Description
fileId	Yes	String	Pass the file's id.
ctx	No	Ctx	Context, such as namespaces and authentication token information.

Returns

Promise<File> - A promise with your File object

Examples

const file = await IafFileSvc.getFile(item._id);

getFileInfoWithUploadMeta

Gets a File class object and its upload metadata, which you can use to resume a file upload.

Parameter	Required	Type	Description
fileId	Yes	String	Pass the file's UUID.
ctx	No	Ctx	Context, such as namespaces and authentication token information.

Returns

Promise<File> - The File object that contains its upload metadata

Examples

const uploadMetadata = IafFileSvc.getFileInfoWithUploadMeta(file._id);

getFilePreviewUrl

Gets a preview URL for a file.

Parameter	Required	Type	Description
fileId	Yes	String	Pass the File object's UUID.
ctx	No	Ctx	Context, such as namespaces and authentication token information.
options	Yes	FilePreviewOptions	Pass a FilePreviewOptions object with your preview options as properties, such as "width", and "height".

Returns

Promise<File> - A promise with a File object that contains the URL.

Examples

const previewUrl = await IafFileSvc.getFilePreviewUrl(
  item._id, 
  ctx,
  {
    width: 42, 
    height: 38
  }
);

getFiles

Gets File class objects that match the criteria you pass.

Parameter	Required	Type	Description
criteria	Yes	FileCriteria	Pass a FileCriteria object with your filter options.
ctx	No	Ctx	Context, such as namespaces and authentication token information.
options	No	GetFileOptions	Pass an Options object with your response pagination options, such as "_offset", and "_pageSize".
withUrl	No	boolean	Set to true to include download URLs for the tip version of the files in the response.

Returns

Promise<Page<File>> -

Examples

// Get all files from specific folder
const criteria = {
  _parents: "5a25417d-1408-42d4-b9a2-812be53bb111"
};

const res = await IafFileSvc.getFiles(criteria, ctx, {}, true);

getFileUrl

Gets a download URL for a file that lasts 48 hours.

Parameter	Required	Type	Description
fileId	Yes	String	Pass the File object's UUID.
ctx	No	Ctx	Context, such as namespaces and authentication token information.

Returns

Promise<File> - A promise with your File object that contains the URL.

Examples

const fileUrl = await IafFileSvc.getFileUrl(item._id);

getFileVersion

Gets a FileVersion object when you pass its id.

Parameter	Required	Type	Description
fileId	Yes	String	Pass the File object's UUID.
vId	Yes	String	Pass the FileVersion's UUID.
ctx	No	Ctx	Context, such as namespaces and authentication token information.

Returns

Promise<FileVersion> - Returns a promise with the FileVersion object

Examples

const fileVersion = IafFileSvc.getFileVersion(file._id, selectedVersion);

getFileVersionPreviewUrl

Gets a download URL for a thumbnail preview of a FileVersion.

Parameter	Required	Type	Description
fileId	Yes	String	Pass the File object's id.
vId	Yes	String	Pass the FileVersion's id.
ctx	No	Ctx	Context, such as namespaces and authentication token information.
options	Yes	GetFileOptions	Pass an Options object with your response pagination options, such as "_offset", and "_pageSize".

Returns

String - Returns the download URL for the thumbnail

Examples

const fileVersionUrlPreview = IafFileSvc.getFileVersionPreviewUrl(file._id, selectedVersion);

getFileVersions

Gets a File object's versions as FileVersion class objects.

Parameter	Required	Type	Description
fileId	Yes	String	Pass the file's UUID.
ctx	No	Ctx	Context, such as namespaces and authentication token information.

Returns

Promise<Page<FileVersion>> - A promise with the File's FileVersion objects

Examples

const fileVersions = IafFileSvc.getFileVersions(file._id);

getFileVersionUrl

Gets a download URL for a specific FileVersion that expires after 48 hours.

Parameter	Required	Type	Description
fileId	Yes	String	Pass the File object's id.
vId	Yes	String	Pass the file version's id.
ctx	No	Ctx	Context, such as namespaces and authentication token information.

Returns

Promise<FileVersion> - Returns a promise with the FileVersion object

Examples

const fileVersionUrl = IafFileSvc.getFileVersionUrl(file._id, selectedVersion);

getPermissions

Gets permissions for File Service resources.

Parameter	Required	Type	Description
criteria	Yes	PermissionCriteria	Pass a PermissionCriteria object with the properties and values you want to filter your search.
ctx	No	Ctx	Context storage that contains data, such as authorization token requirements, namespaces, or session storage.

Returns

Promise<Page<Permission>> - Returns a promise with a page of your Permission objects

Examples

let criteria = {
   _resourceDesc._irn: "datasourcesvc:orchestrator:7600fe2a-5044-11ed-bdc3-0242ac120002",
   _namespace: "ProjA_HEpftR8X"
};

const permissions = IafFileSvc.getPermissions(criteria);

initiateFileUpload

Initiates a resumable file upload. Invoke resumeUpload with your file stream to resume a stopped upload.

Parameter	Required	Type	Description
body	Yes	File	Pass a File object with your metadata.
ctx	No	Ctx	Context, such as namespaces and authentication token information.
options	No	Options	Pass an Options object with your content-encoding header.

Returns

Promise<File> - The File object with your upload metadata

Examples

const file = {"_name":"gzipFile.gzip","_namespaces":["xxxx_yyyy"],"_uploadMeta":{"_size":20702285,"_checksum":"da39a3ee5e6b4b0d3255bfef95601890afd80709"}}
const options = { headers: { "Content-Encoding": "gzip" } };
const fileUpload = IafFileSvc.initiateFileUpload(file, ctx, options);

moveFile

Moves a file or folder to a different parent folder, or to the root.The item's explicit permissions remain unchanged after the move. Inherited permissions from the source folder are removed, and inherited permissions from the target folder are applied.

Parameter	Required	Type	Description
fileId	Yes	String	The ID of the file or folder to move.
targetFolderId	No	String	The destination folder ID. Pass or
to move the item to the root.
ctx	No	Ctx	Context containing namespaces and authentication information.

Returns

Promise<File> - A promise that resolves to the updated file or folder metadata.

Examples

// Move a file or folder into another folder
const item = await IafFileSvc.moveFile(
  "5a25417d-1408-42d4-b9a2-812be53bb111",
  "6b25414d-3429-15d3-a0a4-915be63bb235",
  ctx
);
``````javascript
// Move a file or folder to the root
const item = await IafFileSvc.moveFile(
  "5a25417d-1408-42d4-b9a2-812be53bb111",
  null,
  ctx
);

resumeUpload

Resumes a file upload that was initiated or interrupted.

Parameter	Required	Type	Description
fileInfo	Yes	File	Pass a File object with your upload metadata.
fileStream	Yes	Object	Pass either a File or ReadStream object.
ctx	No	Ctx	Context, such as namespaces and authentication token information.
options	Yes	ResuambleFileUploadProps	Pass a ResuambleFileUploadProps object to add a filename, tags, and callback functions for success, progress and failure.

Examples

let fileInfo = { uploadMeta: { _uploadId: "43r6q6d7-y2t7-555d-79gr-99863bc9a112"} };

IafFileSvc.resumeUpload(fileInfo, fileStreamId, ctx);

updateFile

Updates a File class object in the File Service.

Parameter	Required	Type	Description
fileId	Yes	String	Pass the File's id.
file	Yes	File	Pass your updated File object.
ctx	No	Ctx	Context, such as namespaces and authentication token information.

Returns

Promise<File> -

Examples

const updatdFile = await IafFileSvc.updateFile(
  file._id, 
  {
    _name: "updated_file_name",
    _tags: [...file._tags, "newTag1", "newTag2"]
  }
);

updatePermissions

Updates permissions for File Service resources. If the permissions already exist, the method creates them. The method uses the following properties to identify is the permission exitst: "_resourceDesc", "_namespace", "_user".

Parameter	Required	Type	Description
permissions	Yes	Array<Permission>	Permissions array
ctx	Yes	Ctx	Context storage that contains data, such as authorization token requirements, namespaces, or session storage.

Returns

Promise<CreatePermissionsResponse> - Response with success and failure permissions

Examples

let permissions = [{
  _actions: [  
    IafPermission.PermConst.Action.Read, 
    IafPermission.PermConst.Action.Share, 
    IafPermission.PermConst.Action.Delete
  ],
  _namespace: "ProjA_HEpftR8X",
  _resourceDesc:{
    _irn: IafPermission.NamedUserItemIrnAll
  },
  _user:{
    _id: currentUser._id, // Either user or usergroup id, specify respective _type
    _type: IafPermission.PermConst.UserType.User // Either user or usergroup, specify respective _id
  }
}];

const updatedPermissions = IafFileSvc.updatePermissions(permissions);