Generated from
folio-assistant-core/dsa/processes/dsa-document-lifecycle.bpmnbygen-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.
How it connects
- Called by: no call activity names this process
- Calls: Close the bean, Open the bean, Public comment on a review draft
- Presented on: no docs page section shows this diagram
- Running instances: none recorded
Lanes — who acts
| lane | role | what it does here |
|---|---|---|
| Parties and signatories (provider, recipient) | stakeholder | The 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 author | author | Writes 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) | reviewer | Checks 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-coordinator | Used 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-manager | Gives 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-pipeline | Renders 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.
| step | lane | skill / sub-process | what it does |
|---|---|---|---|
Open the beanCall_BeanOpen | Author and policy author | calls Open the beanbean-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 termsTask_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 textTask_WriteText | Author and policy author | document-authoringnormative-statementsdocument-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 basisTask_RecordLegalBasis | Author and policy author | normative-statements | The 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 summaryTask_PlainSummary | Author and policy author | document-authoring | Consent-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 AgreementTask_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 textTask_CheckOdrl | Reviewer (legal, policy) | content-review | Computable 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 annexesTask_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 agreementTask_Review | Reviewer (legal, policy) | content-reviewreview-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 templateCall_PublicComment | Public review (commenters, review committee, editor) | calls Public comment on a review draftpublic-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 PDFTask_Render | Build pipeline (system) | document-publishing | Render 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 · SignTask_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 URLTask_AssignVersion | Publisher (data provider’s publication manager) | content-publishpackage-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-256Task_Hash | Publisher (data provider’s publication manager) | dsa-checksum | Compute 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 summaryTask_HashSummary | Publisher (data provider’s publication manager) | dsa-checksum | Consent-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 citeTask_ConsentCitation | Publisher (data provider’s publication manager) | content-publish | Consent-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 textTask_OdrlCitesText | Author and policy author | dsa-odrl-source | The 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 URLTask_Publish | Build pipeline (system) | content-publish | Publish 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 recordTask_Catalogue | Publisher (data provider’s publication manager) | dsa-dcat-record | One 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 beanCall_BeanOpenChange | Author and policy author | calls Open the beanbean-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 endTask_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 grantsTask_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 neededTask_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 endedTask_SetStatus | Publisher (data provider’s publication manager) | dsa-catalogue-status | Set 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 dutiesTask_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 beanCall_BeanCloseEnded | Author and policy author | calls Close the beantodo-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.
| decision | what decides it | branches |
|---|---|---|
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 |