Working with files

Send and receive files in a custom connector built with Connector Builder, using multipart parameters for uploads and file-typed output properties for downloads.

Connectors built with Connector Builder can both download files from a provider and upload files to it. The HTTP Request activity does not support files, so it is not an alternative for either case.

Files are handled in two different places:

• Downloads are configured on the activity's output, in the Activity designer.
• Uploads are configured on the API resource, as a multipart parameter, and surfaced as an activity input field.

Downloading a file

To return a file from an activity instead of a JSON payload, change the output property's data type in the Activity designer:

1. In the Activity designer, select the output property that carries the file.
2. Select Edit field.
3. Under Field settings, set Data type to File.

The generated activity then returns a file instead of parsed fields. The output type depends on the project type:

Project type	File output
Studio Desktop and Studio Web RPA projects	An IResource file, named from the Content-Disposition header of the provider response. Pass it to any activity that accepts a resource, such as the file activities in the System or Microsoft 365 activity packages.
API workflows and Maestro	A file reference with ID, FullName, MimeType, and Metadata fields.

In API workflows and Maestro, the activity returns a file only when the file property is its only output field.

Uploading a file

A file is uploaded through a parameter on the API resource. To configure one:

1. In the Activity designer, open the resource and select the parameter that carries the file.
2. Under Parameter settings, set Parameter type to multipart.
3. Set Data type to file.
4. Under Provider information, set Provider type to multipart.
5. Set Provider data type to file.

Connector Builder derives the request content type from the parameter: a resource that has a multipart parameter is sent as multipart/form-data, and a resource that does not is sent as application/json. You do not set the content type yourself.

A resource can mix locations. Alongside the file parameter you can keep parameters in the query, path, header, or body, and add further multipart parameters of other data types — for example a string parameter carrying the file name.

The parameter then appears as a file input on the generated activity, and in the Send Request dialog as a Choose file control, so you can test the resource before you publish.

Tip:

To inspect or modify the parts of a multipart request from a connector script, use the multipart_hook_context_items variable. For details, see Global scripts.

First-party connectors already ship this pattern — the Box connector uses a file-typed multipart parameter for its upload resources.

Known limitations

• Field generation: Connector Builder does not generate fields for a resource that has a multipart parameter, and says so in the Send Request dialog, under Generate resource fields. Define the fields for such a resource manually.
• Request body editor: The request body editor accepts JSON. Multipart requests are expressed through parameters on the API resource.