Generated from folio-assistant-core/dsa/processes/dsa-document-lifecycle.bpmn by gen-processes-viz.ts — do not edit here. All processes · folio-assistant-core processes

Data sharing agreement document life cycle

Process_DsaDocumentLifecycle · advisory · 26 step(s)

How a data sharing agreement is drafted, negotiated, signed, published with a version, a hash and a catalogue record, and later amended, renewed or ended. It covers the agreement as a document folio only: processes P1, P2 and P14 of the DSA process catalogue. Two entry points: a request for an agreement (P1, then P2), and a change to one in force (P14). An amendment or a renewal with a new end date runs P1 and P2 again and publishes a new version linked to the old one; the old version stays readable. Standards named: ODRL 2.2 (the Agreement), DCAT 3 (catalogue record, distributions, checksums, versions) and DCMI Terms (dcterms:source from the policy to the text). No field is defined here. Steps no skill covers yet are user tasks with a no-skill reason starting “Gap:”. Consent rules, which every agreement drawn here keeps. 1. Legal basis: an agreement carries the odrl:obtainConsent duty only when consent is its legal basis; treatment, public-health law and research waivers do not rest on consent (P1.2a, P1.3). 2. Version pinning: a Consent cites the agreement’s fixed-version URL and hash (FHIR R4 Consent.policy.uri), and for a computable agreement the ODRL policy uid is that same URL (P2.1, P2.2b, P2.3); an amendment that widens use needs new consent, one that narrows use does not (P14.3). 3. Plain language: every agreement that needs consent publishes a plain-language summary, hashed with the agreement, and that summary is what the person consents to (P1.2b, P2.2a). How a person gives, withdraws or is asked again for consent is the trust layer’s, not this diagram’s.

BPMN diagram: Data sharing agreement document life cycle

How it connects

Lanes — who acts

lanerolewhat it does here
Parties and signatories (provider, recipient)stakeholderThe data provider and the data recipient (ODRL 2.2 assigner and assignee) and the people who sign for them. Their role is judgement only: they agree the terms, sign, and decide whether to amend, renew or end the agreement. No skill can make those choices for them, so no activity in this lane names one.
Author and policy authorauthorWrites the legal text and, for a computable agreement, derives the ODRL 2.2 Agreement from it. Every loop comes back here: a review that asks for changes, an amendment, and a renewal that needs a new version.
Reviewer (legal, policy)reviewerChecks the ODRL against the text, and reviews the whole draft. Decides whether the public terms go out for public comment, and whether the draft is ready to sign.
Public review (commenters, review committee, editor)review-coordinatorUsed only when the public part of the agreement (the template) goes out for public comment. Comments are handled in Process_PublicComment, the same as for any document folio.
Publisher (data provider’s publication manager)publication-managerGives each signed version its own immutable URL, records its SHA-256 hash, and writes the DCAT 3 catalogue record. Also sets the catalogue status when the agreement ends.
Build pipeline (system)build-pipelineRenders the agreed text before it is signed, and publishes the signed version at its immutable URL.

Steps

Every one of the 26 step(s) is documented.

