# Files

> Read files, make CSV, Excel, PDF, text, JSON and calendar files, edit images and PDFs, and zip or unzip files.

Built-in step · 7 steps. Web page: https://docs.lodol.com/docs/integrations/built-in/files

## Steps

### Combine into one PDF

Put PDFs and images together as one PDF, in the order you give them: a contract and its signed pages, or a month of receipt photos ready to send to your accountant. Each image gets a page of its own.

**Inputs**

- Files (`files`, list, required): The PDFs and images (JPG, PNG, WebP, GIF, BMP or TIFF) to combine, in the order they should appear. Upload them, or pick files or a list of files from earlier steps. Each image is fitted on a page the size of the first PDF's pages, or A4 when there are only images.
- File name (`filename`, text): What to call the PDF, such as October receipts. .pdf is added for you. Leave empty to call it combined.

**Outputs**: The new PDF, kept for 30 days. Give document_ref to a step that takes a file, such as an email's attachments or a drive upload.

- `content_type` (text): Always application/pdf.
- `count` (number): How many files were combined.
- `document_ref` (text): The PDF, for a later step that takes one.
- `documents` (list): The same PDF as a one-item list, the shape steps that download files return.
- `filename` (text): The PDF's name, .pdf included.
- `pages` (number): How many pages the PDF has.
- `size_bytes` (number): The PDF's size in bytes.

**Example output**

```json
{
  "content_type": "application/pdf",
  "count": 5,
  "document_ref": "doc_c9f0f895fb98ab9159f51fd0297e236d",
  "documents": [
    {
      "content_type": "application/pdf",
      "document_ref": "doc_c9f0f895fb98ab9159f51fd0297e236d",
      "filename": "October receipts.pdf",
      "size_bytes": 1284096
    }
  ],
  "filename": "October receipts.pdf",
  "pages": 7,
  "size_bytes": 1284096
}
```

### Create a file

Turn rows, text or data into a file you can attach to an email, upload to a drive, or download: a CSV or Excel spreadsheet, a PDF such as an invoice or a report, a text file, JSON, or a calendar invite that adds events to anyone's calendar.

**Inputs**

