Connect and test an external register
Connect a register in your own system through the appsolut register API, and test the connection.
Studio roles: "Owner" and "Administrator", and Studio users with a permission set that holds "Community: manage".
An external register stays in your own system, such as Pannoniqa's HR system "SAP HR". The Studio asks it live, through the appsolut register API, whenever a membership check needs it. Your IT exposes that API in front of the system; the developer documentation describes it.
Connect the register
You enter the connection when you create the register with the kind "External":
- "Base URL": where the API answers, for example
https://hr.pannoniqa.example/one-register/v1. "Starts with https://. Plain http only for localhost or 127.0.0.1, for a local test register." - "Tenant ID": "Sent as the x-tenant-id header."
- "Scope": "Sent as the x-custom-scope header."
- "Challenge code required": "Onboarding asks for the person's challenge code." It is on unless you switch it off. See Challenge codes.
- "API key": "Sent as the x-api-key header. It is stored encrypted and can never be shown again, only replaced."
Your IT gives you these values.
Change the connection
Open the register and choose the gear at the top right, "Settings". The register's page itself shows its connection health; its settings page starts with the "Connection" card, which shows the API key's state and the connection test, followed by the fields above, and then the recent failures.
- Change the "Base URL", "Tenant ID", "Scope" or "Challenge code required" and choose "Save connection". "Changing the scheme, host or port removes the API key: the new address does not get the old key. Set the key again afterwards."
- To change the key, choose "Replace API key" (or "Set API key" when none is set), enter the "New API key" and choose "Save API key". "The new key takes effect at once and the old one is discarded."

Test the connection
- Open the register's "Settings" (the gear at the top right) and, in the "Connection" card, choose "Test connection".
- Optionally enter a "Test member code (optional)", such as a colleague's member code, to look one person up.
- Choose "Run test".
The test "Asks the register whether it answers (GetHealth), looks up the test member code if you enter one (GetDataByCode), and checks whether it supports GetAllMembers." It shows how long the register took to answer and, for a test member code, which person data came back. "The person data shown here is not stored."
The "Connection" card keeps the last test's result. Its calls are recorded in the connection log like every other call, so they count towards the connection health. If the register cannot be reached, the test names the cause, for example "no answer within 5 seconds" or "credentials rejected (HTTP 401)".
Test again after every change to the connection, and whenever members report that they cannot sign in: while an external register is unavailable, members rely on the grace rule.
Connection health
The register's own page shows below its header how its connection stands, for everyone who may open the register. The Studio records every call it makes to the register (for a membership check, member data, a member code query or a connection test) in the register's connection log, and asks the register every 5 minutes whether it is up. The log is kept 30 days.
The connection health comes from that log alone:
| Connection health | When |
|---|---|
| "Not known" | No call to this register was recorded in the last 15 minutes: none yet, or the check every 5 minutes has stopped (for example, a register without an API key that no one calls). |
| "Unavailable" | The last 3 calls failed, or none of the calls of the last 15 minutes succeeded. |
| "Degraded" | A call failed in the last hour, or the calls of the last hour took over 2 seconds at the median. The check every 5 minutes counts for failures, not for the median. |
| "Healthy" | None of the above. |
A call whose register answered without the person data a check needs ("Missing person data") counts as successful everywhere here: in the connection health, the availability, the chart and the "Successful" filter. The register answered. It is not among the failed calls.
The "Registers" page shows the same connection health under "Connection health", and so does the Dashboard's "Register health" tile.
The page also shows:
- "Last successful call" and "Last failed call", in your time zone.
- "Availability and response times": for the last 24 hours, 7 and 30 days the share of successful calls, the number of calls, and the median and 95th percentile of their duration. The check every 5 minutes counts for the availability and the number of calls, never for the duration: a register that only gets that check shows "—".
- "Calls in the last 24 hours, by hour": successful and failed calls as a chart, the same calls the "Last 24 hours" row counts. "Show the figures as a table" lists the same figures.
- "Recent calls": the 50 most recent calls with time, call, operation, outcome, HTTP status and duration. Choose "Successful" or "Failed" under "All outcomes" to see only those. Owners and administrators open each call's details from it.

Call details
Studio roles: Owner, Administrator
To find out why a call went wrong, open its call details: choose "Details" in its row of "Recent calls". The "Call details" window shows:
- "Call": the time, call, operation, outcome, cause, HTTP status and duration, the "Studio request ID" and the "Register request ID". Give your IT the Studio request ID: the Studio sends it with every call as
x-request-id, so they find the call in their own logs. The register request ID is the register's own, where it answered one. - "Request": the method and the whole address, member code included, the headers and the body, with the details the Studio sent.
- "Response": the HTTP status, the headers and the body the register answered, member data included.
JSON bodies are indented. Each part has a "Copy" button. The Studio stores each body up to 64 KB; a longer one, such as a connection test's list of all members, is cut, and the window says so.
The Studio never stores the organisation's API key, not even as a placeholder, and shows the challenge code as ***, also where the register repeats it. The call details are kept 30 days, like the call. When an organisation membership is anonymized, the call details of every call for its member code, however it was typed, are deleted, and those of the connection tests' member lists; the calls stay in the list without them. Calls from before call details existed have none.
Only the organisation's owners and administrators see "Details", with two-factor authentication where it is set up. Other Studio users, also those who may manage registers, see the calls without request IDs and without details. Each time someone opens call details, the register's activity records who opened which call ("Call details opened"), never what it held.

What the Studio asks
The Studio asks an external register only what a check needs: whether a member code exists, with the person's status, names and birth date, and the claims a filter uses. It stores no birth date or address from it: only the person's names, status and claims, with their organisation membership. Everyone found in the register carries the register's groups.


