Excel Component

The Excel component connects a spreadsheet to the workflow. Use it to read data from an Excel sheet into the workflow (input), to write the results of the workflow to a sheet (output), or both. A workflow can have one Excel component. It is a VXL Live component: you build it in the Vince Platform workflow editor, and the workflow is used from VXL Live.

You set it up on a grid that looks like a worksheet. Fields from other components, such as M3 API or M3 Fetch, are dragged onto the columns.

Example: import 100 item updates

You want users to update 100 items in M3 from a sheet with an item number and a new description in each row.

1. Build the workflow: Trigger → M3 API (an item update transaction) → Excel.
2. In the M3 API step, set the transaction's inputs to the source Excel.
3. Open the Excel step, switch to Inputs, and drag Item number and the description field onto columns A and B.
4. Switch to Outputs and drag Workflow message onto column C, so each row shows its result.
5. Upload your own sheet as the template (see Start from an existing spreadsheet) and save.

In VXL Live, a user pastes the 100 rows into the sheet and runs the workflow. Each row is sent to M3 and the message for each row appears in column C.

---

Input and output

	What it does	Typical use
Inputs	Reads values from the sheet and passes them to the workflow, one row at a time	Importing or updating records, for example sending a list of items to M3
Outputs	Writes values produced by the workflow into the sheet	Exporting data, or showing the result for each row

In the Available parameters panel on the left, choose Inputs or Outputs to see the matching fields. Fields that are already mapped disappear from the list. Use the search box to find a field.

Separate sheets for input and output

For a workflow that reads from the sheet, you can read and write on different sheets. This is useful when the input rows and the results should not share a sheet.

1. Add the Excel component and open its template file (see Start from an existing spreadsheet).
2. Choose the Source sheet, then select Add target sheet and choose the Target sheet. The two sheets must be different.
3. In the editor, switch between the Source and Target tabs above the grid. The source sheet holds the inputs and the target sheet holds the outputs.

Select Remove target sheet to go back to a single sheet.

Import workflows

Mapping an input field means the workflow reads data from a spreadsheet, which makes it an Import Workflow. If the workflow is not one yet, a prompt asks whether you want to enable Import Workflow. Select Yes to enable it and continue mapping. Select No to cancel the mapping.

---

Map fields to columns

1. Open Available parameters. If it is hidden, select the arrow to show it.
2. Select the fields you want. Click a field to select it, hold Shift to select a range, or use Select All.
3. Drag them onto a column of the grid.
4. If you drop several fields onto columns that are already in use, choose whether to Replace existing columns, Insert as new columns or Map to same column.
5. Select Save.

To change a mapping, right-click the column header or the cell. The menu lets you remove mappings, add or delete columns, set the cell style or data type, sort by the column or use it to group rows (imports), and show the mapping info, which lists the fields mapped to a column and lets you remove any of them.

Rows of the sheet

Each sheet has up to three kinds of rows:

• Mapping row: holds the field names the workflow uses to find each column.
• Description row: holds readable headings for people.
• Data row: where the data starts.

The data row must come after the mapping and description rows. At least one of the mapping row and the description row is required, and they cannot be the same row. Use Settings to choose which header rows the sheet has.

Message columns

Under Special fields in the output list are two fields: Environment message and Workflow message. Map them to columns to show messages from the run next to each row. They are listed first among the outputs.

---

Start from an existing spreadsheet

Instead of building the grid by hand, you can start from a spreadsheet you already have.

1. Select Settings.
2. Under Template file, select the upload button and choose an Excel file.
3. In the preview, choose the Source sheet, and a Target sheet if you want separate sheets.
4. Check the rows. Set the Mapping row, Description row and Data row to match the sheet. If you change a row, select the check mark to apply it and run the automatic mapping again.
5. Select Apply. Vince Platform maps the columns it recognises to matching fields.
6. When asked Do you want to use this as design file as well?, answer Yes to also use the file as the design file.

The preview shows a message if something is wrong, such as a data row that is not after the header rows. Fix it before you apply.

The design file is the template people add to their workbook from VXL Live before they run the workflow; see Design files. You can upload, download or delete it under Settings.

---

Settings

Select Settings at the top of the editor.

Setting	Description
Sheet name	Name of the sheet the workflow reads or writes.
Description row / Mapping row	Which header rows the sheet has. At least one stays selected.
Control spreadsheet	Checks that the columns in the user's spreadsheet match the workflow definition, to catch inserted or renamed columns.
Enforce sheet verification	For files with several sheets, checks that the active sheet is the configured one and warns if it is not.
Save backup of output	Saves a copy of each generated Excel file.
Template file and Design file	See above.

You can also select Set common cells style to set fonts and colours for the sheet, and, for import workflows, Grouped by to review the columns used to group rows.

tip

Enable Control spreadsheet in production workflows to prevent silent data mapping failures caused by column changes in the source file.

---

Related

• M3 API — send or fetch M3 data through the spreadsheet
• M3 Fetch — read M3 data into the workflow
• M3 Filter — filter M3 API output before mapping it to Excel
• Table — map workflow data to a Vince Platform table instead of Excel
• File Loader — load the newest file from a SharePoint or OneDrive folder into the workflow
• Generic Filter — filter the spreadsheet rows before they are sent to M3