> For the complete documentation index, see [llms.txt](https://hub.equipme.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://hub.equipme.io/dokumentation/automation/connectors/utilities.md).

# Utility modules: Lists and PDF

Utility modules Lists and PDF: compare and merge lists, convert HTML to PDF – e.g. to reconcile with the HR list or to create a handover protocol.

**Path:** "Automation" → "Workflows" → flow designer → **"Lists"** and **"PDF"** modules

The utility modules **Lists** and **PDF** are part of equipme and complement the other connectors in [workflows](https://hub.equipme.io/dokumentation/automation/workflows.md). They do not connect a system of their own but process data within the flow: comparing and merging lists and generating documents as PDF.

## What for?

* **Reconcile with the HR list:** compare the employee list from equipme with a list from the HR system and handle new, changed and departed employees separately.
* **Inventory reconciliation:** compare assets in equipme with the device inventory of a device management system to find missing or differing entries.
* **Merge lists:** combine results from two sources (e.g. two locations or two systems) into one list.
* **Handover protocol:** when a device is handed out, generate a PDF with device, serial number and employee and send it by email.
* **Reports:** turn a list (e.g. open order requests) into a PDF report and send it regularly.

## Prerequisites

* The activated [Automation module](https://hub.equipme.io/dokumentation/automation.md)
* **Lists:** no connection required.
* **PDF:** a connection of the [equipme connector](https://hub.equipme.io/dokumentation/automation/connectors/equipme.md) (API key). The conversion runs via equipme.

## Setting up the connection

The components of the **Lists** module work without a connection.

For **HtmlToPdf** in the **PDF** module:

1. Drag the *HtmlToPdf* component onto the canvas.
2. Click **Connect account** and select an existing equipme connection or create a new one with **Label** and **API Key** (see [equipme connector](https://hub.equipme.io/dokumentation/automation/connectors/equipme.md#setting-up-the-connection)).
3. The connection appears under **"Accounts"**.

## Triggers

The utility modules have **no triggers**. They work with the data of previous components.

## "Lists" module

| Component | Purpose                                                      | Key options                     |
| --------- | ------------------------------------------------------------ | ------------------------------- |
| Compare   | Compare two lists and distribute the entries to four outputs | Origin, Update, Key, Attributes |
| Join      | Merge two lists into one list                                | Array 1, Array 2                |

### Compare

*Compare* compares an original list (**Origin**) with a new list (**Update**). Both inputs expect a **list** – for equipme components, the Output Type "All items at once".

| Option     | Meaning                                                                                                                                                     |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Origin     | The original list, e.g. the employees from equipme.                                                                                                         |
| Update     | The new list, e.g. the employees from the HR system.                                                                                                        |
| Key        | Required. One or more fields (comma-separated) that uniquely identify an entry, e.g. `email` or `employeeNumber` or `firstName, lastName`.                  |
| Attributes | Optional. Fields (comma-separated) whose change marks an entry as "changed", e.g. `position, costCenter`. Empty: only new and removed entries are detected. |

Outputs:

| Output    | Content                                                                                                                                                              |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| added     | Entries that only exist in **Update** (new).                                                                                                                         |
| changed   | Entries in both lists where at least one of the **Attributes** differs. Fields from both lists are merged; for identical field names the value from **Update** wins. |
| removed   | Entries that only exist in **Origin** (gone).                                                                                                                        |
| unchanged | Entries in both lists without changes. For identical field names the value from **Origin** wins.                                                                     |

Good to know:

* The comparison ignores upper and lower case (`Max@Company.com` = `max@company.com`).
* The field names in **Key** and **Attributes** must be identical in **both** lists. If a field has a different name in the HR system, rename it first (e.g. with a component that rebuilds the list).
* Every output delivers a list – even an empty one. To process entries individually, split the list into single entries afterwards.
* If a key occurs several times in one list, only the last entry counts.

### Join

*Join* appends **Array 2** to **Array 1** and outputs one combined list. Duplicates are **not** removed – clean up the list afterwards with *Compare* or a filter.

## "PDF" module

| Component | Purpose                                                              | Key options                                                         |
| --------- | -------------------------------------------------------------------- | ------------------------------------------------------------------- |
| HtmlToPdf | Convert HTML content into a PDF and provide it as a file in the flow | Title, Header, Body, Footer, margins, Paper Size, Paper Orientation |

### HtmlToPdf

| Option                             | Meaning                                                                                                                     |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| Title                              | File name of the PDF (without extension). Empty: "document.pdf".                                                            |
| Header                             | Optional. HTML for the header of every page, e.g. logo and company name.                                                    |
| Body                               | Required. HTML of the content. Variables from previous components (name, device, serial number …) can be inserted directly. |
| Footer                             | Optional. HTML for the footer of every page, e.g. date or signature line.                                                   |
| Margin Top / Left / Right / Bottom | Margins in pixels. Default: top 130 (40 without header), left and right 45, bottom 100.                                     |
| Paper Size                         | "A4" (default), "A3", "A5", "A6", "Letter", "Legal", "Tabloid", "D", "E". "None" equals A4.                                 |
| Paper Orientation                  | Page orientation, default "Portrait". For wide tables a larger paper size (e.g. "A3") works well.                           |

Result: **File ID**, **File Name** and **Content Type**. Pass the **File ID** to components that accept files – e.g. **Email › Send Email** ("Attachments" field), **Equipme › Upload Service Instance Attachments** or *AddTicketAttachment* in the [Zoho Desk](https://hub.equipme.io/dokumentation/automation/connectors/zoho-desk.md) connector.

{% hint style="info" %}
Use simple HTML with embedded CSS (`<style>` in the body). Images are best included via a publicly reachable URL or as embedded data.
{% endhint %}

## Examples

### Reconcile the employee list with the HR list

1. **Scheduler** – daily at 6 am.
2. **Equipme › List Employees** – Output Type "All items at once".
3. Fetch the HR list, e.g. via **HTTP** from the HR system or from a CSV file. Name the fields as in equipme (e.g. `email`).
4. **Lists › Compare** – Origin = step 2, Update = step 3, Key `email`, Attributes `position, costCenter, phoneBusiness`.
5. Output **added** → **Equipme › Add Employee**; output **changed** → **Equipme › Update Employee**; output **removed** → **Email › Send Email** to HR for review.

### Create and send a handover protocol

1. **Equipme › New Fulfillment Order** – trigger on a new delivery.
2. **PDF › HtmlToPdf** – Title "Handover protocol {last name}", header with logo, body with employee, device, serial number, inventory number and handover date, footer with signature fields.
3. **Email › Send Email** – to the employee and IT, Attachments = File ID from step 2.
4. Optional **Equipme › Upload Service Instance Attachments** – store the PDF on the asset.

### Weekly PDF report

1. **Scheduler** – every Monday.
2. **Equipme › List Order Requests** or another list action – read open entries.
3. **PDF › HtmlToPdf** – list as an HTML table, Paper Size "A4".
4. **Email › Send Email** – report to the people responsible.

## Notes and limits

* *Compare* and *Join* work in the flow's memory. Very large lists (many thousands of entries) slow down the flow.
* A margin of 0 is not applied; the default value is used instead. For borderless pages enter 1.
* *HtmlToPdf* counts as a request to equipme and is subject to the API key's [request limit](https://hub.equipme.io/dokumentation/automation/connectors/equipme.md#request-limit).

## Troubleshooting

| Problem                                                | Cause / solution                                                                              |
| ------------------------------------------------------ | --------------------------------------------------------------------------------------------- |
| *Compare* reports all entries as "added" and "removed" | The **Key** fields have different names in the two lists or are empty. Align the field names. |
| *Compare* reports no changes                           | **Attributes** is empty or the field names do not match.                                      |
| *Compare* or *Join* fails                              | An input is not a list. For equipme components, select Output Type "All items at once".       |
| *HtmlToPdf*: connection error                          | Check the API key of the equipme connection.                                                  |
| PDF is empty or badly formatted                        | The body must contain valid HTML. Embed CSS in a `<style>` block; check external stylesheets. |
| Header or footer overlaps the content                  | Increase Margin Top or Margin Bottom.                                                         |

Logs of every run are available under **"Insights"**.

## Frequently asked questions

**Does the HR list need the same fields as equipme?**

Only the fields in **Key** and **Attributes** must have the same names in both lists. All other fields are passed through unchanged.

**Can I use Compare to reconcile assets too?**

Yes. Any list with a unique key works, e.g. serial number or inventory number.

**Where does the generated PDF end up?**

As a file in the flow. It is only stored permanently when you pass it on – e.g. as an email attachment, as an attachment on the asset or on a ticket.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://hub.equipme.io/dokumentation/automation/connectors/utilities.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
