Handling Binary Files

Integrations in Prismatic generally process serialized JSON, XML or other simple strings and pass deserialized JavaScript objects between steps. But, there are situations when you may want to process and pass binary data between steps. By "binary data", we mean files that are not plain text - PDF files, images, MP3 audio, etc.

Within an integration, a binary file is represented by its contentType (MIME type), and a Buffer that contains the file's data. See Mozilla's documentation for a list of common file MIME types.

{ data: Buffer.from("..."), contentType: "application/pdf" };

Processing binary data as an input

Inputs for binary files are similar to any other input you might create, though you can use the util.types.toData function to ensure that the input has the form { data: Buffer, contentType: string }:

{
  inputs: {
    myFile: input({
      label: "My File",
      type: "data",
      required: true,
      clean: util.types.toData,
    });
  }
}

The myFile property that comes in to your perform function will have the form of a binary file, with data and contentType properties that you can reference.

{
  perform: async (context, params) => {
    const { data: fileData, contentType } = params.myFile;
    // Send the data to an endpoint
    axios.post("http://my-endpoint", fileData, {
      headers: { "Content-Type": contentType },
    });
  };
}

Returning binary data from an action

To return a binary file, from your action, ensure that the data you return is a Buffer and optionally include a contentType property alongside data that indicates its MIME type. For example, if your custom component returns a rendered PDF file and the PDF contents are saved in a Buffer variable named pdfContents, the return block might look like this:

return {
  data: pdfContents,
  contentType: "application/pdf",
};

You can return multiple files, or binary files in a nested object with a similar structure:

return {
  myKey: "myValue",
  myPdf: {
    data: pdfBuffer,
    contentType: "application/pdf",
  },
  myPng: {
    data: pngBuffer,
    contentType: "image/png",
  },
};

Fetching binary data with the Spectral HTTP client

When fetching binary data from an API, you must configure your HTTP client to expect binary data and to write the data to a Buffer. For the HTTP client (which is Axios-based), use the responseType: "arraybuffer" configuration option to ensure the data property returned is a Buffer:

{
  perform: async (context, params) => {
    const client = createBambooClient(params.connection);
    const { data, headers } = await client.get(`/v1/files/${params.fileId}`, {
      responseType: "arraybuffer",
    });
    return { data, contentType: headers["content-type"] };
  };
}