Skip to main content

Upload and attach a file

How to upload and attach a file to an item​

Most items implement the Files Attachable interface, which means you can upload a file to Alloy and then store a link to it within an item's Attachments attribute.

For more information, see:

Example JavaScript​

This example demonstrates how to attach a file to an item. In summary:

  1. Upload the file to Alloy. The response from this request will provide you with a fileItemId.

  2. Fetch the item's details (ItemWebModel). The most important property you require is the item signature, but you should also retrieve the collection, geometry, icon and colour. For another example, see Fetch an item.

  3. Perform a request to edit the item, adding the fileItemId to the item's filesAttachableAttachments attribute. For another example, see Editing an item.

// load a http request library
const axios = require("axios");
const fsPromise = require("fs").promises;
const FormData = require("form-data");

// enter your api key here!
const apiKey = "e0e3a4ef-5ec8-4e05-ac25-a34adadf4a80";

// the id of the item you wish to attach the file to
const attachItemId = 5dda8584ca315005f4be5061

// run
uploadFileAndAttach("asset-photo.jpg", attachItemId)
  .then((updatedItem) => {
    // output the new signature of updated item to the console
    console.log(updatedItem.signature);
  })
  .catch((error) => {
    // output any error data to the console
    console.log(error.response.data);
  });

// function to upload file and attach it to item, returns updated item
async function uploadFileAndAttach(uploadFileName, attachItemId) {
  // upload the file
  const fileId = await uploadFile(uploadFileName);
  // fetch the item's details
  const item = await getItem(attachItemId);
  // edit the item to attach the file
  const updatedItem = await attachFileToItem(item, fileId);

  return updatedItem;
}

// function to upload file, returns ID of uploaded file
async function uploadFile(fileName) {
  const file = await fsPromise.readFile(fileName);

  // create form data and append file to it
  const formData = new FormData();
  formData.append("file", file);

  // send file upload request
  const fileUploadResponse = await axios({
    method: "POST",
    url: `https://api.uk.alloyapp.io/api/file`,
    headers: {
      Authorization: `Bearer ${apiKey}`,
      // specify content-type as multipart/form-data
      "Content-Type": "multipart/form-data",
      // specify content-disposition so that API knows the uploaded file name
      // because Alloy will need it to set the title of the File System Objects item
      "Content-Disposition": `attachment; filename="${fileName}"`,
    },
    // send formData with file
    formData,
  });

  return fileUploadResponse.data.fileItemId;
}

// function to get the item model
async function getItem(itemId) {
  // send request to get latest version of item
  const itemGetResponse = await axios({
    method: "GET",
    url: `https://api.uk.alloyapp.io/api/item/${itemId}`,
    headers: { Authorization: `Bearer ${apiKey}` },
  });

  return itemGetResponse.data.item;
}

// function to attach file to item, returns updated item model
async function attachFileToItem(item, fileId) {
  const itemUpdateResponse = await axios({
    method: "PUT",
    url: `https://api.uk.alloyapp.io/api/item/${item.itemId}`,
    headers: { Authorization: `Bearer ${apiKey}` },
    // set data for item edit
    data: {
      // set signature from item that we just received in item get response
      signature: item.signature,
      // keep item collection
      collection: item.collection,
      // keep item colour
      colour: item.colour,
      // keep item icon
      icon: item.icon,
      // set attributes that you need to edit
      attributes: [
        {
          // set file attachments attribute by passing ID of uploaded file
          attributeCode: "attributes_filesAttachableAttachments",
          value: [fileId]
        }
      ]
    }
  });

  return itemUpdateResponse.data.item;
}