Sharing policy content with other systems

Policies are often needed somewhere other than Policy Core: a learning system that trains people on them, a job description that points at a duty, a payroll or finance procedure that quotes a rule. Policy Core can share the published text of your policies with those systems, so they quote what is really in force instead of a copy that went out of date.

Who can do this: Administrators only; Managers and administrators.

What is shared, and what is not #

• Shared: the title, reference, version, review date, every numbered part (as formatted text and as plain text), the requirements each part relates to, and appendices written in the system. Each policy and each part has a permanent identifier and a content hash.
• Never shared: drafts, old versions, reading records (unless a key is given that permission), and uploaded files themselves. For an uploaded form the system receives its name, type and size only.
• Read only. Another system can read your policies. It cannot change them, publish them or read anything else in Policy Core.

Make a key #

1. Open Settings and find Share policy content with other systems. Only administrators can see it.
2. Type what the key is for, for example Learning system.
3. Tick Also reading confirmations only if that system is meant to receive people's names and work email addresses.
4. Press Make a key. The key is shown once. Copy it into the other system straight away.

Make one key for each system, so that you can stop one without affecting the others. To stop a key, press Revoke. It stops working at once. Policy Core keeps only a scrambled form of each key, so nobody, including us, can read a key back to you.

Reading policies as JSON #

Every request carries the key in an Authorization header. The address starts with your Policy Core address, then /api/v1.

curl -H "Authorization: Bearer pck_your_key_here" \
  https://your-policy-core.example/api/v1/policies

The identifier of a policy is the last part of its address in Policy Core. The identifier of a part is its permanent link key: the twelve characters after /ref/ on the Copy link of that part. Both stay the same when a policy is reorganised or renumbered, which is why a job description can quote a part safely.

Knowing a copy is correct #

Each policy has a content hash: a fingerprint of its title, version, every part and every written appendix. It changes whenever anything in force changes, and in no other case. A system that stores a copy can keep the hash with it and ask later whether the copy is current.

• Ask verify with the stored hash. The answer says is_current true or false, and gives the current version and hash.
• Or ask for the policy again with the ETag you were given. If nothing changed you get an empty 304 answer, which makes regular checks cheap.
• If a part is no longer in the version in force, asking for it returns 404 with a message. A system quoting that part should then flag it for a person to look at.

Learning systems: xAPI #

xAPI is the standard that learning systems and learning record stores use to record that someone did something. Policy Core supports it in two ways.

• Each policy as an activity. /api/v1/policies/{id}/xapi returns the policy as an xAPI activity: a stable identifier, a name, a description and its version, so a learning system can refer to it.
• Reading confirmations as statements. /api/v1/xapi/statements returns each confirmation as a completed statement: who (name and work email), which policy and version, when, and how it was confirmed. It needs a key with the reading permission.

Policy Core does not send statements anywhere. The learning system or record store fetches them, so you decide what leaves and when. Use since for a start date and limit for the page size. When there are more, the answer has a more address to follow. Each confirmation always has the same statement identifier, so fetching a statement twice cannot create a duplicate.

Where this is useful #

Limits and rules #

• Each key may make 300 requests a minute. Requests that arrive too often get a 429 answer and should wait.
• A key that is wrong is refused with a 401 answer. Repeated wrong keys from one place are slowed down.
• A statement page holds up to 500 statements.
• Everything is sent over a secure connection and nothing is cached by shared caches.

Creating and revoking keys is recorded in the activity log, without the key itself. The last time each key was used is shown next to it in Settings.