Class File

Provides properties and methods for obtaining information about a file on the Open Cloud Server and managing its data and versions.

Hierarchy (View Summary)

Endpoint
- File

Constructors

constructor

new File(data: any, httpClient: IHttpClient): File
Parameters
- data: any
  Raw file data received from the server. For more information, see Open Cloud Files API.
- httpClient: IHttpClient
  HTTP client instance used to send requests to the REST API server.
Returns File
Overrides Endpoint.constructor

Properties

headers

headers: HeadersInit

Endpoint-specific HTTP headers for the GET, POST, PUT and DELETE requests. You can add custom headers at any time.

path

path: string

Endpoint API path relative to the REST API server URL.

Accessors

activeVersion

get activeVersion(): number
Active version number of the file.

Returns number

created

get created(): string
File creation time (UTC) in the format specified in ISO 8601.

Returns string

customFields

get customFields(): any
File custom fields object, to store custom data.

Returns any

data

get data(): any
Raw file data received from the server. For more information, see Open Cloud Files API.

Returns any

exports

get exports(): string[]
Returns a list of file formats in which the active version of the file was exported.

To export file to one of the supported formats run the File Converter job using createJob(). To download exported file use downloadResource().

For an example of exporting files to other formats, see the downloadResource help.

Returns string[]

geometryType

get geometryType(): string
Geometry data type of the active file version. Can be one of:
- vsfx - VSFX format, file can be opened in VisualizeJS 3D viewer.
- gltf - glTF format, file can be opened in Three.js 3D viewer.
Returns an empty string if geometry data has not yet been converted. A files without geometry data can be exported to other formas, but cannot be opened in viewer.
Returns string

id

get id(): string
Unique file ID.

Returns string

isFileDeleted

get isFileDeleted(): boolean
Returns true if the source file of the active file version has been deleted.

A files with deleted source file can be opened in the viewer, but cannot be exported to other formats.

Returns boolean

name

get name(): string
File name, including the extension.

Returns string

originalFileId

get originalFileId(): string
If the file is a version, then returns the ID of the original file. Otherwise, returns the file ID.

Returns string

owner

get owner(): IShortUserDesc
File owner information.

Returns IShortUserDesc

previewUrl

get previewUrl(): string
File preview image URL or empty string if the file does not have a preview. Use setPreview() to change preview image.

Returns string

sharedLinkToken

get sharedLinkToken(): string
File shared link token or null if file is not shared yet.

Returns string

size

get size(): number
The size of the active version of the file in bytes.

Returns number

sizeTotal

get sizeTotal(): number
Total size of all versions of the file in bytes.

Returns number

status

get status(): IFileStatus
Data status of the active version of the file. Contains:
- geometry - status of geometry data of vsfx type.
- geometryGltf - status of geometry data of gltf type.
- properties - status of properties.
- validation - status of validation.
Each status entity is a record with properties:
- state - Data state. Can be none, waiting, inprogress, done or failed.
- jobId - Unique ID of the data job.
Returns IFileStatus

type

get type(): string
File type, matches the file extension (includes dot).

Returns string

updatedAt

get updatedAt(): string
File last update time (UTC) in the format specified in ISO 8601.

Returns string

updatedBy

get updatedBy(): IShortUserDesc
Information about the user who made the last update.

Returns IShortUserDesc

version

get version(): number
Zero-based file version number for version files. The original file has version 0.

Returns number

versions

get versions(): IFileVersionInfo[]
List of the file versions.

Returns IFileVersionInfo[]

Methods

checkout

checkout(): Promise<File>
Reloads file data from the server.

Returns Promise<File>

createJob

createJob(outputFormat: string, parameters?: string | object): Promise<Job>
Runs a new job on the server for the active version of the file.
Parameters
- outputFormat: string
  The job type. Can be:
  
  geometry - Convert file geometry data to VSFX format for opening in VisualizeJS 3D viewer.
  
  geometryGltf - Convert file geometry data to glTF format for opening in Three.js 3D viewer.
  
  properties - Extract file properties.
  
  validation - Validate the IFC file.
  
  dwg, obj, gltf, glb, vsf, pdf, 3dpdf - Export file to the specified format. Use exports to get the list of completed file exports. Use downloadResource() to download the exported file.
  
  Other custom job name. Custom job must be registered in the job templates before running.
