# Write custom fields in Simpro

> Write sanda's numbers into custom fields on your Simpro customers, jobs, quotes and leads. Each run sends only the values that changed.

A push to Simpro writes sanda's numbers into custom fields on your Simpro customers, jobs, quotes and leads: a lifetime value on each customer, a lead source on each job, the margin a quote was won at. The numbers come from your [semantic fluid](https://docs.sanda-os.com.au/semantic-fluid), so they mean what your team agreed they mean, and your team sees them on each record's custom fields in Simpro, beside everything else they work from.

Each run sends only the values that changed since Simpro last accepted them. A push updates records Simpro already has, found by their Simpro ID. It never creates or deletes a record, and it never touches a custom field it doesn't write.

:::note
Simpro custom fields is under **Choose a destination** on the **Push** tab once writing to Simpro is switched on for your console. If the card isn't there, ask sanda support.
:::

## Before you start

- **A Simpro user who may change the custom fields.** sanda writes as the user who connects it, and can change exactly what that user can. Their security group needs to allow changing custom fields on the customers, jobs, quotes or leads your pushes write.
- **The custom fields, set up in Simpro.** A push writes into custom fields that already exist. It doesn't make them, and it doesn't change their choices.
- **Each record's Simpro ID in your warehouse.** A push finds each record by its Simpro ID, so the rows it reads need the ID of the customer, job, quote or lead, in a column or a dimension.
- **One company at a time.** A Simpro ID is only unique within one company of a build. A push writes to one company, so a Multi-company build needs a push for each company it writes to.

## Connect your Simpro build

:::steps
1. **Open Push.** Go to **Data · Streams**, open the **Push** tab and press the **Simpro custom fields** card under **Choose a destination**.
2. **Type your Simpro address.** Under the cards, **Simpro address** asks for the address you sign in to Simpro at, such as `yourcompany.simprosuite.com`, or just its first part. An address that doesn't end in simprosuite.com or simprocloud.com is refused before you go anywhere. Press **Continue to Simpro**.
3. **Sign in to Simpro** as the user sanda writes as, and allow sanda. If you don't, nothing is connected.
4. **Back in sanda**, a line at the top of the page says the build is connected, and a new push's editor is open on it.
:::

The build is listed under **Connected** on the **Push** tab, with **Disconnect**, and **Connect again** once Simpro stops accepting the connection, which asks for the address again with the build's filled in. One connection to a build serves every push to it.

sanda keeps the connection encrypted, and it is never shown, in the console or to sam. Simpro ends a connection that goes unused for 14 days, so sanda keeps it alive, and a push that runs once a month, or one paused for a while, still finds its build connected.

**Disconnect** forgets the connection in sanda. Simpro offers sanda no way to end it at Simpro's end, so nothing holds a token for it after that, and Simpro ends it once it has gone unused for 14 days. The pushes to the build stay, and run again once you connect it. A Simpro pull that reads through the same connection stops too.

## Create the push

