Synchronizations

A synchronization is a batch of tasks posted in one PostAsyncTasks call. Each task names what to synchronize (target) and whose access Ubikap uses to read it from your API (source). Ubikap reads the data itself: you never send it.

Identifiers

Every externalId is an id in your software, never a Ubikap key.

Field	What it identifies
source.credential.externalId	A user of your software. Ubikap reads your API with the access this user granted when they connected Ubikap, or else with the office’s own access.
target.workspace.externalId	A dossier. In Ubikap, it becomes a workspace.
target.person.externalId	A person already attached to a Ubikap workspace. Numeric.
target.company.externalId	A company already attached to a Ubikap workspace. Numeric.

The ids are not checked when you post: an unknown id is accepted, and the task fails later.

Task types

tasks holds one entry or more, each with exactly one task type. A batch with a task type that is not implemented is refused as a whole, with INVALID_ARGUMENT This task '<type>' is not implemented: nothing is queued.

Task type	target	What Ubikap does
synchronizeOfficeUsers	{}	Creates, updates and deactivates the office’s users from your software’s users. Runs at most once a day per office: a second request the same day ends done without effect.
upsertWorkspace	workspace	Creates the workspace and its company from the dossier, or updates them. createWorkspace and updateWorkspace do the same.
synchronizeWorkspaceAccesses	workspace	Applies the dossier’s confidentiality, manager and collaborators to the workspace’s accesses.
synchronizeStockholders	workspace	Updates the stockholders and stock types.
synchronizeGovernance	workspace	Updates the workspace’s governance.
updateOtherPerson	workspace, person	Updates a person attached to the workspace.
updateOtherCompany	workspace, company	Updates a company attached to the workspace.
synchronizeFullWorkspace	workspace	Shortcut: expands into upsertWorkspace, synchronizeWorkspaceAccesses, synchronizeStockholders and synchronizeGovernance, plus updateOtherPerson / updateOtherCompany for every person and company already attached to the workspace.

Every task type takes source: { credential: { externalId } }.

The proto also declares createOfficeUser, updateOfficeUser, createMeeting, updateMeeting, createOtherPerson, createOtherCompany, createDocument and updateDocument: they are not implemented yet, and are refused.

Tip

To synchronize a new or changed dossier, post synchronizeFullWorkspace. Post the finer task types when you know what changed, e.g. synchronizeStockholders after a share transfer.

Execution

• PostAsyncTasks only queues the tasks and answers with a synchronizationId (a 64-character hexadecimal string). Each call creates a new synchronization, even with the same tasks.
• The tasks of a synchronization run one after another, in a fixed order whatever the order you posted them in: office users, workspace, accesses, stockholders, governance, persons, companies.
• A failed task does not stop the next ones.
• When a task failed, Ubikap retries the synchronization automatically a few times. Only the tasks that are not done run again.
• Nothing calls you back when a synchronization ends: poll its state.

Task states

State	Meaning
pending	Queued, not started.
running	Running now.
done	Succeeded.
failed	Failed, possibly after retries.

GetSynchroState: one synchronization

GetSynchroState with a synchronizationId returns:

• tasks: every task of the synchronization, with its type, state, createdAt and updatedAt, most recently updated first. A synchronizeFullWorkspace appears as the tasks it expanded into.
• stats: pendingCount, runningCount, doneCount and failedCount.

The synchronization has ended when pendingCount and runningCount are both 0. An unknown synchronizationId returns no task and zero counts, not an error.

GetGlobalSynchroState: the office, or one workspace

GetGlobalSynchroState sums up the synchronizations of the token’s office. With filter.workspace.externalId, it only considers the tasks of that workspace (office-level tasks such as synchronizeOfficeUsers are then left out).

Field	Content
running.synchronizationIds	Synchronizations with a task running.
pending.synchronizationIds	Synchronizations with a task waiting, and none running.
failed.synchronizationIds	Synchronizations holding the latest attempt of a task type, for a workspace, that failed — not every synchronization with a failed task: see below.
lastSuccessful	The most recent synchronization whose tasks are all done: its synchronizationId and its date, when it was posted. Absent when there is none.

Use it to show a “last synchronized” date, or to find what still needs a new attempt.

Caution

failed does not list every failure. It answers “what is still broken?”, not “what ever failed?”. For each workspace and task type, only the most recent task counts. A synchronization with a failed task is therefore left out when:

• a newer synchronization ran the same task type for the same workspace — whether it succeeded, failed, or is still pending or running;
• it is itself still pending or running: it then appears in that list instead.

Office-level tasks such as synchronizeOfficeUsers count as one more group, without workspace, and are left out when filter.workspace is set.

To list the failed tasks of one synchronization, call GetSynchroState with its synchronizationId.