ERP connections
Link one or more Standard Books companies to herbe.calendar for activity sync and creation.
Each ERP connection links herbe.calendar to one Standard Books company. A tenant commonly has two or three connections (e.g. one per legal entity). Connections are independent — each has its own credentials, sync state, and color.
Manage at Admin → Config → Standard ERP Connections.
Adding a connection
Click + Add Connection and fill in:
| Field | Notes |
|---|---|
| Connection name | Friendly name shown in the sources dropdown, e.g. "Burti Production" |
| Company code | The company number in Standard Books, e.g. 3 |
| API base URL | The REST API endpoint, e.g. https://erp.company.com/api |
| Server UUID | (Optional) Enables hansa:// deep links that open records in the desktop client. Use Detect rather than typing it — see below. |
Detecting the Server UUID
Edit a saved connection and click Detect beside the Server UUID field. It reads the value off the ERP itself, using the connection's stored base URL and credentials, so save those first. The alternative is copying it out of Standard Books → Server → Preferences → Server UUID by hand.
Detect fills the field and stops there — Save is what stores it. That is deliberate: the ERP usually reports the id outright, but when it has to be inferred from the response the message under the field says so, and you should check it against Server → Preferences before saving.
The format is five hex groups of eight (9454563D-913AB03A-4AA82D4D-777F0709-40F0F021), not a conventional UUID, so a value that looks wrong is probably right.
Then pick the Sign-in under Authentication:
| Sign-in | What you enter |
|---|---|
| Basic (the default) | A Standard Books username and password. Simple, but the login is static: rotate it in the ERP when needed, then update it here. |
| OAuth (Standard ID) | The Client ID and Client Secret of your OAuth client, then press Connect. See Sign in with OAuth. |
A connection can also sit behind a reverse proxy with its own login: see Proxy in front of the ERP.
Every secret field (password, client secret, proxy password) is write-only. It is stored encrypted, never shown again, and left blank on a later save it keeps what is stored. Saving merges: changing one field never drops the others, so saving a new password does not disconnect OAuth or remove the proxy login.
A save is refused when it would leave the connection with no way to sign in: Basic with no username and password (stored or typed), a switch to OAuth with no client id or client secret, or a proxy username with no proxy password.
Sign in with OAuth
A connection can sign in to the ERP through Standard ID (OAuth) instead of a username and password. You register herbe.calendar once as an OAuth client, press Connect once, and herbe.calendar then renews the sign-in by itself.
- Go to standard-id.hansaworld.com and create an OAuth application.
- Set the redirect URI to
https://<your-domain>/api/herbe/callback. Copy Callback URL on the connection gives the full address. - Under Sign-in pick OAuth (Standard ID), enter the Client ID and Client Secret, and save.
- Press Connect. Standard ID asks you to sign in and approve, then sends you back to this page. Press Test to check it.
If Connect cannot start, the reason is shown under the buttons (for example the connection has no client id yet). If the browser blocks the pop-up, allow it for this site and press the button again.
What the status next to the connection means:
| Status | Meaning |
|---|---|
| Not connected | No sign-in is stored yet. Press Connect. |
| Connected | Tokens are stored and herbe.calendar renews them before they expire. The time is when the status last changed. |
| Needs reconnect | Standard ID refused to renew the sign-in, for example because the client secret was changed or access was withdrawn. The reason is shown in words beside the status. Press Reconnect to sign in again. |
What Needs reconnect does until you reconnect: if a username and password are saved on the connection, REST calls use them (the fallback) and everything keeps working, but the status stays Needs reconnect. If none are saved there is nothing to fall back to, and every ERP call for that connection fails (its sync is skipped, and the calendar shows its cached data) until you press Reconnect.
The reasons you may see:
| Reason | What it means |
|---|---|
| Standard ID refused to renew the sign-in | The refresh token was rejected: the client secret was changed or access was withdrawn. |
| Standard ID gave no refresh token | The sign-in cannot be renewed. Reconnect. |
| Standard ID did not return an access token | Reconnect, and check the client id and secret. |
| No sign-in is stored yet | The connection is set to OAuth but Connect was never pressed. |
How OAuth and the username and password work together:
- OAuth is used whenever it is connected, for every REST call, even when a username and password are also saved.
- The username and password stay in use for WebExcellentAPI, which cannot sign in with OAuth, and as the REST fallback described above. The form says so beside the fields: Used for WebExcellentAPI and as a fallback.
- An OAuth-only connection (no username and password) reads and writes activities through REST, but has none of the WebExcellentAPI features: activity comments, file attachments, the actions that open ERP windows, and deleting activities and tasks. Test then says WebExcellentAPI skipped instead of failing it. Enter the username and password too if you want those features.
- Saving the sign-in as Basic, a different client id or a changed client secret ends the stored tokens. The client id and secret stay, so switching back needs only Connect. With herbe ID sign-in on for the account, this and the changes below ask for a fresh herbe ID confirmation: a link appears under Save Changes, and you save again after confirming.
- The same confirmation is asked for a new client secret, a new proxy password, and removing a proxy. A new ERP username and password do not ask for it.
Proxy in front of the ERP
Use this only when the ERP sits behind a reverse proxy that asks for its own Basic login, so the proxy login and the ERP login are two different logins. Leave Proxy username blank when there is no such proxy: herbe.calendar then sends exactly what it always did.
Open Proxy in front of the ERP (collapsed by default) under the sign-in fields and fill in:
- Proxy username and Proxy password: the proxy's own login. The password is write-only; leave it blank on a later save to keep it. Emptying the username removes the proxy and its password. A proxy username needs a proxy password.
With a proxy username set, herbe.calendar sends the proxy login in the Authorization header and the ERP login (Basic, or the OAuth token) in X-Erp-Authorization. The proxy has to move the second one back onto Authorization before it forwards the request, so whoever runs the proxy adds one line to its configuration:
nginx:
proxy_set_header Authorization $http_x_erp_authorization;
Apache:
RequestHeader set Authorization "expr=%{req:X-Erp-Authorization}"
The screen shows both lines with a copy button.
Test
Test on a connection runs these checks in turn and reports each one. Through a proxy, every one of them goes through it.
| Line | What it checks |
|---|---|
| REST OK (N users) / REST failed | A read of the ERP user list with the connection's sign-in (OAuth when connected, otherwise Basic). |
| REST session OK / none | Whether the ERP handed back a session for later requests. |
| WebExcellentAPI OK / unavailable / skipped | WebExcellentAPI.hal with the saved username and password. Skipped means none are saved (an OAuth-only connection): not a failure. |
| HAL session OK / none | Whether WebExcellentAPI handed back a session. |
Behind a proxy, a refused login (HTTP 401, 403 or 407) can mean the proxy login is wrong, the ERP login is wrong, or the proxy is not passing X-Erp-Authorization on. The message does not tell them apart, so check all three.
The result of the WebExcellentAPI line is remembered on the connection: when it is unavailable or skipped, the calendar does not offer the features that need WebExcellentAPI.
Sync behavior
The incremental sync runs every 15 minutes during business hours and every hour off-hours. It fetches new and updated events using a per-connection cursor. A full reconciliation runs nightly and replaces the whole rolling window.
Events from each connection appear in the calendar under the Outlook source color for that connection. Users see activities from all active connections they have access to.
Connection health
Admin → Cache shows the sync status for each connection — last sync timestamp, next scheduled sync, and any error messages. If a connection shows errors, check the credentials and that the ERP API URL is reachable from the internet.