- Optionalparameters: string | object
  Parameters for the File Converter jobs or custom job. Can be given as JSON object or command line arguments in form --arg=value.
Returns Promise<Job>

createPermission

createPermission(
    actions: string | string[],
    grantedTo: IGrantedTo[],
    _public: boolean,
): Promise<Permission>
Creates a new file permission for a user, project, or group.
Parameters
- actions: string | string[]
  Actions are allowed to be performed on a file with this permission:
  
  read - The ability to read file description, geometry data and properties.
  
  readSourceFile - The ability to download source file.
  
  write - The ability to modify file name, description and references.
  
  readViewpoint - The ability to read file viewpoints.
  
  createViewpoint - The ability to create file viewpoints.
- grantedTo: IGrantedTo[]
  A list of entities that will get access to the file.
- _public: boolean
  Specifies whether all users have access to the file or not.
Returns Promise<Permission>
Example: Grant the specified user permission to "update" the file.
```
const action = "update";
const grantedTo = [{ user: { id: myUser.id, email: myUser.email } }];
await file.createPermission(action, grantedTo);
```
Example: Add a file to the specified project in "read-only" mode.
```
const actions = ["read", "readSourceFile"];
const grantedTo = [{ project: { id: myProject.id, name: myProject.name } }];
await file.createPermission(actions, grantedTo);
```

createSharedLink

createSharedLink(permissions?: ISharedLinkPermissions): Promise<SharedLink>
Creates a file shared link.
Parameters
- Optionalpermissions: ISharedLinkPermissions
  Share permissions.
Returns Promise<SharedLink>

delete

delete(): Promise<any>
Deletes a file and all its versions from the server.

You cannot delete a version file using delete(), only the original file. To delete a version file use deleteVersion().

Returns Promise<any>
Returns the raw data of a deleted file. For more information, see Open Cloud Files API.

Overrides Endpoint.delete

deletePermission

deletePermission(permissionId: string): Promise<any>
Removes the specified permission from the file.
Parameters
- permissionId: string
  Permission ID.
Returns Promise<any>
Returns the raw data of a deleted permission. For more information, see Open Cloud File Permissions API.

deletePreview

deletePreview(): Promise<File>
Removes the file preview.

Returns Promise<File>

deleteSharedLink

deleteSharedLink(): Promise<any>
Deletes the file shared link.

Returns Promise<any>
Returns the raw data of a deleted shared link. For more information, see Open Cloud SharedLinks API.

deleteSource

deleteSource(): Promise<File>
Deletes the source file of the active file version from the server.

Returns Promise<File>

deleteVersion

deleteVersion(version: number): Promise<any>
Deletes the specified version file.
Parameters
- version: number
  Version to delete.
Returns Promise<any>
Returns the raw data of a deleted version file. For more information, see Open Cloud Files API.

deleteViewpoint

deleteViewpoint(guid: string): Promise<any>
Deletes the specified file viewpoint.
Parameters
- guid: string
  Viewpoint GUID.
Returns Promise<any>
Returns the raw data of a deleted viewpoint. For more information, see Open Cloud File Viewpoints API.

download

download(
onProgress?: (progress: number) => void,
signal?: AbortSignal,
): Promise<ArrayBuffer>
Downloads the source file of active version of the file from the server.
Parameters
- OptionalonProgress: (progress: number) => void
  Download progress callback.
- Optionalsignal: AbortSignal
  An AbortController signal. Allows to communicate with a fetch request and abort it if desired.
Returns Promise<ArrayBuffer>

downloadFileRange

downloadFileRange(
    requestId: number,
    records: any,
    dataId: string,
    onProgress?: (
        progress: number,
        downloaded: Uint8Array,
        requestId: number,
    ) => void,
    signal?: AbortSignal,
): Promise<void>
Deprecated since 25.3. Use downloadResourceRange() instead.
Parameters
- requestId: number
- records: any
- dataId: string
- OptionalonProgress: (progress: number, downloaded: Uint8Array, requestId: number) => void
- Optionalsignal: AbortSignal
Returns Promise<void>
Deprecated

downloadResource

downloadResource(
    dataId: string,
    onProgress?: (progress: number, chunk: Uint8Array) => void,
    signal?: AbortSignal,
): Promise<ArrayBuffer>
Downloads a resource file of the active version of the file. Resource files are files that contain model scene descriptions, or geometry data, or exported files.
Parameters
- dataId: string
  Resource file name.
