Skip to main content
A competence is something an employee can hold: a skill, a certificate, a licence, a completed course. Twine splits this into two entities, because the thing itself and the fact that someone holds it change independently.

Competence

The catalogue entry - “First Aid”, “Forklift Licence”, “German B2”. One per organization, shared by everyone who holds it.

Competence Assignment

The link between an employee and a catalogue entry, carrying the level, validity dates and who issued it.
Both use the dated property model, so values can be tracked over time like any other Twine entity.

​
Why two entities

Every serious HR system models it this way, and the reason is practical: renaming “First Aid” to “First Aid (Basic)” should not touch the two hundred employees who hold it, and one employee re-certifying should not touch the catalogue. Keeping them separate also means an organization can curate its catalogue independently of who currently holds what. The consequence for configuration is that they are two separate domains with two separate domain mappings. Syncing the catalogue does not sync who holds what, and vice versa.

​
Competence

The catalogue entry.
Level is not on the catalogue entry. It belongs to the assignment - see below. Systems that model levels as separate catalogue entries (“English B1”, “English B2”) map cleanly anyway: each becomes its own competence, distinguished by name or code, with the assignment level left empty.

​
Competence Assignment

The link between an employee and a catalogue entry. An employee can hold the same competence more than once - a re-certification is a second assignment with a later valid_from, not an edit of the first. The employee and the competence themselves are not properties. They are relationships, resolved by Twine when data moves between systems.

​
Custom properties

Some target systems need a value on the assignment that Twine has no general concept of - a reference to a document held in that system, for example. Rather than adding a field per system, put the value in an organization-defined custom property and map it onto the target’s field. Custom properties are created in the property mapper the same way as for any other domain.

​
Attaching a certificate

A common case is an assignment that should point at a certificate PDF stored in the target system. Twine does not link a file to an assignment for you - it moves the file and tells you what the target called it, and you supply that identifier yourself:
  1. Upload the certificate with POST /v1/org/file-transfers, naming the target system and the employee.
  2. Poll the file transfer until its status is delivered, then read remote_id - the target system’s identifier for the document.
  3. Create the assignment with that value in the custom property mapped onto the target’s document field.
Note the order. Several systems, Simployer One among them, accept a document reference only when the assignment is created; mapping it afterwards will not retrofit an assignment that already exists.

​
How assignments resolve

An assignment refers to an employee and a catalogue entry. When Twine writes one to a target system, it needs that system’s ids for both, which it takes from the entity mappings built up when those domains sync. That leads to the one rule worth knowing before configuring anything:
Both sides must already be mapped. An assignment whose employee or competence has no mapping for the target system is skipped and reported as an anomaly rather than guessed at. The anomaly resolves itself once the missing mapping appears.
This is why the domains are usually configured, and run, in a fixed order:
1

Employees

So every employee has a mapping in the target system.
2

Competences

So every catalogue entry has one too.
3

Competence assignments

Now both sides of every assignment can be resolved.
Sync triggers can express this ordering directly: make the competence trigger a child of the employee trigger, and the assignment trigger a child of the competence one.
Not every integration needs three domain mappings. Some systems carry assignments inside the employee record itself, in which case the assignment domain does not apply. The integration page for each system states which shape it uses.

​
Matching existing data

When a target system already holds competences - most do, before Twine is introduced - the catalogue needs linking up so Twine writes to the existing entries instead of creating duplicates.

Entity Matcher

Link the two catalogues by hand at onboarding. Competences are matched on name by default.
Assignments are not matched this way. Once an employee and a competence are both mapped, the assignment between them is identified by that pair, so there is nothing for a human to link.

​
Deletes

Competence syncing is upsert-only in both directions. A catalogue entry or an assignment removed in one system is not removed in the other - it is left alone. Removing an assignment from a target system is done there directly.