Send manual journals to Xero

A push to Xero turns sanda's numbers into manual journals in a Xero organisation: a month-end work-in-progress accrual, wages owed at the end of a period, revenue recognised as jobs progress. The numbers come from your semantic fluid, so they are the figures your team already agreed on, and the journals land in your books as drafts for your accountant to post, or posted, as you choose.

Each run sends only the journals that changed since Xero last accepted them. A journal sanda made is updated in place when its lines change, and withdrawn when nothing is left on it. sanda never touches a journal it didn't make.

Before you start

• A Xero user and plan that may make manual journals. sanda writes as the user who connects it. Xero lets an app make and change manual journals only where the organisation's Xero plan includes them, and only for a user with the Adviser role, or a Standard user with reporting permissions. sanda checks this when you save a push, and again before every run.
• The accounts the journals post to, set up in Xero. A journal's lines post to accounts already in your chart of accounts. sanda doesn't make accounts, tracking categories or tax rates.
• A date for each period in your warehouse. Rows with the same date become one journal, so the rows a push reads need a date at the grain you want: a month end, a week end, a day.
• Your accountant's agreement. A journal changes your books. Agree with whoever signs them off which accounts a push posts to, whether it posts or leaves drafts, and who looks at the preview before the first run.

Connect a Xero organisation

The organisation is listed under Connected on the Push tab, with Disconnect, and Connect again once Xero stops accepting the connection. One connection to an organisation serves every push to it.

sanda keeps the connection encrypted, and it is never shown, in the console or to sam. Xero ends a connection that goes unused for 60 days, so sanda keeps it alive: a push that runs once a month still finds its organisation connected.

Disconnect forgets the connection, and removes sanda's connection to the organisation at Xero too, unless another sanda workspace still writes to the same organisation through it. The pushes to it stay, and run again once you connect it.

Create the push

The editor is the one every push uses (see create a push), with Xero's form where it writes:

Changing the organisation, or where the journal date comes from, starts the push over: the next run sends every journal again. Where the new source gives a date the push already made a journal for, it finds that journal by its narration and updates it. The journals it made for dates the new source doesn't give, or in another organisation, stay in Xero, posted or drafted beside the new ones, until you void or delete them there: moving Journal date from month ends to week ends, for instance, leaves every month-end journal in your books. The editor says so before you save. Any other change, such as an account, the narration or the status, updates the journals sanda made in place on the next run.

Journal lines

Every journal takes the same lines from its rows: each row gives one line for each line in the table, and lines that are the same in every way but their amount are added together. A push has at least 2 lines and at most 20.

Debits and credits must balance on every journal. sanda checks each one before it sends. A difference of up to 1 cent a line, which rounding each line to the cent can leave, goes on the largest line of the side that is short. A journal still out of balance isn't sent, and the run says by how much.

One journal has at most 500 lines once its rows are spread over the table. A journal that would have more isn't sent: group the push's rows by something coarser, such as cost centre rather than job.

How it sends

Each journal also carries a link back to the push in sanda, which Xero shows on the journal, so whoever opens it in Xero can see where it came from. sanda finds its own journals by their narration and that link, so it never takes over a journal another push or workspace made.

Which periods it reads

A push's rows decide which journals exist. A journal sanda made whose rows have gone, because no row has its date any more, is withdrawn, like one whose lines all come to zero. So set where the journals start with a fixed date, such as Journal date is on or after the first day of this financial year.

What a run does

Each run sends at most 50 journals, one at a time, for at most 7 minutes. When more have changed, the newest go first: this month's journal before last year's, and a period your books have locked never keeps an open one waiting. What is left waits for the next run, so a first run over years of periods takes several runs to send them all.

sanda reads what Xero saved: a journal Xero refused is said in Xero's own words, a journal saved with a warning keeps the warning on the run, and a journal whose saved lines differ from the ones sent, such as an account Xero dropped, is refused so you can check it. Rows with no journal date can't be placed, and the preview counts them as No journal date.

Xero's daily allowance

Xero gives sanda a number of API calls a day in each organisation, and says with every answer how many are left. They are sanda's own: another app connected to the organisation, such as a bank feed or payroll, has an allowance of its own and never spends them. Every push to the organisation shares them, with the editor's lists and the checks a save makes. A run needs 2 calls a journal, and 4 to read the organisation first. sanda leaves the last 50 calls of the day for the editor and the other pushes: a run that would spend into them sends nothing, and says so, and the next run carries on. A run that meets the end of the day part-way records what went.

Send everything again on the push sends every journal it reads again, over the next runs, updating the ones Xero has and making again any voided or deleted there. It costs 2 API calls a journal (see send everything again).

Personal details

A journal carries the amounts you map, and any description or tracking value you take from your rows. Everyone who can see journals in the organisation sees them, so map only what your accountant and your team should see in your books: a job number in a description rather than a customer's name, for instance. A push to Xero sends no hashed details and asks for no consent. Xero is your own books, 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).

When something goes wrong

A failed run counts toward the push pausing itself, as any push's does. See runs.

If Connect fails

• Xero connected sanda to a practice rather than an organisation. Connect again and choose an organisation when Xero asks: a push writes to an organisation's books.
• Xero won't take another connection from sanda's app just now. An organisation can connect only so many apps Xero hasn't certified, and sanda's app has a limit of its own. Nothing was connected: contact sanda support.
• Xero asked whether to allow sanda and the answer was no. Nothing was connected. Start again and allow it.
• Connecting Xero isn't switched on for this workspace yet. Sending journals to Xero isn't switched on for your console. Ask sanda support.
• You ticked several organisations. sanda connects one at a time: it kept the newest and removed its connection to the others. Press Connect Xero again for each of the others.

Limits

• One push maps at most 20 journal lines, and one journal has at most 500 lines.
• One line carries at most 2 tracking categories.
• One run sends at most 50 journals, for at most 7 minutes.
• One push reads at most 50,000 rows.
• A run leaves the last 50 of sanda's daily API calls in the organisation for the editor and the other pushes to it.