Public Files SDK

⚠️⚠️⚠️

This sdk documentation is deprecated and will not be updated. Check out our new docs at https://sdk.buildfire.com/docs/public-files/

⚠️⚠️⚠️

Overview

API accessible via the plugin SDK that allows plugin developers to upload files to our servers.

Note: Additional charges may be added to the app owner. Current Maximum file size is 25mb. Contact your account manager if you'd like to increase capacity.

Prerequisites

On the widget page or control page you need to include scripts/buildfire/services/publicFiles/publicFiles.js:

<script src="../../../scripts/buildfire/services/publicFiles/publicFiles.js"></script>

Methods

buildfire.services.publicFiles.showDialog(options,onProgress ,onComplete, callback);

This method will show up the browse dialog in order to be used by the app user to select the needed files.

arguments

• options : object

  • allowMultipleFilesUpload: boolean
    • This property will give the plugin developers the functionality for allowing the users to select multiple files or single file.
  • filter: array of file content types
    • This property will give the plugin developers the functionality to filter the file types which allowed to be uploaded.
  • permissions: object
    • This property will give the plugin developers the functionality to restrict file access by managing users who have read, write, delete and admin access to file. If no permissions object is passed, file will be public by default. Read more on permissions management below.

• onProgress(error , file) required: function will be invoked when uploading each file and it will return the percentage of completion for each file

• onComplete(error , files ) required: function will be invoked after each file has been uploaded and it will be called on each file completion.

• callback(errors,files) required: function will be invoked after all files have been uploaded.

  • files: array [{fileId , fileName , url , size(KB) , status, type } , {fileId , fileName , url , size(KB) , status, type }]

Example:

var onProgress = function(result){
console.log("onProgress" + JSON.stringify(result));
} 

var onComplete = function(result){
console.log("onComplete" + JSON.stringify(result));
}

var callback = function(err,result){
console.log("callback" + JSON.stringify(result));
}

buildfire.services.publicFiles.showDialog({filter : ["image/jpeg","image/png"] , allowMultipleFilesUpload : true}, onProgress , onComplete ,callback);

buildfire.services.publicFiles.getFileUrl(options, callback);

This method will get signed url that enables access to private files. Any file without "public" in read permissions is considered private. Note: In case the file is not private, it can be accessed directly using url returned from showDialog callback. Read more on permissions management below.

arguments

• options : object

  • fileId: string

• callback(error,file) required: function will be invoked after all files have been uploaded.

  • file: object { url }

Example:

const callback = function(err, file) {
	buildfire.navigation.openWindow(file.url, '_system');
}

buildfire.services.publicFiles.getFileUrl({fileId: "thisIsFileIdFromShowDialogCallback"}, callback);

buildfire.services.publicFiles.modifyPermissions(options, callback);

This method will modify file permissions. User needs to be file admin in order to change file permissions. Read more on permissions management below.

arguments

• options : object

  • fileId: string
  • permissions: object

• callback(error,file) required: function will be invoked after all files have been uploaded.

  • file: object { fileId , fileName , url }

Example:

const callback = function(err, file) {
	buildfire.navigation.openWindow(file.url, '_system');
}

const options = {
	fileId: "thisIsFileIdFromShowDialogCallback",
	permissions: {
		read: ["public"],
		write: ["user@email.com"],
		delete: ["user@email.com"],
		admin: ["user@email.com"]
	}
}

buildfire.services.publicFiles.modifyPermissions(options, callback);

buildfire.services.publicFiles.deleteFile(options, callback);

This method will delete file. User needs to be file admin or have delete permission in order to delete file. Read more on permissions management below.

arguments

• options : object
  • fileId: string
• callback(error,file) required: function will be invoked after all files have been uploaded.
  • file: object { fileId , fileName , url }

Example:

const callback = function(err, file) {
	if(err) return console.error(err);
	console.log("File deleted successfully", file.fileName);
}

const options = {
	fileId: "thisIsFileIdFromShowDialogCallback",
}

buildfire.services.publicFiles.deleteFile(options, callback);

buildfire.services.publicFiles.uploadFiles(files,options,onProgress ,onComplete, callback);

This method lets plugin developers upload files without showing file dialog. This way developer has more freedom on how to display file selection.

arguments

• files : array

  • Array of javascript File objects

• options : object

  • allowMultipleFilesUpload: boolean
    • This property will give the plugin developers the functionality for allowing the users to select multiple files or single file.
  • filter: array of file content types
    • This property will give the plugin developers the functionality to filter the file types which allowed to be uploaded.
  • permissions: object
    • This property will give the plugin developers the functionality to restrict file access by managing users who have read, write, delete and admin access to file. If no permissions object is passed, file will be public by default.

• onProgress(error , file) required: function will be invoked when uploading each file and it will return the percentage of completion for each file

• onComplete(error , files ) required: function will be invoked after each file has been uploaded and it will be called on each file completion.

• callback(errors,files) required: function will be invoked after all files have been uploaded.

  • files: array [{fileId , fileName , url , size(KB) , status, type } , {fileId , fileName , url , size(KB) , status, type }]

Managing Permissions

Permission object consists of 4 keys: read, write, delete and admin

• read - who can access file?
• write - who can edit file?
• delete - who can delete file?
• admin - who can change the read, write and delete arrays above?

Each array above can be made by each of the following:

• userId - buildfire user id
• email - email linked to buildfire user
• tag - buildfire tag
• public - word public

Example

{
	read: ["public"],
	write: ["janedoe@example.com", "__ADMIN__"],
	delete: ["user@example.com"],
	admin: ["user@example.com"]
}

In the example above, anyone with link can access file since read permission have word public inside. User with email janedoe@example and anyone with tag __ADMIN__ can edit file. Only user with user@example.com can delete file and change file permissions.

If no permsissions object is passed in any of the functions above it defaults to

{
	read: ["public"],
	write: ["public"],
	delete: ["public"],
	admin: ["user@example.com"]
}

where user@example.com is email of the user uploading the file.