Upload and Download Files

What happens if you are not programming in javascript?

If you are not programming in javascript, you can use the api directly, see TOTALUM API DOCUMENTATION

If you are programming in javascript, you can use the totalumSdk

Note: If you use totalumSdk inside a totalum plugin, you don't need to authenticate, you can start using totalum sdk functions like this: modules.totalumSdk.crud.uploadFile(); etc...

If you have questions about how to install and use TotalumSdk, check the documentation: Totalum SDK Installation, and Using the SDK

In Totalum, you can upload files and link them to your data. For example, you can upload a PDF file and link it to a client, or upload an image and link it to a product.

To do this, when creating a table, for example a client table, you can add a property of type file, and when creating or editing a client, you will be able to upload a file and link it to the client.

1. Upload the file to Totalum

To scan a document, first you need to upload the file to Totalum. You can do this using the Totalum API directly or using the Totalum SDK.

1.1 Transform the file to a blob

If you are not using javascript, you will need to do this step using the language you are using. Search on internet how to transform a file to a blob in your language. Or also you can ask chatgpt to transform the following examples to your language.

Depending on the platform you are using, you will need to transform the file to a blob. Here are some examples:

From a file input (Frontend)

    const fileInput = document.getElementById('fileInput');
    const fileBlob = fileInput.files[0];

From a file in storage (Backend)

    const fs = require('fs');
    const yourFilePath = 'your_file_path'; // example: /user/your_file.pdf
    const fileBlob = fs.readFileSync(yourFilePath);

From a remote file (Backend)

    const response = await axios.get('your_file_url', { responseType: 'stream' });
    const fileBlob = response.data;

From a base64 string (Frontend/Backend)

    // Convert base64 to binary
    const binaryStr = atob(base64String);
    const len = binaryStr.length;
    const bytes = new Uint8Array(len);
    for (let i = 0; i < len; i++) {
        bytes[i] = binaryStr.charCodeAt(i);
    }

    let fileBlob;

    // Environment check: Node.js or Browser
    if (typeof process === 'object' && process.version) {
        // Node.js environment
        // Convert Uint8Array to Buffer for Node.js usage
        const buffer = Buffer.from(bytes.buffer);
        // Here, 'buffer' can be used similarly to how you'd use a Blob in the browser
        // Note: Direct Blob emulation isn't possible in Node.js, but Buffer is a close alternative for file handling
        fileBlob = buffer;
    } else {
        // Browser environment
        // Create a Blob from the Uint8Array
        const blob = new Blob([bytes], { type: fileType });
        fileBlob = blob;
    }

1.2 Upload the file to Totalum

Using Totalum SDK

    const FormData = require('form-data'); // if you are using node.js

    const fileName = 'your_file_name.png'; // replace 'your_file_name' with the name of your file, replace .png with the extension of your file
    const file = yourFileBlob // your blob file created in the previous step 
    const formData = new FormData();
    formData.append('file', file, fileName);
    const result = await totalumClient.files.uploadFile(formData);
    const fileNameId = result.data.data;

Using Totalum API

    const FormData = require('form-data'); // if you are using node.js

    const fileName = 'your_file_name.png'; // replace 'your_file_name' with the name of your file, replace .png with the extension of your file
    const file = yourFileBlob // your blob file created in the previous step 
    const formData = new FormData();
    formData.append('file', file, fileName);
    const result = await axios.post('https://api.totalum.app/files/upload', formData, {
        headers: {
            'Content-Type': 'multipart/form-data',
            'api-key': 'your api key here', // replace 'your api key here' with your api key
        }
    });
    const fileNameId = result.data.data;

Upload a file to Totalum and link it to an item property

const fileName = 'your_file_name.png';
const file = yourFileBlob 
formData.append('file', file, fileName);
const result = await totalumClient.files.uploadFile(formData);
const fileNameId = result.data.data;

//if you want to link this file to an item, you need to add the fileNameId to the item property of type file
const result2 = await totalumClient.crud.editItemById('your_element_table_name', 'your_item_id', {'your_file_property_name': {name: fileNameId}});
// now the file is linked to the item property, and you can see it in the totalum panel.

