How-to guides - Multipart Form

Multipart form request (opens new window) is typically used to send large files and data to a server.

This request format can be declared in any keys (execute, acquire, fields etc.) in your custom adapter code. This is done by embedding the data format inside the Content-Type header.

Sample code snippet

Let's use the Convert document endpoint in IBM Watson API (opens new window) as an example. This endpoint accepts a document in multipart/form-data format.

A cURL example looks like this:

curl \
  https://gateway.watsonplatform.net/document-conversion/api/v1/convert_document?version=2015-12-15 \
  -X POST \
  -u "{username}":"{password}" \
  -F config="{\"conversion_target\":\"answer_units\"}" \
  -F "[email protected];type=application/pdf"

Workato:

{
  title: "IBM Watson",

  connection: {
    # Some code here
  },

  test: {
    # Some code here
  },

  actions: {
    upload_file: {
      input_fields: lambda do
        [
          { name: "file_name", type: "string" },
          { name: "file_data", type: "string" },
          { name: "conversion_target", type: "string" }
        ]
      end,

      execute: lambda do |connection, input|
        post("https://gateway.watsonplatform.net/document-conversion/api/v1/convert_document").
          params(version: "2015-12-15").
          request_format_multipart_form.
          payload(file: [input['file_data'], 'application/pdf'],
                  file_name: input['file_name'],
                  config: "{\"conversion_target\":\"#{input['conversion_target']}\"}")
      end
    },

    output_fields: {
      # Some code here
    }
  },

  triggers: {
    # Some code here
  },
  object_definitions: {
    # Some code here
  },
  pick_lists: {
    # Some code here
  },
  methods: {
    # Some code here
  }

In the SDK, notice that the file key in the payload takes an array of length 2. This defines the request as form data. The first item in the array is the file data and the second item is the media type (MIME type) of the input file.

Components

cURL	Workato
curl https://gateway.watsonplatform.net/document-conversion/api/v1/convert_document?version=2015-12-15 -X POST	post("https://gateway.watsonplatform.net/document-conversion/api/v1/convert_document") .params(version: "2015-12-15")
-u "{username}":"{password}"	This is defined in the [connection](../authentication/basic-authentication.md) key and is automatically added onto the outgoing request.
-F config="{\"conversion_target\":\"answer_units\"}" -F "[email protected];type=application/pdf"	.request_format_multipart_form .payload(     file: [input['file_data'], 'application/pdf'],     file_name: input['file_name'],     config: "{\"conversion_target\":\"#{input['conversion_target']}\"}")

Variations

Sometimes, the name of the file must be explicitly stated in the multipart form as part of the file payload, instead of a separate key-value pair, like the previous example. To satisfy this, you can adjust your payload to this.

Note: this filename is different from the payload key (file)

execute: lambda do |connection, input|
  post("https://gateway.watsonplatform.net/document-conversion/api/v1/convert_document").
    params(version: "2015-12-15").
    request_format_multipart_form.
    payload(file: [input['file_data'], 'application/pdf', input['file_name']],
            config: "{\"conversion_target\":\"#{input['conversion_target']}\"}")
end