Runs
What each run of a stream did, what a stream in landed and a stream out sent, why a record was refused or held, and what happens when runs fail.
Open a stream to see its runs. Runs lists the last thirty, newest first. Each says in a sentence what it did, such as "Landed 1,204 rows, and 31 more had not changed." for a stream in or "Sent 31 records. Salesforce accepted every one." for a stream out, with how it started (on its schedule, after a sync or a landing, by a stream graph, by Run now, by cherry or by an agent), when, and how long it took. Open a run for the rest: a stream in's requests, or a stream out's API calls and the records it couldn't deliver.
What a run's status means
| Status | What it means |
|---|---|
| succeeded | Everything that changed arrived. A stream out that found nothing changed succeeds without calling Salesforce. |
| partial | Most of it moved, but some records couldn't: a stream in's records with no key, or records Salesforce refused, or rows a stream out couldn't send as they stood. |
| skipped | It moved nothing, for a reason that is nobody's fault: the workspace is paused for its budget, a credential, a database or an org needs connecting again, the stream was paused after the run was queued, the warehouse is at its storage ceiling, your Salesforce org's API allowance was too low, or other streams' runs kept it waiting too long for its turn. It doesn't count as a failure, and isn't charged. |
| failed | It couldn't finish. The reason is one sentence, and it counts toward the stream pausing itself. It isn't charged. |
| cancelled | It was cut off before it finished. A stream in carries on from the last page it landed; a stream out sends what Salesforce didn't confirm on the next run. |
| queued, running, waiting | Under way. queued is also a run waiting for its turn (see runs at once), and waiting is a bulk job Salesforce is still working through. The page updates itself until the run ends. |
Runs at once
For now, a workspace's streams run one at a time, in and out together. A run that starts while another stream's run is under way stays queued and waits for its turn, looking again every 30 seconds. When the other run ends, it goes ahead.
A run still waiting after 20 minutes is skipped, and its sentence says another stream's run took the whole wait. Nothing was read or sent, and the next run carries on from where the last one got to. Most runs take seconds, so a wait is usually short. If runs are often skipped this way, look for a long one (a first load, or Load everything again on a large table) and give the busiest streams slower schedules.
What a stream in's run shows
- Its counts: rows read, landed (new or changed), unchanged, pages and requests. Rows landed are the rows the run bills.
- Its requests, as sanda made them: the method, the host and path, the answer's status, its size and how long it took. Never the address's query or any header, so nothing in the log is a credential. A Postgres stream's run lists each page of rows it read instead, as
SELECT sales.orders on db.example.com, marked read or failed. - Values that didn't fit the column their field became, and records with no key, which didn't land.
A run that hits the app's rate limit waits as the app asks, then carries on. When the wait is long, the run gives the rest to the next one.
How a stream out sends changes
Up to 2,000 changed records go in requests of up to 200, and each record's answer is recorded as it comes back. More than that go as one bulk job, which Salesforce works through in its own time while the run shows waiting. Either way, a value counts as sent only once Salesforce accepts it.
Records a stream out couldn't deliver
There are two kinds, and an open run lists both with the record each was for.
- Rows sanda couldn't send as they stand. A value that doesn't fit its field (text longer than the field holds, a word in a checkbox, a day that doesn't exist), a value that isn't an Id of the object, or several rows that match one record. These never reach Salesforce.
- Records Salesforce refused. Salesforce's own message comes first, because it names your validation rule or field. sanda adds a hint for the common refusals, such as a field the Salesforce user can't edit or a record that has been deleted.
A run keeps up to 200 of them, which is enough to see the pattern. Its counts say how many there were in all.
The preview lists the first kind before anything is sent. See preview and run.
Held records
A record Salesforce refuses 3 runs in a row, for the same value, is held: sanda stops sending it until its value changes. A validation rule that refuses a number refuses it on every run, and sending it again spends your API allowance to learn nothing new. A changed value is a new question, so it is sent.
A refusal about the moment rather than the value, such as Salesforce saving the same record for someone else at that instant, doesn't count toward holding a record. It is sent again on the next run.
Send everything again
Send everything again, on a stream out, sends every record it reads, including the ones Salesforce already has, and releases held records. Use it when values in Salesforce were changed by hand and you want sanda's back, or once you have fixed whatever made Salesforce refuse a record. It costs about one API call for every 200 records.
Load everything again, on a stream in, makes the next run read every record from the start. See load everything again.
Your Salesforce API allowance
Your org's daily API allowance is shared with every other integration and with your own users, so a stream out is careful with it.
- A run with nothing to send makes no call at all. Not even to sign in.
- A run with something to send reads the allowance first. If sending would leave less than 10% of it, and never less than 500 calls, the run sends nothing, says how many calls were left, and is skipped. The next run carries on.
- Most runs are cheap. One call to read the allowance, then one for every 200 changed records. A bulk job costs a handful of calls whatever its size.
Each org under Salesforce orgs on the Streams out page shows how much of the allowance was used at the last reading.
When runs fail
A failed run emails owners and admins, at most once a day for each stream, when When a scheduled run fails, or pauses itself after failing repeatedly is ticked under Settings · Plan & budget · Budget & alerts. See budgets and alerts.
After as many failed runs in a row as its Pause itself after says, a stream pauses itself and is marked suspended. Fix the cause, then press Resume. A skipped run never counts, and neither does a failure caused by a credential or an org needing to be connected again.
When a stream in's connector is the cause (the app changed its API, say), press Ask cherry to fix it. See when it stops working.
Pause, resume and delete
- Pause stops the stream's schedule and its runs after a landing. Run now still works.
- Resume turns it back on, starts its schedule from now rather than catching up on what it missed, and forgets the failures that paused it.
- Delete stream, at the foot of the page, removes it. A stream out changes nothing in Salesforce: the values it wrote stay where they are. A stream in's tables stay in your warehouse, with everything it landed.
If your edition changes
A workspace keeps every stream when it moves to an edition with fewer. The oldest in each direction keep running, up to the new edition's count. The others keep their definitions, show not running, and say why. On Basic, none runs and the page shows what the next edition adds. Moving back up is immediate. See editions.
Something unclear or out of date? Tell us, and we will fix the page.