# File Helpers

The File Helpers connector can be used to create files from content or from URLs as well as converting the character encoding of a file into UTF-8.

## Overview

The File Helpers connector is a useful tool for creating file from ready made content, or from URLs themselves. It can also convert the character encoding of a file into UTF-8 format.

> **MANIPULATING FILE CONTENT**: The File Helpers connector CANNOT manipulate file content, but other connectors within the Tray platform can. For CSV content refer to the [CSV Editor](https://tray.ai/documentation/connectors/core/csv-editor) docs and XML content refer to the [XML Decoder](https://tray.ai/documentation/connectors/core/xml-decoder) docs.

## Important notes

### ANSI

If you are unsure of the file encoding, but know it to be ANSI, within the properties panel in the field 'Original encoding', select: `latin-1` from the dropdown options available.

### ASCII

Please be ware that you cannot convert ASCII to UTF-8 format due to the heritage of this type of encoding.

### Mime type

When using certain connectors, like Google Drive, with File Helpers, we need to define the "mime\_type." This field describes the type of media. For example, when doing the File Upload operation for Google Drive, the file object that is passed as input requires several fields like mime\_type. By default, File Helpers will define mime\_type as null, but Google Drive's File Upload operation doesn't accept null value for mime\_type.
Therefore, to define mime\_type, add a header called "mime\_type" and for the value enter in the mime\_type (e.g "application/pdf"). It is also important to make sure the filename's extension lines up with what you enter for mime\_type (e.g .pdf).

### Create PDF

Please be aware that you can't just encode a pdf. You need to generate it. Unless the content helper has context, just using .pdf won't give you a pdf file.
Below is an example of how you can use the HTTP Client to create a PDF file from some sample HTML. Note that numerous different formats can be used in conjunction with this particular API service.

### 1 - Create PDF

This example uses the [pdf.co API](https://apidocs.pdf.co/) and the HTTP Client in order to convert sample HTML into PDF format. **This is just an example of a service which you could potentially use to do this**.
Here are further details of the [cURL command](https://apidocs.pdf.co/25-pdf-from-html-html-to-pdf?utm_referer=app.pdf.co/login_verify#code-snippet) used. Note that the HTTP Client comes with a handy [Import](https://tray.ai/documentation/connectors/core/http-client/#quickstart---import-a-request) feature which will save you time putting the properties and parameters in manually.
Remember it is good practice to always hide your keys behind your authentication method and not hard code them into the properties panel.
![filehelper-pdf-create](https://tray.ai/documentation/images/connectors/helper/file-helper/4drYgoowqlupRZU2IJ1H9a_filehelper-pdf-create.png)

### 2 - Create downloadable file

The output from the previous step is in URL format. The **Convert file from URL** operation will allow you to download the file locally.
![filehelper-pdf-download](https://tray.ai/documentation/images/connectors/helper/file-helper/79xVfZ1dHsX3M2MIdUHUke_filehelper-pdf-download.png)

## Create File from Object

This example will demonstrate how to create a file from a Salesforce record and then upload the files to an S3 bucket.
The **Create file from content** operation can be used to pull records from services and extract specific data fields in order to create files based on this content.
This example shows the **Create File from Content** operation in action.
The complete workflow (using a Manual Trigger for testing purposes) looks like this:
![file-from-content-workflow](https://tray.ai/documentation/images/connectors/helper/file-helper/2d13afc7-207e7f32_file-from-content-workflow.png)
What we will be doing here is:

* Listing Accounts in Salesforce
* Looping through each account one-by-one
* Pulling the required data from each account to create a JSON file based on each account
* Uploading each account as a file to an S3 bucket
  Note that this example is suitable for working with a very small number of records. In a production environment where you might be working with large numbers you will need to use a [pagination](https://tray.ai/documentation/platform/automation-integration/advanced-use-cases/batching-queueing/pagination) system to split the records into manageable batches.

### 1 - List Salesforce Accounts

Please see our [Salesforce documentation](https://tray.ai/documentation/connectors/service/salesforce/) for instructions on granting Tray access to your Salesforce instance.
With the first **Salesforce** connector, set the operation to **Find Records**, the **Record Type** to **'Account'** and set **'Account ID'** as the **Field** to be returned, as this is what we will use to locate each account in the second Salesforce step:
![file-helpers-sf-find-records](https://tray.ai/documentation/images/connectors/helper/file-helper/2d13afc7-373b75b9_file-helpers-sf-find-records.png)

### 2 - Loop through the Accounts list

For the **Loop connector** set the operation as **Loop List** and then grab the list of records from the first Salesforce step using `$.steps.salesforce-1.records`:
![file-helpers-loop-records](https://tray.ai/documentation/images/connectors/helper/file-helper/2d13afc7-3068e152_file-helpers-loop-records.png)

### 3 - Grab the individual Account data from Salesforce

For each Account, use the second **Salesforce** step to pull the data needed to create each file by using the **Find Records** operation. The Record Type is set as **Account** and you can specify the fields to be returned which will make up the file. The key thing here is that you also set the **Condition** so that the **Account ID** is equal to `$.steps.loop-1.value.Id`:
![file-helpers-sf-find-records-by-id](https://tray.ai/documentation/images/connectors/helper/file-helper/2d13afc7-dc867881_file-helpers-sf-find-records-by-id.png)

### 4 - Create the File from the Account Data

For the **File Helpers** step set the operation to **Create File from Content**:
![file-helpers-create-from-content](https://tray.ai/documentation/images/connectors/helper/file-helper/2d13afc7-c53f4241_file-helpers-create-from-content.png)
In this example we are setting the **Name** of the file to be auto-created using the Account ID. This is done using 'interpolation' where we can keep the field type as String and surround the json path in `{ }`.
This is so that we can append '.json' to the filename.
The full entry is `{$.steps.salesforce-2.records[0].Id}.json`
Note that `records[0].Id` is used here because the output from salesforce-2 is in the format:

```json
{
	"total": 1,
	"next_page_offset": null,
	"records": [
		\{
			"Id": "0014J000003GNllQAG",
			"Name": "sForce",
			"Type": null,
			"Industry": null
		\}
	]
}
```

So you can see that you are using \[0] to get the first record in an array (of one!) and picking **Id** as the value from that record.

### 5 - Upload the file to an S3 bucket

Please see our [AWS S3 documentation](https://tray.ai/documentation/connectors/service/aws-s3/) for instructions on granting Tray access to your S3 buckets.
For the **AWS S3** step, set the operation to **Put Object (File)** and choose the **Bucket name** you wish to upload to. Set the **Object Key** as the file path including the file name (pulled from file-helpers-1) and set the file as `$.steps.file-helpers-1.file`:
![file-helpers-upload-to-s3](https://tray.ai/documentation/images/connectors/helper/file-helper/2d13afc7-29646a75_file-helpers-upload-to-s3.png)

### 6 - Check logs and S3 bucket for uploaded files

Once your workflow is correctly configured, click on 'Run workflow' and then check the 'Debug' tab to see if the run is successful:
![file-helpers-debug](https://tray.ai/documentation/images/connectors/helper/file-helper/2d13afc7-d08063af_file-helpers-debug.png)
Finally you can check in S3 to see the files succesfully uploaded:
![file-helpers-uploaded-to-s3](https://tray.ai/documentation/images/connectors/helper/file-helper/2d13afc7-4713725b_file-helpers-uploaded-to-s3.png)

## Create File from URL

This example shows the **Create File from URL** operation in action by pulling a CSV file attached to an email.
The **Create file from URL** operation can be used to import a file from a URL and subsequently pass it to another service.
The workflow snippet looks like this:
![create-from-url-workflow](https://tray.ai/documentation/images/connectors/helper/file-helper/2d13afc7-d4f5abfd_create-from-url-workflow.png)

### 1 - Email Trigger

The workflow is kicked off by an email trigger, whereby you can send an email with a file (such as a CSV) attached to your worflow, as explained in our [Email Trigger](https://tray.ai/documentation/connectors/trigger/email-trigger/) documentation.

### 2 - Create file from URL

Now, for the File Helpers step you can set the operation to **Create file from url** and use the connector snake to pick up the `$.steps.trigger.attachments[0].url` jsonpath, which will get the file from the temporary url which Tray has made for the attachment:
![get-file-from-url](https://tray.ai/documentation/images/connectors/helper/file-helper/2d13afc7-bc86498e_get-file-from-url.gif)

### 3 - Use the created file

The next step is to start using the created file with our [CSV Editor](https://tray.ai/documentation/connectors/core/csv-editor) or [CSV Reader](https://tray.ai/documentation/connectors/core/csv-reader/).
The **Create CSV from file** operation can use the `$.steps.file-helpers-1.file.url` jsonpath to get the file created by the file helpers step:
![create-csv-file](https://tray.ai/documentation/images/connectors/helper/file-helper/2d13afc7-97e238b3_create-csv-file.png)
For further instructions on how to read and work with CSV files, please see the documentation for our [CSV Editor](https://tray.ai/documentation/connectors/core/csv-editor) or [CSV Reader](https://tray.ai/documentation/connectors/core/csv-reader/).

## Convert to UTF-8 from URL

> **Info:** Please see the above 'Notes on Operations usage' section for information on ANSI, ASCII and Mime type

It is now possible to convert various types of encoded files (such as Base-64), into UTF-8. Below is a good example of how to convert an ANSI encoded file from Google Drive, into a UTF-8 encoded one.

> **Info:** **USER TIP**: This connector and operation is ideally paired with the [CSV Editor](https://tray.ai/documentation/connectors/core/csv-editor) connector as it requires the UTF-8 charsetto function!

The completed workflow will look similar to the following:
![file-helpers-wf-complete](https://tray.ai/documentation/images/connectors/helper/file-helper/2d13afc7-ed2378b3_file-helpers-wf-complete.png)

### Step 1 - Setup Manual Trigger & Get URL

Once you have clicked 'Create new workflow' from your main Tray.io dashboard (and named said new workflow), select the Manual trigger from the trigger options available:
![file-helpers-manual-trigger](https://tray.ai/documentation/images/connectors/helper/file-helper/2d13afc7-c195364f_file-helpers-manual-trigger.png)
This particular File Helpers operation requires a URL for the document you wish to convert to UTF-8.
The easiest way to get this is by using a connector type that is relevant to the source of your document - in this case we are using a Google document, therefore the Google Drive connector will be needed (as this example is showcasing an ANSI encoded file within a Google drive account, that needs to be converted into UTF-8).
By using its available 'Download file' operation we are able to return the URL of the file needed. This should also be true of other Tray.io documentation connectors should you wish to utilise them.
*Note that the  \<Content type link TBD>  connector is needed NOT the  \<Content type link TBD>  connector. For more details see their relevant docs pages.*
With that said, once you have been redirected to the Tray.io workflow dashboard, from the connectors panel on the left add a Google Drive connector as your second step. Set the operation to 'Download File'.
![file-helpers-step-1](https://tray.ai/documentation/images/connectors/helper/file-helper/2d13afc7-16483661_file-helpers-step-1.png)
*Feel free to re-name your steps as you go along to make things clearer for yourself and other users.*

### Step 2 - Collect & Convert File

Once the properties panel for Google Drive is highlighted, add the 'File ID' of the document that needs converting. You can get this from the URL of the file itself.
Open the document you intend to convert in your browser window, and copy the hash displayed within the address bar.
Add a 'File Helpers' connector, as your second step. Set the operation to 'Convert to UTF-8 from URL'
This is an ANSI encoded file, *and because ANSI is a term used to describe a subset of encodings*, for this operation make sure to set the 'Original encoding' field to 'latin-1'. Now lets run the workflow. The 'URL' field can be generated using the connector-snake and jsonpathing methods.
In order to specify the information you want, start by using the 'URL' mapping icon (found next to the list input field, within the properties panel) to generate the connector-snake.
While hovering over the 'Download File' step (with the tail end of the connector-snake), select `URL` from the list of output properties displayed. This will auto-populate a jsonpath within your 'URL' input field, and update the type selector to jsonpath as well.
*For more clarification on the pathways you have available, open the Debug panel to view your step's Input and Output.*

> **Info:** **JSONPATHS:** For more information on what jsonpaths are and how to use jsonpaths with Tray, please see our pages on [Basic data concepts](https://tray.ai/documentation/platform/automation-integration/building-workflows/mapping-data/basic-data-concepts) and [Mapping data between steps](https://tray.ai/documentation/platform/automation-integration/building-workflows/mapping-data/mapping-data-between-steps)

> **Info:** \*\*CONNECTOR-SNAKE: \*\*The simplest and easiest way to generate your jsonpaths is to use our feature called the [Connector-snake](https://tray.ai/documentation/platform/automation-integration/building-workflows/mapping-data/mapping-data-between-steps/#the-connector-snake). Please see the main page for more details.

![file-helpers-step-2](https://tray.ai/documentation/images/connectors/helper/file-helper/2d13afc7-d00062a2_file-helpers-step-2.png)
As the rest of the fields are not mandatory you need not worry about filling them in at this stage, though feel free to do so depending on your use case.

### Step 3 - Display Output

Once you have completed setup, run your workflow by clicking on the green button in the bottom right hand corner named 'Run workflow'.
Open the Debug panel to view your results:
![file-helpers-step-3](https://tray.ai/documentation/images/connectors/helper/file-helper/2d13afc7-ef002958_file-helpers-step-3.png)
Tadah! Through the magic of Tray.io you now have a beautiful flawless newly UTF-8 encoded file!

> **Info:** \*\*BEST PRACTICES: \*\*Whenever you do decide to create your own workflow, be sure to check out some of our key articles such as:- [Using callable workflows](https://tray.ai/documentation/platform/automation-integration/building-workflows/composable-workflows/calling-other-workflows)
> - [Pagination](https://tray.ai/documentation/platform/automation-integration/advanced-use-cases/batching-queueing/pagination)
> - [Data transformation guide](https://tray.ai/documentation/platform/automation-integration/building-workflows/mapping-data/data-transformation-guide)