- OptionalonProgress: (progress: number, chunk: Uint8Array) => void
  Download progress callback.
- Optionalsignal: AbortSignal
  An AbortController signal. Allows to communicate with a fetch request and abort it if desired.
Returns Promise<ArrayBuffer>
Example: Export file to PDF.
```
const job = await file.createJob("pdf");
await job.waitForDone();
const pdfResourceName = file.exports.find((x) => x.endsWith(".pdf"));
const arrayBuffer = await file.downloadResource(pdfResourceName);
const blob = new Blob([arrayBuffer]);
const fileName = file.name + ".pdf";
FileSaver.saveAs(blob, fileName);
```

downloadResourceRange

downloadResourceRange(
    dataId: string,
    requestId: string | number,
    ranges: { begin: number; end: number; requestId: number }[],
    onProgress?: (
        progress: number,
        chunk: Uint8Array,
        requestId: number,
    ) => void,
    signal?: AbortSignal,
): Promise<ArrayBuffer>
Downloads a part of resource file of the active version of the file. Resource files are files that contain model scene descriptions, or geometry data, or exported files.
Parameters
- dataId: string
  Resource file name.
- requestId: string | number
  Specify a non-empty requestId to append the ?requestId= search parameter to the server request. If specified, server-side caching may not work.
- ranges: { begin: number; end: number; requestId: number }[]
  A ranges of resource file contents to download. See HTTP range requests for more details.
- OptionalonProgress: (progress: number, chunk: Uint8Array, requestId: number) => void
  Download progress callback.
- Optionalsignal: AbortSignal
  An AbortController signal. Allows to communicate with a fetch request and abort it if desired.
Returns Promise<ArrayBuffer>

extractGeometry

extractGeometry(type?: string, parameters?: string | object): Promise<Job>
Runs a File Converter job to convert geometry data of active version of the file to the specified format. This is alias to createJob("geometry").
Parameters
- Optionaltype: string
  Geometry data type. Can be one of:
  
  vsfx - VSFX format (default), for opening a file in VisualizeJS 3D viewer.
  
  gltf - glTF format, for opening a file in Three.js 3D viewer.
- Optionalparameters: string | object
  Parameters for the File Converter job. Can be given as command line arguments in form --arg=value.
Returns Promise<Job>

extractProperties

extractProperties(parameters?: string | object): Promise<Job>
Runs a File Converter job to extract properties of the active version of the file. This is alias to createJob("properties").
Parameters
- Optionalparameters: string | object
  Parameters for the File Converter job. Can be given as command line arguments in form --arg=value.
Returns Promise<Job>

getCdaTree

getCdaTree(): Promise<ICdaNode[]>
Returns the CDA tree for an active version of the file.

Returns Promise<ICdaNode[]>

getModels

getModels(): Promise<Model[]>
Returns a list of models of the active version of the file.

Returns Promise<Model[]>

getPermission

getPermission(permissionId: string): Promise<Permission>
Returns information about specified file permission.
Parameters
- permissionId: string
  Permission ID.
Returns Promise<Permission>

getPermissions

getPermissions(): Promise<Permission[]>
Returns a list of file permissions.

Returns Promise<Permission[]>

getProperties

getProperties(handles?: string | string[], group?: boolean): Promise<any[]>
Returns the properties for an objects in the active version of the file.
Parameters
- Optionalhandles: string | string[]
  Object original handle or handles array. Specify undefined to get properties for all objects in the file.
- group: boolean = false
  If the group parameter is true, properties are returned grouped by category. By default, or if group is set to false, properties are returned ungrouped.
  
  To get grouped properties, the --properties_group command line argument must be specified for the properties File Converter job when uploading the file:
  
  await client.uploadFile(file, { geometry: true, properties: true, jobParameters: { properties: "--properties_group" }, waitForDone: true, });
  
  or when running the extract file properties job:
  
  await file.extractProperties("--properties_group");
  
  Otherwise, the properties will be returned ungrouped, even if the group is true.
Returns Promise<any[]>

getReferences

getReferences(signal?: AbortSignal): Promise<IFileReferences>
Returns a list of file references.

References are images, fonts, or any other files to correct rendering of the file.
Parameters
- Optionalsignal: AbortSignal
  An AbortController signal, which can be used to abort waiting as desired.
Returns Promise<IFileReferences>

getSharedLink