The editor is the one every push uses (see [create a push](https://docs.sanda-os.com.au/streams/create-a-stream-out)), with Simpro's choices where it writes:

:::steps
1. **Open the editor.** Press the **Simpro custom fields** card once your build is connected, or **New push**.
2. **Choose when it runs, and name it.** **When it runs** comes first, then **Name** and an optional **Description**. See [when it runs](https://docs.sanda-os.com.au/streams/create-a-stream-out#when-it-runs).
3. **Choose where it writes.** Under **Where it writes**, pick the **Simpro build**, then the **Company**. Most builds have one company, numbered 0. A Multi-company build lists each company the user who connected sanda can reach. Then pick the **Record type**: **Customers**, **Jobs**, **Quotes** or **Leads**.
4. **Choose the sanda value that holds the Simpro ID.** Under **How each record is found**, the push finds each record by its Simpro ID, so it only updates records that already exist and never creates one. Pick the **sanda value that holds it**, a column or a dimension.
5. **Map the custom fields.** Under **What it writes**, pick a custom field on the left and the sanda value for it on the right. Press **Add a custom field** for each one more.
6. **Check the time zone.** Under **How it sends**, **Time zone** is the zone a date custom field takes a date and time's day in.
7. **Narrow the rows, if you need to.** Under **Which rows**, press **add a condition**.
8. **Save.** Press **Save push**. The push opens with **Preview the next run** already read, and nothing has been sent.
:::

Changing the company or the record type starts the push over: the values it remembers belong to the old ones, so the next run sends every value. The editor says so before you save.

## What it writes

Each row a push reads is one record in Simpro, and each custom field it maps is one value. A push that writes three custom fields on two hundred jobs sends up to six hundred values, one request each. A run sends only the values that changed, so after the first run most runs send a handful.

| Record type | Its custom fields |
|---|---|
| **Customers** | Simpro's customer custom fields, for company and individual customers alike |
| **Jobs**, **Quotes** and **Leads** | Simpro's project custom fields, which leads, quotes and jobs share. A field is offered on a record type only when Simpro shows it there |

Each value is sent the way Simpro stores it:

| Simpro field type | What sanda sends |
|---|---|
| Text, Hyperlink | The text as it stands |
| Numeric | The number as plain digits, at most 6 decimal places, never written as an exponent. A number too large to send exactly is refused, and the row's other values still go |
| Date | The day. A date is sent as it stands, and a date and time is its day in the push's **Time zone**, so a job won at 8 in the morning in Sydney is dated that day, where read in UTC it would be the day before |
| List | The choice, in Simpro's own spelling when it matches one of the list's choices without regard to capitals or spaces at either end, and otherwise as it stands, for Simpro to check |

An empty value is sent as empty, which clears the custom field. A metric with nothing to measure doesn't leave last month's number standing.

Under **What it writes**, the custom fields sanda can't write are listed with the reason: archived in Simpro, locked in Simpro, not shown on the record type you chose, or a kind of field sanda doesn't write. A field Simpro marks as required is written like any other, and the save warns that Simpro may refuse an empty value for it.

### Choices in a list field

A list field's choices are read when you save the push, so a run asks Simpro nothing it already knows, and a value that matches one of them is sent the way Simpro spells it. A value that matches none of them, such as a choice added in Simpro since, is sent as it stands. Simpro takes it when it is one of the field's choices, and refuses it, in its own words, when it isn't.

### Values changed by hand

A push sends a value when sanda's number for it changes. A value someone changes by hand in Simpro stays until then. To put sanda's numbers back, press **Send everything again** on the push (see [send everything again](https://docs.sanda-os.com.au/streams/runs#send-everything-again)). It sends every value again over the next runs, at most 1,500 a run, and costs one request each.

## Where the IDs came from

A Simpro ID names one record in one company of one build: the same number in another company is another record. When you save, sanda follows the value that holds the ID back to the table it is read from. If that table came from a pull of a Simpro build, sanda checks the pull read the same build and company the push writes to, and refuses the save in a sentence that names both when it didn't. When the IDs reach the push some other way, through a model or a table sanda didn't land, the save warns that sanda can't tell, so you can check before the first run.

## What a run costs

A run is billed by the Simpro record, not by the value: a job whose three custom fields changed counts once on the **Stream rows** line of your invoice, as one record does on any push. See [what streams cost](https://docs.sanda-os.com.au/streams#what-streams-cost).

Simpro limits how fast one build is asked: it answers no more than 10 requests a second to one build from one app, and sanda's pulls of the build, its pushes, and every sanda workspace connected to the build share that. A push sends at most 5 a second. When Simpro asks sanda to slow down, the run waits a moment and carries on.

## Personal details

A push sends what you map, as it stands. A number about a customer, such as their lifetime value, is visible in Simpro to everyone who can see that customer's custom fields, so map what your team should see there. Simpro is your own system, not an advertising network, so the rule that keeps some sources' data from advertising networks doesn't apply to it (see [what a push never does](https://docs.sanda-os.com.au/streams/out#what-a-push-never-does)).

## When something goes wrong

| What you see | What to do |
|---|---|
| The Simpro user who connected sanda can't change custom fields on jobs in this company | Simpro refused 10 different records in a row and took nothing between them, so the run stopped. Give their security group that permission in Simpro, or press **Connect Simpro** under **Connected** and sign in to the same build as a user who has it. Nothing is held for it: the next run sends everything it didn't |
| Simpro wouldn't let the user who connected sanda change this job's custom fields | Simpro refused that one record, and the run sent the rest. The user's security group may not reach it, such as a job in a cost centre outside the group's business groups. Give the group that access, or connect as a user who has it. A value refused 3 runs in a row is held until it changes |
| A custom field is archived, locked, no longer shown on the record type, or no longer one of Simpro's custom fields | Nothing was sent. Restore it in Simpro, or take it off the push and save it |
| No record of this type in Simpro has this ID, or it isn't in this company | The ID is another record type's, another company's, or a record deleted in Simpro. Check the push's **Company** and the value that holds the ID |
| Simpro refused the value, in its own words | Simpro's own message comes first. A value it refuses on every run is held after 3 tries, until it changes (see [held records](https://docs.sanda-os.com.au/streams/runs#held-records)) |
| Simpro refused a list field's value | The value isn't one of the field's choices in Simpro. Add the choice in Simpro, or send one it has. A value Simpro refused 3 runs in a row is held: press **Send everything again** to send it once more |
| Simpro didn't answer for a value | Nothing to do: the next run sends it again |
| Simpro asked sanda to slow down for longer than one step waits | Nothing to do: the step tries again |
| Simpro no longer accepts sanda's connection to the build | The Simpro user who connected it may have left, or lost access. The push waits until you press **Connect again** under **Connected** and sign in |
| The stream reads more values (rows × custom fields) than one push keeps | Narrow it with a condition, or write fewer custom fields |
| The Simpro IDs come from another company or build | The push writes to one company of one build. Choose the company the IDs came from, or read the IDs from that company's pull |

A failed run counts toward the push pausing itself, as any push's does. See [runs](https://docs.sanda-os.com.au/streams/runs).

### If Connect fails

- **That isn't a Simpro address sanda can connect to.** Type the address you sign in to Simpro at, such as `yourcompany.simprosuite.com`, or just its first part.
- **Simpro didn't finish signing sanda in.** This also happens when the user you signed in as can't use Simpro's API: sanda asks Simpro who connected it, and a user Simpro won't answer for can't connect. Sign in as a user who can, or ask your Simpro admin.
- **Simpro asked whether to allow sanda and the answer was no.** Nothing was connected. Start again and allow it.
- **Connecting Simpro isn't switched on for this workspace yet.** Writing to Simpro isn't switched on for your console. Ask sanda support.

## Limits

- One push writes at most 20 custom fields.
- One run sends at most 1,500 values, for at most 7 minutes, and fewer when Simpro is slow to answer. What is left waits for the next runs, so a first run over many records takes several runs to send them all, and the preview's count of runs is the fewest it could take.
- One push keeps at most 50,000 values (rows × custom fields). A push that reads more refuses to run and says so.
- A push sends at most 5 requests a second to a build.

:::links
- [Push](https://docs.sanda-os.com.au/streams/out): Every way sanda's numbers go out to the systems your team works in.
- [Create a push](https://docs.sanda-os.com.au/streams/create-a-stream-out): The editor every push uses, and its preview.
- [Runs](https://docs.sanda-os.com.au/streams/runs): What each run did, and why a value was refused or held.
:::