- File type (`format`, text, required): CSV and Excel files are spreadsheets made from rows. A PDF is a finished document, such as an invoice, a quote or a report, laid out from text. A text file holds text. JSON holds data for another system to read. A calendar invite adds events to Google Calendar, Outlook or Apple Calendar when it is opened. One of: `csv` (CSV file), `excel` (Excel file), `pdf` (PDF file), `text` (Text file), `json` (JSON file), `calendar` (Calendar invite (.ics)). Default: `csv`.
- Rows (`rows`, list, required): The rows to write, such as the rows a sheet or an earlier step returned. Each row's fields become the columns, and their names the header row. Only when File type is CSV file or Excel file.
- Text (`text`, text, required): What the file says. For a PDF, write it in Markdown (# Heading, **bold**, tables) or HTML, and it is laid out on the page for you. Only when File type is PDF file or Text file.
- Data (`data`, text, required): The data to save, such as an earlier step's result. Only when File type is JSON file.
- Events (`events`, list, required): One event, or a list of them, such as the rows of a sheet. Each needs a title (or summary, or name) and a start, and can have an end, a location, a description, a url and all_day. Dates are read in your time zone. Without an end, an event lasts an hour, or all day when its start is a date with no time. Only when File type is Calendar invite (.ics).
- File name (`filename`, text): What to call the file, such as Weekly leads. The right extension is added for you. Leave empty to call it data (or file, for text). A PDF is named after its title, and a calendar invite after its event (or invite, for several).

**Outputs**: The new file, kept for 30 days. Give document_ref to a step that takes a file, such as an email's attachments or a drive upload.

- `content_type` (text): The file's media type, such as text/csv, or text/calendar for a calendar invite.
- `document_ref` (text): The file, for a later step that takes one.
- `documents` (list): The same file as a one-item list, the shape steps that download files return.
- `filename` (text): The file's name, extension included.
- `size_bytes` (number): The file's size in bytes.

**Example output**

```json
{
  "content_type": "text/csv",
  "document_ref": "doc_8f14e45fceea167a5a36dedd4bea2543",
  "documents": [
    {
      "content_type": "text/csv",
      "document_ref": "doc_8f14e45fceea167a5a36dedd4bea2543",
      "filename": "Weekly leads.csv",
      "size_bytes": 2048
    }
  ],
  "filename": "Weekly leads.csv",
  "size_bytes": 2048
}
```

### Edit a PDF

Change a PDF's pages: keep only some of them (which also splits a PDF or takes one page out), add text such as PAID or CONFIDENTIAL, add an image such as a logo or a signature, or turn its pages into images.

**Inputs**

- PDF (`file`, text, required): The PDF to edit. Upload one, or pick one from an earlier step, such as an email attachment.
- What to do (`operation`, text, required): Keep only some pages makes a new PDF of the pages you choose, which is also how you split a PDF or take one page out. Adding text or an image puts it on top of the pages. Turning pages into images makes one image per page. One of: `keep_pages` (Keep only some pages), `add_text` (Add text to pages), `add_image` (Add an image to pages), `to_images` (Turn pages into images). Default: `keep_pages`.
- Pages to keep (`pages`, text, required): The pages to keep, in the order you want them, such as 1-3, 5 or 2-last. Write last for the last page. Only when What to do is Keep only some pages.
- Text (`text`, text, required): The text to put on the pages, such as PAID, CONFIDENTIAL or an invoice number. Only when What to do is Add text to pages.
- Image (`image`, text, required): The image to put on the pages, such as a logo, a signature or a stamp. A PNG with a see-through background looks best. Only when What to do is Add an image to pages.
- Pages (`on_pages`, text): Which pages, such as 1, 1-3 or last. Leave empty for every page. Only when What to do is Add text to pages, Add an image to pages or Turn pages into images.
- Position (`position`, text): Where on each page it goes. Only when What to do is Add text to pages or Add an image to pages. One of: `bottom_right` (Bottom right), `bottom_left` (Bottom left), `top_right` (Top right), `top_left` (Top left), `center`. Default: `bottom_right`.
- Size (`size`, text): How big it is on the page. Small suits a reference number or a signature; large suits a stamp such as PAID. Only when What to do is Add text to pages or Add an image to pages. One of: `small`, `medium`, `large`. Default: `small`.
- Save as (`image_format`, text): PNG keeps text sharp. JPG makes smaller files, and suits scanned pages and photos. Only when What to do is Turn pages into images. One of: `png`, `jpg`. Default: `png`.
- File name (`filename`, text): What to call the new file. The right extension is added for you. Leave empty to keep the PDF's name. Images are named by page, such as Contract page 1.png.

**Outputs**: What was made, kept for 30 days: a new PDF, or one image per page. Give document_ref to a step that takes a file, such as an email's attachments or a drive upload. For images, go through 'documents' with a Repeat for each, or give 'document_refs' to a step that takes several files.

- `content_type` (text): That file's media type: application/pdf, image/png or image/jpeg.
- `document_ref` (text): The new PDF, for a later step that takes a file. When pages were turned into images, the first image.
- `document_refs` (list): The same files as a plain list, for a step that takes several, such as an email's attachments.
- `documents` (list): Every file made, in page order: the one PDF, or one image per page. Each has document_ref, filename, content_type and size_bytes.
- `filename` (text): That file's name, extension included.
- `pages` (number): How many pages the new PDF has, or how many pages were turned into images.
- `size_bytes` (number): That file's size in bytes.

**Example output**

```json
{
  "content_type": "application/pdf",
  "document_ref": "doc_45c48cce2e2d7fbdea1afc51c7c6ad26",
  "document_refs": [
    "doc_45c48cce2e2d7fbdea1afc51c7c6ad26"
  ],
  "documents": [
    {
      "content_type": "application/pdf",
      "document_ref": "doc_45c48cce2e2d7fbdea1afc51c7c6ad26",
      "filename": "Contract.pdf",
      "size_bytes": 248310
    }
  ],
  "filename": "Contract.pdf",
  "pages": 3,
  "size_bytes": 248310
}
```

### Edit an image

Get a photo ready to post or send: turn it, resize or crop it to a post's size, add a watermark, and save it as a smaller JPG, PNG or WebP, all in one step.

**Inputs**

- Image (`image`, text, required): The photo to edit. Upload one, or pick one from an earlier step, such as an email attachment.
- Rotate (`rotate`, text): Turn the photo, such as one taken on its side. A phone photo is already turned upright for you; this turns it from there, before it is sized. One of: `none` (Don't rotate), `clockwise` (90° clockwise), `half` (180°), `counterclockwise` (90° counter-clockwise). Default: `none`.
- Size (`size`, text): Square and portrait posts suit Instagram and Facebook feeds, a story or reel fills a phone screen, and wide suits X, LinkedIn and YouTube. One of: `original` (Keep its size), `square` (Square post (1080 × 1080)), `portrait` (Portrait post (1080 × 1350)), `story` (Story or reel (1080 × 1920)), `wide` (Wide (1920 × 1080)), `custom` (Custom size). Default: `original`.
- Width (`width`, number): In pixels. Leave empty to follow the height and keep the photo's proportions. Only when Size is Custom size. From 1 to 8000.
- Height (`height`, number): In pixels. Leave empty to follow the width and keep the photo's proportions. Only when Size is Custom size. From 1 to 8000.
- Fit (`fit`, text): When the photo's shape differs from the size: fill the frame by trimming the edges evenly, or show the whole photo with a white border around it. Only when Size is Square post (1080 × 1080), Portrait post (1080 × 1350), Story or reel (1080 × 1920), Wide (1920 × 1080) or Custom size. One of: `fill` (Fill the frame), `whole` (Show the whole photo). Default: `fill`.
- Watermark (`watermark`, text): Your name or logo in a corner, so the photo stays yours wherever it's shared. One of: `none`, `text`, `logo`. Default: `none`.
- Watermark text (`watermark_text`, text, required): Such as © Acme Store or @acmestore. Only when Watermark is Text.
- Logo (`logo`, text, required): The logo to stamp on the photo. A PNG with a see-through background looks best. Only when Watermark is Logo.
- Watermark position (`position`, text): Where on the photo the watermark goes. Only when Watermark is Text or Logo. One of: `bottom_right` (Bottom right), `bottom_left` (Bottom left), `top_right` (Top right), `top_left` (Top left), `center`. Default: `bottom_right`.
- Save as (`format`, text): JPG suits photos and opens everywhere. PNG keeps see-through backgrounds and sharp graphics. WebP is the smallest, for websites. Keeping the original's type saves a GIF, BMP or TIFF as a PNG. One of: `original` (Same as the original), `jpg`, `png`, `webp`. Default: `original`.
- Compression (`compression`, text): How much to shrink the file. Balanced looks right in a post at a fraction of the size; strong suits a size limit, such as a marketplace's or an email's. One of: `light` (Light: best quality), `balanced`, `strong` (Strong: smallest file). Default: `balanced`.
- File name (`filename`, text): What to call the edited image. The right extension is added for you. Leave empty to keep the original's name.

**Outputs**: The edited image, kept for 30 days. Give document_ref to a step that takes a file, such as a social post's media, an email's attachments or a drive upload. Location and camera details are left out.

- `content_type` (text): The image's media type, such as image/jpeg.
- `document_ref` (text): The image, for a later step that takes one.
- `documents` (list): The same image as a one-item list, the shape steps that download files return.
- `filename` (text): The image's name, extension included.
- `height` (number): The image's height in pixels.
- `size_bytes` (number): The image's size in bytes.
- `width` (number): The image's width in pixels.

**Example output**

```json
{
  "content_type": "image/jpeg",
  "document_ref": "doc_45c48cce2e2d7fbdea1afc51c7c6ad26",
  "documents": [
    {
      "content_type": "image/jpeg",
      "document_ref": "doc_45c48cce2e2d7fbdea1afc51c7c6ad26",
      "filename": "Linen shirt.jpg",
      "size_bytes": 186420
    }
  ],
  "filename": "Linen shirt.jpg",
  "height": 1080,
  "size_bytes": 186420,
  "width": 1080
}
```

### Read a file

Get what's inside a file: the rows of a CSV or Excel sheet, the text of a PDF or Word document and how many pages a PDF has, the data in a JSON or XML file, or an image's size and shape. Works with an upload, an email attachment, or a file an earlier step downloaded.

**Inputs**

- File (`file`, text, required): The file to read. Upload one, or pick a file from an earlier step, such as an email attachment.
- Sheet (`sheet`, text): For an Excel file, the sheet to read. Leave empty for the first one.
- First row is a header (`has_header`, true/false): For a spreadsheet, use the first row as the column names. Turn this off when it starts straight into data; the columns are then named column_1, column_2, and so on. Default: `true`.
- Part to read (`part`, text): For an XML file, the part to read, such as //item for every item. Leave empty to read the whole file.

**Outputs**: What's inside the file. A spreadsheet's rows are in 'rows', each keyed by its column header (row.Email); a document's words are in 'text' and a PDF's page count in 'pages'; a JSON or XML file's value is in 'data'; an image's size and shape are in 'image'.

- `count` (number): How many rows were read.
- `data`: A JSON or XML file's value: an object, a list, or a single value. In XML, each element's attributes and the elements inside it are its fields, a tag repeated inside one element is a list, and an element holding only text is that text. With a Part to read, the parts found, as a list. Empty (null) for any other file.
- `filename` (text): The file's name.
- `headers` (list): A spreadsheet's column names, in order. Empty for a document.
- `image` (object): An image's details, as it is seen (a photo taken on its side counts as upright). Empty (null) for any other file.
- `pages` (number): How many pages a PDF has. Empty (null) for any other file.
- `rows` (list): One object per data row of a spreadsheet, keyed by column header. Empty for a document.
- `text` (text): Everything in the file as text: a document's words, or a spreadsheet's cells line by line. Empty for an image.
- `type` (text): What kind of file it was.

**Example output**

```json
{
  "count": 2,
  "data": null,
  "filename": "leads.csv",
  "headers": [
    "Name",
    "Email",
    "Company"
  ],
  "image": null,
  "pages": null,
  "rows": [
    {
      "Company": "Acme Corp",
      "Email": "jordan@acme.test",
      "Name": "Jordan Lee"
    },
    {
      "Company": "Northwind",
      "Email": "sam@northwind.test",
      "Name": "Sam Rivera"
    }
  ],
  "text": "Name,Email,Company\nJordan Lee,jordan@acme.test,Acme Corp\nSam Rivera,sam@northwind.test,Northwind",
  "type": "csv"
}
```

### Unzip a file

Open a ZIP file into the files inside it, such as a batch of invoices sent as one attachment. Each file is ready to read, upload or attach, one by one with a Repeat for each, or all at once.

**Inputs**

- ZIP file (`file`, text, required): The ZIP file to open. Upload one, or pick one from an earlier step, such as an email attachment.

**Outputs**: The files that were inside the ZIP, each kept for 30 days. Go through 'documents' with a Repeat for each to read or upload them one at a time, or give 'document_refs' to an email's attachments to send them all.

- `count` (number): How many files were inside.
- `document_refs` (list): The same files as a plain list, for a step that takes several, such as an email's attachments.
- `documents` (list): One entry per file, in the order they were zipped: document_ref, filename, the folder it was in inside the ZIP (empty at the top), content_type and size_bytes.
- `filename` (text): The ZIP file's name.

**Example output**

```json
{
  "count": 2,
  "document_refs": [
    "doc_45c48cce2e2d7fbdea1afc51c7c6ad26",
    "doc_d3d9446802a44259755d38e6d163e820"
  ],
  "documents": [
    {
      "content_type": "application/pdf",
      "document_ref": "doc_45c48cce2e2d7fbdea1afc51c7c6ad26",
      "filename": "INV-1042.pdf",
      "folder": "",
      "size_bytes": 84213
    },
    {
      "content_type": "application/pdf",
      "document_ref": "doc_d3d9446802a44259755d38e6d163e820",
      "filename": "INV-1043.pdf",
      "folder": "",
      "size_bytes": 79520
    }
  ],
  "filename": "October invoices.zip"
}
```

### Zip files

Pack files into one ZIP file, to send or upload them together: uploads, email attachments, or files earlier steps created or downloaded.

**Inputs**

- Files (`files`, list, required): The files to put in the ZIP. Upload them, or pick files or a list of files from earlier steps.
- File name (`filename`, text): What to call the ZIP file, such as October invoices. .zip is added for you. Leave empty to call it files.

**Outputs**: The new ZIP file, kept for 30 days. Give document_ref to a step that takes a file, such as an email's attachments or a drive upload.

- `content_type` (text): Always application/zip.
- `count` (number): How many files are in it.
- `document_ref` (text): The ZIP file, for a later step that takes one.
- `documents` (list): The same ZIP file as a one-item list, the shape steps that download files return.
- `filename` (text): The ZIP file's name, .zip included.
- `size_bytes` (number): The ZIP file's size in bytes.

**Example output**

```json
{
  "content_type": "application/zip",
  "count": 2,
  "document_ref": "doc_6512bd43d9caa6e02c990b0a82652dca",
  "documents": [
    {
      "content_type": "application/zip",
      "document_ref": "doc_6512bd43d9caa6e02c990b0a82652dca",
      "filename": "October invoices.zip",
      "size_bytes": 151872
    }
  ],
  "filename": "October invoices.zip",
  "size_bytes": 151872
}
```