getSharedLink(): Promise<SharedLink>
Returns information about the file shared link or undefined if file is not shared.

Returns Promise<SharedLink>

getSnapshot

getSnapshot(guid: string): Promise<string>
Returns viewpoint snapshot as base64-encoded Data URL.
Parameters
- guid: string
  Viewpoint GUID.
Returns Promise<string>

getSnapshotData

getSnapshotData(guid: string, bitmapGuid: string): Promise<string>
Returns viewpoint snapshot data.
Parameters
- guid: string
  Viewpoint GUID.
- bitmapGuid: string
  Bitmap GUID.
Returns Promise<string>

getVersion

getVersion(version: number): Promise<File>
Returns information about the specified version file.
Parameters
- version: number
  Desired version.
Returns Promise<File>

getVersions

getVersions(): Promise<File[]>
Returns a list of version files.

Returns Promise<File[]>

getViewpoints

getViewpoints(): Promise<any[]>
Returns a list of file viewpoints. For more information, see Open Cloud File Viewpoints API.

Returns Promise<any[]>

partialDownloadResource

partialDownloadResource(
    dataId: string,
    onProgress?: (progress: number, downloaded: Uint8Array) => void,
    signal?: AbortSignal,
): Promise<ArrayBuffer>
Deprecated since 25.3. Use downloadResource() instead.
Parameters
- dataId: string
- OptionalonProgress: (progress: number, downloaded: Uint8Array) => void
- Optionalsignal: AbortSignal
Returns Promise<ArrayBuffer>
Deprecated

save

save(): Promise<File>
Saves file properties changes to the server. Call this method to update file data on the server after any property changes.

Returns Promise<File>

saveViewpoint

saveViewpoint(viewpoint: any): Promise<any>
Saves a new file viewpoint to the server. To create a viewpoint use Viewer.createViewpoint().
Parameters
- viewpoint: any
  Viewpoint object. For more information, see Open Cloud File Viewpoints API.
Returns Promise<any>

searchProperties

searchProperties(searchPattern: any): Promise<any[]>
Returns the list of original handles for an objects in the active version of the file that match the specified patterns. Search patterns may be combined using query operators.
Parameters
- searchPattern: any
  Search pattern or combination of the patterns, see example below.
Returns Promise<any[]>
Example: Simple search pattern.
```
searchPattern = {
  key: "Category",
  value: "OST_Stairs",
};
```
Example: Search patterns combination.
```
searchPattern = {
  $or: [
    {
      $and: [
        { key: "Category", value: "OST_GenericModel" },
        { key: "Level", value: "03 - Floor" },
      ],
    },
    { key: "Category", value: "OST_Stairs" },
  ],
};
```

setActiveVersion

setActiveVersion(version: number): Promise<File>
Replaces the active version of the file with the selected version.
Parameters
- version: number
  Desired active version.
Returns Promise<File>

setPreview

setPreview(image?: BodyInit): Promise<File>
Sets or removes the file preview.
Parameters
- Optionalimage: BodyInit
  Preview image. Can be a Data URL string, ArrayBuffer, Blob or Web API File object. Setting the image to null will remove the preview.
Returns Promise<File>

setReferences

setReferences(references: IFileReferences): Promise<IFileReferences>
Sets the file references.

References are images, fonts, or any other files to correct rendering of the file. Reference files must be uploaded to the server before they can be assigned to the current file.
Parameters
- references: IFileReferences
  File references.
Returns Promise<IFileReferences>

update

update(data: any): Promise<File>
Updates file data on the server.
Parameters
- data: any
  Raw file data. For more information, see Open Cloud Files API.
Returns Promise<File>

uploadVersion

uploadVersion(
    file: File,
    params?: {
        geometry?: boolean;
        interval?: number;
        onProgress?: (progress: number, file: File) => void;
        properties?: boolean;
        signal?: AbortSignal;
        timeout?: number;
        waitForDone?: boolean;
    },
): Promise<File>
Uploads the new version of the file to the server, convert the geometry data and extract properties as needed.
Parameters
- file: File
  Web API File object are generally retrieved from a FileList object returned as a result of a user selecting files using the HTML <input> element.