steplaneskill / sub-processwhat it does
Open the bean
Call_BeanOpen
Author and policy authorcalls Open the bean
bean-coordination
Process_BeanOpen: check before you create, find out whose the bean is, and claim it — or leave it alone when it is someone else’s. The one place a claim is drawn; the gateway after this reads which end it reached.
P1.1 · Agree the terms
Task_AgreeTerms
Parties and signatories (provider, recipient)—The parties agree the purpose, the datasets, the period, the conditions and duties, which trust anchors each side accepts, and the legal basis the sharing rests on (consent, treatment, public-health law or a research waiver). This sets what the text must say; it is a negotiation between people.
P1.2 · Write the legal text
Task_WriteText
Author and policy authordocument-authoring
normative-statements
document-structure
Write the agreement as a document folio: one normative statement per clause the parties must keep, through normative-statements. The text says which governs if it and a machine-readable form disagree (suggested: the text).
P1.2a · Record the legal basis
Task_RecordLegalBasis
Author and policy authornormative-statementsThe text states the legal basis the parties agreed in P1.1 as a normative statement: consent, treatment, public-health law, or a research waiver. Consent rule 1: only an agreement whose legal basis is consent carries the odrl:obtainConsent duty; treatment, public-health law and research waivers do not rest on consent. The gateway that follows, the ODRL and the reviewers all read the basis from this statement.
P1.2b · Draft the plain summary
Task_PlainSummary
Author and policy authordocument-authoringConsent-based only. Write a plain-language summary of the agreement in the same document folio: what it lets the recipient do with the person’s data, in words the person can read. Consent rule 3: every agreement that needs consent publishes this summary, hashed with the agreement (P2.2a), and the summary is what the person consents to. It is reviewed, rendered and versioned with the text.
P1.3 · Derive the ODRL 2.2 Agreement
Task_DeriveOdrl
Author and policy author—Computable only. One assigner and one assignee (ODRL 2.2 §2.1.3), permissions and prohibitions with target assets (§2.2), constraints (§2.5.1) and duties (§2.6.3), written as JSON-LD. Purposes from HL7 PurposeOfUse. Consent rule 1: the Agreement carries the odrl:obtainConsent duty only when the legal basis recorded in P1.2a is consent.
P1.4 · Check the ODRL against the text
Task_CheckOdrl
Reviewer (legal, policy)content-reviewComputable only. A person checks that the ODRL says what the text says, and signs it off. A program can check the ODRL is well formed; it cannot check that it matches the text. The check includes the consent duty: present when the legal basis is consent, absent otherwise (consent rule 1).
P1.5 · Split public terms from private annexes
Task_SplitAnnexes
Author and policy author—Split the agreement into a public template and private annexes (security controls, named staff). Only the hash of a private annex is ever published.
Review the draft agreement
Task_Review
Reviewer (legal, policy)content-review
review-comments
Legal and policy review of the whole draft. Reviewers comment on blocks through review-comments; review says which review skill answers which question. For a consent-based agreement the reviewers also check that the plain-language summary says what the text says, since it is what the person consents to (consent rule 3).
Public comment on the template
Call_PublicComment
Public review (commenters, review committee, editor)calls Public comment on a review draft
public-comment
Comments on the frozen, line-numbered review version of the public template are placed, triaged, weighed and decided (public-comment.bpmn). Private annexes are never circulated.
Render the text to HTML and PDF
Task_Render
Build pipeline (system)document-publishingRender the agreed text to the form that will be signed (HTML and PDF), without a TeX installation. A consent-based agreement’s plain-language summary is rendered with it.
P1.6 · Sign
Task_Sign
Parties and signatories (provider, recipient)—The signatories sign: wet ink, or an electronic signature under national law. Technically a detached JWS (RFC 7515) or CMS (RFC 5652); PAdES for a signed PDF needs the owner’s approval.
P2.1 · Assign version and fixed URL
Task_AssignVersion
Publisher (data provider’s publication manager)content-publish
package-release
Each signed version gets its own immutable URL (for example /dsa/42/v3). A ‘latest’ URL may exist; nothing cites it. A new version never overwrites an old one. This fixed-version URL is the one a Consent cites (consent rule 2), and a computable agreement’s ODRL policy uid is set to it (P2.3).
P2.2 · Record each file’s SHA-256
Task_Hash
Publisher (data provider’s publication manager)dsa-checksumCompute SHA-256 (FIPS 180-4) of the signed text, and of the ODRL file if there is one, recorded as DCAT 3 spdx:checksum and verified by check:dsa-hash.
P2.2a · Hash the plain summary
Task_HashSummary
Publisher (data provider’s publication manager)dsa-checksumConsent-based only. Record the SHA-256 of the plain-language summary beside the agreement’s, in the same version (consent rule 3). The summary a person consented to can then be checked against the agreement it summarises; a changed summary is a new version.
P2.2b · State the URL and hash to cite
Task_ConsentCitation
Publisher (data provider’s publication manager)content-publishConsent-based only. The version’s publication metadata states the fixed-version URL (P2.1) and the hash (P2.2) that a Consent cites in FHIR R4 Consent.policy.uri (consent rule 2), never the ‘latest’ URL. For a computable agreement that URL is also the ODRL policy uid (P2.3): a Consent counts only when its Consent.policy.uri equals the agreement’s ODRL policy uid, so the two are the same string.
P2.3 · Make the ODRL cite the text
Task_OdrlCitesText
Author and policy authordsa-odrl-sourceThe ODRL policy names the signed text distribution with dcterms:source (DCMI Terms), pointing at the immutable URL whose spdx:checksum was just recorded. Its uid is that same fixed-version URL, the URL a Consent cites in Consent.policy.uri (consent rule 2).
Publish the version at its URL
Task_Publish
Build pipeline (system)content-publishPublish the files at the version’s immutable URL. If the parties’ names are sensitive, publish only the template and the hash of the signed instance. A consent-based agreement publishes its plain-language summary and its hash with the text (consent rule 3). Check before publishing (consent rule 2): a computable agreement’s ODRL policy uid equals this version’s fixed-version URL, the URL a Consent cites; if they differ, the version is not published.
P2.4–5 · Write the DCAT 3 record
Task_Catalogue
Publisher (data provider’s publication manager)dsa-dcat-recordOne DCAT 3 record: the agreement as a catalogued resource, each file a dcat:Distribution with dcat:downloadURL and spdx:checksum; datasets it covers carry odrl:hasPolicy. Versions are linked with DCAT 3 versioning (previous version, version, current version).
Open the bean
Call_BeanOpenChange
Author and policy authorcalls Open the bean
bean-coordination
Process_BeanOpen: check before you create, find out whose the bean is, and claim it — or leave it alone when it is someone else’s. The one place a claim is drawn; the gateway after this reads which end it reached.
Decide: amend, renew or end
Task_DecideChange
Parties and signatories (provider, recipient)—The parties decide what happens to the agreement. Deciding to amend or terminate is human; expiry of a computable agreement is already enforced by its ODRL dateTime constraint.
P14.2 · Decide what happens to existing grants
Task_DecideGrants
Parties and signatories (provider, recipient)—Existing grants keep citing the old hash. The parties decide, per agreement: they stay valid until expiry, or they are revoked and reissued against the new version (in smart-trust). The old version stays readable.
P14.3 · New consent needed
Task_NewConsentNeeded
Parties and signatories (provider, recipient)—The amendment widens use, so a Consent citing the old version’s URL and hash does not cover the new version (consent rule 2). Record on the bean, and in the new version’s text, that new consent is needed; the new version gets its own plain-language summary (P1.2b). Asking each person again is the trust layer’s.
P14.5 · Set the status to ended
Task_SetStatus
Publisher (data provider’s publication manager)dsa-catalogue-statusSet the life-cycle status of the agreement’s DCAT 3 record (DCAT 3 §6.4.30). The published versions stay readable at their URLs.
Revoke grants and start end-of-agreement duties
Task_EndDuties
Parties and signatories (provider, recipient)—All grants are revoked (P13) and the end-of-agreement duties start: return or delete the data, then check them (P12). Those are server processes in smart-trust; this step records that the parties started them.
Close the bean
Call_BeanCloseEnded
Author and policy authorcalls Close the bean
todo-manager
Process_BeanClose: end the bean in a state that says why — complete and archive it, scrap it with its reasons and archive it, or record the blocker and hand it back. The one place resolve and archive are drawn; placed straight before the end so the engine’s resolve sees nothing left but the archive step.