//what happens if your_file_property_name is a multiple file property?
const result2 = await totalumClient.crud.editItemById('your_element_table_name', 'your_item_id', [{'your_file_property_name': {name: fileNameId}}]);
// in this case, you must set an array of files, but if you don't want to lost existing files, you can set the existing files in the array and add the new file at the end of the array

example:

Imagine you have a table called client with the following properties:

name (text)
email (text)
phone (text)
photo (file)

And you want to create a new client with name John Doe, the email [email protected], the phone +34 123 456 789, and the birthday 1990-01-01, and you want to link a photo to the client.

// first, we upload the file
const fileName = 'your_file_name.png';
const file = yourFileBlob
formData.append('file', file, fileName);
const result = await totalumClient.files.uploadFile(formData);
const fileNameId = result.data.data;

// then, we create the client
const tableElementName = 'client';
const clientToCreate = {
    name: 'John Doe',
    email: '[email protected]',
    phone: '+34 123 456 789',
    photo: {
        name: fileNameId
    }
};

const result2 = await totalumClient.crud.createItem(tableElementName, clientToCreate);

// now the client is created and the photo is linked to the client

//what happens if your_file_property_name is a multiple file property?
const clientToCreate = {
    name: 'John Doe',
    email: '[email protected]',
    phone: '+34 123 456 789',
    photo: [{
        name: fileNameId
    }]
};
// in this case, you must set an array of files, but if you don't want to lost existing files, you can set the existing files in the array and add the new file at the end of the array

Remove a file from Totalum

// you can remove a file from totalum using the file name id
const fileNameId = 'your_file_name.png'; // replace 'your_file_name' with the name id of your file, replace .png with the extension of your file

const result = await totalumClient.files.deleteFile(fileNameId);

If you want to remove a file linked to an item property, you can do it like this:

const tableElementName = 'client';
let your_item_id = '5f9b2b1b9c6f6b0001a3b2b1';
const result = await totalumClient.crud.editItemById(tableElementName, your_item_id, {'photo': null});
// this will remove the photo from the client with id '5f9b2b1b9c6f6b0001a3b2b1'

Download a file from Totalum

// you can get the fileNameId from the result of the upload file function
const fileNameId = 'your_file_name.png'; // replace 'your_file_name' with the name id of your file, replace .png with the extension of your file

//optional options
const options = {
    // the default expiration time is 128 hours, but you can set it to whatever you want, after the expiration time the url will not return the file
    expirationTime: Date.now() + (128 * 60 * 60 * 1000); // Set to expire in 128 hours, how it works is, set the current date in milliseconds + the milliseconds you want the url to expire
}

const result = await totalumClient.files.getDownloadUrl(fileNameId, options);
let [fileUrl] = result.data.data;
// the result will be a full url that you can use to download the file

Download a file linked to an item property

PD: usually, when you link a file to an item property, the property automatically generates a file url that you can use to download the file.

You can access the file linked to an item property in this way:

Imagine you have a table called client with the following properties:

name (text)
email (text)
phone (text)
photo (file)

And you want to download the photo of the client with id 5f9b2b1b9c6f6b0001a3b2b1.

const tableElementName = 'client';
let clientId = '5f9b2b1b9c6f6b0001a3b2b1';

const result = await totalumClient.crud.getItemById(tableElementName, clientId);

const client = result.data.data;

let clientPhotoUrl = client.photo.url; // this is the url of the photo, you can use it to download the photo

// but in some cases, if you want to get a new temporal url to download the file, you can do it like this:
const clientPhotoId = client.photo.name;

const result2 = await totalumClient.files.getDownloadUrl(clientPhotoId);

let [fileUrl] = result2.data.data;

Upload and Download Files

What happens if you are not programming in javascript?​

If you are programming in javascript, you can use the totalumSdk​

1. Upload the file to Totalum​

1.1 Transform the file to a blob​

From a file input (Frontend)​

From a file in storage (Backend)​

From a remote file (Backend)​

From a base64 string (Frontend/Backend)​

1.2 Upload the file to Totalum​

Upload a file to Totalum and link it to an item property​

Remove a file from Totalum​

If you want to remove a file linked to an item property, you can do it like this:​

Download a file from Totalum​

Download a file linked to an item property​