Build a Wrangle

A wrangle is “the definition of one or more steps used to manipulate data and create a new Data Store.” You lay the steps out on a canvas like a flowchart: read data in, transform it, write the result out to a data store.

Think of it as a recipe your data follows every time the wrangle runs. Once it’s built, you can run it again whenever the source data changes, or on a schedule, without repeating the work by hand.

When to use this

Build a wrangle when you need to change data, not only look at it: recode values, join two data sources, translate or score text, or weight the data. The result is a new (or updated) data store that the rest of the platform can use.

Permission Requirements

Any Licensed user can create a wrangle. To change one, you need to be its Owner or have edit access. Others can open a wrangle, but their changes won’t save.

---

Create a wrangle

1. Open the Create menu - On the Data Wrangler home, click the arrow on the Create Data Store button and choose Create Wrangle. After that, the button reads Create Wrangle until you reload the page, so you can click it directly to create another.
2. Name it - In the New Wrangle dialog, type a Name and click OK.
3. Start building - The wrangle editor opens, with an empty canvas.

To open a wrangle later, click View on its row in the Wrangles group. To rename it, use More → Rename on the Data Wrangler home; there’s no rename inside the editor.

---

The wrangle editor

The editor has four parts:

• The palette, on the left, lists the steps you can add, in two groups: I/O and MICROSERVICES.
• The canvas, in the middle, is where you place and connect steps.
• The settings panel opens below the canvas when you click a step.
• The toolbar has Toggle Annotation, Undo, Redo and More (for Publish Now and Define Schedule).

The steps

Group	Step	What it does
I/O	Reader	”The starting point of any Wrangle”: picks the data source and the fields to bring in
I/O	Writer	”The final stage of a Wrangle”: sets the output data store and the fields it contains
MICROSERVICES	Recode	Recodes values into a new or existing field. See Recode data.
MICROSERVICES	Join	Combines two data sources. See Join data.
MICROSERVICES	Redaction, Translation, Text Scoring, Focus Words	Work with open text. See Process text.
MICROSERVICES	Weighting	Weights the data to target proportions. See Weight data.

Every wrangle needs at least one Reader and one Writer. The microservice steps are optional.

---

Add and connect steps

1. Drag a step onto the canvas - From the palette. If you drop it onto an existing line between two steps, it’s slotted in between.
2. Connect the steps - Drag from the right-hand edge of one step to the left-hand edge of the next. The lines set the order the steps run in.
3. Set up each step - Click a step to open its settings below the canvas. Click close to put them away.

A few rules:

• A Reader only has an output, and a Writer only has an input. Every other step needs a line in and a line out.
• A Join has two inputs: Input 1 (Left) and Input 2 (Right).
• A wrangle can have only one Focus Words step.

Label your steps

Each new step is labeled “add note”. Double-click the label to describe what the step does, like “Recode NPS into groups”. Click Toggle Annotation to show or hide all the labels.

Remove a step, or undo

• To remove a step, right-click it and choose Delete.
• Click Undo or Redo in the toolbar to step back or forward through your changes.
• To read about a step, right-click it and choose About this node.
• To find a step’s ID for support, right-click it and choose Node Guid. A Node Guid box shows the ID.
• To stop a connector being dragged out of place, right-click it and choose Lock. Choose Unlock to allow it again.

---

Set up the Reader

The Reader chooses where your data comes from.

1. Click the Reader - Its settings open on the Field Picker tab.
2. Choose a data source - Click Data Source Name. In Add New Data Source, choose Data Store or Survey, then pick the one you want.
3. Choose the fields - Move the fields you need from Available Fields to Selected Fields: drag them, double-click them, or use the arrows to move them all.
4. Filter rows if you need to - Use the Row Filter tab to bring in only some records.

You need access to the source data store. If it hasn’t been shared with you, you’ll see: “You do not have access to the source DataStore. Please ask the DataStore’s owner to share it with you”.

Changing the source resets later steps

If you choose a different data source, the Reader’s fields and filter are cleared, and the steps connected after it are disconnected and reset. There’s no warning first. Removing fields from a connected Reader also resets the steps after it, but that does ask you to confirm.

You don’t need to remove fields you don’t want from the Reader. You can leave them out at the Writer instead.

---

Set up the Writer

The Writer decides where the result goes.

1. Click the Writer - Its settings open on the Field Picker tab.
2. Choose Write To -
   • New DataStore: type a name in Output DataStore Name.
   • Existing DataStore: click SELECT and pick the data store to write to.
3. Choose When Processing - Append New Data (“append any new data to the existing dataset”) or Replace All Data (“delete all existing data and re-insert”).
4. Choose the output fields - Move the fields you want from Available Fields to Output Fields.

Replace All Data deletes the output every run

With Replace All Data, every time the wrangle runs, everything in the output data store is deleted and written again. Anything else stored there, including data added by hand, is lost. Choose Append New Data if you want to keep what’s there.

If the Writer writes to the same data store a Reader reads from, Replace All Data is turned off to protect your data.

---

Saving

The editor saves your changes automatically as you work. You’ll see SAVE SUCCESS after each save.

Opening a step’s settings and closing them again also counts as a change. You’ll see SAVE SUCCESS, and the wrangle’s Last Edited date on the Data Wrangler home moves on, even if you didn’t change anything.

If someone else has changed the wrangle since you opened it, you’ll be told “Your data wrangler is not up to date!”, with who changed it and when. Click YES to reload the latest version. Your own unsaved changes are replaced.

Building the wrangle doesn’t run it. To produce your output data store, publish it. See Run & schedule a wrangle.

---

Frequently Asked Questions

Why do I see SAVE FAILED?

You may not have edit access to this wrangle. You can open it, but changes won’t save. Ask the owner for edit access.

Can I have more than one Reader or Writer?

Yes. You need at least one of each, and you can only have one Focus Words step.

Why is Replace All Data greyed out?

The Writer is writing to the same data store a Reader reads from. Turning off Replace All Data stops the wrangle from deleting its own source.

How do I rename a wrangle?

On the Data Wrangler home, hover over the wrangle and choose More → Rename.

What happened to the steps after my Reader?

Changing the Reader’s data source, or removing its fields, resets the steps connected after it. Reconnect them and set them up again.

---

Common Issues and Solutions

”SAVE FAILED”

Your change wasn’t saved.

1. Check your access - You need edit access to the wrangle.
2. Reload - Reload the page and make the change again.

”Your data wrangler is not up to date!”

Someone else saved the wrangle after you opened it.

1. Reload - Click YES to load their version, then make your change again.

”You do not have access to the source DataStore.”

The data store you want to read from isn’t shared with you.

1. Ask for access - Ask the data store’s owner to share it with you. See Share content.

”Only one Focus Words node in one Wrangle.”

A wrangle can have only one Focus Words step.

1. Use the one you have - Or build a second wrangle for another Focus Words model.

”Please detach existing connectors first”

You dropped a step that’s already connected onto another line.

1. Disconnect it first - Remove the step’s existing lines, then drop it onto the new line.

”Missing connector to node : …” or “Missing connector from node : …”

A step isn’t connected properly. You’ll see this when you publish.

1. Find the step - Steps with problems show a red ”!”.
2. Connect it - Add the missing line, then publish again.