- params: {
      geometry?: boolean;
      interval?: number;
      onProgress?: (progress: number, file: File) => void;
      properties?: boolean;
      signal?: AbortSignal;
      timeout?: number;
      waitForDone?: boolean;
  } = ...
  An object containing upload parameters.
  - Optionalgeometry?: boolean
    Create job to convert file geometry data. The geometry data type is the same as the original file.
  - Optionalinterval?: number
    The time, in milliseconds, the function should delay in between checking jobs status.
  - OptionalonProgress?: (progress: number, file: File) => void
    Upload progress callback.
  - Optionalproperties?: boolean
    Create job to extract file properties.
  - Optionalsignal?: AbortSignal
    An AbortController signal, which can be used to abort waiting as desired.
  - Optionaltimeout?: number
    The time, in milliseconds that the function should wait jobs. If no one jobs are done during this time, the TimeoutError exception will be thrown.
  - OptionalwaitForDone?: boolean
    Wait for geometry and properties jobs to complete.
Returns Promise<File>

useVersion

useVersion(version?: number): this
Makes the given version active on client side. Does not change the active file version on the server.

This version change will affect the result:
- getModels()
- getProperties()
- searchProperties()
- getCdaTree()
- download()
- downloadResource()
- createJob()
- extractGeometry()
- extractProperties()
- validate()
- waitForDone()
- Viewer.open()
Other clients will still continue to use the current active version of the file. Use undefined to revert back to the active version.

You need to reload the file data using checkout() to match the size and status fields to the version you selected.
Parameters
- Optionalversion: number
Returns this
Overrides Endpoint.useVersion

validate

validate(parameters?: string | object): Promise<Job>
Runs an IFC validator job to validate the active version of the file. This is alias to createJob("validation").

To get validation report use downloadResource("validation_report.json").
Parameters
- Optionalparameters: string | object
  Parameters for the IFC validator tool. Can be given as command line arguments in form --arg=value.
Returns Promise<Job>

waitForDone

waitForDone(
    jobs: string | string[],
    waitAll?: boolean,
    params?: {
        interval?: number;
        onCheckout?: (file: File, ready: boolean) => boolean;
        signal?: AbortSignal;
        timeout?: number;
    },
): Promise<File>
Waits for jobs of the active version of the file to be done. Job is done when it changes to none, done or failed status.
Parameters
- jobs: string | string[]
  Job name or array of job names to wait on. Can be geometry, geometryGltf, properties, validation, dwg, obj, gltf, glb, vsf, pdf, 3dpdf or custom job name.
- OptionalwaitAll: boolean
  If this parameter is true, the function returns when all the specified jobs have done. If false, the function returns when any one of the jobs are done.
- Optionalparams: {
      interval?: number;
      onCheckout?: (file: File, ready: boolean) => boolean;
      signal?: AbortSignal;
      timeout?: number;
  }
  An object containing waiting parameters.
  - Optionalinterval?: number
    The time, in milliseconds, the function should delay in between checking jobs status.
  - OptionalonCheckout?: (file: File, ready: boolean) => boolean
    Waiting progress callback. Return true to cancel waiting.
  - Optionalsignal?: AbortSignal
    An AbortController signal, which can be used to abort waiting as desired.
  - Optionaltimeout?: number
    The time, in milliseconds that the function should wait jobs. If no one jobs are done during this time, the TimeoutError exception will be thrown.
Returns Promise<File>

Class File

Hierarchy (View Summary)

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Parameters

Returns File

Properties

headers

path

Accessors

activeVersion

Returns number

created

Returns string

customFields

Returns any

data

Returns any

exports

Returns string[]

geometryType

Returns string

id

Returns string

isFileDeleted

Returns boolean

name

Returns string

originalFileId

Returns string

owner

Returns IShortUserDesc

previewUrl

Returns string

sharedLinkToken

Returns string

size

Returns number

sizeTotal

Returns number

status

Returns IFileStatus

type

Returns string

updatedAt

Returns string

updatedBy

Returns IShortUserDesc

version

Returns number

versions

Returns IFileVersionInfo[]

Methods

checkout

Returns Promise<File>

createJob

Parameters

Returns Promise<Job>

createPermission

Parameters

Returns Promise<Permission>

Example: Grant the specified user permission to "update" the file.

Example: Add a file to the specified project in "read-only" mode.

createSharedLink

Parameters

Returns Promise<SharedLink>

delete

Returns Promise<any>

deletePermission

Parameters

Returns Promise<any>

deletePreview

Returns Promise<File>

deleteSharedLink

Returns Promise<any>