Decisions

Every one of the 11 decision(s) is documented.

decisionwhat decides itbranches
Bean claimed?
GW_BeanYours
Reads which end Process_BeanOpen reached. claimed: the bean is in progress and this process works it. not yours: a sibling session or a human holds it, nothing was written to it, and this process stops here rather than work a bean it does not own (bean-coordination).not yours → Not yours — left alone
claimed → P1.1 · Agree the terms
Consent the legal basis?
GW_ConsentBasis
Reads the legal basis recorded in P1.2a. consent: the agreement needs a plain-language summary (consent rule 3) and, if it is computable, the odrl:obtainConsent duty (consent rule 1). treatment, law or waiver: no summary for consent and no consent duty.consent → P1.2b · Draft the plain summary
treatment, law or waiver → GW_ConsentBasisJoin
Computable agreement?
GW_Computable
Does this agreement carry a machine-readable ODRL 2.2 Agreement beside its text? yes derives it and has it checked; document only goes straight on (a signed PDF is a valid agreement).yes → P1.3 · Derive the ODRL 2.2 Agreement
document only → GW_ComputableJoin
Public comment on the public terms?
GW_PublicComment
Should the public template go out for public comment before signing? yes runs Process_PublicComment; no goes straight to the readiness decision. A private agreement between two parties usually answers no.yes → Public comment on the template
no → GW_CommentJoin
Ready to sign?
GW_ReadyToSign
The reviewers’ call. changes needed sends the draft back to the author; ready renders it for signing.changes needed → GW_DraftMerge
ready → Render the text to HTML and PDF
Consent-based agreement?
GW_ConsentPublish
The legal basis recorded in P1.2a. consent: hash the plain-language summary with the agreement, and state the fixed-version URL and hash a Consent cites. not consent-based: go straight on.consent → P2.2a · Hash the plain summary
not consent-based → GW_ConsentPublishJoin
ODRL to update?
GW_CiteComputable
Is there an ODRL Agreement for this version? yes: it must cite the text by URL and hash. document only: go straight to publishing.yes → P2.3 · Make the ODRL cite the text
document only → GW_CiteJoin
Bean claimed?
GW_BeanYoursChange
Reads which end Process_BeanOpen reached. claimed: the bean is in progress and this process works it. not yours: a sibling session or a human holds it, nothing was written to it, and this process stops here rather than work a bean it does not own (bean-coordination).not yours → Not yours — left alone
claimed → Decide: amend, renew or end
Amend, renew or end?
GW_ChangeKind
The parties’ decision. new version (amend, or renew with a new end date) runs P1 again and publishes a new version linked to the old one. renew by grant (the version has no end date): nothing in the document changes. end (expiry or termination) closes the agreement.new version → P14.2 · Decide what happens to existing grants
renew by grant → Renewed by a new grant
end → P14.5 · Set the status to ended
Consent-based: does the amendment widen use?
GW_WidensUse
Consent rule 2, for a new version only. widens use (for example more data, more purposes, more recipients or a longer period): the Consents that cite the old version do not cover the new one, so new consent is needed. narrows use: no new consent is needed. not consent-based: there is no consent to renew.widens use → P14.3 · New consent needed
narrows use → GW_WidensJoin
not consent-based → GW_WidensJoin
How did it end?
GW_BeanClosedHow
Which outcome the bean was closed with, so each ends at its own named end event. The bean is closed once, on every path (bpmn-authoring: open and close the bean at the top, once).published → Version published — agreement in force
ended → Agreement ended

folio-assistant — code under the Apache License 2.0, documentation under CC BY 3.0. Generated schema and API references are rebuilt from source on every push to main.

deployed dev