From 4ade080f1c8054a93695707b172efabec7f7e378 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20B=C3=B6hringer?= Date: Wed, 28 May 2025 16:42:06 +0200 Subject: [PATCH 01/12] Overhauled conditions for api v1 and added conditions for api v2 --- docs/src/process-development/api-v1/bpmn/conditions.md | 2 +- docs/src/process-development/api-v2/bpmn/conditions.md | 8 ++++++++ 2 files changed, 9 insertions(+), 1 deletion(-) create mode 100644 docs/src/process-development/api-v2/bpmn/conditions.md diff --git a/docs/src/process-development/api-v1/bpmn/conditions.md b/docs/src/process-development/api-v1/bpmn/conditions.md index 41447df07..d383fe4e0 100644 --- a/docs/src/process-development/api-v1/bpmn/conditions.md +++ b/docs/src/process-development/api-v1/bpmn/conditions.md @@ -5,4 +5,4 @@ icon: creative ### Conditions -[Conditions](https://docs.camunda.org/manual/7.21/user-guide/process-engine/expression-language/#conditions) allow you to change the behaviour of BPMN processes during execution. There are two ways you are able to add decision logic to Conditions. The [Camunda Modeler](https://camunda.com/download/modeler/) refers to them as `Type`. You can find them in the ``Condition`` tab of certain BPMN elements. The first one is `Script`. This allows you to add arbitrary complexity to your decisions logic and is rarely used for process plugins. The more common Type is `Expression`. Expressions have the following syntax: `${expression}`. An example of a simple expression would be a boolean condition like `var == true`. For this to work during BPMN process execution, the variable you want to use for the boolean condition must be available in the BPMN process variables before [Sequence Flow](sequence-flow.md) reaches the evaluation of the expression. You can learn more advanced features of Expressions [here](https://docs.camunda.org/manual/7.21/user-guide/process-engine/expression-language/). \ No newline at end of file +BPMN elements can have a property attached to them which either executes a script or evaluates an expression in order to make a decision. The most common example of this is the [Sequence Flow](./sequence-flow.md) elements following an [Exclusive Gateway](./gateways.md). Each [Sequence Flow](./sequence-flow.md) element will have a condition attached to decide which flow should be pursued. The [Camunda Modeler](https://camunda.com/download/modeler/) distinguishes the two types in the `Type` attribute of the `Condition` tab in a BPMN element. Camunda comes with a GraalVM JavaScript engine but can be extended with other types of scripting engines. See the Camunda documentation on [scripting](https://docs.camunda.org/manual/latest/user-guide/process-engine/scripting/) for more details. Expressions are short boolean evaluations and have the following syntax: `${expression}`. An example of a simple expression would be a condition like `var = true`. For this to work during BPMN process execution, the variable that is used for the boolean condition must be available in the BPMN process variables before the [Sequence Flow](sequence-flow.md) reaches the evaluation of the expression. You can learn more advanced features of Expressions [here](https://docs.camunda.org/manual/7.21/user-guide/process-engine/expression-language/). \ No newline at end of file diff --git a/docs/src/process-development/api-v2/bpmn/conditions.md b/docs/src/process-development/api-v2/bpmn/conditions.md new file mode 100644 index 000000000..d383fe4e0 --- /dev/null +++ b/docs/src/process-development/api-v2/bpmn/conditions.md @@ -0,0 +1,8 @@ +--- +title: Conditions +icon: creative +--- + +### Conditions + +BPMN elements can have a property attached to them which either executes a script or evaluates an expression in order to make a decision. The most common example of this is the [Sequence Flow](./sequence-flow.md) elements following an [Exclusive Gateway](./gateways.md). Each [Sequence Flow](./sequence-flow.md) element will have a condition attached to decide which flow should be pursued. The [Camunda Modeler](https://camunda.com/download/modeler/) distinguishes the two types in the `Type` attribute of the `Condition` tab in a BPMN element. Camunda comes with a GraalVM JavaScript engine but can be extended with other types of scripting engines. See the Camunda documentation on [scripting](https://docs.camunda.org/manual/latest/user-guide/process-engine/scripting/) for more details. Expressions are short boolean evaluations and have the following syntax: `${expression}`. An example of a simple expression would be a condition like `var = true`. For this to work during BPMN process execution, the variable that is used for the boolean condition must be available in the BPMN process variables before the [Sequence Flow](sequence-flow.md) reaches the evaluation of the expression. You can learn more advanced features of Expressions [here](https://docs.camunda.org/manual/7.21/user-guide/process-engine/expression-language/). \ No newline at end of file From ffc836b0b00073f3fb154c6692233ded171fa1af Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20B=C3=B6hringer?= Date: Wed, 28 May 2025 17:34:51 +0200 Subject: [PATCH 02/12] Overhauled gateways for api v1 and added gateways for api v2 --- .../api-v1/bpmn/gateways.md | 12 +++++++---- .../api-v2/bpmn/gateways.md | 20 +++++++++++++++++++ 2 files changed, 28 insertions(+), 4 deletions(-) create mode 100644 docs/src/process-development/api-v2/bpmn/gateways.md diff --git a/docs/src/process-development/api-v1/bpmn/gateways.md b/docs/src/process-development/api-v1/bpmn/gateways.md index 630b26ae0..b62dae140 100644 --- a/docs/src/process-development/api-v1/bpmn/gateways.md +++ b/docs/src/process-development/api-v1/bpmn/gateways.md @@ -5,12 +5,16 @@ icon: creative ### Gateways -[Gateways](https://docs.camunda.org/manual/7.21/reference/bpmn20/gateways/) allow you to control the [Sequence Flow](sequence-flow.md). Different types of gateways are useful for different scenarios. +[Gateways](https://docs.camunda.org/manual/7.21/reference/bpmn20/gateways/) allow modelling of decision-based and concurrent workflows. [Exclusive Gateways](#exclusive-gateways) model a decision where one flow gets pursued over other flows. [Event-based Gateways](#event-based-gateways) also model a decision, but are based on events. [Parallel Gateways](#parallel-gateways) model concurrency. #### Exclusive Gateways -[Exclusive Gateways](https://docs.camunda.org/manual/7.21/reference/bpmn20/gateways/exclusive-gateway/) allow you to decide which [Sequence Flow](sequence-flow.md) should be followed based on [conditions](https://docs.camunda.org/manual/7.21/user-guide/process-engine/expression-language/#conditions). [Conditions](https://docs.camunda.org/manual/7.21/user-guide/process-engine/expression-language/#conditions) are not part of the [Exclusive Gateways](https://docs.camunda.org/manual/7.21/reference/bpmn20/gateways/exclusive-gateway/) themselves. You set them through the sequence flow exiting the [Exclusive Gateway](https://docs.camunda.org/manual/7.21/reference/bpmn20/gateways/exclusive-gateway/). In the [Camunda Modeler](https://camunda.com/download/modeler/), you can add conditions to [Sequence Flow](sequence-flow.md) by selecting a [Sequence Flow](sequence-flow.md) and opening the `Condition` tab. You can find more information on how to use Conditions [here](conditions.md). +[Exclusive Gateways](https://docs.camunda.org/manual/7.21/reference/bpmn20/gateways/exclusive-gateway/) decide which one out of multiple [Sequence Flow](sequence-flow.md) should be followed based on [conditions](https://docs.camunda.org/manual/7.21/user-guide/process-engine/expression-language/#conditions). [Conditions](https://docs.camunda.org/manual/7.21/user-guide/process-engine/expression-language/#conditions) are not part of the [Exclusive Gateways](https://docs.camunda.org/manual/7.21/reference/bpmn20/gateways/exclusive-gateway/) themselves. They are set through the sequence flow exiting the [Exclusive Gateway](https://docs.camunda.org/manual/7.21/reference/bpmn20/gateways/exclusive-gateway/). In the [Camunda Modeler](https://camunda.com/download/modeler/), you can add conditions to [Sequence Flows](sequence-flow.md) by selecting a [Sequence Flow](sequence-flow.md) and opening the `Condition` tab. You can find more information on how to use Conditions [here](conditions.md). -#### Event-based Gateway +#### Event-based Gateways -The [Event-based Gateway](https://docs.camunda.org/manual/7.21/reference/bpmn20/gateways/event-based-gateway/) allows you model scenarios where you are expecting one out of a number of events to occur. \ No newline at end of file +The [Event-based Gateway](https://docs.camunda.org/manual/7.21/reference/bpmn20/gateways/event-based-gateway/) models a decision in the workflow. But instead of [conditions](./conditions.md), the [Event-based Gateway](https://docs.camunda.org/manual/7.21/reference/bpmn20/gateways/event-based-gateway/) uses the triggering of an event to dicide which [Sequence Flow](sequence-flow.md) to pursue. + +#### Parallel Gateways + +[Parallel Gateways](https://docs.camunda.org/manual/latest/reference/bpmn20/gateways/parallel-gateway/) model concurrent workflows. Their outgoing flows can be joined together again with another [Parallel Gateway](https://docs.camunda.org/manual/latest/reference/bpmn20/gateways/parallel-gateway/). This makes process execution wait for both flows to arrive at the gateway before continuing. \ No newline at end of file diff --git a/docs/src/process-development/api-v2/bpmn/gateways.md b/docs/src/process-development/api-v2/bpmn/gateways.md new file mode 100644 index 000000000..b62dae140 --- /dev/null +++ b/docs/src/process-development/api-v2/bpmn/gateways.md @@ -0,0 +1,20 @@ +--- +title: Gateways +icon: creative +--- + +### Gateways + +[Gateways](https://docs.camunda.org/manual/7.21/reference/bpmn20/gateways/) allow modelling of decision-based and concurrent workflows. [Exclusive Gateways](#exclusive-gateways) model a decision where one flow gets pursued over other flows. [Event-based Gateways](#event-based-gateways) also model a decision, but are based on events. [Parallel Gateways](#parallel-gateways) model concurrency. + +#### Exclusive Gateways + +[Exclusive Gateways](https://docs.camunda.org/manual/7.21/reference/bpmn20/gateways/exclusive-gateway/) decide which one out of multiple [Sequence Flow](sequence-flow.md) should be followed based on [conditions](https://docs.camunda.org/manual/7.21/user-guide/process-engine/expression-language/#conditions). [Conditions](https://docs.camunda.org/manual/7.21/user-guide/process-engine/expression-language/#conditions) are not part of the [Exclusive Gateways](https://docs.camunda.org/manual/7.21/reference/bpmn20/gateways/exclusive-gateway/) themselves. They are set through the sequence flow exiting the [Exclusive Gateway](https://docs.camunda.org/manual/7.21/reference/bpmn20/gateways/exclusive-gateway/). In the [Camunda Modeler](https://camunda.com/download/modeler/), you can add conditions to [Sequence Flows](sequence-flow.md) by selecting a [Sequence Flow](sequence-flow.md) and opening the `Condition` tab. You can find more information on how to use Conditions [here](conditions.md). + +#### Event-based Gateways + +The [Event-based Gateway](https://docs.camunda.org/manual/7.21/reference/bpmn20/gateways/event-based-gateway/) models a decision in the workflow. But instead of [conditions](./conditions.md), the [Event-based Gateway](https://docs.camunda.org/manual/7.21/reference/bpmn20/gateways/event-based-gateway/) uses the triggering of an event to dicide which [Sequence Flow](sequence-flow.md) to pursue. + +#### Parallel Gateways + +[Parallel Gateways](https://docs.camunda.org/manual/latest/reference/bpmn20/gateways/parallel-gateway/) model concurrent workflows. Their outgoing flows can be joined together again with another [Parallel Gateway](https://docs.camunda.org/manual/latest/reference/bpmn20/gateways/parallel-gateway/). This makes process execution wait for both flows to arrive at the gateway before continuing. \ No newline at end of file From 687ab069c84d89270748a0badd3f97f6ea612f52 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20B=C3=B6hringer?= Date: Wed, 28 May 2025 17:38:31 +0200 Subject: [PATCH 03/12] bpmn concepts stay the say for api v2 --- .../process-development/api-v2/bpmn/index.md | 15 ++++++++++++ .../api-v2/bpmn/messaging.md | 24 +++++++++++++++++++ .../api-v2/bpmn/sequence-flow.md | 7 ++++++ .../api-v2/bpmn/service-tasks.md | 8 +++++++ .../timer-intermediate-catching-events.md | 8 +++++++ .../api-v2/bpmn/user-tasks.md | 8 +++++++ 6 files changed, 70 insertions(+) create mode 100644 docs/src/process-development/api-v2/bpmn/index.md create mode 100644 docs/src/process-development/api-v2/bpmn/messaging.md create mode 100644 docs/src/process-development/api-v2/bpmn/sequence-flow.md create mode 100644 docs/src/process-development/api-v2/bpmn/service-tasks.md create mode 100644 docs/src/process-development/api-v2/bpmn/timer-intermediate-catching-events.md create mode 100644 docs/src/process-development/api-v2/bpmn/user-tasks.md diff --git a/docs/src/process-development/api-v2/bpmn/index.md b/docs/src/process-development/api-v2/bpmn/index.md new file mode 100644 index 000000000..d74ae074d --- /dev/null +++ b/docs/src/process-development/api-v2/bpmn/index.md @@ -0,0 +1,15 @@ +--- +title: BPMN +icon: creative +--- + +## Introduction +The DSF uses BPMN 2.0 to model processes. Specifically, the [Camunda 7](https://docs.camunda.org/manual/7.21/) dialect from the [Camunda Modeler](https://camunda.com/de/download/modeler/). Modeling processes for the DSF requires this modeler or any other modeler which is able to produce the correct Camunda dialect. + +## Details +- [Conditions](conditions.md) +- [Gateways](gateways.md) +- [Messaging](messaging.md) +- [Sequence Flow](sequence-flow.md) +- [Service Tasks](service-tasks.md) +- [Timer Intermediate Catching Events](timer-intermediate-catching-events.md) \ No newline at end of file diff --git a/docs/src/process-development/api-v2/bpmn/messaging.md b/docs/src/process-development/api-v2/bpmn/messaging.md new file mode 100644 index 000000000..97d05703b --- /dev/null +++ b/docs/src/process-development/api-v2/bpmn/messaging.md @@ -0,0 +1,24 @@ +--- +title: Messaging +icon: creative +--- + + +### Messaging + +In order to enable communication with other lanes, pools or even entirely separate processes you need to be able to exchange information. In BPMN, you can use [Message Events](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/message-events/) to model this information exchange. Modeling communication with [Message Events](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/message-events/) in the same diagram uses Message Flow. Message Flow is typically represented by a dashed line arrow between BPMN elements with a black (send) or white (receive) envelope icon. The following BPMN collaboration diagram shows message exchange between two processes. + +![BPMN collaboration diagram with two processes using message flow to exchange information between two organizations](/photos/developer-documentation/message_flow.svg) + +#### Message Start Event + +[Message Start Events](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/message-events/#message-start-event) allow a BPMN process to be started by an incoming message. In the DSF, all BPMN processes are started via messages. Therefore, you will have to include a [Message Start Event](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/message-events/#message-start-event) at the beginning of all of your BPMN models. + +#### Message Intermediate Throwing Event +[Message Intermediate Throwing Events](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/message-events/#message-intermediate-throwing-event) are used to send messages during process execution. + +#### Message Intermediate Catching Event +[Message Intermediate Catching Events](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/message-events/#message-intermediate-catching-event) serve as the counterpart to [Message Intermediate Throwing Events](messaging.md#message-intermediate-throwing-event). Use them whenever you expect to receive a message from another process or organization during execution. + +#### Message End Event +The [Message End Event](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/message-events/#message-end-event) will stop the execution of a BPMN process and finish by sending a message. \ No newline at end of file diff --git a/docs/src/process-development/api-v2/bpmn/sequence-flow.md b/docs/src/process-development/api-v2/bpmn/sequence-flow.md new file mode 100644 index 000000000..3650cc635 --- /dev/null +++ b/docs/src/process-development/api-v2/bpmn/sequence-flow.md @@ -0,0 +1,7 @@ +--- +title: Sequence Flow +icon: creative +--- + +### Sequence Flow +BPMN 2.0 calls the continuous arrows connecting the BPMN elements in BPMN models, Sequence Flow. Sequence Flow exits one BPMN element and points at the next BPMN element to be processed. diff --git a/docs/src/process-development/api-v2/bpmn/service-tasks.md b/docs/src/process-development/api-v2/bpmn/service-tasks.md new file mode 100644 index 000000000..ebe8ad3c9 --- /dev/null +++ b/docs/src/process-development/api-v2/bpmn/service-tasks.md @@ -0,0 +1,8 @@ +--- +title: Service Tasks +icon: creative +--- + +### Service Tasks + +One of the most common types of BPMN Tasks used for modeling DSF processes is the [Service Task](https://docs.camunda.org/manual/7.21/reference/bpmn20/tasks/service-task/). They are different from regular BPMN Tasks in that they offer the ability to link an implementation to the [Service Task](https://docs.camunda.org/manual/7.21/reference/bpmn20/tasks/service-task/) which can be called and executed by a BPMN engine. The BPE (Business Process Engine) server of the DSF leverages this engine to execute your BPMN processes. \ No newline at end of file diff --git a/docs/src/process-development/api-v2/bpmn/timer-intermediate-catching-events.md b/docs/src/process-development/api-v2/bpmn/timer-intermediate-catching-events.md new file mode 100644 index 000000000..49ab4a8fc --- /dev/null +++ b/docs/src/process-development/api-v2/bpmn/timer-intermediate-catching-events.md @@ -0,0 +1,8 @@ +--- +title: Timer Intermediate Catching Events +icon: creative +--- + +### Timer Intermediate Catching Events + +A [Timer Intermediate Catching Event](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/timer-events/#timer-intermediate-catching-event) allows you to model stopwatch behavior. A timer is started once the BPMN execution arrives at the event. The duration until the timer runs out is specified using the [ISO 8601 Durations](http://en.wikipedia.org/wiki/ISO_8601#Durations) format. Examples can be found [here](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/timer-events/#time-duration). After running out, the BPMN process executes the [Sequence Flow](sequence-flow.md) following the [Timer Intermediate Catching Event](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/timer-events/#timer-intermediate-catching-event). \ No newline at end of file diff --git a/docs/src/process-development/api-v2/bpmn/user-tasks.md b/docs/src/process-development/api-v2/bpmn/user-tasks.md new file mode 100644 index 000000000..8dda98d17 --- /dev/null +++ b/docs/src/process-development/api-v2/bpmn/user-tasks.md @@ -0,0 +1,8 @@ +--- +title: User Tasks +icon: creative +--- + +### User Tasks + +User Tasks define a process step that requires some kind of human interaction. Usually this is done by providing some kind of form the user can fill out. The Camunda Modeler allows to configure these forms as either a propriatary format called [Camunda Forms](https://docs.camunda.io/docs/guides/utilizing-forms/) or custom forms called `Embedded or External Task Forms`. The DSF uses such `External Task Forms` in the form of [Questionnaire](https://www.hl7.org/fhir/R4/questionnaire.html) and [Questionnaire Response](https://www.hl7.org/fhir/R4/questionnaireresponse.html) resources. This mechanism is further expanded upon in [User Tasks in the DSF](../guides/user-tasks-in-the-dsf.md). \ No newline at end of file From e8143f69c8cd231a12898a64594bec72f61d1a92 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20B=C3=B6hringer?= Date: Fri, 13 Jun 2025 16:40:40 +0200 Subject: [PATCH 04/12] Correcting all API v2 documentation by making sure it is referencing API v2 concepts and rewriting texts so they are more objective and don't speak to the reader directly --- ...questionnaire-and-questionnaireresponse.md | 0 docs/src/process-development/api-v2/README.md | 8 - .../api-v2/bpmn/conditions.md | 2 +- .../api-v2/bpmn/gateways.md | 10 +- .../api-v2/bpmn/messaging.md | 16 +- .../api-v2/bpmn/sequence-flow.md | 2 +- .../api-v2/bpmn/service-tasks.md | 4 +- .../timer-intermediate-catching-events.md | 4 +- .../api-v2/bpmn/user-tasks.md | 4 +- .../api-v2/dsf/bpmn-process-execution.md | 8 + .../api-v2/dsf/bpmn-process-variables.md | 10 + .../api-v2/dsf/draft-task-resources.md | 21 + .../api-v2/dsf/environment-variables.md | 10 + .../process-development/api-v2/dsf/index.md | 20 + .../api-v2/dsf/message-correlation.md | 10 + .../api-v2/dsf/message-delegates.md | 18 + .../api-v2/dsf/organization-identifiers.md | 13 + .../api-v2/dsf/process-plugin-api.md | 40 + .../api-v2/dsf/process-plugin-definition.md | 19 + .../api-v2/dsf/read-access-tag.md | 25 + .../api-v2/dsf/requester-and-recipient.md | 254 ++++++ .../api-v2/dsf/service-delegates.md | 15 + .../dsf/spring-framework-integration.md | 24 + .../api-v2/dsf/target-and-targets.md | 19 + .../api-v2/dsf/versions-placeholders-urls.md | 41 + .../api-v2/fhir/activitydefinition.md | 26 + .../api-v2/fhir/codesystem.md | 15 + .../process-development/api-v2/fhir/index.md | 14 + ...questionnaire-and-questionnaireresponse.md | 11 + .../process-development/api-v2/fhir/task.md | 20 + .../api-v2/fhir/valueset.md | 13 + .../accessing-bpmn-process-variables.md | 12 + ...cessing-task-resources-during-execution.md | 12 + ...-task-input-parameters-to-task-profiles.md | 213 +++++ .../guides/configuring-read-access-tags.md | 416 ++++++++++ .../guides/creating-activity-definitions.md | 753 ++++++++++++++++++ .../creating-codesystems-for-dsf-processes.md | 45 ++ ...ng-task-resources-based-on-a-definition.md | 236 ++++++ .../creating-valuesets-for-dsf-processes.md | 64 ++ .../api-v2/guides/index.md | 17 + ...-incoming-messages-and-missing-messages.md | 18 + .../setting-targets-for-message-events.md | 12 + .../starting-a-process-via-task-resources.md | 36 + .../api-v2/guides/user-tasks-in-the-dsf.md | 58 ++ docs/src/process-development/api-v2/index.md | 47 ++ 45 files changed, 2606 insertions(+), 29 deletions(-) create mode 100644 docs/src/process-development/api-v1/fhir/questionnaire-and-questionnaireresponse.md delete mode 100644 docs/src/process-development/api-v2/README.md create mode 100644 docs/src/process-development/api-v2/dsf/bpmn-process-execution.md create mode 100644 docs/src/process-development/api-v2/dsf/bpmn-process-variables.md create mode 100644 docs/src/process-development/api-v2/dsf/draft-task-resources.md create mode 100644 docs/src/process-development/api-v2/dsf/environment-variables.md create mode 100644 docs/src/process-development/api-v2/dsf/index.md create mode 100644 docs/src/process-development/api-v2/dsf/message-correlation.md create mode 100644 docs/src/process-development/api-v2/dsf/message-delegates.md create mode 100644 docs/src/process-development/api-v2/dsf/organization-identifiers.md create mode 100644 docs/src/process-development/api-v2/dsf/process-plugin-api.md create mode 100644 docs/src/process-development/api-v2/dsf/process-plugin-definition.md create mode 100644 docs/src/process-development/api-v2/dsf/read-access-tag.md create mode 100644 docs/src/process-development/api-v2/dsf/requester-and-recipient.md create mode 100644 docs/src/process-development/api-v2/dsf/service-delegates.md create mode 100644 docs/src/process-development/api-v2/dsf/spring-framework-integration.md create mode 100644 docs/src/process-development/api-v2/dsf/target-and-targets.md create mode 100644 docs/src/process-development/api-v2/dsf/versions-placeholders-urls.md create mode 100644 docs/src/process-development/api-v2/fhir/activitydefinition.md create mode 100644 docs/src/process-development/api-v2/fhir/codesystem.md create mode 100644 docs/src/process-development/api-v2/fhir/index.md create mode 100644 docs/src/process-development/api-v2/fhir/questionnaire-and-questionnaireresponse.md create mode 100644 docs/src/process-development/api-v2/fhir/task.md create mode 100644 docs/src/process-development/api-v2/fhir/valueset.md create mode 100644 docs/src/process-development/api-v2/guides/accessing-bpmn-process-variables.md create mode 100644 docs/src/process-development/api-v2/guides/accessing-task-resources-during-execution.md create mode 100644 docs/src/process-development/api-v2/guides/adding-task-input-parameters-to-task-profiles.md create mode 100644 docs/src/process-development/api-v2/guides/configuring-read-access-tags.md create mode 100644 docs/src/process-development/api-v2/guides/creating-activity-definitions.md create mode 100644 docs/src/process-development/api-v2/guides/creating-codesystems-for-dsf-processes.md create mode 100644 docs/src/process-development/api-v2/guides/creating-task-resources-based-on-a-definition.md create mode 100644 docs/src/process-development/api-v2/guides/creating-valuesets-for-dsf-processes.md create mode 100644 docs/src/process-development/api-v2/guides/index.md create mode 100644 docs/src/process-development/api-v2/guides/managing-mutiple-incoming-messages-and-missing-messages.md create mode 100644 docs/src/process-development/api-v2/guides/setting-targets-for-message-events.md create mode 100644 docs/src/process-development/api-v2/guides/starting-a-process-via-task-resources.md create mode 100644 docs/src/process-development/api-v2/guides/user-tasks-in-the-dsf.md create mode 100644 docs/src/process-development/api-v2/index.md diff --git a/docs/src/process-development/api-v1/fhir/questionnaire-and-questionnaireresponse.md b/docs/src/process-development/api-v1/fhir/questionnaire-and-questionnaireresponse.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/src/process-development/api-v2/README.md b/docs/src/process-development/api-v2/README.md deleted file mode 100644 index a0c73805e..000000000 --- a/docs/src/process-development/api-v2/README.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: API 2 (alpha) Overview -icon: code ---- -## Overview -- [About API2](description) -- [Implementation Guide](implementation) -- [Migration Guide](migration) \ No newline at end of file diff --git a/docs/src/process-development/api-v2/bpmn/conditions.md b/docs/src/process-development/api-v2/bpmn/conditions.md index d383fe4e0..12360366d 100644 --- a/docs/src/process-development/api-v2/bpmn/conditions.md +++ b/docs/src/process-development/api-v2/bpmn/conditions.md @@ -3,6 +3,6 @@ title: Conditions icon: creative --- -### Conditions +## Conditions BPMN elements can have a property attached to them which either executes a script or evaluates an expression in order to make a decision. The most common example of this is the [Sequence Flow](./sequence-flow.md) elements following an [Exclusive Gateway](./gateways.md). Each [Sequence Flow](./sequence-flow.md) element will have a condition attached to decide which flow should be pursued. The [Camunda Modeler](https://camunda.com/download/modeler/) distinguishes the two types in the `Type` attribute of the `Condition` tab in a BPMN element. Camunda comes with a GraalVM JavaScript engine but can be extended with other types of scripting engines. See the Camunda documentation on [scripting](https://docs.camunda.org/manual/latest/user-guide/process-engine/scripting/) for more details. Expressions are short boolean evaluations and have the following syntax: `${expression}`. An example of a simple expression would be a condition like `var = true`. For this to work during BPMN process execution, the variable that is used for the boolean condition must be available in the BPMN process variables before the [Sequence Flow](sequence-flow.md) reaches the evaluation of the expression. You can learn more advanced features of Expressions [here](https://docs.camunda.org/manual/7.21/user-guide/process-engine/expression-language/). \ No newline at end of file diff --git a/docs/src/process-development/api-v2/bpmn/gateways.md b/docs/src/process-development/api-v2/bpmn/gateways.md index b62dae140..619e001f2 100644 --- a/docs/src/process-development/api-v2/bpmn/gateways.md +++ b/docs/src/process-development/api-v2/bpmn/gateways.md @@ -3,18 +3,18 @@ title: Gateways icon: creative --- -### Gateways +## Gateways [Gateways](https://docs.camunda.org/manual/7.21/reference/bpmn20/gateways/) allow modelling of decision-based and concurrent workflows. [Exclusive Gateways](#exclusive-gateways) model a decision where one flow gets pursued over other flows. [Event-based Gateways](#event-based-gateways) also model a decision, but are based on events. [Parallel Gateways](#parallel-gateways) model concurrency. -#### Exclusive Gateways +### Exclusive Gateways -[Exclusive Gateways](https://docs.camunda.org/manual/7.21/reference/bpmn20/gateways/exclusive-gateway/) decide which one out of multiple [Sequence Flow](sequence-flow.md) should be followed based on [conditions](https://docs.camunda.org/manual/7.21/user-guide/process-engine/expression-language/#conditions). [Conditions](https://docs.camunda.org/manual/7.21/user-guide/process-engine/expression-language/#conditions) are not part of the [Exclusive Gateways](https://docs.camunda.org/manual/7.21/reference/bpmn20/gateways/exclusive-gateway/) themselves. They are set through the sequence flow exiting the [Exclusive Gateway](https://docs.camunda.org/manual/7.21/reference/bpmn20/gateways/exclusive-gateway/). In the [Camunda Modeler](https://camunda.com/download/modeler/), you can add conditions to [Sequence Flows](sequence-flow.md) by selecting a [Sequence Flow](sequence-flow.md) and opening the `Condition` tab. You can find more information on how to use Conditions [here](conditions.md). +[Exclusive Gateways](https://docs.camunda.org/manual/7.21/reference/bpmn20/gateways/exclusive-gateway/) decide which one out of multiple [Sequence Flow](sequence-flow.md) should be followed based on [conditions](https://docs.camunda.org/manual/7.21/user-guide/process-engine/expression-language/#conditions). [Conditions](https://docs.camunda.org/manual/7.21/user-guide/process-engine/expression-language/#conditions) are not part of the [Exclusive Gateways](https://docs.camunda.org/manual/7.21/reference/bpmn20/gateways/exclusive-gateway/) themselves. They are set through the sequence flow exiting the [Exclusive Gateway](https://docs.camunda.org/manual/7.21/reference/bpmn20/gateways/exclusive-gateway/). In the [Camunda Modeler](https://camunda.com/download/modeler/), conditions can be added to [Sequence Flows](sequence-flow.md) by selecting a [Sequence Flow](sequence-flow.md) and opening the `Condition` tab. More information on how to use Conditions can be found in [Conditions](conditions.md). -#### Event-based Gateways +### Event-based Gateways The [Event-based Gateway](https://docs.camunda.org/manual/7.21/reference/bpmn20/gateways/event-based-gateway/) models a decision in the workflow. But instead of [conditions](./conditions.md), the [Event-based Gateway](https://docs.camunda.org/manual/7.21/reference/bpmn20/gateways/event-based-gateway/) uses the triggering of an event to dicide which [Sequence Flow](sequence-flow.md) to pursue. -#### Parallel Gateways +### Parallel Gateways [Parallel Gateways](https://docs.camunda.org/manual/latest/reference/bpmn20/gateways/parallel-gateway/) model concurrent workflows. Their outgoing flows can be joined together again with another [Parallel Gateway](https://docs.camunda.org/manual/latest/reference/bpmn20/gateways/parallel-gateway/). This makes process execution wait for both flows to arrive at the gateway before continuing. \ No newline at end of file diff --git a/docs/src/process-development/api-v2/bpmn/messaging.md b/docs/src/process-development/api-v2/bpmn/messaging.md index 97d05703b..10657a006 100644 --- a/docs/src/process-development/api-v2/bpmn/messaging.md +++ b/docs/src/process-development/api-v2/bpmn/messaging.md @@ -4,21 +4,21 @@ icon: creative --- -### Messaging +## Messaging -In order to enable communication with other lanes, pools or even entirely separate processes you need to be able to exchange information. In BPMN, you can use [Message Events](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/message-events/) to model this information exchange. Modeling communication with [Message Events](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/message-events/) in the same diagram uses Message Flow. Message Flow is typically represented by a dashed line arrow between BPMN elements with a black (send) or white (receive) envelope icon. The following BPMN collaboration diagram shows message exchange between two processes. +Enabling communication with other lanes, pools or even entirely separate processes requires the ability to exchange information. In BPMN, [Message Events](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/message-events/) are used to model this information exchange. Modeling communication with [Message Events](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/message-events/) in the same diagram uses Message Flow. Message Flow is typically represented by a dashed line arrow between BPMN elements with a black (send) or white (receive) envelope icon. The following BPMN collaboration diagram shows message exchange between two processes. ![BPMN collaboration diagram with two processes using message flow to exchange information between two organizations](/photos/developer-documentation/message_flow.svg) -#### Message Start Event +### Message Start Event -[Message Start Events](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/message-events/#message-start-event) allow a BPMN process to be started by an incoming message. In the DSF, all BPMN processes are started via messages. Therefore, you will have to include a [Message Start Event](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/message-events/#message-start-event) at the beginning of all of your BPMN models. +[Message Start Events](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/message-events/#message-start-event) allow a BPMN process to be started by an incoming message. In the DSF, all BPMN processes are started via messages. Therefore, a [Message Start Event](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/message-events/#message-start-event) has to be included at the beginning of all of your BPMN models. -#### Message Intermediate Throwing Event +### Message Intermediate Throwing Event [Message Intermediate Throwing Events](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/message-events/#message-intermediate-throwing-event) are used to send messages during process execution. -#### Message Intermediate Catching Event -[Message Intermediate Catching Events](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/message-events/#message-intermediate-catching-event) serve as the counterpart to [Message Intermediate Throwing Events](messaging.md#message-intermediate-throwing-event). Use them whenever you expect to receive a message from another process or organization during execution. +### Message Intermediate Catching Event +[Message Intermediate Catching Events](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/message-events/#message-intermediate-catching-event) serve as the counterpart to [Message Intermediate Throwing Events](messaging.md#message-intermediate-throwing-event). Use them whenever it is expected to receive a message from another process or organization during execution. -#### Message End Event +### Message End Event The [Message End Event](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/message-events/#message-end-event) will stop the execution of a BPMN process and finish by sending a message. \ No newline at end of file diff --git a/docs/src/process-development/api-v2/bpmn/sequence-flow.md b/docs/src/process-development/api-v2/bpmn/sequence-flow.md index 3650cc635..2a248406d 100644 --- a/docs/src/process-development/api-v2/bpmn/sequence-flow.md +++ b/docs/src/process-development/api-v2/bpmn/sequence-flow.md @@ -3,5 +3,5 @@ title: Sequence Flow icon: creative --- -### Sequence Flow +## Sequence Flow BPMN 2.0 calls the continuous arrows connecting the BPMN elements in BPMN models, Sequence Flow. Sequence Flow exits one BPMN element and points at the next BPMN element to be processed. diff --git a/docs/src/process-development/api-v2/bpmn/service-tasks.md b/docs/src/process-development/api-v2/bpmn/service-tasks.md index ebe8ad3c9..84114ab8c 100644 --- a/docs/src/process-development/api-v2/bpmn/service-tasks.md +++ b/docs/src/process-development/api-v2/bpmn/service-tasks.md @@ -3,6 +3,6 @@ title: Service Tasks icon: creative --- -### Service Tasks +## Service Tasks -One of the most common types of BPMN Tasks used for modeling DSF processes is the [Service Task](https://docs.camunda.org/manual/7.21/reference/bpmn20/tasks/service-task/). They are different from regular BPMN Tasks in that they offer the ability to link an implementation to the [Service Task](https://docs.camunda.org/manual/7.21/reference/bpmn20/tasks/service-task/) which can be called and executed by a BPMN engine. The BPE (Business Process Engine) server of the DSF leverages this engine to execute your BPMN processes. \ No newline at end of file +One of the most common types of BPMN Tasks used for modeling DSF processes is the [Service Task](https://docs.camunda.org/manual/7.21/reference/bpmn20/tasks/service-task/). They are different from regular BPMN Tasks in that they offer the ability to link an implementation to the [Service Task](https://docs.camunda.org/manual/7.21/reference/bpmn20/tasks/service-task/) which can be called and executed by a BPMN engine. The BPE (Business Process Engine) server of the DSF leverages this engine to execute BPMN processes. \ No newline at end of file diff --git a/docs/src/process-development/api-v2/bpmn/timer-intermediate-catching-events.md b/docs/src/process-development/api-v2/bpmn/timer-intermediate-catching-events.md index 49ab4a8fc..55aa68cbc 100644 --- a/docs/src/process-development/api-v2/bpmn/timer-intermediate-catching-events.md +++ b/docs/src/process-development/api-v2/bpmn/timer-intermediate-catching-events.md @@ -3,6 +3,6 @@ title: Timer Intermediate Catching Events icon: creative --- -### Timer Intermediate Catching Events +## Timer Intermediate Catching Events -A [Timer Intermediate Catching Event](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/timer-events/#timer-intermediate-catching-event) allows you to model stopwatch behavior. A timer is started once the BPMN execution arrives at the event. The duration until the timer runs out is specified using the [ISO 8601 Durations](http://en.wikipedia.org/wiki/ISO_8601#Durations) format. Examples can be found [here](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/timer-events/#time-duration). After running out, the BPMN process executes the [Sequence Flow](sequence-flow.md) following the [Timer Intermediate Catching Event](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/timer-events/#timer-intermediate-catching-event). \ No newline at end of file +A [Timer Intermediate Catching Event](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/timer-events/#timer-intermediate-catching-event) allows for modelling stopwatch behavior. A timer is started once the BPMN execution arrives at the event. The duration until the timer runs out is specified using the [ISO 8601 Durations](http://en.wikipedia.org/wiki/ISO_8601#Durations) format. Examples can be found [here](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/timer-events/#time-duration). After running out, the BPMN process executes the [Sequence Flow](sequence-flow.md) following the [Timer Intermediate Catching Event](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/timer-events/#timer-intermediate-catching-event). \ No newline at end of file diff --git a/docs/src/process-development/api-v2/bpmn/user-tasks.md b/docs/src/process-development/api-v2/bpmn/user-tasks.md index 8dda98d17..f405823e1 100644 --- a/docs/src/process-development/api-v2/bpmn/user-tasks.md +++ b/docs/src/process-development/api-v2/bpmn/user-tasks.md @@ -3,6 +3,6 @@ title: User Tasks icon: creative --- -### User Tasks +## User Tasks -User Tasks define a process step that requires some kind of human interaction. Usually this is done by providing some kind of form the user can fill out. The Camunda Modeler allows to configure these forms as either a propriatary format called [Camunda Forms](https://docs.camunda.io/docs/guides/utilizing-forms/) or custom forms called `Embedded or External Task Forms`. The DSF uses such `External Task Forms` in the form of [Questionnaire](https://www.hl7.org/fhir/R4/questionnaire.html) and [Questionnaire Response](https://www.hl7.org/fhir/R4/questionnaireresponse.html) resources. This mechanism is further expanded upon in [User Tasks in the DSF](../guides/user-tasks-in-the-dsf.md). \ No newline at end of file +User Tasks define a process step that requires some kind of human interaction. Usually this is done by providing some kind of form the user can fill out. The Camunda Modeler allows to configure these forms as either a proprietary format called [Camunda Forms](https://docs.camunda.io/docs/guides/utilizing-forms/) or custom forms called `Embedded or External Task Forms`. The DSF uses such `External Task Forms` in the form of [Questionnaire](https://www.hl7.org/fhir/R4/questionnaire.html) and [Questionnaire Response](https://www.hl7.org/fhir/R4/questionnaireresponse.html) resources. This mechanism is further expanded upon in [User Tasks in the DSF](../guides/user-tasks-in-the-dsf.md). \ No newline at end of file diff --git a/docs/src/process-development/api-v2/dsf/bpmn-process-execution.md b/docs/src/process-development/api-v2/dsf/bpmn-process-execution.md new file mode 100644 index 000000000..99416972d --- /dev/null +++ b/docs/src/process-development/api-v2/dsf/bpmn-process-execution.md @@ -0,0 +1,8 @@ +--- +title: BPMN Process Execution +icon: creative +--- + +## BPMN Process Execution + +The BPMN process execution is the in-memory representation of a running BPMN process. BPMN processes have their executions structured as a tree hierarchy. Each BPMN process starts with the [process instance](https://docs.camunda.org/manual/7.21/user-guide/process-engine/process-engine-concepts/#process-instances) as its root level execution. If, for example, this root execution reaches a parallel gateway with two paths, it would spawn two child executions under itself for them to process all tasks along their paths on their own. Executions can access all the BPMN elements from the BPMN model as well as the [BPMN process variables](bpmn-process-variables.md). Access to this representation in your Java code is provided through the `variables` parameter when overriding certain methods in [Service](service-delegates.md) / [Message](message-delegates.md) Delegates like `execute` or `getAdditionalInputParameters`. \ No newline at end of file diff --git a/docs/src/process-development/api-v2/dsf/bpmn-process-variables.md b/docs/src/process-development/api-v2/dsf/bpmn-process-variables.md new file mode 100644 index 000000000..04218a1d7 --- /dev/null +++ b/docs/src/process-development/api-v2/dsf/bpmn-process-variables.md @@ -0,0 +1,10 @@ +--- +title: BPMN Process Variables +icon: creative +--- + +## BPMN Process Variables + +BPMN process variables hold additional information which has to be available during BPMN process execution. Variables can be directly related to BPMN elements like the boolean value for [Conditions](../bpmn/conditions.md), but do not have to be. BPMN process variables are stored as key-value pairs with the key being the variable name. They are accessible during the entirety of the execution to all [Service](service-delegates.md) / [Message](message-delegates.md) Delegates. + +More information on how to access to the BPMN process variables is found in the guide on accessing [BPMN process variables](../guides/accessing-bpmn-process-variables.md). \ No newline at end of file diff --git a/docs/src/process-development/api-v2/dsf/draft-task-resources.md b/docs/src/process-development/api-v2/dsf/draft-task-resources.md new file mode 100644 index 000000000..782558b65 --- /dev/null +++ b/docs/src/process-development/api-v2/dsf/draft-task-resources.md @@ -0,0 +1,21 @@ +--- +title: Draft Task Resources +icon: creative +--- + +## Draft Task Resources + +[Task](../fhir/task.md) resources with status `draft` are used to create the DSF FHIR server's functionality of starting processes via its web interface. They are stored in `.../tutorial-process/src/main/resources/fhir/Task`. Compared to regular [Task](../fhir/task.md) resources used to start BPMN processes, this type of [Task](../fhir/task.md) resource requires the status `draft` instead of the usual `requested`. It also replaces the value for `authoredOn` with the placeholder `#{date}`, the values of organization identifiers with the placeholder `#{organization}` and all instances of version numbers with `#{version}`. Additionally, it requires setting the `Task.identifier` element. It should look something like this: + +```xml + + + + +``` +`processKey` should be the same one used in [URLs](versions-placeholders-urls.md#urls). +`task-name` can be any String this task should be identified with. E.g. you can use the file name of the Draft Task. + +A complete example for a Draft Task Resource can be found in the [Ping Pong Process Plugin](https://github.com/datasharingframework/dsf-process-ping-pong/blob/main/src/main/resources/fhir/Task/dsf-task-start-ping.xml). + +There is also a [guide for creating task resources based on a StructureDefinition](../guides/creating-task-resources-based-on-a-definition.md) if more information on how to create [Task](../fhir/task.md) resources is required. \ No newline at end of file diff --git a/docs/src/process-development/api-v2/dsf/environment-variables.md b/docs/src/process-development/api-v2/dsf/environment-variables.md new file mode 100644 index 000000000..a5af97668 --- /dev/null +++ b/docs/src/process-development/api-v2/dsf/environment-variables.md @@ -0,0 +1,10 @@ +--- +title: Environment Variables +icon: creative +--- + +## Environment Variables + +Environment variables offer a way to make configuration data available at the start of a [BPMN process execution](bpmn-process-execution.md). They are the same for all running process instances. They can be defined by adding a member variable with the [Spring-Framework @Value](https://docs.spring.io/spring-framework/docs/current/reference/html/core.html#beans-value-annotations) annotation to any Spring managed bean. For the DSF, the most prominent are classes annotated with [`@Configuration`](https://docs.spring.io/spring-framework/reference/core/beans/java/configuration-annotation.html). The value of the annotation uses the `${..}` notation and follows the form `${some.property:defaultValue}`, where each dot in the property name corresponds to an underscore in the equivalent environment variable. Environment variables are always written upper-case. The property `some.property` therefore corresponds to the environment variable `SOME_PROPERTY`. + +The DSF provides a feature to automatically generate documentation of environment variables during the Maven build process. Use the `@ProcessDocumentation` annotation to automatically generate Markdown documentation for all fields with this annotation. Simply add [dsf-tools-documentation-generator](https://mvnrepository.com/artifact/dev.dsf/dsf-tools-documentation-generator) as a maven plugin. There is an example `pom.xml` for the `tutorial-process` submodule located on [GitHub](https://github.com/datasharingframework/dsf-process-tutorial/blob/main/tutorial-process/pom.xml) which uses the maven plugin. The `` field has to point to the package where documentation is desired. \ No newline at end of file diff --git a/docs/src/process-development/api-v2/dsf/index.md b/docs/src/process-development/api-v2/dsf/index.md new file mode 100644 index 000000000..f70d7104e --- /dev/null +++ b/docs/src/process-development/api-v2/dsf/index.md @@ -0,0 +1,20 @@ +--- +title: DSF +icon: creative +--- + +## Details +- [BPMN Process Execution](bpmn-process-execution.md) +- [BPMN Process Variables](bpmn-process-variables.md) +- [Draft Task Resources](draft-task-resources.md) +- [Environment Variables](environment-variables.md) +- [Message Correlation](message-correlation.md) +- [Message Delegates](message-delegates.md) +- [Organization Identifiers](organization-identifiers.md) +- [Process Plugin API](process-plugin-api.md) +- [Process Plugin Definition](process-plugin-definition.md) +- [Read Access Tag](read-access-tag.md) +- [Requester and Recipient](requester-and-recipient.md) +- [Service Delegates](service-delegates.md) +- [Spring Framework Integration](spring-framework-integration.md) +- [Versions, Placeholders and URLs](versions-placeholders-urls.md) \ No newline at end of file diff --git a/docs/src/process-development/api-v2/dsf/message-correlation.md b/docs/src/process-development/api-v2/dsf/message-correlation.md new file mode 100644 index 000000000..7074e1028 --- /dev/null +++ b/docs/src/process-development/api-v2/dsf/message-correlation.md @@ -0,0 +1,10 @@ +--- +title: Message Correlation +icon: creative +--- + +## Message Correlation + +In order for messages to be able to be sent back and forth between organizations with potentially multiple of the same process plugin instances running at the same time and still arriving at the correct process instance, some mechanism is needed to map messages to their rightful process instance. This mechanism is called Message Correlation and requires attaching a unique identifier to every process instance. This identifier is called the `business-key`. The `business-key` will get attached to every outgoing message automatically. + +It is possible that the `business-key` is insufficient to map messages to the correct process instance. This happens during subprocesses in your BPMN model which all expect messages to be sent to them, not the parent process. To solve this issue, [Task](../fhir/task.md) resources also come with an [Input Parameter](../fhir/task.md#task-input-parameters) called `correlation-key`. This is a secondary identifier that has to be attached to all messages in order for them to arrive at a specific subprocess. This is done when creating [targets](../dsf/target-and-targets.md#targets) for outgoing messages and requires setting the `correlation-key` as a local variable using the constant `BpmnExecutionVariables.CORRELATION_KEY` before a message is received in the subprocess. \ No newline at end of file diff --git a/docs/src/process-development/api-v2/dsf/message-delegates.md b/docs/src/process-development/api-v2/dsf/message-delegates.md new file mode 100644 index 000000000..8ff0e27d6 --- /dev/null +++ b/docs/src/process-development/api-v2/dsf/message-delegates.md @@ -0,0 +1,18 @@ +--- +title: Message Delegates +icon: creative +--- + +## Message Delegates + +Message Delegates are the Java representation of the [Message Events](../bpmn/messaging.md) in a BPMN model. Message Delegates are linked to a certain [Message Event](../bpmn/messaging.md) by selecting the Message Event in the [Camunda Modeler](https://camunda.com/download/modeler/) and adding a Java class to the `Implementation` field. This uses the fully qualified class name. For example: +``` +org.package.MyClass +``` + +Message Delegates are only needed for [Message Send Events](../bpmn/messaging.md). Incoming messages will be resolved to the correct [BPMN process execution](bpmn-process-execution.md) automatically using [Message Correlation](message-correlation.md) and the message inputs will be added to that execution's [process variables](bpmn-process-variables.md). + +To make a Message Delegate for [Message Send Events](../../concepts/bpmn/messaging.md), the Java class needs to implement the interface `MessageSendTask`. Most of the time, there will not be any processing logic inside Message Delegates, therefore the `execute` method will not be overridden like with [Service Delegates](../../concepts/dsf/service-delegates.md). Although there might be cases where this is necessary. Instead, Message Delegates should be used to aggregate previously computed data and attach it to the message. This is done by overriding the `getAdditionalInputParamters` method. The DSF translates BPMN messages into FHIR [Task](../../concepts/fhir/task.md) resources to execute the communication modeled in BPMN diagrams. The information being sent to another BPMN process is specified in the Task.input elements a.k.a. [Input Parameters](../../concepts/fhir/task.md#task-input-parameters), hence the name of the method. + +## Related Topics +[Messaging](../bpmn/messaging.md), [Input Parameters](../../concepts/fhir/task.md#task-input-parameters), [Adding Input Parameter to Task Profiles](../guides/adding-task-input-parameters-to-task-profiles.md) \ No newline at end of file diff --git a/docs/src/process-development/api-v2/dsf/organization-identifiers.md b/docs/src/process-development/api-v2/dsf/organization-identifiers.md new file mode 100644 index 000000000..eadc32cc9 --- /dev/null +++ b/docs/src/process-development/api-v2/dsf/organization-identifiers.md @@ -0,0 +1,13 @@ +--- +title: Organization Identifiers +icon: creative +--- + +## Organization Identifiers +DSF FHIR server instances can configure an `organization identifier`. It uniquely identifies the organization the DSF FHIR server instance belongs to for its [Allow-List mechanism](https://dsf.dev/intro/info/allowList.html). It is set as an [environment variable](https://dsf.dev/stable/maintain/fhir/configuration.html#dev-dsf-fhir-server-organization-identifier-value). A GET request to `https://domain/fhir/Organization` will return a list of all organizations for the DSF FHIR server instance running under `domain`. The results will also include the `organization identifier` of each organization. + +### Organization Identifiers in Task Resources +[Task](../fhir/task.md) resources require a reference to an organization via its identifier as the `Task.requester` and `Task.restriction.recipient` elements. The exact values for these elements depend on the [ActivityDefinition](../fhir/activitydefinition.md) the [Task](../fhir/task.md) resource should conform to. As a general rule, the identifier of your own organization should be used as the `Task.requester` and `Task.restriction.recipient` elements for [Task](../fhir/task.md) resources which initially start processes. All other cases depend on the context of the message being sent during process execution. + +## Related Topics +[Allow-List](https://dsf.dev/intro/info/allowList.html), [ActivityDefinition](../fhir/activitydefinition.md), [Environment Variables](environment-variables.md), [Requester and Recipient](requester-and-recipient.md), [Task](../fhir/task.md) \ No newline at end of file diff --git a/docs/src/process-development/api-v2/dsf/process-plugin-api.md b/docs/src/process-development/api-v2/dsf/process-plugin-api.md new file mode 100644 index 000000000..fc7fc78f6 --- /dev/null +++ b/docs/src/process-development/api-v2/dsf/process-plugin-api.md @@ -0,0 +1,40 @@ +--- +title: Process Plugin API +icon: creative +--- + +## Process Plugin API Maven Module + +The [DSF Process Plugin API module](https://central.sonatype.com/artifact/dev.dsf/dsf-bpe-process-api-v2) consists of a set of utility classes designed to provide easy access to common solutions for process plugin use cases which would otherwise require lots of boilerplate code. An example is the `Variables` class, which provides access to the [BPMN process variables](bpmn-process-variables.md). + +Maven Dependency: + +```xml + + + dev.dsf + dsf-bpe-process-api-v2 + ${dsf.version} + provided + + +``` + +### Process Plugin Api +[Service Delegates](service-delegates.md) or [Message Delegates](message-delegates.md) expose a `ProcessPluginApi` instance when overriding their `execute` and `getAdditionalInputParameters` methods. This API instance the following utility classes: +- `FhirClientProvider`**:** Provides access to a generic, configurable FHIR web client. Used for connections to FHIR servers that are not the DSF FHIR server. +- `DsfClientProvider`**:** Provides access to preconfigured FHIR web client to access DSF FHIR server including utility methods. +- `TaskHelper`**:** Provides utility methods to interact with Task resource. Namely, Input and Output Parameters. +- `FhirContext`**:** Provides access to the FHIR context. +- `EndpointProvider`**:** Provides utility methods to interact with Endpoint resources. +- `MailService`**:** Provides methods to use the DSF's e-mail functionality. +- `ObjectMapper`**:** Provides access to an ObjectMapper instance to perform e.g. JSON-serialization. +- `OrganizationProvider`**:** Provides utility methods to interact with Organization resources. +- `OidcClientProvider`**:** Provides utility methods for OIDC functionality. +- `ProcessAuthorizationHelper`**:** Provides utility methods to interact with process authorization in [ActivityDefinitions](../fhir/activitydefinition.md). +- `ProxyConfig`**:** Allows you to retrieve information about the DSF proxy. +- `QuestionnaireResponseHelper`**:** Provides utility methods to interact with [QuestionnaireResponse](../fhir/questionnaire-and-questionnaireresponse.md) resources. +- `ReadAccessHelper`**:** Provides utility methods to modify a resource's [read access tag](read-access-tag.md). + +## Related Topics +[Service Delegates](service-delegates.md), [Message Delegates](message-delegates.md) \ No newline at end of file diff --git a/docs/src/process-development/api-v2/dsf/process-plugin-definition.md b/docs/src/process-development/api-v2/dsf/process-plugin-definition.md new file mode 100644 index 000000000..45fd48de1 --- /dev/null +++ b/docs/src/process-development/api-v2/dsf/process-plugin-definition.md @@ -0,0 +1,19 @@ +--- +title: Process Plugin Definition +icon: creative +--- + +## Process Plugin Definition + +In order for the DSF BPE server to load a plugin properly, it needs to provide the following information in what is called the process plugin definition: +* A plugin [version](versions-placeholders-urls.md#version-pattern) +* A release date +* A plugin name +* The BPMN model files +* The FHIR resources grouped by BPMN process ID. A plugin may have any number of BPMN models. Each has their own BPMN process ID and FHIR resources specific to that BPMN process (like [Task](../fhir/task.md) resources needed for messages specific to that BPMN model) +* The Class holding a [Spring Framework Configuration](spring-framework-integration.md) + +To provide this information, one of the classes in the process plugin has to implement the `dev.dsf.bpe.ProcessPluginDefinition` interface. The DSF BPE server then searches for classes implementing this interface using the Java [ServiceLoader](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/ServiceLoader.html) mechanism. Therefore, the class also needs to be registered in the `src/main/resources/META-INF/services/dev.dsf.bpe.ProcessPluginDefinition` file. An example of this can be found in the [process plugin tutorial](https://github.com/datasharingframework/dsf-process-tutorial/). + +## Related Topics +[Spring Integration](spring-framework-integration.md), [Versions, Placeholders and URLs](versions-placeholders-urls.md) \ No newline at end of file diff --git a/docs/src/process-development/api-v2/dsf/read-access-tag.md b/docs/src/process-development/api-v2/dsf/read-access-tag.md new file mode 100644 index 000000000..9bb03f8f8 --- /dev/null +++ b/docs/src/process-development/api-v2/dsf/read-access-tag.md @@ -0,0 +1,25 @@ +--- +title: Read Access Tag +icon: creative +--- + +## Read Access Tag + +Axiomatically, nobody is allowed to write FHIR resources (except [Task](../fhir/task.md)) to the DSF FHIR server unless it is the organization running the instance, which is [configurable](https://dsf.dev/operations/latest/fhir/configuration.html#dev-dsf-fhir-server-organization-identifier-value). By default, the same applies to reading FHIR resources (again except [Task](../fhir/task.md)). But since the DSF is often used to offer medical data in form of FHIR resources, other organizations should be allowed to read some of the resources on the DSF FHIR server. The `Resource.meta.tag` element is used define access rules for all FHIR resources in the DSF, with the exception of [Task](../fhir/task.md) resources. For example, allowing read access for all organizations would use the following `system` and `code` in your FHIR resource: + +```xml + + + + + + +``` +All codes for the Read Access Tag can be found in its [CodeSystem](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/CodeSystem/dsf-read-access-tag-1.0.0.xml). + +The read access rules for [Task](../fhir/task.md) resources are defined through the `requester` and `recipient` elements of the [dsf-extension-process-authorization](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-extension-process-authorization-1.0.0.xml) in a plugin's [ActivityDefinitions](../fhir/activitydefinition.md). Therefore, no `read-access-tag` is needed. + +It is also possible to restrict read access of FHIR resources to organizations with a specific role in a parent organization or a specific identifier. More information on that can be found in the [guide on configuring the Read Access Tag](../guides/configuring-read-access-tags.md). + +## Related Topics +[Configuring Read Access Tags](../guides/configuring-read-access-tags.md) \ No newline at end of file diff --git a/docs/src/process-development/api-v2/dsf/requester-and-recipient.md b/docs/src/process-development/api-v2/dsf/requester-and-recipient.md new file mode 100644 index 000000000..e633350cb --- /dev/null +++ b/docs/src/process-development/api-v2/dsf/requester-and-recipient.md @@ -0,0 +1,254 @@ +--- +title: Requester and Recipient +icon: creative +--- + +## Requester and Recipient Elements + +Below is a set of examples for each Coding used by `requester` and `recipient` elements from the [dsf-extension-process-authorization](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-extension-process-authorization-1.0.0.xml). CodeSystems referenced in the examples can be found [here](https://github.com/datasharingframework/dsf/tree/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/CodeSystem). This collection aims to provide a reference point when creating [ActivityDefinitions](../fhir/activitydefinition.md). + +### Requester +The `requester` element uses one of the following Codings: +```xml + + + + + + + + + +``` + +#### Local All +```xml + + + + + + +``` + +#### Local All Practitioner +```xml + + + + + + + + + + + + +``` + +#### Local Organization +```xml + + + + + + + + + + + + +``` + +#### Local Organization Practitioner +```xml + + + + + + + + + + + + + + + + + + + + +``` + +#### Local Parent Organization Role +```xml + + + + + + + + + + + + + + + + + + + + +``` + +#### Local Parent Organization Role Practitioner +```xml + + + + + + + + + + + + + + + + + + + + + + + + + + +``` + +#### Remote All +```xml + + + + + + +``` + +#### Remote Organization +```xml + + + + + + + + + + + + +``` + +#### Remote Parent Organization Role +```xml + + + + + + + + + + + + + + + + + + + + +``` + +### Recipient +The `recipeint` element uses one of the following Codings: +```xml + + + +``` + +#### Local All +```xml + + + + + + +``` + +#### Local Organization +```xml + + + + + + + + + + + + +``` + +#### Local Parent Organization Role +```xml + + + + + + + + + + + + + + + + + + + + +``` + + +## Related Topics +[ActivityDefinition](../fhir/activitydefinition.md) \ No newline at end of file diff --git a/docs/src/process-development/api-v2/dsf/service-delegates.md b/docs/src/process-development/api-v2/dsf/service-delegates.md new file mode 100644 index 000000000..a56fbf7bd --- /dev/null +++ b/docs/src/process-development/api-v2/dsf/service-delegates.md @@ -0,0 +1,15 @@ +--- +title: Service Delegates +icon: creative +--- + +## Service Delegates + +Service Delegates are the Java representation of the [Service Tasks](../bpmn/service-tasks.md) in a BPMN model. Service Delegates are linked to a certain [Service Task](../bpmn/service-tasks.md) by selecting the [Service Task](../bpmn/service-tasks.md) in the [Camunda Modeler](https://camunda.com/download/modeler/) and adding a Java class to the `Implementation` field. This uses the fully qualified class name: +``` +org.package.myClass +``` +Java classes need to implement the `ServiceTask` interface and override the `execute` method. This method holds the actual business logic. The method will be called when the [BPMN process execution](../dsf/bpmn-process-execution.md) arrives at the [Service Task](../bpmn/service-tasks.md) a Service Delegate is linked to. + +## Related Topics +[BPMN Process Execution](../dsf/bpmn-process-execution.md), [Message Delegates](message-delegates.md), [Service Tasks](../bpmn/service-tasks.md) \ No newline at end of file diff --git a/docs/src/process-development/api-v2/dsf/spring-framework-integration.md b/docs/src/process-development/api-v2/dsf/spring-framework-integration.md new file mode 100644 index 000000000..5c8967403 --- /dev/null +++ b/docs/src/process-development/api-v2/dsf/spring-framework-integration.md @@ -0,0 +1,24 @@ +--- +title: Spring Framework Integration +icon: creative +--- + +## Spring Framework Integration + +The DSF uses some of the [Spring Framework's](https://spring.io/projects/spring-framework) functionality. When deployed, every process plugin exists in its own [Spring context](https://docs.spring.io/spring-framework/reference/core/beans/introduction.html). Process plugins require [Spring Beans](https://docs.spring.io/spring-framework/reference/core/beans/definition.html) with `prototype` [scope](https://docs.spring.io/spring-framework/reference/core/beans/factory-scopes.html) for all classes which either extend or implement the following classes/interfaces: +- `Activity` +- `DefaultUserTaskListener` +- `ExecutionListener` +- `MessageActivity` +- `MessageEndEvent` +- `MessageIntermediateThrowEvent` +- `MessageSendTask` +- `ServiceTask` +- `UserTaskListener` + +Examples can be found in the guide on [registering prototype Beans](../../guides/registering-prototype-beans.md). + +A [Spring-Framework configuration class](https://docs.spring.io/spring-framework/docs/current/reference/html/core.html#beans-java-basic-concepts) located in the `spring/config` directory is expected to provide the Spring Beans. If you are unfamiliar with the Spring Framework, you can find more information in [Java-based Container Configuration](https://docs.spring.io/spring-framework/reference/core/beans/java.html) of the Spring Framework documentation, specifically the topics [Using the @Bean Annotation](https://docs.spring.io/spring-framework/reference/core/beans/java/bean-annotation.html) and [Using the @Configuration Annotation](https://docs.spring.io/spring-framework/reference/core/beans/java/configuration-annotation.html). + +## Related Topics +[Environment Variables](environment-variables.md), [Message Delegates](message-delegates.md), [Service Delegates](service-delegates.md) \ No newline at end of file diff --git a/docs/src/process-development/api-v2/dsf/target-and-targets.md b/docs/src/process-development/api-v2/dsf/target-and-targets.md new file mode 100644 index 000000000..8b8df62db --- /dev/null +++ b/docs/src/process-development/api-v2/dsf/target-and-targets.md @@ -0,0 +1,19 @@ +--- +title: Target and Targets +icon: creative +--- + +## Target + +A target is a container for all information necessary to send messages to other DSF instances. This information includes: +- **Organization Identifier:** Identifier of an [Organization Resource](https://www.hl7.org/fhir/R4/organization.html). Can be acquired through the API's `OrganizationProvider` or by querying a FHIR server (usually the DSF FHIR server) using a `FhirWebserviceClient` provided by the API's `FhirWebserviceProvider`. +- **Endpoint Identifier:** Identifier of an [Endpoint Resource](https://www.hl7.org/fhir/R4/endpoint.html) with the `managingOrganization` being the same organization as the one from the `Organization Identifier` above. Can be acquired through the API's `EndpointProvider` or by querying a FHIR server (usually the DSF FHIR server) using a `FhirWebserviceClient` provided by the API's `FhirWebserviceProvider`. +- **Endpoint URL:** The URL of the endpoint. The [Endpoint Resource](https://www.hl7.org/fhir/R4/endpoint.html) provides this value through its `address` field. +- **Correlation Key:** A value used to correlate messages, that are sent to this target, to their correct process instances. More information on this mechanism can be found in [Message Correlation](message-correlation.md). + +## Targets + +Targets is a container class for a collection of [Target](#target) objects. It also provides utility methods for manipulating the underlying collection. + +## Related Topics +[Message Correlation](message-correlation.md), [Setting Targets for Message Events](../guides/setting-targets-for-message-events.md) \ No newline at end of file diff --git a/docs/src/process-development/api-v2/dsf/versions-placeholders-urls.md b/docs/src/process-development/api-v2/dsf/versions-placeholders-urls.md new file mode 100644 index 000000000..e60407558 --- /dev/null +++ b/docs/src/process-development/api-v2/dsf/versions-placeholders-urls.md @@ -0,0 +1,41 @@ +--- +title: Versions, Placeholders and URLs +icon: creative +--- + +## Versions, Placeholders and URLs + +### Version Pattern + +Process plugin versions have to obey the pattern: +``` +\d+\.\d+\.\d+\.\d+ Example: 1.2.3.4 +``` + +The first two numbers (`1.2`) are used in FHIR resources and signal changes which break compatibility with previous process versions. For example, altering FHIR resources usually results in a breaking change. The latter two (`3.4`) signal changes which do not break compatibility with previous process versions. Specifically, the 4th number is reserved for bug-fixes and the 3rd number includes all other non-breaking changes. + +### Placeholders + +To avoid specifying the version and release date in multiple files, the placeholders `#{version}` and `#{date}` can be used within FHIR resources and BPMN models. They are replaced with the values returned by the methods `ProcessPluginDefinition#getResourceVersion` and `ProcessPluginDefinition#getReleaseDate` respectively during deployment of a process plugin by the DSF BPE server. There is also a placeholder for the organization the DSF instance is running in: `#{organization}`, typically use in [Draft Task Resources](draft-task-resources.md). + +### URLs + +BPMN models have an ID called process definition key. The BPMN process definition key needs to be specified following the pattern: +``` +^[-a-zA-Z0-9]+_[-a-zA-Z0-9]+$ Example: domainorg_processKey +``` +In addition, the BPMN model needs to specify a version. The `#{version}` [placeholder](#placeholders) should be used for this as well. The DSF will also reference this process in URL form in FHIR resources: +``` +http://domain.org/bpe/Process/processKey|1.2 +``` + +The version in the URL `|1.2` only uses the resource version and omits the code base version. As mentioned in [Version Pattern](#version-pattern), this means that only changes to the first two version numbers are significant to signal compatibility when communicating with other process plugin instances. The process definition key and URL are also related to each other. The DSF will try to match BPMN models to FHIR resources by transforming the URL into a process definition key. That is why it is mandatory to follow the pattern above. + +The above URL will be used as the instantiatesCanonical value for [Task](../fhir/task.md) profile definitions as well as references to [Task](../fhir/task.md) profiles in other resources. It is also used as the URL value for [ActivityDefinitions](../fhir/activitydefinition.md). In this case though, the URL has to be split into two parts. The version (`|1.2`) needs to be separated from the URL and used as a value for the `ActivityDefinition.version` element. Since it refers to the plugin's resource version, the `#{version}` [placeholder](#placeholders) should be used here instead. Going by the example from above, the final URL looks like this: +``` +http://domain.org/bpe/Process/processKey +``` +This will be the value for the `ActivityDefinition.url` element with `#{version}` as the value for the `ActivityDefinition.version` element. + +## Related Topics +[ActivityDefinition](../fhir/activitydefinition.md), [Process Plugin Definition](process-plugin-definition.md) \ No newline at end of file diff --git a/docs/src/process-development/api-v2/fhir/activitydefinition.md b/docs/src/process-development/api-v2/fhir/activitydefinition.md new file mode 100644 index 000000000..0882e648d --- /dev/null +++ b/docs/src/process-development/api-v2/fhir/activitydefinition.md @@ -0,0 +1,26 @@ +--- +title: ActivityDefinition +icon: creative +--- + +## ActivityDefinition + +[ActivityDefinitions](http://hl7.org/fhir/R4/activitydefinition.html) are used by the DSF to advertise which processes are available at any given instance and who is allowed to request and who is allowed to execute a process. The DSF defined elements for this purpose in the [dsf-activity-definition](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-activity-definition-1.0.0.xml) profile. + + +The most important elements in ActivityDefinitions are: +- `message-name` +- `task-profile` +- `requester` +- `recipient` + +The `message-name` element contains the name of the [BPMN message start event](../bpmn/messaging.md#message-start-event) or [BPMN message intermediate catching event](../bpmn/messaging.md#message-intermediate-catching-event) which expects a [Task](task.md) resource complying to the profile defined by `task-profile`. + +The `requester` and `recipient` elements define the organisation(s) or person(s) who are allowed to request or receive the message specified by `message-name`. The receiving DSF instance is the one who will execute the process connected to the message. + +Creating [ActivityDefinitions](activitydefinition.md) is part of developing a process plugin. Readers fluent in understanding XML FHIR definitions and translating them into resources may take a look at the DSF's profile for ActivityDefinitions [here](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-activity-definition-1.0.0.xml). ActivityDefinitions also reference other resource definitions. Depending on the resource they are located in one of [these folders](https://github.com/datasharingframework/dsf/tree/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir). FHIR beginners can read the guide on [creating ActivityDefinitions](../guides/creating-activity-definitions.md). + +There is also a list of examples for all possible `requester` and `recipient` elements located [here](../dsf/requester-and-recipient.md). + +## Related Topics +[Requester and Recipient](../dsf/requester-and-recipient.md), [Read Access Tag](../dsf/read-access-tag.md), [Task](task.md) \ No newline at end of file diff --git a/docs/src/process-development/api-v2/fhir/codesystem.md b/docs/src/process-development/api-v2/fhir/codesystem.md new file mode 100644 index 000000000..c370209ba --- /dev/null +++ b/docs/src/process-development/api-v2/fhir/codesystem.md @@ -0,0 +1,15 @@ +--- +title: CodeSystem +icon: creative +--- + +## CodeSystem + +[CodeSystems](https://www.hl7.org/fhir/R4/codesystem.html) usually represent a set of concepts which can be assigned to a code (think LOINC). Using a Code in a resource requires them to be included in a [ValueSet](valueset.md). + +Plugin development for the DSF requires the use of [CodeSystems](https://www.hl7.org/fhir/R4/codesystem.html) in two major ways: +1. Using existing [DSF CodeSystems](https://github.com/datasharingframework/dsf/tree/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/CodeSystem) in other FHIR resources like the [dsf-extension-process-authorization](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-extension-process-authorization-1.0.0.xml). +2. Creating custom CodeSystem to add additional [Input Parameters](task.md#task-input-parameters) to [Task](task.md) profiles. + +## Related Topics +[ActivityDefinition](activitydefinition.md), [Task](task.md), [ValueSet](valueset.md) \ No newline at end of file diff --git a/docs/src/process-development/api-v2/fhir/index.md b/docs/src/process-development/api-v2/fhir/index.md new file mode 100644 index 000000000..f09084455 --- /dev/null +++ b/docs/src/process-development/api-v2/fhir/index.md @@ -0,0 +1,14 @@ +--- +title: FHIR +icon: creative +--- + +## Introduction +The DSF uses a variety of [FHIR resources](https://dsf.dev/intro/info/basics.html#why-are-we-using-fhir-and-bpmn). The DSF uses XML as the format for FHIR resources. The most important resources for plugin development are [ActivityDefinitions](activitydefinition.md), [CodeSystems](codesystem.md), [Tasks](task.md) and [ValueSets](valueset.md). There is also a catalog of DSF-specific FHIR resources including CodeSystems, ValueSets and Extensions. They can be found in the official [DSF GitHub repository](https://github.com/datasharingframework/dsf/tree/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir). + +## Details +- [ActivityDefinition](activitydefinition.md) +- [CodeSystem](codesystem.md) +- [Questionnaire and QuestionnaireResponse](questionnaire-and-questionnaireresponse.md) +- [Task](task.md) +- [ValueSet](valueset.md) \ No newline at end of file diff --git a/docs/src/process-development/api-v2/fhir/questionnaire-and-questionnaireresponse.md b/docs/src/process-development/api-v2/fhir/questionnaire-and-questionnaireresponse.md new file mode 100644 index 000000000..8dfdc4944 --- /dev/null +++ b/docs/src/process-development/api-v2/fhir/questionnaire-and-questionnaireresponse.md @@ -0,0 +1,11 @@ +--- +title: Questionnaire and QuestionnaireResponse +icon: creative +--- + +## Questionnaire and QuestionnaireResponse + +[Questionnaire](https://www.hl7.org/fhir/R4/questionnaire.html) and [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html) resources are used by the DSF to implement the user interaction required in [User Tasks](../bpmn/user-tasks.md). Whenever a [User Task](../bpmn/user-tasks.md) is processed, the DSF will create a [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html) response resource on the DSF FHIR server. This [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html) is based on a [Questionnaire](https://www.hl7.org/fhir/R4/questionnaire.html) resource that is provided by the process plugin. This mechanism is described in more detail in the topic on [User Tasks in the DSF](../guides/user-tasks-in-the-dsf.md). + +## Related Topics +[User Tasks](../bpmn/user-tasks.md), [User Tasks in the DSF](../guides/user-tasks-in-the-dsf.md) \ No newline at end of file diff --git a/docs/src/process-development/api-v2/fhir/task.md b/docs/src/process-development/api-v2/fhir/task.md new file mode 100644 index 000000000..0d4cd5d6d --- /dev/null +++ b/docs/src/process-development/api-v2/fhir/task.md @@ -0,0 +1,20 @@ +--- +title: Task +icon: creative +--- + +## Task + +The [FHIR Task](https://www.hl7.org/fhir/R4/task.html) resource enables the DSF's distributed communication. Whenever a BPMN process instance communicates with a different process instance, the DSF will create a Task resource based on parameters set in the BPMN model and during execution. It will then automatically send the Task resource to the recipient to start or continue whatever process the Task resource referred to. All Task resources used in the DSF derive from the [dsf-task-base](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-task-base-1.0.0.xml). This profile includes a splicing for `Task.input` with three additional [Input Parameters](task.md#task-input-parameters): +- `message-name` +- `business-key` +- `correlation-key` + +When creating a process plugin, it is usually necessary to create new profiles based on the [dsf-task-base](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-task-base-1.0.0.xml) and put them into `src/resources/fhir/StructureDefinition`. + +### Task Input Parameters + +Task Input Parameters allow adding additional information to [Task](task.md#task) resources. For example, if a particular data exchange requires additional medical data, one would add a slice to the Task profile in the same way the [dsf-task-base](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-task-base-1.0.0.xml) adds slices to the original [FHIR Task](https://www.hl7.org/fhir/R4/task.html) resource. It is import to know that this also requires creating a [CodeSystem](codesystem.md) and including it in a [ValueSet](valueset.md) to be able to use it in the Task resource. + +## Related Topics +[ActivityDefinition](activitydefinition.md), [Adding Task Input Parameter to Task Profiles](../guides/adding-task-input-parameters-to-task-profiles.md) \ No newline at end of file diff --git a/docs/src/process-development/api-v2/fhir/valueset.md b/docs/src/process-development/api-v2/fhir/valueset.md new file mode 100644 index 000000000..001ab3e4b --- /dev/null +++ b/docs/src/process-development/api-v2/fhir/valueset.md @@ -0,0 +1,13 @@ +--- +title: ValueSet +icon: creative +--- + +## ValueSet + +[ValueSets](https://www.hl7.org/fhir/R4/valueset.html) bind codes from [CodeSystems](codesystem.md) to coded elements like `code`, `Coding` or `CodeableConcept`. + +[ValueSets](https://www.hl7.org/fhir/R4/valueset.html) are mostly needed to use the [Concepts](https://www.hl7.org/fhir/R4/codesystem-definitions.html#CodeSystem.concept) from [CodeSystems](codesystem.md) in [Task](task.md) profiles. + +## Related Topics +[CodeSystem](codesystem.md), [Task](task.md) \ No newline at end of file diff --git a/docs/src/process-development/api-v2/guides/accessing-bpmn-process-variables.md b/docs/src/process-development/api-v2/guides/accessing-bpmn-process-variables.md new file mode 100644 index 000000000..420700c86 --- /dev/null +++ b/docs/src/process-development/api-v2/guides/accessing-bpmn-process-variables.md @@ -0,0 +1,12 @@ +--- +title: Accessing BPMN Process Variables +icon: creative +--- + +## Accessing BPMN Process Variables + +Access to retrieve data from or store data in the [BPMN process variables](../dsf/bpmn-process-variables.md) can be acquired via the `Variables` class. An instance is usually available when overriding methods in [Service Delegates](../dsf/service-delegates.md) and [Message Delegates](../dsf/message-delegates.md). If an instance is missing in a place where it should be accessible, please [let us know](https://dsf.dev/community/contribute/). + +The `Variables` class provides lots of utility methods to read or write certain types +of [BPMN process variables](../concepts/dsf/bpmn-process-variables.md). If for some reason you find the methods provided by the `Variables` class insufficient to solve your problem, we would like to learn how the current API of the `Variables` class is limiting you. Again, please [let us know](https://dsf.dev/community/contribute/). + diff --git a/docs/src/process-development/api-v2/guides/accessing-task-resources-during-execution.md b/docs/src/process-development/api-v2/guides/accessing-task-resources-during-execution.md new file mode 100644 index 000000000..1c7edce32 --- /dev/null +++ b/docs/src/process-development/api-v2/guides/accessing-task-resources-during-execution.md @@ -0,0 +1,12 @@ +--- +title: Accessing Task Resources During Execution +icon: creative +--- + +## Accessing Task Resources During Execution + +Access to the [Task](../fhir/task.md) resources in [Service](../dsf/service-delegates.md) / [Message](../dsf/message-delegates.md) Delegates is provided by the `Variables` class. It comes with methods which return certain kinds of [Task](../fhir/task.md) resources. The most commonly used ones are the start [Task](../fhir/task.md), referring to the [Task](../fhir/task.md) / [Message Start Event](../bpmn/messaging.md#message-start-event) responsible for starting the process, and the latest [Task](../fhir/task.md), referring to most recently received [Task](../fhir/task.md) / Message. +In principle, this is sufficient to access all information in a [Task](../fhir/task.md) resource, since there is access to the full in-memory representation of the [Task](../fhir/task.md) resource. This however can be very cumbersome to use and produces a lot of boilerplate when traversing the resource tree to access certain common elements. +Instead of navigating the [Task](../fhir/task.md) resource's element tree, it is recommended to use the [ProcessPluginApi's](../dsf/process-plugin-api.md) `TaskHelper` in conjunction with the method above. The `TaskHelper` class offers specific methods related to [Task](../fhir/task.md) resources. +The most common use case for this is retrieving data from a [Task's](../fhir/task.md) [Input Parameter](../fhir/task.md#task-input-parameters) or creating a new [Input Parameter](../fhir/task.md#task-input-parameters) for a [Message Delegate's](../dsf/message-delegates.md) `getAdditionalInputParameters` method. When retrieving data from a [Task's](../fhir/task.md) Input Parameter one first has to get to the [Input Parameter](../fhir/task.md#task-input-parameters) one is looking to extract data from. The `TaskHelper's` getters for [Input Parameters](../fhir/task.md#task-input-parameters) are useful to find the right one. The methods will try to match the provided [CodeSystem](../fhir/codesystem.md) and Code to any [Input Parameter](../fhir/task.md#task-input-parameters) of the provided [Task](../fhir/task.md) resource. Depending on the method it is possible to receive all matches or just the first one. +To create new [Input Parameters](../fhir/task.md#task-input-parameters) to attach to a [Task](../fhir/task.md) resource, one may invoke the `TaskHelper#createInput` method. This is most often used when overriding the `getAdditionalInputParameters` method of a [Message Delegate](../dsf/message-delegates.md). \ No newline at end of file diff --git a/docs/src/process-development/api-v2/guides/adding-task-input-parameters-to-task-profiles.md b/docs/src/process-development/api-v2/guides/adding-task-input-parameters-to-task-profiles.md new file mode 100644 index 000000000..198aded02 --- /dev/null +++ b/docs/src/process-development/api-v2/guides/adding-task-input-parameters-to-task-profiles.md @@ -0,0 +1,213 @@ +--- +title: Adding Task Input Parameters to Task Profiles +icon: creative +--- + +## Adding Task Input Parameters to Task Profiles + +When adding a new [Input Parameter](../fhir/task.md#task-input-parameters) to a [Task](../fhir/task.md) profile, a new slice is added to `Task.input`. [Slicing](https://www.hl7.org/fhir/R4/profiling.html#slicing) is part of [profiling](https://www.hl7.org/fhir/R4/profiling.html) in FHIR. Profiling lets you create your own FHIR definitions based on pre-existing FHIR definitions. A slicing defines constraints on element lists like `Task.input` e.g. by only allowing the elements to be of certain types. +For example, there might be a list of fruits in a `FruitBasket` resource. Constraining that list to only include fruits of type `Apple`, `Banana` and `Orange` would be considered [slicing](https://www.hl7.org/fhir/R4/profiling.html#slicing). +This guide will not cover how slicing works in general, only for the case presented by the DSF FHIR resource context. The goal will be to add a new [Input Parameter](../fhir/task.md#task-input-parameters) of type `example-input` to the `task-start-dic-process.xml` profile which will be used to submit `integer` values to a process called `dicProcess`. + +As a first step, a slice to `task-start-dic-process.xml` is added. Since there is already a slicing defined on `Task.input` by `task-start-dic-process.xml`'s `baseDefinition`, this resource has to be looked at first. As a part of the [differential](https://www.hl7.org/fhir/R4/profiling.html#snapshot) statement, slicing also uses [Element Definitions](https://www.hl7.org/fhir/R4/elementdefinition.html). +The slicing for `Task.input` is defined in this part of the `baseDefinition`: +```xml + + + + + + + + + + + + + + + + + + +``` +*The resource can be found [here](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-task-base-1.0.0.xml)* + +First look at the `discriminator` tag. Discriminators define the elements a FHIR processor needs to distinguish slices by. In this case, a processor would look at the values for `type.coding.system` and `type.coding.code` to determine which slice this element belongs to. The discriminator type `value` implies that `type.coding.system` and `type.coding.code` have to be present in all slices and need to have a fixed value. There is more information about discriminators in the [official FHIR documentation](https://www.hl7.org/fhir/R4/profiling.html#discriminator). + +Now revisit `task-start-dic-process.xml` and start adding a slice called `example-input` to it: +```xml + + ... + + ... + + + + + + + + +``` +*Irrelevant elements for this guide are hidden by ... placeholders.* + +There is now a slice defined on `Task.input` with the name and id of `example-input` and cardinality of `1..1`. The name and cardinality depend on the use case. It is recommended to also take a look at the documentation for [ElementDefinition.id](https://www.hl7.org/fhir/R4/elementdefinition.html#id) and [ElementDefinition.path](https://www.hl7.org/fhir/R4/elementdefinition.html#path). They explain how to create the proper values for these elements. Cardinality is also part of the [element definition](https://www.hl7.org/fhir/R4/elementdefinition.html) hierarchy (see [ElementDefinition.min](https://www.hl7.org/fhir/R4/elementdefinition-definitions.html#ElementDefinition.min) and [ElementDefinition.max](https://www.hl7.org/fhir/R4/elementdefinition-definitions.html#ElementDefinition.max)). + +Next up is the binding for `Task.input:example-input.type`. Because `Task.input.type` is a `CodeableConcept` which uses codings from a [ValueSet](../fhir/valueset.md), the [discriminator](https://www.hl7.org/fhir/R4/profiling.html#discriminator) requires the use of `required` as the binding strength: +```xml + + ... + + ... + + + + + + + + + + + + + + + +``` +The binding now references a [ValueSet](../fhir/valueset.md). Moving beyond this example will require referencing an existing [ValueSet](../fhir/valueset.md) resource or create a new one. A guide on how to create them can be found [here](../guides/creating-valuesets-for-dsf-processes.md). + +Since the [discriminator](https://www.hl7.org/fhir/R4/profiling.html#discriminator) requires `Task.input.coding.code` and `Task.input.coding.system` to be present, `Task.input.coding` will be marked as mandatory as well: +```xml + + ... + + ... + + + + + + + + + + + + + + + + + + + +``` + +The beginning mentioned how `Task.input.type.coding.system` and `Task.input.type.coding.code` have to use fixed values. Here is how this is accomplished: + +```xml + + ... + + ... + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +``` +*Notice the two new elements were marked as mandatory because they are required by the discriminator.* + +The `type.coding.system` element references a [CodeSystem](../fhir/codesystem.md). The `type.coding.code` element uses a code from this [CodeSystem](../fhir/codesystem.md) called `example-input`. This is the mechanism by which [Input Parameter](../fhir/task.md#task-input-parameters) are "named". The `type.coding.code` value will identify the [Input Parameter](../fhir/task.md#task-input-parameters) when it is used in an actual [Task](../fhir/task.md#task-input-parameters) resource. Here is how this would look like: + +```xml + + ... + + + + + + + + ... + + +``` + +Adding a slice in a different use case will also require to reference an existing [CodeSystem](../fhir/codesystem.md) resource or create a new one to reference. A guide on how to create them can be found [here](../guides/creating-codesystems-for-dsf-processes.md). + +`Task.input.value[x]` is the actual value submitted when using the Input Parameter. They may be any of [these](https://www.hl7.org/fhir/R4/datatypes.html#open) data types. This is because `Type.input.value[x]` refers to `*` instead of any particular type in its [definition](https://www.hl7.org/fhir/R4/task-definitions.html#Task.input.value_x_). In this case, let it be an `integer` type`: + +```xml + + ... + + ... + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +``` + +There is now a new Input Parameter of type `example-input` which accepts any `integer` as its value. + +## Related Topics +[Creating CodeSystems for DSF processes](creating-codesystems-for-dsf-processes.md), [Creating ValueSets for DSF processes](creating-valuesets-for-dsf-processes.md), [Task](../fhir/task.md) \ No newline at end of file diff --git a/docs/src/process-development/api-v2/guides/configuring-read-access-tags.md b/docs/src/process-development/api-v2/guides/configuring-read-access-tags.md new file mode 100644 index 000000000..fa4ca30dc --- /dev/null +++ b/docs/src/process-development/api-v2/guides/configuring-read-access-tags.md @@ -0,0 +1,416 @@ +--- +title: Configuring Read Access Tags +icon: creative +--- + +## Configuring Read Access Tags + +Before starting to configure anything, it is advised to take a look at the [CodeSystem](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/CodeSystem/dsf-read-access-tag-1.0.0.xml) defined for the [Read Access Tag](../dsf/read-access-tag.md) and choose one of the codes from it: +```xml + + ... + + ... + + + + + + + + + + + + + + + + + + + + + +``` + +The codes `LOCAL` and `ALL` are trivial. Their [Read Access Tag](../dsf/read-access-tag.md) would look like this: +```xml + + + + + + +``` + +Now to configure a Read Access Tag whose code uses an extension. This example will use the code `ROLE`. It starts out the same way as before: +```xml + + + + + + +``` + +The `definition` element of the `ROLE` code references an extension called [dsf-extension-read-access-parent-organization-role](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-extension-read-access-parent-organization-role-1.0.0.xml). + +The most important part of it is the `differential` statement. It uses [element definitions](https://www.hl7.org/fhir/R4/elementdefinition.html) to describe how the extensions needs to be implemented: +```xml + + ... + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +``` + +All extensions for the [Read Access Tag](../dsf/read-access-tag.md) CodeSystem are defined on the `meta.tag.extension` element through the extension's `context` element: +```xml + + + + +``` + +That is why the first element to be added to `meta.tag` is an `extension` element: +```xml + + + + + + + + + +``` + +Now to process the `differential` statement one element at a time, starting at the top: +```xml + + ... + + + + + + + + + + + + ... + + +``` + +It defines a [slicing](https://www.hl7.org/fhir/R4/profiling.html#slicing) for the `Extension.extension` element, meaning this is a nested extension. The `discriminator` element defines that slices will be identified by the value of their `url` attribute. A `rules` element with value `open` means other types of slices may be added later on e.g. when creating a profile. This element is not added to the `meta.tag.extension` element it only serves the purpose of defining the `discriminator`. Next up is the first slice called `parentOrganization`: + +```xml + + ... + + ... + + + + + + + + + + + + + + + + + + + + + + + + + + + ... + + +``` + +The first element defines a slice called `parentOrganization` on the `Extension.extension` element with cardinality `1..1`. The second element defines the url attribute of the `parentOrganization` slice to be fixed to the value `parent-organization`. With this information the next element can be added to `meta.tag`. Since it is defined on `Extension.extension` it will be added it to `meta.tag.extension.extension` like this: +```xml + + + + + + + + + + + +``` + +After that, it defines `parentOrganization.value[x]` to occur at least once and have a type of `Identifier`. To turn this into an element to add to `meta.tag.extension.extension` requires replacing `[x]` with the code in `value[x].type`, which in this case is `Identifier`. It is important to note, that `value[x]` should be camel cased after replacement. This means there will be a `meta.tag.extension.extension.valueIdentifier` element: +```xml + + + + + + + + + + + + + +``` + +The last two elements define a `system` element with a fixed value and `value` element that can be freely set, since it does not have any constraints applied. Notice that the element definition still uses `value[x].system` and `value[x].value`. The replacement mentioned earlier does not happen in the element definition, but since `value[x]` is defined to have the type `Identifier`, it is inferred that `Identifier.system` and `Identifier.value` are referenced. The example will use an arbitrary `Identifier` value, but real application should be using an actual organization identifier depending on which organization has read access to the resource. + +```xml + + + + + + + + + + + + + + +``` + +Next is the slice is called `organizationRole`: +```xml + + ... + + ... + + + + + + + + + + + + + + + + + + + + + + + + + + ... + + +``` + +Like with `parentOrganization`, an extension element to `meta.tag.extension` is added with the fixed url value defined above: +```xml + + + + + + + + + + + + + + + + + +``` + +Instead of `Identifier`, the `value[x]` element is now defined as a `Coding` type. This the next element to add will be `valueCoding`: +```xml + + + + + + + + + + + + + + + + + + + +``` + +A `Coding` has to belong to some [CodeSystem](../fhir/codesystem.md). The DSF has a CodeSystem called [dsf-organization-role](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/CodeSystem/dsf-organization-role-1.0.0.xml). Before creating new CodeSystems, it is worth taking a look at it to see if an appropriate role already exists for an organization. The example will be using the `DIC` role: +```xml + + + + + + + + + + + + + + + + + + + + +``` + +Now there is only two elements left in the `differential` statement: + +```xml + + ... + + ... + + + + + + + + + + +``` + +The `Extension.url` element requires a url attribute to be added to `meta.tag.extension`. The last element defines that there must not be a `meta.tag.extension.value[x]` element. This results in this final Read Access Tag: + +```xml + + + + + + + + + + + + + + + + + + + + +``` + +## Related Topics +[Read Access Tag](../dsf/read-access-tag.md) \ No newline at end of file diff --git a/docs/src/process-development/api-v2/guides/creating-activity-definitions.md b/docs/src/process-development/api-v2/guides/creating-activity-definitions.md new file mode 100644 index 000000000..87f48457c --- /dev/null +++ b/docs/src/process-development/api-v2/guides/creating-activity-definitions.md @@ -0,0 +1,753 @@ +--- +title: Creating ActivityDefinitions +icon: creative +--- + +## Creating ActivityDefinitions + +This guide will explain how to create an ActivityDefinition based on the [dsf-activity-definition](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-activity-definition-1.0.0.xml) profile for a process plugin. +It is divided into steps for each of the main components of ActivityDefinitions: +1. Read Access Tag +2. Extension: process authorization +3. BPE Managed Elements +4. Regular Elements + +*Regular elements* are all elements not part of the first 3 main components. + +*This guide assumes the reader knows how to translate [ElementDefinitions](https://www.hl7.org/fhir/R4/elementdefinition.html) to actual elements in a FHIR resource. If not, the guide on [creating Task resources](../guides/creating-task-resources-based-on-a-definition.md) includes explanations for this.* + +### 1. Read Access Tag +Start out with an empty [ActivityDefinition](../fhir/activitydefinition.md): +```xml + + + +``` + +The first element in DSF FHIR resources is always the [Read Access Tag](../dsf/read-access-tag.md). It describes who is allowed to read this resource through the DSF FHIR server's REST API. More complex configurations of the [Read Access Tag](../dsf/read-access-tag.md) are explained in [this guide](../dsf/read-access-tag.md). For this example, everyone will be allowed to read the resource: + +```xml + + + + + + + + +``` + +### 2. Extension: Process Authorization +This part of the ActivityDefinition will tell the DSF who is allowed to request and receive messages ([Task](../fhir/task.md) resources) for BPMN process. If the plugin contains more than one BPMN process, there will have to be one [ActivityDefinition](../fhir/activitydefinition.md) for each BPMN process. It is important to note that authorization rules need to be included for **ALL** messages received in the BPMN process. This includes the messages starting the BPMN process initially. The extension containing all possible rules is found [here](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-extension-process-authorization-1.0.0.xml). Next up is adding the [extension element](http://hl7.org/fhir/R4/extensibility.html#extension) with the correct URL. The value for the URL is found in the `Extension.url` element: +```xml + + ... + + + + +``` +*Elements not relevant to the current component are hidden with `...` to increase readability.* + +The [differential](https://www.hl7.org/fhir/R4/profiling.html#snapshot) statement starts by defining the [slicing](https://www.hl7.org/fhir/R4/profiling.html#snapshot) for the `Extension.extension` element: + +```xml + + ... + + + + + + + + + + + + + + + + ... + + +``` + +The above states that whenever this extension is used in a profile, the profile needs to include this extension at least once (``). The [slicing](https://www.hl7.org/fhir/R4/profiling.html#snapshot) on `Extension.extension` defines that elements of this [slicing](https://www.hl7.org/fhir/R4/profiling.html#snapshot) are identified by the value of their URL (``), which is always the case for extensions, and that other extensions can be added to the [slicing](https://www.hl7.org/fhir/R4/profiling.html#snapshot) (``). Since there is a [slicing](https://www.hl7.org/fhir/R4/profiling.html#snapshot) on `Extension.extension`, this is a nested extension. + +After these initial element definitions come the elements relevant for the process plugin. The first one is the `message-name` slice: +```xml + + ... + + ... + + + + + + + + + + + + + + + + + + ... + + +``` + +This section defines that there has to be exactly one extension element from the `message-name` slice in the [ActivityDefinition](../fhir/activitydefinition.md). The extension element will have a URL value of `message-name`. This URL value identifies the element to belong to the `message-name` slice on `Extension.extension`, in accordance with the `discriminator`. Lastly, the extension element includes a `valueString` element. FHIR does not allow using `value[x]` as actual element. The value in `value[x]` is always strictly bound to some kind of type. FHIR uses the `value[x].type.code` value to determine this type and replaces `[x]` with an uppercase version of `element.type.code`. This results in the following extension element: +```xml + + + +``` + +`myMessage` will have to be replaced with the name of the [BPMN message event](../bpmn/messaging.md) in a BPMN process that is expecting this message. + +
+This is how the ActivityDefinition should look like so far + +```xml + + + + + + + + + + + + + +``` +
+ +The next slice is called `task-profile`: +```xml + + ... + + ... + + + + + + + + + + + + + + + + + + ... + + +``` + +This section has almost the same structure as `message-name`. The only difference is the value for `value[x].type.code`. This means that instead of `valueString`, it requires using a `valueCanonical` element for `task-profile.value[x]`. Canonical values referring to [Task](../fhir/task.md) profiles in ActivityDefinitions have to conform to the rules outlined by the documentation on [URLs](../dsf/versions-placeholders-urls.md#urls). From the definition above, the following extension element is created and added to the [ActivityDefinition](../fhir/activitydefinition.md): +```xml + + + +``` + +
+This is how the ActivityDefinition should look like so far + +```xml + + + + + + + + + + + + + + + + +``` +
+ +The next slice is `requester`: +```xml + + ... + + ... + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ... + + +``` +Instead of a `string` or `canonical` type for `value[x]` there now is a `Coding` type. See the [FHIR documentation on Codings](https://www.hl7.org/fhir/R4/datatypes.html#Coding) for more in-depth information. `Codings` are elements which contain, among other things, a `code` and the `system` the code belongs to. In the same way `value[x]` transformed into `valueString` or `valueCanonical` before, `value[x]` will be transformed into `valueCoding`. To use `Codings` in `valueCoding` elements, they are usually bound to the element through a [ValueSet](../fhir/valueset.md). This is the responsibility of the `binding` element. There is also a list of `value[x].type.profile` elements referencing other [StructureDefinitions](https://www.hl7.org/fhir/R4/structuredefinition.html). Instead of defining the elements in the same file, they were defined in different files for better readability. The use case decides which one to pick. +Here is what they mean: +- `local-all`: All local requests will be allowed. Local requests are identified by matching the requester's certificate to a thumbprint which was internally marked by the DSF FHIR server as belonging to a local organization. +- `local-organization`: All local requests made from an organization with a specific `organization-identifier` will be allowed. +- `local-parent-organization-role`: All local requests made from an organization having a specific role inside a specific parent organization will be allowed. +- `remote` versions of the above rules work the same but the requester's certificate is instead required to match a thumbprint marked as a remote organization. +- `practitioner` suffixes all work the same. They include the same rules as their prefixes but now additionally require the requester to match a certain `practitioner-role`. A list of them + can be found [here](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/CodeSystem/dsf-practitioner-role-1.0.0.xml). This allows + for more granularity when defining authorization rules within an organization and can be integrated into local user management via [OpenID Connect](https://dsf.dev/stable/maintain/fhir/access-control.html). + +There are no `practitioner` versions of `remote` authorization rules. From the perspective of the receiving DSF instance, remote requests are always issued by an organization. They do not hold any information about the local user management of the requesting organization. Examples of all Codings from above can be found [here](../dsf/requester-and-recipient.md). + +It is also good to keep in mind that any number of `requester` elements may be added to an [ActivityDefinition](../fhir/activitydefinition.md). Start out by adding a `requester` element like previous extensions: + +```xml + + + + + +``` + +The remaining element definitions are found in one of the profiles. This example will use the [dsf-coding-process-authorization-local-organization-practitioner](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-coding-process-authorization-local-organization-practitioner-1.0.0.xml) profile. Since all elements listed in the [Coding definition](https://www.hl7.org/fhir/R4/datatypes.html#codesystem) are optional, only the `differential` elements from the profile are relevant: + +```xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +``` +It defines an extension called `organization-practitioner` which is identified through its url attribute. Again, the extension is only referenced, its location is in a [different file](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-extension-process-authorization-organization-practitioner-1.0.0.xml). Below is its `differential` element in order to see how the extension needs to be populated: +```xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +``` + +This extension does not reference any other files. This means this is the "deepest" level. The process can now proceed by translating this definition into actual extension elements, inserting it into the selected Coding, translating the remaining element definitions from the Coding resource, and incorporating all components into the [ActivityDefinition](../fhir/activitydefinition.md). + +Start with the `Extension.url` element, since the `Extension` element is the parent element for all slices on the `Extension.extension` elements: +```xml + + + +``` + +Next, add the `organization` slice: +```xml + + + + + + + + +``` +Finally, add the `practitionerRole` slice: + +```xml + + + + + + + + + + + + + + +``` + +There is no `binding` element specified for `practitionerRole.value[x]`. This is intentional. The example used a code from the [dsf-practitioner-role](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/CodeSystem/dsf-practitioner-role-1.0.0.xml) CodeSystem. This CodeSystem includes a standard set of codes which are often sufficient for DSF use cases. Other/new CodeSystems if may be added if these codes do not apply for a given use case. The code set here can be used in the [DSF role config](https://dsf.dev/stable/maintain/fhir/access-control.html) to allow certain users with this `practitioner-role` to send requests. + +Now add the extension as the `Coding.extension:organization-practitioner` element: +```xml + + + + + + + + + + + + + + + + + + +``` +Look at the [differential](#coding-differential) from the Coding again. The next elements to be added are `Coding.system` and `Coding.code`: +```xml + + + + + + + + + + + + + + + + + + + + +``` +The `requester` extension is now finished and can be added it to the [ActivityDefinition](../fhir/activitydefinition.md) under the [dsf-extension-process-authorization](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-extension-process-authorization-1.0.0.xml). + +
+This is how the ActivityDefinition should look like so far + +```xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +``` +
+ +Back to looking at the [dsf-extension-process-authorization](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-extension-process-authorization-1.0.0.xml) again. The last slice for this extension is `recipient`: +```xml + + ... + + ... + + + + + + + + + + + + + + + + + + + + + + + + ... + + +``` + +The `recipient` will decide which DSF instance is allowed to process that message. That is the reason why there are no Codings for `remote` or `practitioner` here. For `requester`, it was decided to only allow users with a certain role from a local organization to send this message. The message should now also only be processable by that same local organization. The right Coding for this job is the [coding-process-authorization-local-organization](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-coding-process-authorization-local-organization-1.0.0.xml). The configuration of a local requester and local receiver is often used for the message that starts up the first BPMN process of the plugin. The process of adding the `recipient` slice is the exact same as it is for `requester`. It's possible to follow the same steps for the `requester` slice again but using a different Coding. + +
+This is how the ActivityDefinition should look like + +```xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +``` +
+ +The last element defined in the [process authorization extension](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-extension-process-authorization-1.0.0.xml) is `Extension.url`. This was already added at the very beginning of the working through the extension, so there is nothing more to add. + +#### 3. BPE Managed Elements + +Some elements of [ActivityDefinitions](../fhir/activitydefinition.md) are managed by the DSF BPE and replaced with certain values at appropriate times. + +The following elements are managed by the DSF BPE: +- `ActivityDefinition.version` should use the [placeholder](../dsf/versions-placeholders-urls.md#placeholders) `#{version}` +- `ActivityDefinition.date` is not required, but if it is included, it should use the [placeholder](../dsf/versions-placeholders-urls.md#placeholders) `#{date}` +- `ActivityDefinition.status` must have a value of `unknown` + +
+The ActivityDefinition should now look like this + +```xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +``` +
+ +### 4. Regular Elements + +The only required elements in this set are `ActivityDefinition.url` and `ActivityDefinition.kind`. `ActivityDefinition.url` expects a certain format. This is explained in detail in the [documentation on URLs](../dsf/versions-placeholders-urls.md#urls). `ActivityDefinition.kind` must have the value `Task`. +All other elements can technically be omitted. Still, the following elements are recommended to be populated: +- `AcitivityDefinition.name` +- `AcitivityDefinition.title` +- `AcitivityDefinition.subtitle` +- `AcitivityDefinition.experimental` +- `AcitivityDefinition.publisher` +- `AcitivityDefinition.contact` +- `AcitivityDefinition.description` + +
+The finished ActivityDefinition should now look something like this + +```xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + <subtitle value="Information Processing Process"/> + <experimental value="false"/> + <publisher value="DSF"/> + <contact> + <name value="DSF"/> + <telecom> + <system value="email"/> + <value value="noreply@dsf.dev"/> + </telecom> + </contact> + <description value="My Process processes information"/> +</ActivityDefinition> +``` +</details> + +## Related Topics +[ActivityDefinition](../fhir/activitydefinition.md), [Creating CodeSystems for DSF Processes](creating-codesystems-for-dsf-processes.md), [Creating ValueSets for DSF Processes](creating-valuesets-for-dsf-processes.md), [Task](../fhir/task.md) \ No newline at end of file diff --git a/docs/src/process-development/api-v2/guides/creating-codesystems-for-dsf-processes.md b/docs/src/process-development/api-v2/guides/creating-codesystems-for-dsf-processes.md new file mode 100644 index 000000000..359349177 --- /dev/null +++ b/docs/src/process-development/api-v2/guides/creating-codesystems-for-dsf-processes.md @@ -0,0 +1,45 @@ +--- +title: Creating CodeSystems for DSF Processes +icon: creative +--- + +## Creating CodeSystems for DSF Processes + +Sometimes it is necessary to create custom [CodeSystem](../fhir/codesystem.md) resources. For example, when defining the type of an [Input Parameter](../fhir/task.md#task-input-parameters). [CodeSystems](../fhir/codesystem.md) for the DSF differ from regular [CodeSystems](../fhir/codesystem.md) in that some element's values are managed by the DSF BPE server. The following template can be populated with custom values: +```xml +<CodeSystem xmlns="http://hl7.org/fhir"> + <meta> + <tag> + <system value="http://dsf.dev/fhir/CodeSystem/read-access-tag" /> + <code value="ALL" /> + </tag> + </meta> + <url value="http://dsf.dev/fhir/CodeSystem/my-code-system" /> <!--dummy value--> + <!-- version managed by bpe --> + <version value="#{version}" /> + <name value="My CodeSystem" /> <!--dummy value--> + <title value="My CodeSystem Title" /> <!--dummy value--> + <!-- status managed by bpe --> + <status value="unknown" /> + <experimental value="false" /> + <!-- date managed by bpe --> + <date value="#{date}" /> + <publisher value="DSF" /> <!--dummy value--> + <description value="CodeSystem with codes for me" /> <!--dummy value--> + <caseSensitive value="true" /> + <hierarchyMeaning value="grouped-by" /> + <versionNeeded value="false" /> + <content value="complete" /> + <concept> + <code value="my-code" /> <!--dummy value--> + <display value="My Code" /> <!--dummy value--> + <definition value="My code used for myself" /> <!--dummy value--> + </concept> +</CodeSystem> +``` +Dummy values should be replaced with appropriate values. Elements managed by the DSF BPE server should not be changed. More codes can be added by defining more `concept` elements. + +The DSF BPE server will read the [CodeSystem](../fhir/codesystem.md) from `tutorial-process/src/main/resources/fhir/CodeSystem`. + +## Related Topics +[Adding Task Input Parameters to Task Profiles](adding-task-input-parameters-to-task-profiles.md), [CodeSystem](../fhir/codesystem.md), [Creating ValueSets for DSF processes](creating-valuesets-for-dsf-processes.md), [ValueSet](../fhir/valueset.md) \ No newline at end of file diff --git a/docs/src/process-development/api-v2/guides/creating-task-resources-based-on-a-definition.md b/docs/src/process-development/api-v2/guides/creating-task-resources-based-on-a-definition.md new file mode 100644 index 000000000..31b95f8c1 --- /dev/null +++ b/docs/src/process-development/api-v2/guides/creating-task-resources-based-on-a-definition.md @@ -0,0 +1,236 @@ +--- +title: Creating Task Resources Based on a Definition +icon: creative +--- + +## Creating Task Resources Based on a Definition + +This short guide provides an overview of how to create [Task](../fhir/task.md) resources for use in [Starting A Process Via Task Resources](../guides/starting-a-process-via-task-resources.md). The free version of [Forge](https://simplifier.net/forge?utm_source=firely-forge) is used to support visualization. A free account can be created to follow the process directly; however, screenshots of relevant views are included for reference. Note that the free version of Forge [must not be used commercially](https://simplifier.net/pricing). As an example, a [Task](../fhir/task.md) resource based on the [`task-start-dic-process.xml`](https://github.com/datasharingframework/dsf-process-tutorial/blob/main/tutorial-process/src/main/resources/fhir/StructureDefinition/task-start-dic-process.xml) profile is created. + + +### 1st Step: Removing Placeholders +[`task-start-dic-process.xml`](https://github.com/datasharingframework/dsf-process-tutorial/blob/main/tutorial-process/src/main/resources/fhir/StructureDefinition/task-start-dic-process.xml) includes placeholders for the `version` and `date` elements. For the purpose of this guide, these elements can either be removed or commented out to prevent Forge from performing type checking on them, which would otherwise result in an error and cause Forge to not load the file. + +### 2nd Step: Differential Chain +If the resource profile is only available as a [differential](https://www.hl7.org/fhir/R4/profiling.html#snapshot), as in this case, it is helpful to aggregate the changes made to the base resource (in this case [Task](../fhir/task.md)) by all profiles to improve readability. To accomplish this, all relevant profiles are required. The [`task-start-dic-process.xml`](https://github.com/datasharingframework/dsf-process-tutorial/blob/main/tutorial-process/src/main/resources/fhir/StructureDefinition/task-start-dic-process.xml) file is already present. This file lists a resource called `task-base` in its `baseDefinition` element. The `task-base` resource is part of the DSF and can be found [here](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-task-base-1.0.0.xml). It should also be placed in the same folder as [`task-start-dic-process.xml`](https://github.com/datasharingframework/dsf-process-tutorial/blob/main/tutorial-process/src/main/resources/fhir/StructureDefinition/task-start-dic-process.xml). Since `task-base` uses the original FHIR Task as its `baseDefinition` element, no additional resources are needed to complete this chain. In Forge, opening the folder containing both resources and selecting the [`task-start-dic-process.xml`](https://github.com/datasharingframework/dsf-process-tutorial/blob/main/tutorial-process/src/main/resources/fhir/StructureDefinition/task-start-dic-process.xml) profile should display a view similar to the following: + + +![Forge overview](/photos/developer-documentation/forge_overview.png) + +### 3rd Step: Building the Task Resource +Each element will now be reviewed and included in the [Task](../fhir/task.md) resource if it is mandatory (cardinality of at least `1..1`) according to the profile. Placeholders such as `#{version}` must not be used for resources that are not read by the DSF BPE server. This applies when creating a [Task](../fhir/task.md) resource intended for use with [cURL](../guides/starting-a-process-via-task-resources.md#using-curl). In contrast, placeholders should be used in [Draft Task Resources](../dsf/draft-task-resources.md) instead of actual values wherever possible, as these resources are read by the DSF BPE server. This guide demonstrates the creation of a [Task](../fhir/task.md) resource without placeholders, beginning with the base element required for all [Task](../fhir/task.md) resources: +```xml +<Task xmlns="http://hl7.org/fhir"> + +</Task> +``` + +Before adding any elements listed in Forge's element tree, the `Task.meta.profile` element must be included. Its requirement is not visible in the element tree, which is why it is mentioned explicitly. This is the only instance where it does not appear in the element tree. It should look like this: +```xml +<Task xmlns="http://hl7.org/fhir"> + <meta> + <profile value="http://dsf.dev/fhir/StructureDefinition/task-start-dic-process|1.0"/> + </meta> +</Task> +``` + +The first element listed in the element tree is the `instantiatesCanonical` element. To add this element, an XML element with the same name should be created, using a value as specified in [URLs](../dsf/versions-placeholders-urls.md#urls): +```xml +<Task xmlns="http://hl7.org/fhir"> + <meta> + <profile value="http://dsf.dev/fhir/StructureDefinition/task-start-dic-process|1.0"/> + </meta> + <instantiatesCanonical value="http://dsf.dev/bpe/Process/dicProcess|1.0" /> +</Task> +``` +We can continue this process for all primitive elements like these. Just make sure you pay attention to use the correct data type (e.g. proper coding value for elements with `coding` type). + +The [Task](../fhir/task.md) resource should look something like this: +<details> +<summary>Suggested solution</summary> + +```xml +<Task xmlns="http://hl7.org/fhir"> + <meta> + <profile value="http://dsf.dev/fhir/StructureDefinition/task-start-dic-process|1.0"/> + </meta> + <instantiatesCanonical value="http://dsf.dev/bpe/Process/dicProcess|1.0" /> + <status value="requested"/> + <intent value="order"/> + <authoredOn value="2024-02-08T10:00:00+00:00" /> +</Task> +``` +</details> + +Now a more complex element like the `requester` element: + +![Forge requester view](/photos/developer-documentation/forge_requester_view.png) + +The beginning is the same as primitive elements, adding the `requester` element: +```xml +<Task xmlns="http://hl7.org/fhir"> + <meta> + <profile value="http://dsf.dev/fhir/StructureDefinition/task-start-dic-process|1.0"/> + </meta> + <instantiatesCanonical value="http://dsf.dev/bpe/Process/dicProcess|1.0" /> + <status value="requested"/> + <intent value="order"/> + <authoredOn value="2024-02-08T10:00:00+00:00" /> + <requester> + + </requester> +</Task> +``` + +Then, primitive elements are added to `requester` like before for `Task`: +```xml +<Task xmlns="http://hl7.org/fhir"> + <meta> + <profile value="http://dsf.dev/fhir/StructureDefinition/task-start-dic-process|1.0"/> + </meta> + <instantiatesCanonical value="http://dsf.dev/bpe/Process/dicProcess|1.0" /> + <status value="requested"/> + <intent value="order"/> + <authoredOn value="2024-02-08T10:00:00+00:00" /> + <requester> + <type value="Organization"/> + </requester> +</Task> +``` +*Important to note here that the value for the `status` will always be `requested` for Tasks being posted using cURL and the `type` element for `requester` and `recipient` will always have the value `Organization` in the DSF context.* + +Next, the `identifier` element and its primitive sub-elements are added just like before. The `identifier.value` in this case will be `dic.dsf.test`. To understand why, take a look at the topic on [organization identifiers](../dsf/organization-identifiers.md): +```xml +<Task xmlns="http://hl7.org/fhir"> + <meta> + <profile value="http://dsf.dev/fhir/StructureDefinition/task-start-dic-process|1.0"/> + </meta> + <instantiatesCanonical value="http://dsf.dev/bpe/Process/dicProcess|1.0" /> + <status value="requested"/> + <intent value="order"/> + <authoredOn value="2024-02-08T10:00:00+00:00" /> + <requester> + <type value="Organization"/> + <identifier> + <system value="http://dsf.dev/sid/organization-identifier"/> + <value value="dic.dsf.test" /> + </identifier> + </requester> +</Task> +``` +*The `requester.identifier.system` has a `Fixed value` annotation. Clicking on the `system` element in Forge or looking at the XML for the right Task profile reveals what the value is supposed to be. The right side will have all information about that element, including the actual value for `Fixed value`.* + +Filling out all elements in the [Task](../fhir/task.md) resource is now the same until the [slicing](https://www.hl7.org/fhir/R4/profiling.html#slicing) for `Task.input`. The [Task](../fhir/task.md) resource should look something like this: +<details> +<summary>Suggested solution</summary> + +```xml +<Task xmlns="http://hl7.org/fhir"> + <meta> + <profile value="http://dsf.dev/fhir/StructureDefinition/task-start-dic-process|1.0"/> + </meta> + <instantiatesCanonical value="http://dsf.dev/bpe/Process/dicProcess|1.0" /> + <status value="requested"/> + <intent value="order"/> + <authoredOn value="2024-02-08T10:00:00+00:00" /> + <requester> + <type value="Organization"/> + <identifier> + <system value="http://dsf.dev/sid/organization-identifier"/> + <value value="dic.dsf.test" /> + </identifier> + </requester> + <restriction> + <recipient> + <type value="Organization"/> + <identifier> + <system value="http://dsf.dev/sid/organization-identifier" /> + <value value="dic.dsf.test" /> + </identifier> + </recipient> + </restriction> +</Task> +``` +</details> + + +[Slicings](https://www.hl7.org/fhir/R4/profiling.html#slicing) are a bit different from regular elements. Starting with the slice `message-name`: + +![Forge slice message name](/photos/developer-documentation/forge_slice_message_name.png) + +Including slices to the [Task](../fhir/task.md) resource like previous element would add a `message-name` element to our XML like this: + +```xml +<Task xmlns="http://hl7.org/fhir"> + ... + <input> + <message-name> + ... + </message-name> + </input> +</Task> +``` + +This approach however, would not work. FHIR processors do not use the name of the slice to map entries in your [Task](../fhir/task.md) resource to the correct slice. They use [discriminators](https://www.hl7.org/fhir/R4/profiling.html#discriminator). Discriminators define the elements a processor needs to distinguish slices by. The discriminator configuration can be seen by selecting the `input` element in Forge. In this case, a processor would look at the values for `input.type.coding.system` and `input.type.coding.code` to determine which slice this element belongs to. This only works because `input.type.coding.system` and `input.type.coding.code` are present in all slices and have a `Fixed value`. More about discriminators can be read [here](https://www.hl7.org/fhir/R4/profiling.html#discriminator). This means effectively ignoring the name of the slice as an element and start adding elements like before: + +```xml +<Task xmlns="http://hl7.org/fhir"> + ... + <input> + <type> + <coding> + <system value="http://dsf.dev/fhir/CodeSystem/bpmn-message" /> + <code value="message-name" /> + </coding> + </type> + <valueString value="dicProcess" /> + </input> +</Task> +``` + +This covers all ways of adding elements. Adding the remaining elements is left as an exercise. In the end, it should look something like this: +<details> +<summary>Suggested solution</summary> + +```xml +<Task xmlns="http://hl7.org/fhir"> + <meta> + <profile value="http://dsf.dev/fhir/StructureDefinition/task-start-dic-process|1.0"/> + </meta> + <instantiatesCanonical value="http://dsf.dev/bpe/Process/dicProcess|1.0" /> + <status value="requested"/> + <intent value="order"/> + <authoredOn value="2024-02-08T10:00:00+00:00" /> + <requester> + <type value="Organization"/> + <identifier> + <system value="http://dsf.dev/sid/organization-identifier"/> + <value value="dic.dsf.test" /> + </identifier> + </requester> + <restriction> + <recipient> + <type value="Organization"/> + <identifier> + <system value="http://dsf.dev/sid/organization-identifier" /> + <value value="dic.dsf.test" /> + </identifier> + </recipient> + </restriction> + <input> + <type> + <coding> + <system value="http://dsf.dev/fhir/CodeSystem/bpmn-message" /> + <code value="message-name" /> + </coding> + </type> + <valueString value="dicProcess"/> + </input> +</Task> +``` +</details> + +**Do not forget to restore the version and date placeholders in [`task-start-dic-process.xml`](https://github.com/datasharingframework/dsf-process-tutorial/blob/main/tutorial-process/src/main/resources/fhir/StructureDefinition/task-start-dic-process.xml) when reusing the resource in a process plugin!** + +## Related Topics +[Draft Task Resources](../dsf/draft-task-resources.md), [Task](../fhir/task.md) \ No newline at end of file diff --git a/docs/src/process-development/api-v2/guides/creating-valuesets-for-dsf-processes.md b/docs/src/process-development/api-v2/guides/creating-valuesets-for-dsf-processes.md new file mode 100644 index 000000000..2eb548dc1 --- /dev/null +++ b/docs/src/process-development/api-v2/guides/creating-valuesets-for-dsf-processes.md @@ -0,0 +1,64 @@ +--- +title: Creating ValueSets for DSF Processes +icon: creative +--- + +## Creating ValueSets for DSF Processes + +In some cases, it may be necessary to create a [ValueSet](../fhir/valueset.md). For example, when adding [Input Parameters](../fhir/task.md#task-input-parameters) to DSF [Task](../fhir/task.md) resources, a [ValueSet](../fhir/valueset.md) resource must also be referenced in the binding for `Task.input.type` to define the type of the [Input Parameter](../fhir/task.md#task-input-parameters). [ValueSets](../fhir/valueset.md) for the DSF differ from regular [ValueSets](../fhir/valueset.md) in that certain element values are managed by the DSF BPE server. The following template can be used for a [ValueSet](../fhir/valueset.md): + +```xml +<ValueSet xmlns="http://hl7.org/fhir"> + <meta> + <tag> + <system value="http://dsf.dev/fhir/CodeSystem/read-access-tag" /> + <code value="ALL" /> + </tag> + </meta> + <url value="http://dsf.dev/fhir/ValueSet/my-value-set"/> <!--dummy value--> + <!-- version managed by bpe --> + <version value="#{version}" /> + <name value="My ValueSet"/> <!--dummy value--> + <title value="My ValueSet Title"/> <!--dummy value--> + <!-- status managed by bpe --> + <status value="unknown" /> + <experimental value="false"/> + <!-- date managed by bpe --> + <date value="#{date}"/> + <publisher value="DSF"/> <!--dummy value--> + <description value="ValueSet with all codes from my-code-system"/> <!--dummy value--> + <immutable value="true"/> + <compose> + <include> + <system value="http://dsf.dev/fhir/CodeSystem/my-code-system"/> <!--dummy value--> + <version value="#{version}"/> + </include> + </compose> +</ValueSet> +``` +Dummy values should be replaced with appropriate, context-specific values. Elements managed by the DSF BPE server must not be modified. The `compose` element defines the codes included in this [ValueSet](../fhir/valueset.md) and contains at least one `include` element. Each `include` element references a [CodeSystem](../fhir/codesystem.md) and includes a list of `concept` elements, each containing an individual `code` element. The use of one code from `my-code-system` and one code from `my-other-code-system` results in the following `compose` element: +```xml +<ValueSet xmlns="http://hl7.org/fhir"> + ... + <compose> + <include> + <system value="http://dsf.dev/fhir/CodeSystem/my-code-system"/> + <version value="#{version}"/> + <concept> + <code value="my-code"/> + </concept> + </include> + <include> + <system value="http://dsf.dev/fhir/CodeSystem/my-other-code-system"/> + <version value="#{version}"/> + <concept> + <code value="my-other-code"/> + </concept> + </include> + </compose> +</ValueSet> +``` +The DSF BPE server will read the [ValueSet](../fhir/valueset.md) from `tutorial-process/src/main/resources/fhir/ValueSet` inside the process plugin. + +## Related Topics +[CodeSystem](../fhir/codesystem.md), [Creating CodeSystems for DSF processes](creating-codesystems-for-dsf-processes.md), [ValueSet](../fhir/valueset.md) \ No newline at end of file diff --git a/docs/src/process-development/api-v2/guides/index.md b/docs/src/process-development/api-v2/guides/index.md new file mode 100644 index 000000000..2841de106 --- /dev/null +++ b/docs/src/process-development/api-v2/guides/index.md @@ -0,0 +1,17 @@ +--- +title: Guides +icon: creative +--- + +## Details +- [Accessing BPMN Process Variables](accessing-bpmn-process-variables.md) +- [Accessing Task Resources During Execution](accessing-task-resources-during-execution.md) +- [Adding Task Input Parameters to Task Profiles](adding-task-input-parameters-to-task-profiles.md) +- [Configuring Read Access Tags](configuring-read-access-tags.md) +- [Creating ActivityDefinitions](creating-activity-definitions.md) +- [Creating CodeSystems for DSF Processes](creating-codesystems-for-dsf-processes.md) +- [Creating Task Resources Based on a Definition](creating-task-resources-based-on-a-definition.md) +- [Creating ValueSets for DSF Processes](creating-valuesets-for-dsf-processes.md) +- [Managing Multiple Incoming Messages and Missing Messages](managing-mutiple-incoming-messages-and-missing-messages.md) +- [Setting Targets for Message Events](setting-targets-for-message-events.md) +- [Starting a Process via Task Resources](starting-a-process-via-task-resources.md) \ No newline at end of file diff --git a/docs/src/process-development/api-v2/guides/managing-mutiple-incoming-messages-and-missing-messages.md b/docs/src/process-development/api-v2/guides/managing-mutiple-incoming-messages-and-missing-messages.md new file mode 100644 index 000000000..b93703762 --- /dev/null +++ b/docs/src/process-development/api-v2/guides/managing-mutiple-incoming-messages-and-missing-messages.md @@ -0,0 +1,18 @@ +--- +title: Managing Multiple Incoming Messages and Missing Messages +icon: creative +--- + +## Managing Multiple Incoming Messages and Missing Messages + +If an already running process instance is waiting for a message from another organization, the corresponding FHIR [Task](../fhir/task.md) may never arrive. Either because the other organization decides to never send the message or because some technical problem prohibits the [Task](../fhir/task.md) resource from being posted to the DSF FHIR server. This would result in stale process instances that never finish. + +At the same time, it might also be expected to receive one out of a number of different message types at once. + +An [Event Based Gateway](../bpmn/gateways.md#event-based-gateway) can be used to solve both problems by adding it to the process waiting for a response and then either handling a [Task](../fhir/task.md) resource with the response and finish the process in a success state or triggering a [Timer Intermediate Catching Event](../bpmn/timer-intermediate-catching-events.md) after a defined wait period and finish the process in an error state. The following BPMN collaboration diagram shows how the process at the first organization would look like if we wanted to react to multiple different messages or missing messages: + +<picture> + <source media="(prefers-color-scheme: dark)" srcset="/photos/developer-documentation/event_based_gateway_inverted.svg"> + <source media="(prefers-color-scheme: light)" srcset="/photos/developer-documentation/event_based_gateway.svg"> + <img alt="BPMN collaboration diagram with an Event Based Gateway" src="/photos/developer-documentation/event_based_gateway.svg"> +</picture> diff --git a/docs/src/process-development/api-v2/guides/setting-targets-for-message-events.md b/docs/src/process-development/api-v2/guides/setting-targets-for-message-events.md new file mode 100644 index 000000000..8d5eb40a7 --- /dev/null +++ b/docs/src/process-development/api-v2/guides/setting-targets-for-message-events.md @@ -0,0 +1,12 @@ +--- +title: Setting Targets for Message Events +icon: creative +--- + +## Setting Targets for Message Events + +Setting a target for a message event requires a `Target` object. Creating this object requires the target's organization identifier, endpoint identifier, and endpoint address. These values can be obtained from the DSF FHIR server's web interface or by querying the FHIR server via an instance of `DsfClient` or a `generic FHIR client`. By clicking the `Show Bookmarks` button in the top right corner and selecting `Endpoint`, a list of all Endpoints available to the FHIR server will be displayed. Instances of `DsfClient` or a `generic FHIR client` can be accessed via the [process plugin API](../dsf/process-plugin-api.md). +Targets should be added in a [Service Task](../bpmn/service-tasks.md) before a [Message Event](../bpmn/messaging.md). A `Variables` instance provides helper methods to set targets in a [Service Task's](../bpmn/service-tasks.md) `execute` method. + +## Related Topics +[Process Plugin API](../dsf/process-plugin-api.md), [Message Correlation](../dsf/message-correlation.md), [Target and Targets](../dsf/target-and-targets.md) \ No newline at end of file diff --git a/docs/src/process-development/api-v2/guides/starting-a-process-via-task-resources.md b/docs/src/process-development/api-v2/guides/starting-a-process-via-task-resources.md new file mode 100644 index 000000000..3211d6cad --- /dev/null +++ b/docs/src/process-development/api-v2/guides/starting-a-process-via-task-resources.md @@ -0,0 +1,36 @@ +--- +title: Starting a Process via Task Resources +icon: creative +--- + +## Starting a Process via Task Resources + +To start a BPMN process, a new [Task](../fhir/task.md) resource must be created in the DSF FHIR server by sending an HTTP request in accordance with the [FHIR RESTful API](https://www.hl7.org/fhir/R4/http.html). Specifically, a [create](https://www.hl7.org/fhir/R4/http.html#create) operation is required to generate the resource for the first time. The [Task](../fhir/task.md) resource being sent must conform to the [Task](../fhir/task.md) profile of the intended process and adhere to the [ActivityDefinition's](../fhir/activitydefinition.md) authorization rules. +There are two major ways of making this HTTP request: +1. Using cURL +2. Using the DSF FHIR server's web interface + +### Using cURL +To use cURL, an appropriate [Task](../fhir/task.md) resource must be created and posted to the DSF FHIR server. There is a guide on [creating Task Resources based on a StructureDefinition](../guides/creating-task-resources-based-on-a-definition.md). A file named `example-task.xml` is available in `tutorial-process/src/main/resources/fhir` in the [DSF Process Tutorial](https://github.com/datasharingframework/dsf-process-tutorial) and can serve as a starting point. The [solution branches of the tutorial](https://github.com/datasharingframework/dsf-process-tutorial/blob/solutions/exercise-1/tutorial-process/src/main/resources/fhir/Task/task-start-dic-process.xml) can be consulted for a full example. + +Below is a cURL command skeleton. All <>-Placeholders should be replaced with appropriate values. Host name depends on the instance that should be addressed. + +#### Linux: +```shell +curl https://<instance-host-name>/fhir/Task \ +--cacert <path/to/ca-certificate-file.pem> \ +--cert <path/to/client-certificate-file.pem>:password \ +--key <path/to/client-private-key-file.pem> \ +-H "Content-Type: application/fhir+xml" \ +-H "Accept: application/fhir+xml" \ +-d @<path/to/example-task.xml> +``` + +### Using the DSF FHIR Server's Web Interface + +When accessing the web interface of a DSF FHIR server instance (e.g. https://instance-name/fhir), the DSF FHIR server can be queried using the [FHIR RESTful API](https://www.hl7.org/fhir/R4/http.html) to return a list of all [Draft Task Resources](../dsf/draft-task-resources.md). These [Task](../fhir/task.md) resources serve as templates for instantiating [Task](../fhir/task.md) resources that initiate BPMN processes. Instead of performing the query manually, a predefined bookmark can be used to navigate to the query URL. A list of bookmarks is available in the top right corner of the web interface. Selecting the bookmark referencing `?_sort=_profile,identifier&status=draft` under the `Task` section will display the list of all [Draft Task Resources](../dsf/draft-task-resources.md). From this list, the desired resource to start the BPMN process can be selected. A detailed view of the resource will be shown, allowing the specification of any necessary [Task Input Parameters](../fhir/task.md#task-input-parameters). If all required information is provided correctly, the process can be initiated by clicking `Start Process`. + +For [Draft Task Resources](../dsf/draft-task-resources.md) to be available, they must be included in the mapping for the BPMN process ID in `ProcessPluginDefinition#getFhirResourcesByProcessId`. Additional information can be found in [the Process Plugin Definition](../dsf/process-plugin-definition.md). + +## Related Topics +[Task](../fhir/task.md) \ No newline at end of file diff --git a/docs/src/process-development/api-v2/guides/user-tasks-in-the-dsf.md b/docs/src/process-development/api-v2/guides/user-tasks-in-the-dsf.md new file mode 100644 index 000000000..e5e9908c2 --- /dev/null +++ b/docs/src/process-development/api-v2/guides/user-tasks-in-the-dsf.md @@ -0,0 +1,58 @@ +### User Tasks in the DSF + +Creating a [User Task](../concepts/bpmn/user-tasks.md) in a BPMN model causes the DSF to automatically generate a [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html) resource based on the [Questionnaire](https://www.hl7.org/fhir/R4/questionnaire.html) specified in the [User Task's](../concepts/bpmn/user-tasks.md) `Forms` field when process execution reaches the [User Task](../concepts/bpmn/user-tasks.md). The `Forms` field must have the type `Embedded or External Task Forms`, with the `Form key` set to the URL of the [Questionnaire](https://www.hl7.org/fhir/R4/questionnaire.html) resource. The [Questionnaire](https://www.hl7.org/fhir/R4/questionnaire.html) resource must be placed in the `src/main/resources/fhir/Questionnaire` directory. + +The generated [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html) can be accessed and answered by navigating to `https://your.dsf.fhir.server/fhir/QuestionnaireResponse?_sort=-_lastUpdated&status=in-progress` in the DSF FHIR server UI. After completing and submitting the [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html), the process execution will proceed to the next BPMN element following the [User Task](../concepts/bpmn/user-tasks.md). The updated [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html) will then be accessible via the [Process Plugin Api's](../concepts/dsf/process-api.md) `Variables` instance by calling `getLatestReceivedQuestionnaireResponse()`. + +It is also possible to register a [Task Listener](https://docs.camunda.org/manual/7.21/user-guide/process-engine/delegation-code/#task-listener) on the [User Task](../concepts/bpmn/user-tasks.md). This enables manipulation of the [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html) before it is posted to the DSF FHIR server. This can be achieved by extending the `DefaultUserTaskListener` class, which provides overrides for interacting with the [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html). + +Dynamically changing the `item.text` value of an item in a [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html) (if the item is **not** of type `display`) is not permitted. To change text dynamically, the `item.text` value of the corresponding [Questionnaire](https://www.hl7.org/fhir/R4/questionnaire.html) resource must also be updated. As an alternative, an item of type `display` can be placed above the item requiring dynamic text, and its `item.text` value can be modified instead, as shown in the template. In this case, the `item.text` element of the item below the display item may be omitted. + + +Below is a template for a [Questionnaire](https://www.hl7.org/fhir/R4/questionnaire.html) resource. The placeholder `questionnaire-name` should be replaced with the actual name of the [Questionnaire](https://www.hl7.org/fhir/R4/questionnaire.html), and the file should be named accordingly. The items `business-key` and `user-task-id` are required by the DSF and must always be included. Additional items can be added to the [Questionnaire](https://www.hl7.org/fhir/R4/questionnaire.html) as needed. + + +### Questionnaire Template +```xml +<Questionnaire xmlns="http://hl7.org/fhir"> + <meta> + <profile value="http://dsf.dev/fhir/StructureDefinition/questionnaire|1.5.0"/> + <tag> + <system value="http://dsf.dev/fhir/CodeSystem/read-access-tag"/> + <code value="ALL"/> + </tag> + </meta> + <url value="http://dsf.dev/fhir/Questionnaire/questionnaire-name"/> <!-- file name should be same as the name of your Questionnaire --> + <!-- version managed by bpe --> + <version value="#{version}"/> + <!-- date managed by bpe --> + <date value="#{date}"/> + <!-- status managed by bpe --> + <status value="unknown"/> + <item> + <!-- required --> + <linkId value="business-key"/> + <type value="string"/> + <text value="The business-key of the process execution"/> + <required value="true"/> + </item> + <item> + <!-- required --> + <linkId value="user-task-id"/> + <type value="string"/> + <text value="The user-task-id of the process execution"/> + <required value="true"/> + </item> + <item> + <linkId value="text-to-display-above-item"/> + <type value="display"/> + <text value="foo"/> + </item> + <item> + <linkId value="item"/> + <type value="boolean"/> + <text value="Item description"/> + <required value="true"/> + </item> +</Questionnaire> +``` \ No newline at end of file diff --git a/docs/src/process-development/api-v2/index.md b/docs/src/process-development/api-v2/index.md new file mode 100644 index 000000000..f70012ebd --- /dev/null +++ b/docs/src/process-development/api-v2/index.md @@ -0,0 +1,47 @@ +--- +title: API 2 (alpha) Overview +icon: code +--- + +## BPMN +- [Conditions](bpmn/conditions.md) +- [Gateways](bpmn/gateways.md) +- [Messaging](bpmn/messaging.md) +- [Sequence Flow](bpmn/sequence-flow.md) +- [Service Tasks](bpmn/service-tasks.md) +- [Timer Intermediate Catching Events](bpmn/timer-intermediate-catching-events.md) + +## FHIR +- [ActivityDefinition](fhir/activitydefinition.md) +- [Codesystem](fhir/codesystem.md) +- [Task](fhir/task.md) +- [ValueSet](fhir/valueset.md) + +## DSF +- [BPMN Process Execution](dsf/bpmn-process-execution.md) +- [BPMN Process Variables](dsf/bpmn-process-variables.md) +- [Draft Task Resources](dsf/draft-task-resources.md) +- [Environment Variables](dsf/environment-variables.md) +- [Message Correlation](dsf/message-correlation.md) +- [Message Delegates](dsf/message-delegates.md) +- [Organization Identifiers](dsf/organization-identifiers.md) +- [Process Plugin API](dsf/process-plugin-api.md) +- [Process Plugin Definition](dsf/process-plugin-definition.md) +- [Read Access Tag](dsf/read-access-tag.md) +- [Requester and Recipient](dsf/requester-and-recipient.md) +- [Service Delegates](dsf/service-delegates.md) +- [Spring Framework Integration](dsf/spring-framework-integration.md) +- [Versions, Placeholders and URLs](dsf/versions-placeholders-urls.md) + +## Guides +- [Accessing BPMN Process Variables](guides/accessing-bpmn-process-variables.md) +- [Accessing Task Resources During Execution](guides/accessing-task-resources-during-execution.md) +- [Adding Task Input Parameters to Task Profiles](guides/adding-task-input-parameters-to-task-profiles.md) +- [Configuring Read Access Tags](guides/configuring-read-access-tags.md) +- [Creating ActivityDefinitions](guides/creating-activity-definitions.md) +- [Creating CodeSystems for DSF Processes](guides/creating-codesystems-for-dsf-processes.md) +- [Creating Task Resources Based on a Definition](guides/creating-task-resources-based-on-a-definition.md) +- [Creating ValueSets for DSF Processes](guides/creating-valuesets-for-dsf-processes.md) +- [Managing Multiple Incoming Messages and Missing Messages](guides/managing-mutiple-incoming-messages-and-missing-messages.md) +- [Setting Targets for Message Events](guides/setting-targets-for-message-events.md) +- [Starting a Process via Task Resources](guides/starting-a-process-via-task-resources.md) \ No newline at end of file From 6206e2abe00e15eb1de7e3575aab88455bdbb900 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20B=C3=B6hringer?= <jan.boehringer@hs-heilbronn.de> Date: Mon, 23 Jun 2025 10:02:43 +0200 Subject: [PATCH 05/12] In line with api v2 doc --- docs/src/process-development/api-v1/bpmn/conditions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/process-development/api-v1/bpmn/conditions.md b/docs/src/process-development/api-v1/bpmn/conditions.md index d383fe4e0..12360366d 100644 --- a/docs/src/process-development/api-v1/bpmn/conditions.md +++ b/docs/src/process-development/api-v1/bpmn/conditions.md @@ -3,6 +3,6 @@ title: Conditions icon: creative --- -### Conditions +## Conditions BPMN elements can have a property attached to them which either executes a script or evaluates an expression in order to make a decision. The most common example of this is the [Sequence Flow](./sequence-flow.md) elements following an [Exclusive Gateway](./gateways.md). Each [Sequence Flow](./sequence-flow.md) element will have a condition attached to decide which flow should be pursued. The [Camunda Modeler](https://camunda.com/download/modeler/) distinguishes the two types in the `Type` attribute of the `Condition` tab in a BPMN element. Camunda comes with a GraalVM JavaScript engine but can be extended with other types of scripting engines. See the Camunda documentation on [scripting](https://docs.camunda.org/manual/latest/user-guide/process-engine/scripting/) for more details. Expressions are short boolean evaluations and have the following syntax: `${expression}`. An example of a simple expression would be a condition like `var = true`. For this to work during BPMN process execution, the variable that is used for the boolean condition must be available in the BPMN process variables before the [Sequence Flow](sequence-flow.md) reaches the evaluation of the expression. You can learn more advanced features of Expressions [here](https://docs.camunda.org/manual/7.21/user-guide/process-engine/expression-language/). \ No newline at end of file From d944156ea28820f2b659e7b91e65e9bd675fa09d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20B=C3=B6hringer?= <jan.boehringer@hs-heilbronn.de> Date: Mon, 23 Jun 2025 10:03:10 +0200 Subject: [PATCH 06/12] fixed typo in api v2 doc and made api v1 doc be in line with api v2 doc --- docs/src/process-development/api-v1/bpmn/gateways.md | 12 ++++++------ docs/src/process-development/api-v2/bpmn/gateways.md | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/src/process-development/api-v1/bpmn/gateways.md b/docs/src/process-development/api-v1/bpmn/gateways.md index b62dae140..cbf844bf6 100644 --- a/docs/src/process-development/api-v1/bpmn/gateways.md +++ b/docs/src/process-development/api-v1/bpmn/gateways.md @@ -3,18 +3,18 @@ title: Gateways icon: creative --- -### Gateways +## Gateways [Gateways](https://docs.camunda.org/manual/7.21/reference/bpmn20/gateways/) allow modelling of decision-based and concurrent workflows. [Exclusive Gateways](#exclusive-gateways) model a decision where one flow gets pursued over other flows. [Event-based Gateways](#event-based-gateways) also model a decision, but are based on events. [Parallel Gateways](#parallel-gateways) model concurrency. -#### Exclusive Gateways +### Exclusive Gateways -[Exclusive Gateways](https://docs.camunda.org/manual/7.21/reference/bpmn20/gateways/exclusive-gateway/) decide which one out of multiple [Sequence Flow](sequence-flow.md) should be followed based on [conditions](https://docs.camunda.org/manual/7.21/user-guide/process-engine/expression-language/#conditions). [Conditions](https://docs.camunda.org/manual/7.21/user-guide/process-engine/expression-language/#conditions) are not part of the [Exclusive Gateways](https://docs.camunda.org/manual/7.21/reference/bpmn20/gateways/exclusive-gateway/) themselves. They are set through the sequence flow exiting the [Exclusive Gateway](https://docs.camunda.org/manual/7.21/reference/bpmn20/gateways/exclusive-gateway/). In the [Camunda Modeler](https://camunda.com/download/modeler/), you can add conditions to [Sequence Flows](sequence-flow.md) by selecting a [Sequence Flow](sequence-flow.md) and opening the `Condition` tab. You can find more information on how to use Conditions [here](conditions.md). +[Exclusive Gateways](https://docs.camunda.org/manual/7.21/reference/bpmn20/gateways/exclusive-gateway/) decide which one out of multiple [Sequence Flow](sequence-flow.md) should be followed based on [conditions](https://docs.camunda.org/manual/7.21/user-guide/process-engine/expression-language/#conditions). [Conditions](https://docs.camunda.org/manual/7.21/user-guide/process-engine/expression-language/#conditions) are not part of the [Exclusive Gateways](https://docs.camunda.org/manual/7.21/reference/bpmn20/gateways/exclusive-gateway/) themselves. They are set through the sequence flow exiting the [Exclusive Gateway](https://docs.camunda.org/manual/7.21/reference/bpmn20/gateways/exclusive-gateway/). In the [Camunda Modeler](https://camunda.com/download/modeler/), conditions can be added to [Sequence Flows](sequence-flow.md) by selecting a [Sequence Flow](sequence-flow.md) and opening the `Condition` tab. More information on how to use Conditions can be found in [Conditions](conditions.md). -#### Event-based Gateways +### Event-based Gateways -The [Event-based Gateway](https://docs.camunda.org/manual/7.21/reference/bpmn20/gateways/event-based-gateway/) models a decision in the workflow. But instead of [conditions](./conditions.md), the [Event-based Gateway](https://docs.camunda.org/manual/7.21/reference/bpmn20/gateways/event-based-gateway/) uses the triggering of an event to dicide which [Sequence Flow](sequence-flow.md) to pursue. +The [Event-based Gateway](https://docs.camunda.org/manual/7.21/reference/bpmn20/gateways/event-based-gateway/) models a decision in the workflow. But instead of [conditions](./conditions.md), the [Event-based Gateway](https://docs.camunda.org/manual/7.21/reference/bpmn20/gateways/event-based-gateway/) uses the triggering of an event to decide which [Sequence Flow](sequence-flow.md) to pursue. -#### Parallel Gateways +### Parallel Gateways [Parallel Gateways](https://docs.camunda.org/manual/latest/reference/bpmn20/gateways/parallel-gateway/) model concurrent workflows. Their outgoing flows can be joined together again with another [Parallel Gateway](https://docs.camunda.org/manual/latest/reference/bpmn20/gateways/parallel-gateway/). This makes process execution wait for both flows to arrive at the gateway before continuing. \ No newline at end of file diff --git a/docs/src/process-development/api-v2/bpmn/gateways.md b/docs/src/process-development/api-v2/bpmn/gateways.md index a86fb4467..4c0726281 100644 --- a/docs/src/process-development/api-v2/bpmn/gateways.md +++ b/docs/src/process-development/api-v2/bpmn/gateways.md @@ -13,7 +13,7 @@ icon: creative ### Event-based Gateways -The [Event-based Gateway](https://docs.camunda.org/manual/7.21/reference/bpmn20/gateways/event-based-gateway/) models a decision in the workflow. But instead of [conditions](./conditions.md), the [Event-based Gateway](https://docs.camunda.org/manual/7.21/reference/bpmn20/gateways/event-based-gateway/) uses the triggering of an event to dicide which [Sequence Flow](sequence-flow.md) to pursue. +The [Event-based Gateway](https://docs.camunda.org/manual/7.21/reference/bpmn20/gateways/event-based-gateway/) models a decision in the workflow. But instead of [conditions](./conditions.md), the [Event-based Gateway](https://docs.camunda.org/manual/7.21/reference/bpmn20/gateways/event-based-gateway/) uses the triggering of an event to decide which [Sequence Flow](sequence-flow.md) to pursue. ### Parallel Gateways From 1191fe7dfc12fe2834b2fe4ab20659626c6807f4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20B=C3=B6hringer?= <jan.boehringer@hs-heilbronn.de> Date: Mon, 23 Jun 2025 10:06:28 +0200 Subject: [PATCH 07/12] Resolve conflict --- docs/src/process-development/api-v2/bpmn/sequence-flow.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/src/process-development/api-v2/bpmn/sequence-flow.md b/docs/src/process-development/api-v2/bpmn/sequence-flow.md index ede347b8f..2a248406d 100644 --- a/docs/src/process-development/api-v2/bpmn/sequence-flow.md +++ b/docs/src/process-development/api-v2/bpmn/sequence-flow.md @@ -3,9 +3,5 @@ title: Sequence Flow icon: creative --- -<<<<<<< HEAD ## Sequence Flow -======= -### Sequence Flow ->>>>>>> 5fe79c63b80478fe0af17c27b46c1315f7a96ba5 BPMN 2.0 calls the continuous arrows connecting the BPMN elements in BPMN models, Sequence Flow. Sequence Flow exits one BPMN element and points at the next BPMN element to be processed. From 5979bddfefe91a033ef72a5732d97d0cf2165e0b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20B=C3=B6hringer?= <jan.boehringer@hs-heilbronn.de> Date: Mon, 23 Jun 2025 16:11:20 +0200 Subject: [PATCH 08/12] Brought api v1 doc style (removed direct speech) in line with api v2 and made various small fixes to the content of both --- .../api-v1/bpmn/messaging.md | 16 ++-- .../api-v1/bpmn/sequence-flow.md | 2 +- .../api-v1/bpmn/service-tasks.md | 4 +- .../timer-intermediate-catching-events.md | 4 +- .../api-v1/bpmn/user-tasks.md | 4 +- .../api-v1/dsf/bpmn-process-execution.md | 4 +- .../api-v1/dsf/bpmn-process-variables.md | 4 +- .../api-v1/dsf/draft-task-resources.md | 10 +-- .../api-v1/dsf/environment-variables.md | 6 +- .../api-v1/dsf/message-correlation.md | 6 +- .../api-v1/dsf/message-delegates.md | 14 +-- .../api-v1/dsf/organization-identifiers.md | 11 ++- .../api-v1/dsf/process-plugin-api.md | 10 +-- .../api-v1/dsf/process-plugin-definition.md | 13 +-- .../api-v1/dsf/read-access-tag.md | 13 +-- .../api-v1/dsf/requester-and-recipient.md | 36 ++++---- .../api-v1/dsf/service-delegates.md | 9 +- .../dsf/spring-framework-integration.md | 56 +++++++++++- .../api-v1/dsf/versions-placeholders-urls.md | 21 +++-- .../api-v1/fhir/activitydefinition.md | 9 +- .../api-v1/fhir/codesystem.md | 9 +- .../process-development/api-v1/fhir/index.md | 1 + ...questionnaire-and-questionnaireresponse.md | 11 +++ .../process-development/api-v1/fhir/task.md | 13 +-- .../api-v1/fhir/valueset.md | 7 +- .../accessing-bpmn-process-variables.md | 10 ++- ...cessing-task-resources-during-execution.md | 16 ++-- ...-task-input-parameters-to-task-profiles.md | 37 ++++---- .../guides/configuring-read-access-tags.md | 33 +++---- .../guides/creating-activity-definitions.md | 87 ++++++++++--------- .../creating-codesystems-for-dsf-processes.md | 11 ++- ...ng-task-resources-based-on-a-definition.md | 49 ++++++----- .../creating-valuesets-for-dsf-processes.md | 13 +-- ...-incoming-messages-and-missing-messages.md | 10 ++- .../setting-targets-for-message-events.md | 12 ++- .../starting-a-process-via-task-resources.md | 33 +++---- .../api-v1/guides/user-tasks-in-the-dsf.md | 17 +++- .../api-v2/dsf/bpmn-process-execution.md | 2 +- .../api-v2/dsf/environment-variables.md | 2 +- .../api-v2/dsf/message-delegates.md | 5 +- .../api-v2/dsf/organization-identifiers.md | 4 +- .../api-v2/dsf/process-plugin-api.md | 2 +- .../dsf/spring-framework-integration.md | 56 +++++++++++- .../api-v2/fhir/activitydefinition.md | 6 +- .../accessing-bpmn-process-variables.md | 4 +- ...cessing-task-resources-during-execution.md | 4 + .../creating-codesystems-for-dsf-processes.md | 2 +- .../creating-valuesets-for-dsf-processes.md | 2 +- ...-incoming-messages-and-missing-messages.md | 4 + .../api-v2/guides/user-tasks-in-the-dsf.md | 16 +++- 50 files changed, 460 insertions(+), 270 deletions(-) diff --git a/docs/src/process-development/api-v1/bpmn/messaging.md b/docs/src/process-development/api-v1/bpmn/messaging.md index 97d05703b..10657a006 100644 --- a/docs/src/process-development/api-v1/bpmn/messaging.md +++ b/docs/src/process-development/api-v1/bpmn/messaging.md @@ -4,21 +4,21 @@ icon: creative --- -### Messaging +## Messaging -In order to enable communication with other lanes, pools or even entirely separate processes you need to be able to exchange information. In BPMN, you can use [Message Events](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/message-events/) to model this information exchange. Modeling communication with [Message Events](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/message-events/) in the same diagram uses Message Flow. Message Flow is typically represented by a dashed line arrow between BPMN elements with a black (send) or white (receive) envelope icon. The following BPMN collaboration diagram shows message exchange between two processes. +Enabling communication with other lanes, pools or even entirely separate processes requires the ability to exchange information. In BPMN, [Message Events](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/message-events/) are used to model this information exchange. Modeling communication with [Message Events](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/message-events/) in the same diagram uses Message Flow. Message Flow is typically represented by a dashed line arrow between BPMN elements with a black (send) or white (receive) envelope icon. The following BPMN collaboration diagram shows message exchange between two processes. ![BPMN collaboration diagram with two processes using message flow to exchange information between two organizations](/photos/developer-documentation/message_flow.svg) -#### Message Start Event +### Message Start Event -[Message Start Events](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/message-events/#message-start-event) allow a BPMN process to be started by an incoming message. In the DSF, all BPMN processes are started via messages. Therefore, you will have to include a [Message Start Event](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/message-events/#message-start-event) at the beginning of all of your BPMN models. +[Message Start Events](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/message-events/#message-start-event) allow a BPMN process to be started by an incoming message. In the DSF, all BPMN processes are started via messages. Therefore, a [Message Start Event](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/message-events/#message-start-event) has to be included at the beginning of all of your BPMN models. -#### Message Intermediate Throwing Event +### Message Intermediate Throwing Event [Message Intermediate Throwing Events](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/message-events/#message-intermediate-throwing-event) are used to send messages during process execution. -#### Message Intermediate Catching Event -[Message Intermediate Catching Events](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/message-events/#message-intermediate-catching-event) serve as the counterpart to [Message Intermediate Throwing Events](messaging.md#message-intermediate-throwing-event). Use them whenever you expect to receive a message from another process or organization during execution. +### Message Intermediate Catching Event +[Message Intermediate Catching Events](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/message-events/#message-intermediate-catching-event) serve as the counterpart to [Message Intermediate Throwing Events](messaging.md#message-intermediate-throwing-event). Use them whenever it is expected to receive a message from another process or organization during execution. -#### Message End Event +### Message End Event The [Message End Event](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/message-events/#message-end-event) will stop the execution of a BPMN process and finish by sending a message. \ No newline at end of file diff --git a/docs/src/process-development/api-v1/bpmn/sequence-flow.md b/docs/src/process-development/api-v1/bpmn/sequence-flow.md index 3650cc635..2a248406d 100644 --- a/docs/src/process-development/api-v1/bpmn/sequence-flow.md +++ b/docs/src/process-development/api-v1/bpmn/sequence-flow.md @@ -3,5 +3,5 @@ title: Sequence Flow icon: creative --- -### Sequence Flow +## Sequence Flow BPMN 2.0 calls the continuous arrows connecting the BPMN elements in BPMN models, Sequence Flow. Sequence Flow exits one BPMN element and points at the next BPMN element to be processed. diff --git a/docs/src/process-development/api-v1/bpmn/service-tasks.md b/docs/src/process-development/api-v1/bpmn/service-tasks.md index ebe8ad3c9..4128d5a2e 100644 --- a/docs/src/process-development/api-v1/bpmn/service-tasks.md +++ b/docs/src/process-development/api-v1/bpmn/service-tasks.md @@ -3,6 +3,6 @@ title: Service Tasks icon: creative --- -### Service Tasks +## Service Tasks -One of the most common types of BPMN Tasks used for modeling DSF processes is the [Service Task](https://docs.camunda.org/manual/7.21/reference/bpmn20/tasks/service-task/). They are different from regular BPMN Tasks in that they offer the ability to link an implementation to the [Service Task](https://docs.camunda.org/manual/7.21/reference/bpmn20/tasks/service-task/) which can be called and executed by a BPMN engine. The BPE (Business Process Engine) server of the DSF leverages this engine to execute your BPMN processes. \ No newline at end of file +One of the most common types of BPMN Tasks used for modeling DSF processes is the [Service Task](https://docs.camunda.org/manual/7.21/reference/bpmn20/tasks/service-task/). They are different from regular BPMN Tasks in that they offer the ability to link an implementation to the [Service Task](https://docs.camunda.org/manual/7.21/reference/bpmn20/tasks/service-task/) which can be called and executed by a BPMN engine. The BPE (Business Process Engine) server of the DSF leverages this engine to execute BPMN processes. diff --git a/docs/src/process-development/api-v1/bpmn/timer-intermediate-catching-events.md b/docs/src/process-development/api-v1/bpmn/timer-intermediate-catching-events.md index 49ab4a8fc..ff19cb3a8 100644 --- a/docs/src/process-development/api-v1/bpmn/timer-intermediate-catching-events.md +++ b/docs/src/process-development/api-v1/bpmn/timer-intermediate-catching-events.md @@ -3,6 +3,6 @@ title: Timer Intermediate Catching Events icon: creative --- -### Timer Intermediate Catching Events +## Timer Intermediate Catching Events -A [Timer Intermediate Catching Event](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/timer-events/#timer-intermediate-catching-event) allows you to model stopwatch behavior. A timer is started once the BPMN execution arrives at the event. The duration until the timer runs out is specified using the [ISO 8601 Durations](http://en.wikipedia.org/wiki/ISO_8601#Durations) format. Examples can be found [here](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/timer-events/#time-duration). After running out, the BPMN process executes the [Sequence Flow](sequence-flow.md) following the [Timer Intermediate Catching Event](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/timer-events/#timer-intermediate-catching-event). \ No newline at end of file +A [Timer Intermediate Catching Event](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/timer-events/#timer-intermediate-catching-event) allows for modelling stopwatch behavior. A timer is started once the BPMN execution arrives at the event. The duration until the timer runs out is specified using the [ISO 8601 Durations](http://en.wikipedia.org/wiki/ISO_8601#Durations) format. Examples can be found [here](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/timer-events/#time-duration). After running out, the BPMN process executes the [Sequence Flow](sequence-flow.md) following the [Timer Intermediate Catching Event](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/timer-events/#timer-intermediate-catching-event). diff --git a/docs/src/process-development/api-v1/bpmn/user-tasks.md b/docs/src/process-development/api-v1/bpmn/user-tasks.md index 8dda98d17..a34f257f7 100644 --- a/docs/src/process-development/api-v1/bpmn/user-tasks.md +++ b/docs/src/process-development/api-v1/bpmn/user-tasks.md @@ -3,6 +3,6 @@ title: User Tasks icon: creative --- -### User Tasks +## User Tasks -User Tasks define a process step that requires some kind of human interaction. Usually this is done by providing some kind of form the user can fill out. The Camunda Modeler allows to configure these forms as either a propriatary format called [Camunda Forms](https://docs.camunda.io/docs/guides/utilizing-forms/) or custom forms called `Embedded or External Task Forms`. The DSF uses such `External Task Forms` in the form of [Questionnaire](https://www.hl7.org/fhir/R4/questionnaire.html) and [Questionnaire Response](https://www.hl7.org/fhir/R4/questionnaireresponse.html) resources. This mechanism is further expanded upon in [User Tasks in the DSF](../guides/user-tasks-in-the-dsf.md). \ No newline at end of file +User Tasks define a process step that requires some kind of human interaction. Usually this is done by providing some kind of form the user can fill out. The Camunda Modeler allows to configure these forms as either a proprietary format called [Camunda Forms](https://docs.camunda.io/docs/guides/utilizing-forms/) or custom forms called `Embedded or External Task Forms`. The DSF uses such `External Task Forms` in the form of [Questionnaire](https://www.hl7.org/fhir/R4/questionnaire.html) and [Questionnaire Response](https://www.hl7.org/fhir/R4/questionnaireresponse.html) resources. This mechanism is further expanded upon in [User Tasks in the DSF](../guides/user-tasks-in-the-dsf.md). diff --git a/docs/src/process-development/api-v1/dsf/bpmn-process-execution.md b/docs/src/process-development/api-v1/dsf/bpmn-process-execution.md index f711532c9..94a9b04ec 100644 --- a/docs/src/process-development/api-v1/dsf/bpmn-process-execution.md +++ b/docs/src/process-development/api-v1/dsf/bpmn-process-execution.md @@ -3,6 +3,6 @@ title: BPMN Process Execution icon: creative --- -### BPMN Process Execution +## BPMN Process Execution -The BPMN process execution is the in-memory representation of a running BPMN process. BPMN processes have their executions structured as a tree hierarchy. Each BPMN process starts with the [process instance](https://docs.camunda.org/manual/7.21/user-guide/process-engine/process-engine-concepts/#process-instances) as its root level execution. If, for example, this root execution reaches a parallel gateway with two paths, it would spawn two child executions under itself for them to process all tasks along their paths on their own. Executions can access all the BPMN elements from the BPMN model as well as the [BPMN process variables](bpmn-process-variables.md). You have access to this representation in your Java code through the `execution` parameter when overriding certain methods in [Service](service-delegates.md) / [Message](message-delegates.md) Delegates like `execute` or `getAdditionalInputParameters` through the `variables` parameter. \ No newline at end of file +The BPMN process execution is the in-memory representation of a running BPMN process. BPMN processes have their executions structured as a tree hierarchy. Each BPMN process starts with the [process instance](https://docs.camunda.org/manual/7.21/user-guide/process-engine/process-engine-concepts/#process-instances) as its root level execution. If, for example, this root execution reaches a parallel gateway with two paths, it would spawn two child executions under itself for them to process all tasks along their paths on their own. Executions can access all the BPMN elements from the BPMN model as well as the [BPMN process variables](bpmn-process-variables.md). Access to this representation in the Java code is provided through the `execution` parameter when overriding certain methods in [Service](service-delegates.md) / [Message](message-delegates.md) Delegates like `execute` or `getAdditionalInputParameters`. \ No newline at end of file diff --git a/docs/src/process-development/api-v1/dsf/bpmn-process-variables.md b/docs/src/process-development/api-v1/dsf/bpmn-process-variables.md index 6170e1b1e..cd2baf68e 100644 --- a/docs/src/process-development/api-v1/dsf/bpmn-process-variables.md +++ b/docs/src/process-development/api-v1/dsf/bpmn-process-variables.md @@ -3,8 +3,8 @@ title: BPMN Process Variables icon: creative --- -### BPMN Process Variables +## BPMN Process Variables BPMN process variables hold additional information which has to be available during BPMN process execution. Variables can be directly related to BPMN elements like the boolean value for [Conditions](../bpmn/conditions.md), but do not have to be. BPMN process variables are stored as key-value pairs with the key being the variable name. They are accessible during the entirety of the execution to all [Service](service-delegates.md) / [Message](message-delegates.md) Delegates. -You can learn how to access to the BPMN process variables [here](../guides/accessing-bpmn-process-variables.md). \ No newline at end of file +More information on how to access to the BPMN process variables is found in the guide on accessing [BPMN process variables](../guides/accessing-bpmn-process-variables.md). diff --git a/docs/src/process-development/api-v1/dsf/draft-task-resources.md b/docs/src/process-development/api-v1/dsf/draft-task-resources.md index c1bcaa28c..c8ed0e4f4 100644 --- a/docs/src/process-development/api-v1/dsf/draft-task-resources.md +++ b/docs/src/process-development/api-v1/dsf/draft-task-resources.md @@ -3,9 +3,9 @@ title: Draft Task Resources icon: creative --- -### Draft Task Resources +## Draft Task Resources -[Task](../fhir/task.md) resources with status `draft` are used to create the DSF FHIR server's functionality of starting processes via its web interface. They are stored in `.../tutorial-process/src/main/resources/fhir/Task`. Compared to regular [Task](../fhir/task.md) resources used to start BPMN processes, this type of [Task](../fhir/task.md) resource requires the status `draft` instead the usual `requested`. It also replaces the value for `authoredOn` with the placeholder `#{date}`, the values of organization identifiers with the placeholder `#{organization}` and all instances of version numbers with `#{version}`. Additionally, it requires setting the `Task.identifier` element. It should look something like this: +[Task](../fhir/task.md) resources with status `draft` are used to create the DSF FHIR server's functionality of starting processes via its web interface. They are stored in `.../tutorial-process/src/main/resources/fhir/Task`. Compared to regular [Task](../fhir/task.md) resources used to start BPMN processes, this type of [Task](../fhir/task.md) resource requires the status `draft` instead of the usual `requested`. It also replaces the value for `authoredOn` with the placeholder `#{date}`, the values of organization identifiers with the placeholder `#{organization}` and all instances of version numbers with `#{version}`. Additionally, it requires setting the `Task.identifier` element. It should look something like this: ```xml <identifier> @@ -14,8 +14,8 @@ icon: creative </identifier> ``` `processKey` should be the same one used in [URLs](versions-placeholders-urls.md#urls). -`task-name` can be any String you wish to identify this task with. E.g. you can use the file name of the Draft Task. +`task-name` can be any String this task should be identified with. E.g. you can use the file name of the Draft Task. -For a complete example you can take a look at the Draft Task Resource in one of the solution branches and compare it to the one needed for cURL. The [Task](../fhir/task.md) resource created for cURL can be found at `.../tutorial-process/src/main/resources/example-task.xml`. +A complete example for a Draft Task Resource can be found in the [Ping Pong Process Plugin](https://github.com/datasharingframework/dsf-process-ping-pong/blob/main/src/main/resources/fhir/Task/dsf-task-start-ping.xml). -You might also want to check out [this guide](../guides/creating-task-resources-based-on-a-definition.md) if you do not know how to create [Task](../fhir/task.md) resources in general. \ No newline at end of file +There is also a [guide for creating task resources based on a StructureDefinition](../guides/creating-task-resources-based-on-a-definition.md) if more information on how to create [Task](../fhir/task.md) resources is required. diff --git a/docs/src/process-development/api-v1/dsf/environment-variables.md b/docs/src/process-development/api-v1/dsf/environment-variables.md index fcea6697c..4f0b5bd7e 100644 --- a/docs/src/process-development/api-v1/dsf/environment-variables.md +++ b/docs/src/process-development/api-v1/dsf/environment-variables.md @@ -3,8 +3,8 @@ title: Environment Variables icon: creative --- -### Environment Variables +## Environment Variables -Environment variables offer a way to make configuration data available at the start of a [BPMN process execution](bpmn-process-execution.md). They are the same for all running process instances. They can be defined by adding a member variable with the [Spring-Framework @Value](https://docs.spring.io/spring-framework/docs/current/reference/html/core.html#beans-value-annotations) annotation to the configuration class `TutorialConfig`. The value of the annotation uses the `${..}` notation and follows the form `${some.property:defaultValue}`, where each dot in the property name corresponds to an underscore in the equivalent environment variable. Environment variables are always written upper-case. The property `some.property` therefore corresponds to the environment variable `SOME_PROPERTY`. +Environment variables offer a way to make configuration data available at the start of a [BPMN process execution](bpmn-process-execution.md). They are the same for all running process instances. They can be defined by adding a member variable with the [Spring-Framework @Value](https://docs.spring.io/spring-framework/docs/current/reference/html/core.html#beans-value-annotations) annotation to any Spring managed bean. For the DSF, the most prominent are classes annotated with [`@Configuration`](https://docs.spring.io/spring-framework/reference/core/beans/java/configuration-annotation.html). The value of the annotation uses the `${..}` notation and follows the form `${some.property:defaultValue}`, where each dot in the property name corresponds to an underscore in the equivalent environment variable. Environment variables are always written upper-case. The property `some.property` therefore corresponds to the environment variable `SOME_PROPERTY`. -The DSF provides a feature to automatically generate documentation of environment variables during the Maven build process. You can use the `@ProcessDocumentation` annotation to automatically generate Markdown documentation for all fields with this annotation. You simply have to add [dsf-tools-documentation-generator](https://mvnrepository.com/artifact/dev.dsf/dsf-tools-documentation-generator) as a maven plugin. You can take a look at the `pom.xml` for the `tutorial-process` submodule [here](https://github.com/datasharingframework/dsf-process-tutorial/blob/main/tutorial-process/pom.xml) to see how you can add it to your own project. Keep in mind to point the `<workingPackage>` field to the package you want documentation for. \ No newline at end of file +The DSF provides a feature to automatically generate documentation of environment variables during the Maven build process. The `@ProcessDocumentation` annotation can be used to automatically generate Markdown documentation for all fields with this annotation. This requires adding [dsf-tools-documentation-generator](https://mvnrepository.com/artifact/dev.dsf/dsf-tools-documentation-generator) as a maven plugin. There is an example `pom.xml` for the `tutorial-process` submodule located on [GitHub](https://github.com/datasharingframework/dsf-process-tutorial/blob/main/tutorial-process/pom.xml) which uses the maven plugin. The `<workingPackage>` field has to point to the package where documentation is desired. diff --git a/docs/src/process-development/api-v1/dsf/message-correlation.md b/docs/src/process-development/api-v1/dsf/message-correlation.md index 23b18e3e3..2c7ba5a10 100644 --- a/docs/src/process-development/api-v1/dsf/message-correlation.md +++ b/docs/src/process-development/api-v1/dsf/message-correlation.md @@ -3,8 +3,8 @@ title: Message Correlation icon: creative --- -### Message Correlation +## Message Correlation -In order for messages to be able to be sent back and forth between organizations with potentially multiple of the same process plugin instances running at the same time and still arriving at the correct process instance, we need some mechanism to map messages to their rightful process instance. This mechanism is called Message Correlation and requires attaching a unique identifier to every process instance. This identifier is called the `business-key`. The `business-key` will get attached to every outgoing message automatically. +In order for messages to be able to be sent back and forth between organizations with potentially multiple of the same process plugin instances running at the same time and still arriving at the correct process instance, some mechanism is needed to map messages to their rightful process instance. This mechanism is called Message Correlation and requires attaching a unique identifier to every process instance. This identifier is called the `business-key`. The `business-key` will get attached to every outgoing message automatically. -It is possible that the `business-key` is insufficient to map messages to the correct process instance. This happens when you use subprocesses in your BPMN model which all expect messages to be sent to them, not the parent process. To solve this issue, [Task](../fhir/task.md) resources also come with an [Input Parameter](../fhir/task.md#task-input-parameters) called `correlation-key`. This is a secondary identifier you can attach to all messages if you need them to arrive at a specific subprocess. You can learn more about how `correlation-keys` are used by studying the [Ping-Pong Process](https://github.com/datasharingframework/dsf-process-ping-pong). \ No newline at end of file +It is possible that the `business-key` is insufficient to map messages to the correct process instance. This happens during subprocesses in your BPMN model which all expect messages to be sent to them, not the parent process. To solve this issue, [Task](../fhir/task.md) resources also come with an [Input Parameter](../fhir/task.md#task-input-parameters) called `correlation-key`. This is a secondary identifier that has to be attached to all messages in order for them to arrive at a specific subprocess. This is done when creating [targets](../dsf/target-and-targets.md#targets) for outgoing messages and requires setting the `correlation-key` as a local variable using the constant `BpmnExecutionVariables.CORRELATION_KEY` before a message is received in the subprocess. diff --git a/docs/src/process-development/api-v1/dsf/message-delegates.md b/docs/src/process-development/api-v1/dsf/message-delegates.md index 61a1a06f1..3c95d96a9 100644 --- a/docs/src/process-development/api-v1/dsf/message-delegates.md +++ b/docs/src/process-development/api-v1/dsf/message-delegates.md @@ -3,13 +3,17 @@ title: Message Delegates icon: creative --- -### Message Delegates +## Message Delegates -Message Delegates are the Java representation of the [Message Events](../bpmn/messaging.md) in your BPMN model. You link a Message Delegate to a certain [Message Event](../bpmn/messaging.md) by selecting the Message Event in the [Camunda Modeler](https://camunda.com/download/modeler/) and adding a Java class to the `Implementation` field. Make sure you use the fully qualified class name. Like this: +Message Delegates are the Java representation of the [Message Events](../bpmn/messaging.md) in a BPMN model. Message Delegates are linked to a certain [Message Event](../bpmn/messaging.md) by selecting the Message Event in the [Camunda Modeler](https://camunda.com/download/modeler/) and adding a Java class to the `Implementation` field. This uses the fully qualified class name. For example: ``` -org.package.myClass +org.package.MyClass ``` -You will only need Message Delegates for [Message Send Events](../bpmn/messaging.md). Incoming messages will be resolved to the correct [BPMN process execution](bpmn-process-execution.md) automatically using [Message Correlation](message-correlation.md) and the message inputs will be added to that execution's [process variables](bpmn-process-variables.md). +Message Delegates are only needed for [Message Send Events](../bpmn/messaging.md). Incoming messages will be resolved to the correct [BPMN process execution](bpmn-process-execution.md) automatically using [Message Correlation](message-correlation.md) and the message inputs will be added to that execution's [process variables](bpmn-process-variables.md). -To make a Message Delegate for [Message Send Events](../bpmn/messaging.md), your Java class needs to extend `AbstractTaskMessageSend`. Most of the time, you will not be adding any processing logic to your Message Delegates, therefore you usually won't be overwriting the `doExecute` method like with [Service Delegates](service-delegates.md). Instead, you most likely want to aggregate the information you processed in earlier steps and attach it to a message. For this you need to overwrite the `getAdditionalInputParamters` method. The DSF translates BPMN messages into FHIR [Task](../fhir/task.md) resources to execute the communication modeled by your BPMN diagrams. The information you are sending to another BPMN process is specified in the Task.input elements a.k.a. [Input Parameters](../fhir/task.md#task-input-parameters), hence the name of the method. The constructor of your delegate class should also forward a `ProcessPluginApi` instance to its superclass constructor. You can learn more about the `ProcessPluginApi` [here](process-plugin-api.md). +To make a Message Delegate for [Message Send Events](../bpmn/messaging.md), the Java class needs to extend `AbstractTaskMessageSend`. Most of the time, there will not be any processing logic inside Message Delegates, therefore the `execute` method will not be overridden like with [Service Delegates](../dsf/service-delegates.md). Although there might be cases where this is necessary. Instead, Message Delegates should be used to aggregate previously computed data and attach it to the message. This is done by overriding the `getAdditionalInputParamters` method. The DSF translates BPMN messages into FHIR [Task](../fhir/task.md) resources to execute the communication modeled in BPMN diagrams. The information being sent to another BPMN process is specified in the Task.input elements a.k.a. [Input Parameters](../fhir/task.md#task-input-parameters), hence the name of the method. The constructor of your delegate class should also forward a `ProcessPluginApi` instance to its superclass constructor. + + +## Related Topics +[Messaging](../bpmn/messaging.md), [Input Parameters](../fhir/task.md#task-input-parameters), [Adding Input Parameter to Task Profiles](../guides/adding-task-input-parameters-to-task-profiles.md) \ No newline at end of file diff --git a/docs/src/process-development/api-v1/dsf/organization-identifiers.md b/docs/src/process-development/api-v1/dsf/organization-identifiers.md index 691a551d8..dfb78a204 100644 --- a/docs/src/process-development/api-v1/dsf/organization-identifiers.md +++ b/docs/src/process-development/api-v1/dsf/organization-identifiers.md @@ -3,8 +3,11 @@ title: Organization Identifiers icon: creative --- -### Organization Identifiers -DSF FHIR server instances always have something called an `organization identifer`. It uniquely identifies the organization the DSF FHIR server instance belongs to for its [Allow-List mechanism](https://dsf.dev/intro/info/allowList.html). It is configured as an [environment variable](https://dsf.dev/operations/latest/fhir/configuration.html#dev-dsf-fhir-server-organization-identifier-value). You can make a GET request to `https://domain/fhir/Organization` to get a list of all organizations for the DSF FHIR server instance running under `domain`. The results will also include the `organization identifier` of each organization. +## Organization Identifiers +DSF FHIR server instances can configure an `organization identifier`. It uniquely identifies the organization the DSF FHIR server instance belongs to for its [Allow-List mechanism](https://dsf.dev/intro/info/allowList.html). It is set as an [environment variable](https://dsf.dev/stable/maintain/fhir/configuration.html#dev-dsf-fhir-server-organization-identifier-value). A GET request to `https://domain/fhir/Organization` will return a list of all organizations for the DSF FHIR server instance running under `domain`. The results will also include the `organization identifier` of each organization. -#### Organization Identifiers in Task Resources -[Task](../fhir/task.md) resources require you to reference an organization via its identifier as the `Task.requester` and `Task.restriction.recipient` elements. The exact values for these elements depend on the [ActivityDefinition](../fhir/activitydefinition.md) the [Task](../fhir/task.md) resource should conform to. As a general rule, you will want to put the identifier of your own organization as the `Task.requester` and `Task.restriction.recipient` elements for [Task](../fhir/task.md) resources which initially start processes. All other cases depend on the context of the message being sent during process execution. \ No newline at end of file +### Organization Identifiers in Task Resources +[Task](../fhir/task.md) resources require a reference to an organization via its identifier as the `Task.requester` and `Task.restriction.recipient` elements. The exact values for these elements depend on the [ActivityDefinition](../fhir/activitydefinition.md) the [Task](../fhir/task.md) resource should conform to. As a general rule, the identifier of your own organization should be used as the `Task.requester` and `Task.restriction.recipient` elements for [Task](../fhir/task.md) resources which initially start processes. All other cases depend on the context of the message being sent during process execution. An easy way to generalize this in [Draft Task Resources](draft-task-resources.md) is to use the `#{organization}` [placeholder](versions-placeholders-urls.md#placeholders). + +## Related Topics +[Allow-List](https://dsf.dev/intro/info/allowList.html), [ActivityDefinition](../fhir/activitydefinition.md), [Environment Variables](environment-variables.md), [Requester and Recipient](requester-and-recipient.md), [Task](../fhir/task.md) \ No newline at end of file diff --git a/docs/src/process-development/api-v1/dsf/process-plugin-api.md b/docs/src/process-development/api-v1/dsf/process-plugin-api.md index 5d1381a5a..f09d3ef3b 100644 --- a/docs/src/process-development/api-v1/dsf/process-plugin-api.md +++ b/docs/src/process-development/api-v1/dsf/process-plugin-api.md @@ -3,9 +3,9 @@ title: Process Plugin API icon: creative --- -### Process Plugin API v1 Maven Module +## Process Plugin API Maven Module -The [DSF Process Plugin API module](https://mvnrepository.com/artifact/dev.dsf/dsf-bpe-process-api-v1) consists of a set of utility classes designed to provide easy access to solutions for process plugin use cases. This includes for example the `Variables` class, which provides access to the [BPMN process variables](bpmn-process-variables.md). +The [DSF Process Plugin API module](https://central.sonatype.com/artifact/dev.dsf/dsf-bpe-process-api-v2) consists of a set of utility classes designed to provide easy access to common solutions for process plugin use cases which would otherwise require lots of boilerplate code. An example is the `Variables` class, which provides access to the [BPMN process variables](bpmn-process-variables.md). Maven Dependency: @@ -20,9 +20,9 @@ Maven Dependency: </dependencies> ``` -#### Process Plugin Api -When creating [Service Delegates](service-delegates.md) or [Message Delegates](message-delegates.md) you wil notice that you need to provide a constructor which expects a `ProcessPluginApi` object and forward it to the superclasses' constructor. -This API instance provides a variety of utility classes: +### Process Plugin Api +[Service Delegates](service-delegates.md) or [Message Delegates](message-delegates.md) require a constructor which expects a `ProcessPluginApi` object which is forwarded to the superclasses' constructor. The API instance can then be used when overriding their `execute` and/or `getAdditionalInputParameters` methods. +It provides the following utility classes: - `ProxyConfig`**:** forward proxy configuration - `EndpointProvider`**:** access to Endpoint resources - `FhirContext`**:** HAPI FHIR Context for parsing/serializing diff --git a/docs/src/process-development/api-v1/dsf/process-plugin-definition.md b/docs/src/process-development/api-v1/dsf/process-plugin-definition.md index a13bdbe26..498ae2514 100644 --- a/docs/src/process-development/api-v1/dsf/process-plugin-definition.md +++ b/docs/src/process-development/api-v1/dsf/process-plugin-definition.md @@ -3,14 +3,17 @@ title: Process Plugin Definition icon: creative --- -### Process Plugin Definition +## Process Plugin Definition -In order for the DSF BPE server to load your plugin you need to provide it with the following information: +In order for the DSF BPE server to load a plugin properly, it needs to provide the following information in what is called the process plugin definition: * A plugin [version](versions-placeholders-urls.md#version-pattern) * A release date * A plugin name * The BPMN model files -* The FHIR resources grouped by BPMN process ID. Your plugin may have any number of BPMN models. Each has their own BPMN process ID and FHIR resources specific to that BPMN process (think [Task](../fhir/task.md) resources needed for messages specific to that BPMN model) -* The Class holding your [Spring Framework Configuration](spring-framework-integration.md) +* The FHIR resources grouped by BPMN process ID. A plugin may have any number of BPMN models. Each has their own BPMN process ID and FHIR resources specific to that BPMN process (like [Task](../fhir/task.md) resources needed for messages specific to that BPMN model) +* The Class holding a [Spring Framework Configuration](spring-framework-integration.md) -You will provide this information by implementing the `dev.dsf.bpe.ProcessPluginDefinition` interface. The DSF BPE server then searches for classes implementing this interface using the Java [ServiceLoader](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/ServiceLoader.html) mechanism. Therefore, you will have to register your interface implementation in the `src/main/resources/META-INF/services/dev.dsf.bpe.ProcessPluginDefinition` file. For this tutorial, the class implementing the `ProcessPluginDefinition` interface, `TutorialProcessPluginDefinition`, has already been added to the file. You can use it as a reference for later when you want to create your own plugin. \ No newline at end of file +To provide this information, one of the classes in the process plugin has to implement the `dev.dsf.bpe.ProcessPluginDefinition` interface. The DSF BPE server then searches for classes implementing this interface using the Java [ServiceLoader](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/ServiceLoader.html) mechanism. Therefore, the class also needs to be registered in the `src/main/resources/META-INF/services/dev.dsf.bpe.ProcessPluginDefinition` file. An example of this can be found in the [process plugin tutorial](https://github.com/datasharingframework/dsf-process-tutorial/). + +## Related Topics +[Spring Integration](spring-framework-integration.md), [Versions, Placeholders and URLs](versions-placeholders-urls.md) diff --git a/docs/src/process-development/api-v1/dsf/read-access-tag.md b/docs/src/process-development/api-v1/dsf/read-access-tag.md index 47a02b2c1..90aad4ced 100644 --- a/docs/src/process-development/api-v1/dsf/read-access-tag.md +++ b/docs/src/process-development/api-v1/dsf/read-access-tag.md @@ -3,9 +3,9 @@ title: Read Access Tag icon: creative --- -### Read Access Tag +## Read Access Tag -Axiomatically, nobody is allowed to write FHIR resources (except [Task](../fhir/task.md)) to the DSF FHIR server unless it is your own organization. By default, the same applies to reading FHIR resources (again except [Task](../fhir/task.md)). But since the DSF is often used to offer medical data in form of FHIR resources, you will find yourself wanting other organizations to be allowed to read the resources you are offering. The `Resource.meta.tag` element is used define access rules for all FHIR resources in the DSF, with the exception of [Task](../fhir/task.md) resources. We will explain the reason for this exception shortly. For example, allowing read access for all organizations, you would use the following `system` and `code` in your FHIR resource: +Axiomatically, nobody is allowed to write FHIR resources (except [Task](../fhir/task.md)) to the DSF FHIR server unless it is the organization running the instance, which is [configurable](https://dsf.dev/operations/latest/fhir/configuration.html#dev-dsf-fhir-server-organization-identifier-value). By default, the same applies to reading FHIR resources (again except [Task](../fhir/task.md)). But since the DSF is often used to offer medical data in form of FHIR resources, other organizations should be allowed to read some of the resources on the DSF FHIR server. The `Resource.meta.tag` element is used define access rules for all FHIR resources in the DSF, with the exception of [Task](../fhir/task.md) resources. For example, allowing read access for all organizations would use the following `system` and `code` in your FHIR resource: ```xml <meta> @@ -15,8 +15,11 @@ Axiomatically, nobody is allowed to write FHIR resources (except [Task](../fhir/ </tag> </meta> ``` -You can find all codes for the Read Access Tag in its [CodeSystem](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/CodeSystem/dsf-read-access-tag-1.0.0.xml). +All codes for the Read Access Tag can be found in its [CodeSystem](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/CodeSystem/dsf-read-access-tag-1.0.0.xml). -The read access rules for [Task](../fhir/task.md) resources are defined through the `requester` and `recipient` elements of the [dsf-extension-process-authorization](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-extension-process-authorization-1.0.0.xml) in your plugin's [ActivityDefinitions](../fhir/activitydefinition.md). Therefore, no `read-access-tag` is needed. +The read access rules for [Task](../fhir/task.md) resources are defined through the `requester` and `recipient` elements of the [dsf-extension-process-authorization](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-extension-process-authorization-1.0.0.xml) in a plugin's [ActivityDefinitions](../fhir/activitydefinition.md). Therefore, no `read-access-tag` is needed. -It is also possible to restrict read access of FHIR resources to organizations with a specific role in a parent organization or a specific identifier. If you want to find out more, you may look at the [guide on configuring the Read Access Tag](../guides/configuring-read-access-tags.md). +It is also possible to restrict read access of FHIR resources to organizations with a specific role in a parent organization or a specific identifier. More information on that can be found in the [guide on configuring the Read Access Tag](../guides/configuring-read-access-tags.md). + +## Related Topics +[Configuring Read Access Tags](../guides/configuring-read-access-tags.md) diff --git a/docs/src/process-development/api-v1/dsf/requester-and-recipient.md b/docs/src/process-development/api-v1/dsf/requester-and-recipient.md index 8407bb318..0aa1a7e9d 100644 --- a/docs/src/process-development/api-v1/dsf/requester-and-recipient.md +++ b/docs/src/process-development/api-v1/dsf/requester-and-recipient.md @@ -3,11 +3,11 @@ title: Requester and Recipient icon: creative --- -### Requester and Recipient Elements +## Requester and Recipient Elements -Below you will find a set of examples for each Coding used by `requester` and `recipient` elements from the [dsf-extension-process-authorization](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-extension-process-authorization-1.0.0.xml). CodeSystems referenced in the examples can be found [here](https://github.com/datasharingframework/dsf/tree/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/CodeSystem). Use this collection as a reference point when creating your own [ActivityDefinitions](../fhir/activitydefinition.md). +Below is a set of examples for each Coding used by `requester` and `recipient` elements from the [dsf-extension-process-authorization](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-extension-process-authorization-1.0.0.xml). CodeSystems referenced in the examples can be found [here](https://github.com/datasharingframework/dsf/tree/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/CodeSystem). This collection aims to provide a reference point when creating [ActivityDefinitions](../fhir/activitydefinition.md). -#### Requester +### Requester The `requester` element uses one of the following Codings: ```xml <profile value="http://dsf.dev/fhir/StructureDefinition/coding-process-authorization-local-all|1.0.0" /> @@ -21,7 +21,7 @@ The `requester` element uses one of the following Codings: <profile value="http://dsf.dev/fhir/StructureDefinition/coding-process-authorization-remote-parent-organization-role|1.0.0" /> ``` -##### Local All +#### Local All ```xml <extension url="requester"> <valueCoding> @@ -31,7 +31,7 @@ The `requester` element uses one of the following Codings: </extension> ``` -##### Local All Practitioner +#### Local All Practitioner ```xml <extension url="requester"> <valueCoding> @@ -47,7 +47,7 @@ The `requester` element uses one of the following Codings: </extension> ``` -##### Local Organization +#### Local Organization ```xml <extension url="requester"> <valueCoding> @@ -63,7 +63,7 @@ The `requester` element uses one of the following Codings: </extension> ``` -##### Local Organization Practitioner +#### Local Organization Practitioner ```xml <extension url="requester"> <valueCoding> @@ -87,7 +87,7 @@ The `requester` element uses one of the following Codings: </extension> ``` -##### Local Parent Organization Role +#### Local Parent Organization Role ```xml <extension url="requester"> <valueCoding> @@ -111,7 +111,7 @@ The `requester` element uses one of the following Codings: </extension> ``` -##### Local Parent Organization Role Practitioner +#### Local Parent Organization Role Practitioner ```xml <extension url="requester"> <valueCoding> @@ -141,7 +141,7 @@ The `requester` element uses one of the following Codings: </extension> ``` -##### Remote All +#### Remote All ```xml <extension url="requester"> <valueCoding> @@ -151,7 +151,7 @@ The `requester` element uses one of the following Codings: </extension> ``` -##### Remote Organization +#### Remote Organization ```xml <extension url="requester"> <valueCoding> @@ -167,7 +167,7 @@ The `requester` element uses one of the following Codings: </extension> ``` -##### Remote Parent Organization Role +#### Remote Parent Organization Role ```xml <extension url="requester"> <valueCoding> @@ -191,7 +191,7 @@ The `requester` element uses one of the following Codings: </extension> ``` -#### Recipient +### Recipient The `recipeint` element uses one of the following Codings: ```xml <profile value="http://dsf.dev/fhir/StructureDefinition/coding-process-authorization-local-all|1.0.0" /> @@ -199,7 +199,7 @@ The `recipeint` element uses one of the following Codings: <profile value="http://dsf.dev/fhir/StructureDefinition/coding-process-authorization-local-parent-organization-role|1.0.0" /> ``` -##### Local All +#### Local All ```xml <extension url="recipient"> <valueCoding> @@ -209,7 +209,7 @@ The `recipeint` element uses one of the following Codings: </extension> ``` -##### Local Organization +#### Local Organization ```xml <extension url="recipient"> <valueCoding> @@ -225,7 +225,7 @@ The `recipeint` element uses one of the following Codings: </extension> ``` -##### Local Parent Organization Role +#### Local Parent Organization Role ```xml <extension url="recipient"> <valueCoding> @@ -248,3 +248,7 @@ The `recipeint` element uses one of the following Codings: </valueCoding> </extension> ``` + + +## Related Topics +[ActivityDefinition](../fhir/activitydefinition.md) diff --git a/docs/src/process-development/api-v1/dsf/service-delegates.md b/docs/src/process-development/api-v1/dsf/service-delegates.md index 278b51e34..1a9bd18cd 100644 --- a/docs/src/process-development/api-v1/dsf/service-delegates.md +++ b/docs/src/process-development/api-v1/dsf/service-delegates.md @@ -3,10 +3,13 @@ title: Service Delegates icon: creative --- -### Service Delegates +## Service Delegates -Service Delegates are the Java representation of the [Service Tasks](../bpmn/service-tasks.md) in your BPMN model. You link a Service Delegate to a certain [Service Task](../bpmn/service-tasks.md) by selecting the [Service Task](../bpmn/service-tasks.md) in the [Camunda Modeler](https://camunda.com/download/modeler/) and adding a Java class to the `Implementation` field. Make sure you use the fully qualified class name. Like this: +Service Delegates are the Java representation of the [Service Tasks](../bpmn/service-tasks.md) in a BPMN model. Service Delegates are linked to a certain [Service Task](../bpmn/service-tasks.md) by selecting the [Service Task](../bpmn/service-tasks.md) in the [Camunda Modeler](https://camunda.com/download/modeler/) and adding a Java class to the `Implementation` field. This uses the fully qualified class name: ``` org.package.myClass ``` -All that is left is for your Java class to extend `AbstractServiceDelegate` and override the `doExecute` method. This is the place where you can put your actual business logic. The method will be called when the [BPMN process execution](bpmn-process-execution.md) arrives at the [Service Task](../bpmn/service-tasks.md) your Service Delegate is linked to. The constructor of your delegate class should also forward a `ProcessPluginApi` instance to its superclass constructor. You can learn more about the `ProcessPluginApi` [here](process-plugin-api.md). \ No newline at end of file +Java classes need to extend `AbstractServiceDelegate` and override the `doExecute` method. This method holds the actual business logic. The method will be called when the [BPMN process execution](../dsf/bpmn-process-execution.md) arrives at the [Service Task](../bpmn/service-tasks.md) a Service Delegate is linked to. The constructor of delegate classes also has to forward a `ProcessPluginApi` instance to its superclass constructor. An instance of the API can be [autowired](https://docs.spring.io/spring-framework/reference/core/beans/annotation-config/autowired.html) in the plugin's Spring configuration class when registering the delegate as a [Spring Bean](https://docs.spring.io/spring-framework/reference/core/beans/introduction.html). + +## Related Topics +[BPMN Process Execution](../dsf/bpmn-process-execution.md), [Message Delegates](message-delegates.md), [Process Plugin API](process-plugin-api.md), [Service Tasks](../bpmn/service-tasks.md) \ No newline at end of file diff --git a/docs/src/process-development/api-v1/dsf/spring-framework-integration.md b/docs/src/process-development/api-v1/dsf/spring-framework-integration.md index 55f96f342..8f6d080f9 100644 --- a/docs/src/process-development/api-v1/dsf/spring-framework-integration.md +++ b/docs/src/process-development/api-v1/dsf/spring-framework-integration.md @@ -3,12 +3,62 @@ title: Spring Framework Integration icon: creative --- -### Spring Framework Integration +## Spring Framework Integration -Since the DSF also employs the use of the [Spring Framework](https://spring.io/projects/spring-framework) you will also have to provide some Spring functionality. When deployed, every process plugin exists in its own [Spring context](https://docs.spring.io/spring-framework/reference/core/beans/introduction.html). To make the process plugin work, you have to provide [Spring Beans](https://docs.spring.io/spring-framework/reference/core/beans/definition.html) with `prototype` [scope](https://docs.spring.io/spring-framework/reference/core/beans/factory-scopes.html) for all classes which either extend or implement the following classes/interfaces (as of version 1.4.0): +The DSF uses some of the [Spring Framework's](https://spring.io/projects/spring-framework) functionality. When deployed, every process plugin exists in its own [Spring context](https://docs.spring.io/spring-framework/reference/core/beans/introduction.html). Process plugins require [Spring Beans](https://docs.spring.io/spring-framework/reference/core/beans/definition.html) with `prototype` [scope](https://docs.spring.io/spring-framework/reference/core/beans/factory-scopes.html) for all classes which either extend or implement the following classes/interfaces: - `AbstractTaskMessageSend` - `AbstractServiceDelegate` - `DefaultUserTaskListener` - `ProcessPluginDeploymentStateListener` -A [Spring-Framework configuration class](https://docs.spring.io/spring-framework/docs/current/reference/html/core.html#beans-java-basic-concepts) located in `spring/config` is expected to provide the Spring Beans. For this tutorial, the `TutorialConfig` class will take this role. If you are unfamiliar with the Spring Framework, you might want to check out the chapter [Java-based Container Configuration](https://docs.spring.io/spring-framework/reference/core/beans/java.html) of the Spring Framework documentation, specifically the topics [Using the @Bean Annotation](https://docs.spring.io/spring-framework/reference/core/beans/java/bean-annotation.html) and [Using the @Configuration Annotation](https://docs.spring.io/spring-framework/reference/core/beans/java/configuration-annotation.html). \ No newline at end of file +A [Spring-Framework configuration class](https://docs.spring.io/spring-framework/docs/current/reference/html/core.html#beans-java-basic-concepts) located in the `spring/config` directory is expected to provide the Spring Beans. If you are unfamiliar with the Spring Framework, you can find more information in [Java-based Container Configuration](https://docs.spring.io/spring-framework/reference/core/beans/java.html) of the Spring Framework documentation, specifically the topics [Using the @Bean Annotation](https://docs.spring.io/spring-framework/reference/core/beans/java/bean-annotation.html) and [Using the @Configuration Annotation](https://docs.spring.io/spring-framework/reference/core/beans/java/configuration-annotation.html). + +Below is an example of a Spring configuration class: +```java +@Configuration +public class TutorialConfig +{ + @Autowired + private ProcessPluginApi api; //instance will be injected at runtime + + @Value("${dev.dsf.process.tutorial.loggingEnabled:false}") + @ProcessDocumentation(description = "Set to true to enable logging", required = false, processNames = PROCESS_NAME_FULL_DIC) + private boolean loggingEnabled; //environment variable + + @Value("${dev.dsf.process.tutorial.userVote:false}") + @ProcessDocumentation(description = "Set to true to enable users to vote", required = false, processNames = PROCESS_NAME_FULL_VOTING_PROCESS) + private boolean userVote; //environment variable + + //register classes as prototype beans + @Bean + @Scope(SCOPE_PROTOTYPE) + public DicTask dicTask() + { + return new DicTask(api, loggingEnabled); + } + + @Bean + @Scope(SCOPE_PROTOTYPE) + public DecideWhetherUserVote decideWhetherUserVote() + { + return new DecideWhetherUserVote(api, userVote); + } + + @Bean + @Scope(SCOPE_PROTOTYPE) + public HelloCosMessage helloCosMessage() + { + return new HelloCosMessage(api); + } + + @Bean + @Scope(SCOPE_PROTOTYPE) + public UserVoteListener userVoteListener() + { + return new UserVoteListener(api); + } +} +``` + +## Related Topics +[Environment Variables](environment-variables.md), [Message Delegates](message-delegates.md), [Service Delegates](service-delegates.md) diff --git a/docs/src/process-development/api-v1/dsf/versions-placeholders-urls.md b/docs/src/process-development/api-v1/dsf/versions-placeholders-urls.md index 0381ec629..1fb0ecf0c 100644 --- a/docs/src/process-development/api-v1/dsf/versions-placeholders-urls.md +++ b/docs/src/process-development/api-v1/dsf/versions-placeholders-urls.md @@ -3,9 +3,9 @@ title: Versions, Placeholders and URLs icon: creative --- -### Versions, Placeholders and URLs +## Versions, Placeholders and URLs -#### Version Pattern +### Version Pattern Process plugin versions have to obey the pattern: ``` @@ -14,25 +14,28 @@ Process plugin versions have to obey the pattern: The first two numbers (`1.2`) are used in FHIR resources and signal changes which break compatibility with previous process versions. For example, altering FHIR resources usually results in a breaking change. The latter two (`3.4`) signal changes which do not break compatibility with previous process versions. Specifically, the 4th number is reserved for bug-fixes and the 3rd number includes all other non-breaking changes. -#### Placeholders +### Placeholders To avoid specifying the version and release date in multiple files, the placeholders `#{version}` and `#{date}` can be used within FHIR resources and BPMN models. They are replaced with the values returned by the methods `ProcessPluginDefinition#getResourceVersion` and `ProcessPluginDefinition#getReleaseDate` respectively during deployment of a process plugin by the DSF BPE server. There is also a placeholder for the organization the DSF instance is running in: `#{organization}`, typically use in [Draft Task Resources](draft-task-resources.md). -#### URLs +### URLs -BPMN models have an ID call process definition key. The BPMN process definition key needs to be specified following the pattern: +BPMN models have an ID called process definition key. The BPMN process definition key needs to be specified following the pattern: ``` ^[-a-zA-Z0-9]+_[-a-zA-Z0-9]+$ Example: domainorg_processKey ``` -In addition, the BPMN model needs to specify a version. You should be using the ``#{version}`` [placeholder](#placeholders) for this as well. The DSF will also reference this process in URL form in FHIR resources: +In addition, the BPMN model needs to specify a version. The `#{version}` [placeholder](#placeholders) should be used for this as well. The DSF will also reference this process in URL form in FHIR resources: ``` http://domain.org/bpe/Process/processKey|1.2 ``` -As you can see, the version in the URL ``|1.2`` only uses the resource version and omits the code base version. As mentioned in [Version Pattern](#version-pattern), this means that only changes to the first two version numbers are significant to signal compatibility when communicating with other process plugin instances. The process definition key and URL are also related to each other. The DSF will try to match BPMN models to FHIR resources by transforming the URL into a process definition key. That is why it is important you obey the pattern above. +The version in the URL `|1.2` only uses the resource version and omits the code base version. As mentioned in [Version Pattern](#version-pattern), this means that only changes to the first two version numbers are significant to signal compatibility when communicating with other process plugin instances. The process definition key and URL are also related to each other. The DSF will try to match BPMN models to FHIR resources by transforming the URL into a process definition key. That is why it is mandatory to follow the pattern above. -You will use the above URL as your instantiatesCanonical value for [Task](../fhir/task.md) profile definitions as well as references to [Task](../fhir/task.md) profiles in other resources. You will also use it as the URL value for your [ActivityDefinitions](../fhir/activitydefinition.md). In this case though, you have to split up the URL into two parts. You will separate the version (``|1.2``) from the URL and use it as a value for the `ActivityDefinition.version` element. Since it refers to the plugin's resource version, you should also use the `#{version}` [placeholder](#placeholders) here instead. Going by the example from above, you will be left with a URL that looks like this: +The above URL will be used as the instantiatesCanonical value for [Task](../fhir/task.md) profile definitions as well as references to [Task](../fhir/task.md) profiles in other resources. It is also used as the URL value for [ActivityDefinitions](../fhir/activitydefinition.md). In this case though, the URL has to be split into two parts. The version (`|1.2`) needs to be separated from the URL and used as a value for the `ActivityDefinition.version` element. Since it refers to the plugin's resource version, the `#{version}` [placeholder](#placeholders) should be used here instead. Going by the example from above, the final URL looks like this: ``` http://domain.org/bpe/Process/processKey ``` -This will be the value for your `ActivityDefinition.url` element with `#{version}` as the value for your `ActivityDefinition.version` element. \ No newline at end of file +This will be the value for the `ActivityDefinition.url` element with `#{version}` as the value for the `ActivityDefinition.version` element. + +## Related Topics +[ActivityDefinition](../fhir/activitydefinition.md), [Process Plugin Definition](process-plugin-definition.md) diff --git a/docs/src/process-development/api-v1/fhir/activitydefinition.md b/docs/src/process-development/api-v1/fhir/activitydefinition.md index 5cd27ca91..ae4e64c9a 100644 --- a/docs/src/process-development/api-v1/fhir/activitydefinition.md +++ b/docs/src/process-development/api-v1/fhir/activitydefinition.md @@ -3,7 +3,7 @@ title: ActivityDefinition icon: creative --- -### ActivityDefinition +## ActivityDefinition [ActivityDefinitions](http://hl7.org/fhir/R4/activitydefinition.html) are used by the DSF to advertise which processes are available at any given instance and who is allowed to request and who is allowed to execute a process. The DSF defined elements for this purpose in the [dsf-activity-definition](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-activity-definition-1.0.0.xml) profile. @@ -16,8 +16,9 @@ The most important elements in ActivityDefinitions are: The `message-name` element contains the name of the [BPMN message start event](../bpmn/messaging.md#message-start-event) or [BPMN message intermediate catching event](../bpmn/messaging.md#message-intermediate-catching-event) which expects a [Task](task.md) resource complying to the profile defined by `task-profile`. -The `requester` and `recipient` elements define the organisation(s) or person(s) who are allowed to request or receive the message specified by `message-name`. The receiving DSF instance is the one who will execute the process connected to the message. +The `requester` and `recipient` elements define the organisation(s) or person(s) who are allowed to request or receive the message specified by `message-name`. The receiving DSF instance is the one who will execute the process connected to the message. A list of examples for all possible `requester` and `recipient` elements is located [here](../dsf/requester-and-recipient.md). -You will have to create your own [ActivityDefinitions](activitydefinition.md) when developing a process plugin. If you are fluent in reading XML FHIR definitions and translating them into XML resources, you can take a look at the DSF's profile for ActivityDefinitions [here](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-activity-definition-1.0.0.xml). ActivityDefinitions also reference other resource definitions. Depending on the resource, you will find them in one of [these folders](https://github.com/datasharingframework/dsf/tree/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir). If you are not as comfortable with these requirements you might want to check out the guide on [creating ActivityDefinitions](../guides/creating-activity-definitions.md). +Creating [ActivityDefinitions](activitydefinition.md) is part of developing a process plugin. Readers fluent in understanding XML FHIR definitions and translating them into resources may take a look at the DSF's profile for ActivityDefinitions [here](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-activity-definition-1.0.0.xml). ActivityDefinitions also reference other resource definitions. Depending on the resource they are located in one of [these folders](https://github.com/datasharingframework/dsf/tree/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir). There is also the guide on [creating ActivityDefinitions](../guides/creating-activity-definitions.md) for more in-depth information. -You can also find examples for all possible `requester` and `recipient` elements [here](../dsf/requester-and-recipient.md). \ No newline at end of file +## Related Topics +[Requester and Recipient](../dsf/requester-and-recipient.md), [Read Access Tag](../dsf/read-access-tag.md), [Task](task.md) diff --git a/docs/src/process-development/api-v1/fhir/codesystem.md b/docs/src/process-development/api-v1/fhir/codesystem.md index e40a365f2..ec31894dd 100644 --- a/docs/src/process-development/api-v1/fhir/codesystem.md +++ b/docs/src/process-development/api-v1/fhir/codesystem.md @@ -3,10 +3,13 @@ title: CodeSystem icon: creative --- -### CodeSystem +## CodeSystem -[CodeSystems](https://www.hl7.org/fhir/R4/codesystem.html) usually represent a set of concepts which can be assigned to a code (think LOINC). If you want to use a Code in a resource, you will usually include them in a [ValueSet](valueset.md). +[CodeSystems](https://www.hl7.org/fhir/R4/codesystem.html) usually represent a set of concepts which can be assigned to a code (think LOINC). Using a Code in a resource requires them to be included in a [ValueSet](valueset.md). Plugin development for the DSF requires the use of [CodeSystems](https://www.hl7.org/fhir/R4/codesystem.html) in two major ways: 1. Using existing [DSF CodeSystems](https://github.com/datasharingframework/dsf/tree/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/CodeSystem) in other FHIR resources like the [dsf-extension-process-authorization](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-extension-process-authorization-1.0.0.xml). -2. Creating your own CodeSystem to add additional [Input Parameters](task.md#task-input-parameters) to your [Task](task.md) profiles. \ No newline at end of file +2. Creating custom CodeSystem to add additional [Input Parameters](task.md#task-input-parameters) to [Task](task.md) profiles. + +## Related Topics +[ActivityDefinition](activitydefinition.md), [Task](task.md), [ValueSet](valueset.md) diff --git a/docs/src/process-development/api-v1/fhir/index.md b/docs/src/process-development/api-v1/fhir/index.md index 47e4a6cda..e3ad1350a 100644 --- a/docs/src/process-development/api-v1/fhir/index.md +++ b/docs/src/process-development/api-v1/fhir/index.md @@ -9,5 +9,6 @@ The DSF uses a variety of [FHIR resources](https://dsf.dev/intro/info/basics.htm ## Details - [ActivityDefinition](activitydefinition.md) - [CodeSystem](codesystem.md) +- [Questionnaire and QuestionnaireResponse](questionnaire-and-questionnaireresponse.md) - [Task](task.md) - [ValueSet](valueset.md) \ No newline at end of file diff --git a/docs/src/process-development/api-v1/fhir/questionnaire-and-questionnaireresponse.md b/docs/src/process-development/api-v1/fhir/questionnaire-and-questionnaireresponse.md index e69de29bb..8dfdc4944 100644 --- a/docs/src/process-development/api-v1/fhir/questionnaire-and-questionnaireresponse.md +++ b/docs/src/process-development/api-v1/fhir/questionnaire-and-questionnaireresponse.md @@ -0,0 +1,11 @@ +--- +title: Questionnaire and QuestionnaireResponse +icon: creative +--- + +## Questionnaire and QuestionnaireResponse + +[Questionnaire](https://www.hl7.org/fhir/R4/questionnaire.html) and [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html) resources are used by the DSF to implement the user interaction required in [User Tasks](../bpmn/user-tasks.md). Whenever a [User Task](../bpmn/user-tasks.md) is processed, the DSF will create a [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html) response resource on the DSF FHIR server. This [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html) is based on a [Questionnaire](https://www.hl7.org/fhir/R4/questionnaire.html) resource that is provided by the process plugin. This mechanism is described in more detail in the topic on [User Tasks in the DSF](../guides/user-tasks-in-the-dsf.md). + +## Related Topics +[User Tasks](../bpmn/user-tasks.md), [User Tasks in the DSF](../guides/user-tasks-in-the-dsf.md) \ No newline at end of file diff --git a/docs/src/process-development/api-v1/fhir/task.md b/docs/src/process-development/api-v1/fhir/task.md index a647fc46c..53503e18c 100644 --- a/docs/src/process-development/api-v1/fhir/task.md +++ b/docs/src/process-development/api-v1/fhir/task.md @@ -3,17 +3,18 @@ title: Task icon: creative --- -### Task +## Task -The [FHIR Task](https://www.hl7.org/fhir/R4/task.html) resource enables the DSF's distributed communication. Whenever a BPMN process instance communicates with a different process instance, the DSF will create a Task resource based on parameters you set in the BPMN model and during execution. It will then automatically send the Task resource to the recipient to start or continue whatever process the Task resource referred to. All Task resources used in the DSF derive from the [dsf-task-base](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-task-base-1.0.0.xml). This profile includes a splicing for `Task.input` with three additional [Input Parameters](task.md#task-input-parameters): +The [FHIR Task](https://www.hl7.org/fhir/R4/task.html) resource enables the DSF's distributed communication. Whenever a BPMN process instance communicates with a different process instance, the DSF will create a Task resource based on parameters set in the BPMN model and during execution. It will then automatically send the Task resource to the recipient to start or continue whatever process the Task resource referred to. All Task resources used in the DSF derive from the [dsf-task-base](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-task-base-1.0.0.xml). This profile includes a splicing for `Task.input` with three additional [Input Parameters](task.md#task-input-parameters): - `message-name` - `business-key` - `correlation-key` -When creating your own plugin, you will want to create your own profiles based on the [dsf-task-base](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-task-base-1.0.0.xml). +When creating a process plugin, it is usually necessary to create new profiles based on the [dsf-task-base](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-task-base-1.0.0.xml) and put them into `src/resources/fhir/StructureDefinition`. -#### Task Input Parameters +### Task Input Parameters -Task Input Parameters allow you to add additional information to [Task](task.md#task) resources. For example, if your particular data exchange requires additional medical data, you would add a slice to your Task profile in the same way the [dsf-task-base](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-task-base-1.0.0.xml) adds slices to the original [FHIR Task](https://www.hl7.org/fhir/R4/task.html) resource. Notice that this also requires creating a [CodeSystem](codesystem.md) and including it in a [ValueSet](valueset.md) to be able to use it in the Task resource. +Task Input Parameters allow adding additional information to [Task](task.md#task) resources. For example, if a particular data exchange requires additional medical data, one would add a slice to the Task profile in the same way the [dsf-task-base](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-task-base-1.0.0.xml) adds slices to the original [FHIR Task](https://www.hl7.org/fhir/R4/task.html) resource. It is import to know that this also requires creating a [CodeSystem](codesystem.md) and including it in a [ValueSet](valueset.md) to be able to use it in the Task resource. -If these instructions are insufficient you can check out the guide on [how to add Task Input Parameters](../guides/adding-task-input-parameters-to-task-profiles.md). \ No newline at end of file +## Related Topics +[ActivityDefinition](activitydefinition.md), [Adding Task Input Parameter to Task Profiles](../guides/adding-task-input-parameters-to-task-profiles.md) diff --git a/docs/src/process-development/api-v1/fhir/valueset.md b/docs/src/process-development/api-v1/fhir/valueset.md index 6be03a3fb..e980c4cf3 100644 --- a/docs/src/process-development/api-v1/fhir/valueset.md +++ b/docs/src/process-development/api-v1/fhir/valueset.md @@ -3,8 +3,11 @@ title: ValueSet icon: creative --- -### ValueSet +## ValueSet [ValueSets](https://www.hl7.org/fhir/R4/valueset.html) bind codes from [CodeSystems](codesystem.md) to coded elements like `code`, `Coding` or `CodeableConcept`. -[ValueSets](https://www.hl7.org/fhir/R4/valueset.html) are mostly needed to use the [Concepts](https://www.hl7.org/fhir/R4/codesystem-definitions.html#CodeSystem.concept) from [CodeSystems](codesystem.md) in your [Task](task.md) profiles. \ No newline at end of file +[ValueSets](https://www.hl7.org/fhir/R4/valueset.html) are mostly needed to use the [Concepts](https://www.hl7.org/fhir/R4/codesystem-definitions.html#CodeSystem.concept) from [CodeSystems](codesystem.md) in [Task](task.md) profiles. + +## Related Topics +[CodeSystem](codesystem.md), [Task](task.md) diff --git a/docs/src/process-development/api-v1/guides/accessing-bpmn-process-variables.md b/docs/src/process-development/api-v1/guides/accessing-bpmn-process-variables.md index f03bee5d0..2c809593c 100644 --- a/docs/src/process-development/api-v1/guides/accessing-bpmn-process-variables.md +++ b/docs/src/process-development/api-v1/guides/accessing-bpmn-process-variables.md @@ -3,8 +3,12 @@ title: Accessing BPMN Process Variables icon: creative --- -### Accessing BPMN Process Variables +## Accessing BPMN Process Variables -After creating a [Service Delegate](../dsf/service-delegates.md) or [Message Delegate](../dsf/message-delegates.md), you might want to retrieve data from or store data in the [BPMN process variables](../dsf/bpmn-process-variables.md). You can achieve this either through the [BPMN process execution](../dsf/bpmn-process-execution.md) or via the `Variables` class. *It is very much recommended to use the latter method*. +Access to retrieve data from or store data in the [BPMN process variables](../dsf/bpmn-process-variables.md) can be acquired via the `Variables` class. An instance is usually available when overriding methods in [Service Delegates](../dsf/service-delegates.md) and [Message Delegates](../dsf/message-delegates.md). If an instance is missing in a place where it should be accessible, please [let us know](https://dsf.dev/community/contribute/). -The `Variables` class provides lots of utility methods to read or write certain types of [BPMN process variables](../dsf/bpmn-process-variables.md). If for some reason you need to fall back on the [BPMN process execution](../dsf/bpmn-process-execution.md) to solve your problem, we would like to learn how the current API of the `Variables` class is limiting you. Contact us, and we might turn it into a feature request ([Contribute](https://dsf.dev/stable/contribute)). +The `Variables` class provides lots of utility methods to read or write certain types +of [BPMN process variables](../dsf/bpmn-process-variables.md). If the methods provided by the `Variables` class are insufficient to solve a problem, we would like to learn in what way the current API of the `Variables` class is limiting. Again, please [let us know](https://dsf.dev/community/contribute/). + +## Related Topics +[BPMN Process Variables](../dsf/bpmn-process-variables.md), [Message Delegates](../dsf/message-delegates.md), [Service Delegates](../dsf/service-delegates.md) \ No newline at end of file diff --git a/docs/src/process-development/api-v1/guides/accessing-task-resources-during-execution.md b/docs/src/process-development/api-v1/guides/accessing-task-resources-during-execution.md index 196e16381..f5cbf1e50 100644 --- a/docs/src/process-development/api-v1/guides/accessing-task-resources-during-execution.md +++ b/docs/src/process-development/api-v1/guides/accessing-task-resources-during-execution.md @@ -3,10 +3,14 @@ title: Accessing Task Resources During Execution icon: creative --- -### Accessing Task Resources During Execution +## Accessing Task Resources During Execution -If you want access to the [Task](../fhir/task.md) resources in your [Service](../dsf/service-delegates.md) / [Message](../dsf/message-delegates.md) Delegates, the `Variables` class will provide methods which return certain kinds of [Task](../fhir/task.md) resources. The most commonly used ones are the start [Task](../fhir/task.md), referring to the [Task](../fhir/task.md) / [Message Start Event](../bpmn/messaging.md#message-start-event) responsible for starting the process, and the latest [Task](../fhir/task.md), referring to most recently received [Task](../fhir/task.md) / Message. -In principle, this is sufficient to access all information in a [Task](../fhir/task.md) resource, since you have the [Task](../fhir/task.md) resource's Java object, but very cumbersome. -Instead of navigating the [Task](../fhir/task.md) resource's element tree, you should first try to use the [ProcessPluginApi's](../dsf/process-plugin-api.md) `TaskHelper` in conjunction with the method above. The `TaskHelper` class offers specific methods related to [Task](../fhir/task.md) resources. -The most common use case for this is retrieving data from a [Task's](../fhir/task.md) [Input Parameter](../fhir/task.md#task-input-parameters) or creating a new [Input Parameter](../fhir/task.md#task-input-parameters) for a [Message Delegate's](../dsf/message-delegates.md) `getAdditionalInputParameters` method. When retrieving data from a [Task's](../fhir/task.md) Input Parameter you first have to get to the [Input Parameter](../fhir/task.md#task-input-parameters) you are looking to extract data from. You can use one of the `TaskHelper's` getters for [Input Parameters](../fhir/task.md#task-input-parameters) to find the right one. The methods will try to match the provided [CodeSystem](../fhir/codesystem.md) and Code to any [Input Parameter](../fhir/task.md#task-input-parameters) of the provided [Task](../fhir/task.md) resource. Depending on the method you chose you will for example receive all matches or just the first one. -To create new [Input Parameters](../fhir/task.md#task-input-parameters) to attach to a [Task](../fhir/task.md) resource, you may invoke the `TaskHelper#createInput` method. This is most often used when overriding the `getAdditionalInputParamters` method of you [Message Delegate](../dsf/message-delegates.md). \ No newline at end of file +Access to the [Task](../fhir/task.md) resources in [Service](../dsf/service-delegates.md) / [Message](../dsf/message-delegates.md) Delegates is provided by the `Variables` class. It comes with methods which return certain kinds of [Task](../fhir/task.md) resources. The most commonly used ones are the start [Task](../fhir/task.md), referring to the [Task](../fhir/task.md) / [Message Start Event](../bpmn/messaging.md#message-start-event) responsible for starting the process, and the latest [Task](../fhir/task.md), referring to most recently received [Task](../fhir/task.md) / Message. +In principle, this is sufficient to access all information in a [Task](../fhir/task.md) resource, since there is access to the full in-memory representation of the [Task](../fhir/task.md) resource. This however can be very cumbersome to use and produces a lot of boilerplate when traversing the resource tree to access certain common elements. +Instead of navigating the [Task](../fhir/task.md) resource's element tree, it is recommended to use the [ProcessPluginApi's](../dsf/process-plugin-api.md) `TaskHelper` in conjunction with the method above. The `TaskHelper` class offers specific methods related to [Task](../fhir/task.md) resources. +The most common use case for this is retrieving data from a [Task's](../fhir/task.md) [Input Parameter](../fhir/task.md#task-input-parameters) or creating a new [Input Parameter](../fhir/task.md#task-input-parameters) for a [Message Delegate's](../dsf/message-delegates.md) `getAdditionalInputParameters` method. When retrieving data from a [Task's](../fhir/task.md) Input Parameter one first has to get to the [Input Parameter](../fhir/task.md#task-input-parameters) one is looking to extract data from. The `TaskHelper's` getters for [Input Parameters](../fhir/task.md#task-input-parameters) are useful to find the right one. The methods will try to match the provided [CodeSystem](../fhir/codesystem.md) and Code to any [Input Parameter](../fhir/task.md#task-input-parameters) of the provided [Task](../fhir/task.md) resource. Depending on the method it is possible to receive all matches or just the first one. +To create new [Input Parameters](../fhir/task.md#task-input-parameters) to attach to a [Task](../fhir/task.md) resource, one may invoke the `TaskHelper#createInput` method. This is most often used when overriding the `getAdditionalInputParameters` method of a [Message Delegate](../dsf/message-delegates.md). + + +## Related Topics +[Accessing BPMN Process Variables](accessing-bpmn-process-variables.md), [Message Delegates](../dsf/message-delegates.md), [Service Delegates](../dsf/service-delegates.md), [Task](../fhir/task.md) \ No newline at end of file diff --git a/docs/src/process-development/api-v1/guides/adding-task-input-parameters-to-task-profiles.md b/docs/src/process-development/api-v1/guides/adding-task-input-parameters-to-task-profiles.md index 7a625d5f4..1480ee8f8 100644 --- a/docs/src/process-development/api-v1/guides/adding-task-input-parameters-to-task-profiles.md +++ b/docs/src/process-development/api-v1/guides/adding-task-input-parameters-to-task-profiles.md @@ -3,13 +3,13 @@ title: Adding Task Input Parameters to Task Profiles icon: creative --- -### Adding Task Input Parameters to Task Profiles +## Adding Task Input Parameters to Task Profiles -When adding a new [Input Parameter](../fhir/task.md#task-input-parameters) to a [Task](../fhir/task.md) profile, you are essentially adding a new slice to `Task.input`. [Slicing](https://www.hl7.org/fhir/R4/profiling.html#slicing) is part of [profiling](https://www.hl7.org/fhir/R4/profiling.html) in FHIR. Profiling lets you create your own FHIR definitions based on pre-existing FHIR definitions. A slicing defines constraints on element lists like `Task.input` e.g. by only allowing the elements to be of certain types. -For example, you might have a list of fruits in a `FruitBasket` resource. Constraining that list to only include fruits of type `Apple`, `Banana` and `Orange` would be considered [slicing](https://www.hl7.org/fhir/R4/profiling.html#slicing). -This guide will not cover how slicing works in general, only for the case presented by the DSF FHIR resource context. Our goal will be to add a new [Input Parameter](../fhir/task.md#task-input-parameters) of type `example-input` to the `task-start-dic-process.xml` profile which will be used to submit `integer` values to our `dicProcess`. +When adding a new [Input Parameter](../fhir/task.md#task-input-parameters) to a [Task](../fhir/task.md) profile, a new slice is added to `Task.input`. [Slicing](https://www.hl7.org/fhir/R4/profiling.html#slicing) is part of [profiling](https://www.hl7.org/fhir/R4/profiling.html) in FHIR. Profiling lets you create your own FHIR definitions based on pre-existing FHIR definitions. A slicing defines constraints on element lists like `Task.input` e.g. by only allowing the elements to be of certain types. +For example, there might be a list of fruits in a `FruitBasket` resource. Constraining that list to only include fruits of type `Apple`, `Banana` and `Orange` would be considered [slicing](https://www.hl7.org/fhir/R4/profiling.html#slicing). +This guide will not cover how slicing works in general, only for the case presented by the DSF FHIR resource context. The goal will be to add a new [Input Parameter](../fhir/task.md#task-input-parameters) of type `example-input` to the `task-start-dic-process.xml` profile which will be used to submit `integer` values to a process called `dicProcess`. -Let us start out by adding a slice to `task-start-dic-process.xml`. Since there is already a slicing defined on `Task.input` by `task-start-dic-process.xml`'s `baseDefinition`, we have to check out this resource first. As a part of the [differential](https://www.hl7.org/fhir/R4/profiling.html#snapshot) statement, slicing also uses [Element Definitions](https://www.hl7.org/fhir/R4/elementdefinition.html). +As a first step, a slice to `task-start-dic-process.xml` is added. Since there is already a slicing defined on `Task.input` by `task-start-dic-process.xml`'s `baseDefinition`, this resource has to be looked at first. As a part of the [differential](https://www.hl7.org/fhir/R4/profiling.html#snapshot) statement, slicing also uses [Element Definitions](https://www.hl7.org/fhir/R4/elementdefinition.html). The slicing for `Task.input` is defined in this part of the `baseDefinition`: ```xml <element id="Task.input"> @@ -33,9 +33,9 @@ The slicing for `Task.input` is defined in this part of the `baseDefinition`: ``` *The resource can be found [here](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-task-base-1.0.0.xml)* -We will only need to take a look at the `discrimitator` tag for now. Discriminators define the elements a FHIR processor needs to distinguish slices by. In our case, a processor would look at the values for `type.coding.system` and `type.coding.code` to determine which slice this element belongs to. The discriminator type `value` implies that `type.coding.system` and `type.coding.code` have to be present in all slices and need to have a fixed value. You can learn more about discriminators [here](https://www.hl7.org/fhir/R4/profiling.html#discriminator). +First look at the `discriminator` tag. Discriminators define the elements a FHIR processor needs to distinguish slices by. In this case, a processor would look at the values for `type.coding.system` and `type.coding.code` to determine which slice this element belongs to. The discriminator type `value` implies that `type.coding.system` and `type.coding.code` have to be present in all slices and need to have a fixed value. There is more information about discriminators in the [official FHIR documentation](https://www.hl7.org/fhir/R4/profiling.html#discriminator). -Let us revisit `task-start-dic-process.xml` and start adding a slice called `example-input` to it: +Now revisit `task-start-dic-process.xml` and start adding a slice called `example-input` to it: ```xml <StructureDefinition xmlns="http://hl7.org/fhir"> ... @@ -52,9 +52,9 @@ Let us revisit `task-start-dic-process.xml` and start adding a slice called `exa ``` *Irrelevant elements for this guide are hidden by ... placeholders.* -We have now defined a slice on `Task.input` with the name and id of `example-input` and cardinality of `1..1`. You might want a different cardinality for your use case. We recommend you also take a look at the documentation for [ElementDefinition.id](https://www.hl7.org/fhir/R4/elementdefinition.html#id) and [ElementDefinition.path](https://www.hl7.org/fhir/R4/elementdefinition.html#path). They explain how to create the proper values for these elements. Cardinality is also part of the [element definition](https://www.hl7.org/fhir/R4/elementdefinition.html) hierarchy (see [ElementDefinition.min](https://www.hl7.org/fhir/R4/elementdefinition-definitions.html#ElementDefinition.min) and [ElementDefinition.max](https://www.hl7.org/fhir/R4/elementdefinition-definitions.html#ElementDefinition.max)). +There is now a slice defined on `Task.input` with the name and id of `example-input` and cardinality of `1..1`. The name and cardinality depend on the use case. It is recommended to also take a look at the documentation for [ElementDefinition.id](https://www.hl7.org/fhir/R4/elementdefinition.html#id) and [ElementDefinition.path](https://www.hl7.org/fhir/R4/elementdefinition.html#path). They explain how to create the proper values for these elements. Cardinality is also part of the [element definition](https://www.hl7.org/fhir/R4/elementdefinition.html) hierarchy (see [ElementDefinition.min](https://www.hl7.org/fhir/R4/elementdefinition-definitions.html#ElementDefinition.min) and [ElementDefinition.max](https://www.hl7.org/fhir/R4/elementdefinition-definitions.html#ElementDefinition.max)). -Next up, we need to define the binding for `Task.input:example-input.type`. Because `Task.input.type` is a `CodeableConcept` which uses codings from a [ValueSet](../fhir/valueset.md), the [discriminator](https://www.hl7.org/fhir/R4/profiling.html#discriminator) requires us to use `required` as the binding strength: +Next up is the binding for `Task.input:example-input.type`. Because `Task.input.type` is a `CodeableConcept` which uses codings from a [ValueSet](../fhir/valueset.md), the [discriminator](https://www.hl7.org/fhir/R4/profiling.html#discriminator) requires the use of `required` as the binding strength: ```xml <StructureDefinition xmlns="http://hl7.org/fhir"> ... @@ -76,9 +76,9 @@ Next up, we need to define the binding for `Task.input:example-input.type`. Beca </differential> </StructureDefinition> ``` -As you can see, we referenced a [ValueSet](../fhir/valueset.md) in this binding. When adding an actual slice for your use case, you will have to reference an existing [ValueSet](../fhir/valueset.md) resource or create a new one. A guide on how to create them can be found [here](../guides/creating-valuesets-for-dsf-processes.md). +The binding now references a [ValueSet](../fhir/valueset.md). Moving beyond this example will require referencing an existing [ValueSet](../fhir/valueset.md) resource or create a new one. A guide on how to create them can be found [here](../guides/creating-valuesets-for-dsf-processes.md). -Since the [discriminator](https://www.hl7.org/fhir/R4/profiling.html#discriminator) requires `Task.input.coding.code` and `Task.input.coding.system` to be present, we will make `Task.input.coding` mandatory as well: +Since the [discriminator](https://www.hl7.org/fhir/R4/profiling.html#discriminator) requires `Task.input.coding.code` and `Task.input.coding.system` to be present, `Task.input.coding` will be marked as mandatory as well: ```xml <StructureDefinition xmlns="http://hl7.org/fhir"> ... @@ -105,7 +105,7 @@ Since the [discriminator](https://www.hl7.org/fhir/R4/profiling.html#discriminat </StructureDefinition> ``` -In the beginning we mentioned how `Task.input.type.coding.system` and `Task.input.type.coding.code` have to use fixed values. Here is how we accomplish this: +The beginning mentioned how `Task.input.type.coding.system` and `Task.input.type.coding.code` have to use fixed values. Here is how this is accomplished: ```xml <StructureDefinition xmlns="http://hl7.org/fhir"> @@ -142,9 +142,9 @@ In the beginning we mentioned how `Task.input.type.coding.system` and `Task.inpu </differential> </StructureDefinition> ``` -*Notice that we also made the two elements mandatory because they are required by the discriminator.* +*Notice the two new elements were marked as mandatory because they are required by the discriminator.* -For the `type.coding.system` element we referenced a [CodeSystem](../fhir/codesystem.md). The `type.coding.code` element uses a code from this [CodeSystem](../fhir/codesystem.md) called `example-input`. This is the mechanism by which you actually "name" your [Input Parameter](../fhir/task.md#task-input-parameters). The `type.coding.code` value will identify your [Input Parameter](../fhir/task.md#task-input-parameters) when you use it in an actual [Task](../fhir/task.md#task-input-parameters) resource. Here is how this would look like: +The `type.coding.system` element references a [CodeSystem](../fhir/codesystem.md). The `type.coding.code` element uses a code from this [CodeSystem](../fhir/codesystem.md) called `example-input`. This is the mechanism by which [Input Parameter](../fhir/task.md#task-input-parameters) are "named". The `type.coding.code` value will identify the [Input Parameter](../fhir/task.md#task-input-parameters) when it is used in an actual [Task](../fhir/task.md#task-input-parameters) resource. Here is how this would look like: ```xml <Task xmlns="http://hl7.org/fhir"> @@ -161,9 +161,9 @@ For the `type.coding.system` element we referenced a [CodeSystem](../fhir/codesy </Task> ``` -When adding an actual slice for your use case, you will also need to reference an existing [CodeSystem](../fhir/codesystem.md) resource or create a new one to reference. A guide on how to create them can be found [here](../guides/creating-codesystems-for-dsf-processes.md). +Adding a slice in a different use case will also require to reference an existing [CodeSystem](../fhir/codesystem.md) resource or create a new one to reference. A guide on how to create them can be found [here](../guides/creating-codesystems-for-dsf-processes.md). -`Task.input.value[x]` is the actual value you will submit using your Input Parameter. You can make it any of [these](https://www.hl7.org/fhir/R4/datatypes.html#open) data types. This is because `Type.input.value[x]` refers to `*` instead of any particular type in its [definition](https://www.hl7.org/fhir/R4/task-definitions.html#Task.input.value_x_). Let us define it as an `integer` type`: +`Task.input.value[x]` is the actual value submitted when using the Input Parameter. They may be any of [these](https://www.hl7.org/fhir/R4/datatypes.html#open) data types. This is because `Type.input.value[x]` refers to `*` instead of any particular type in its [definition](https://www.hl7.org/fhir/R4/task-definitions.html#Task.input.value_x_). In this case, let it be an `integer` type`: ```xml <StructureDefinition xmlns="http://hl7.org/fhir"> @@ -207,4 +207,7 @@ When adding an actual slice for your use case, you will also need to reference a </StructureDefinition> ``` -Now we have a new Input Parameter of type `example-input` which accepts any `integer` as its value. +There is now a new Input Parameter of type `example-input` which accepts any `integer` as its value. + +## Related Topics +[Creating CodeSystems for DSF processes](creating-codesystems-for-dsf-processes.md), [Creating ValueSets for DSF processes](creating-valuesets-for-dsf-processes.md), [Task](../fhir/task.md) diff --git a/docs/src/process-development/api-v1/guides/configuring-read-access-tags.md b/docs/src/process-development/api-v1/guides/configuring-read-access-tags.md index 404f2286e..7ac655e5a 100644 --- a/docs/src/process-development/api-v1/guides/configuring-read-access-tags.md +++ b/docs/src/process-development/api-v1/guides/configuring-read-access-tags.md @@ -3,9 +3,9 @@ title: Configuring Read Access Tags icon: creative --- -### Configuring Read Access Tags +## Configuring Read Access Tags -To start off, you want to take a look at the [CodeSystem](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/CodeSystem/dsf-read-access-tag-1.0.0.xml) defined for the [Read Access Tag](../dsf/read-access-tag.md) and choose one of the codes from it: +Before starting to configure anything, it is advised to take a look at the [CodeSystem](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/CodeSystem/dsf-read-access-tag-1.0.0.xml) defined for the [Read Access Tag](../dsf/read-access-tag.md) and choose one of the codes from it: ```xml <CodeSystem xmlns="http://hl7.org/fhir"> ... @@ -44,7 +44,7 @@ The codes `LOCAL` and `ALL` are trivial. Their [Read Access Tag](../dsf/read-acc </meta> ``` -Let us try to configure a Read Access Tag whose code uses an extension. We will choose `ROLE` for this example. We start out the same way as before: +Now to configure a Read Access Tag whose code uses an extension. This example will use the code `ROLE`. It starts out the same way as before: ```xml <meta> <tag> @@ -56,7 +56,7 @@ Let us try to configure a Read Access Tag whose code uses an extension. We will The `definition` element of the `ROLE` code references an extension called [dsf-extension-read-access-parent-organization-role](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-extension-read-access-parent-organization-role-1.0.0.xml). -The most important part of it is the `differential` statement. It uses [element definitions](https://www.hl7.org/fhir/R4/elementdefinition.html) to describe how we need to implement the extension: +The most important part of it is the `differential` statement. It uses [element definitions](https://www.hl7.org/fhir/R4/elementdefinition.html) to describe how the extensions needs to be implemented: ```xml <StructureDefinition xmlns="http://hl7.org/fhir"> ... @@ -142,7 +142,7 @@ All extensions for the [Read Access Tag](../dsf/read-access-tag.md) CodeSystem a </context> ``` -That is why the first element we are adding to `meta.tag` is an `extension` element: +That is why the first element to be added to `meta.tag` is an `extension` element: ```xml <meta> <tag> @@ -155,7 +155,7 @@ That is why the first element we are adding to `meta.tag` is an `extension` elem </meta> ``` -We will now go through the `differential` statement one element at a time, starting at the top: +Now to process the `differential` statement one element at a time, starting at the top: ```xml <StructureDefinition xmlns="http://hl7.org/fhir"> ... @@ -175,7 +175,7 @@ We will now go through the `differential` statement one element at a time, start </StructureDefinition> ``` -It defines a [slicing](https://www.hl7.org/fhir/R4/profiling.html#slicing) for the `Extension.extension` element, meaning we are dealing with a nested extension. The `discriminator` element tells us that slices will be identified by the value of their `url` attribute. A `rules` element with value `open` means other types of slices may be added later on e.g. when creating a profile. We do not have to add any elements from here to the `meta.tag.extension` element. Next up is the first slice called `parentOrganization`: +It defines a [slicing](https://www.hl7.org/fhir/R4/profiling.html#slicing) for the `Extension.extension` element, meaning this is a nested extension. The `discriminator` element defines that slices will be identified by the value of their `url` attribute. A `rules` element with value `open` means other types of slices may be added later on e.g. when creating a profile. This element is not added to the `meta.tag.extension` element it only serves the purpose of defining the `discriminator`. Next up is the first slice called `parentOrganization`: ```xml <StructureDefinition xmlns="http://hl7.org/fhir"> @@ -213,7 +213,7 @@ It defines a [slicing](https://www.hl7.org/fhir/R4/profiling.html#slicing) for t </StructureDefinition> ``` -The first element defines a slice called `parentOrganization` on the `Extension.extension` element with cardinality `1..1`. The second element defines the url attribute of the `parentOrganization` slice to be fixed to the value `parent-organization`. With this information we can add the next element to `meta.tag`. Since it is defined on `Extension.extension` we will add it to `meta.tag.extension.extension` like this: +The first element defines a slice called `parentOrganization` on the `Extension.extension` element with cardinality `1..1`. The second element defines the url attribute of the `parentOrganization` slice to be fixed to the value `parent-organization`. With this information the next element can be added to `meta.tag`. Since it is defined on `Extension.extension` it will be added it to `meta.tag.extension.extension` like this: ```xml <meta> <tag> @@ -228,7 +228,7 @@ The first element defines a slice called `parentOrganization` on the `Extension. </meta> ``` -After that, it defines `parentOrganization.value[x]` to occur at least once and have a type of `Identifier`. To turn this into an element to add to `meta.tag.extension.extension` we have to replace `[x]` with our code in `value[x].type`, which in this case is `Identifier`. It is important to note, that should the value in the code element be lowercase, you will have make it uppercase before replacement. In our case this means we will have a `meta.tag.extension.extension.valueIdentifier` element: +After that, it defines `parentOrganization.value[x]` to occur at least once and have a type of `Identifier`. To turn this into an element to add to `meta.tag.extension.extension` requires replacing `[x]` with the code in `value[x].type`, which in this case is `Identifier`. It is important to note, that `value[x]` should be camel cased after replacement. This means there will be a `meta.tag.extension.extension.valueIdentifier` element: ```xml <meta> <tag> @@ -245,7 +245,7 @@ After that, it defines `parentOrganization.value[x]` to occur at least once and </meta> ``` -The last two elements define a `system` element with a fixed value and `value` element we can fill in on our own, since it does not have any constraints applied. Notice that the element definition still uses `value[x].system` and `value[x].value`. The replacement mentioned earlier does not happen in the element definition, but since `value[x]` is defined to have the type `Identifier` it is inferred that we mean to reference `Identifier.system` and `Identifier.value`. We will choose an arbitrary `Idenfier` value, but you should be using an actual organization identifier depending on who you want to allow read access to the resource. +The last two elements define a `system` element with a fixed value and `value` element that can be freely set, since it does not have any constraints applied. Notice that the element definition still uses `value[x].system` and `value[x].value`. The replacement mentioned earlier does not happen in the element definition, but since `value[x]` is defined to have the type `Identifier`, it is inferred that `Identifier.system` and `Identifier.value` are referenced. The example will use an arbitrary `Identifier` value, but real application should be using an actual organization identifier depending on which organization has read access to the resource. ```xml <meta> @@ -300,7 +300,7 @@ Next is the slice is called `organizationRole`: </StructureDefinition> ``` -Like with `parentOrganization`, we will add an extension element to `meta.tag.extension` with the fixed url value defined above: +Like with `parentOrganization`, an extension element to `meta.tag.extension` is added with the fixed url value defined above: ```xml <meta> <tag> @@ -321,7 +321,7 @@ Like with `parentOrganization`, we will add an extension element to `meta.tag.ex </meta> ``` -Instead of `Identifier`, the `value[x]` element is now defined as a `Coding` type. This means we will add a `valueCoding` element to the extension: +Instead of `Identifier`, the `value[x]` element is now defined as a `Coding` type. This the next element to add will be `valueCoding`: ```xml <meta> <tag> @@ -344,7 +344,7 @@ Instead of `Identifier`, the `value[x]` element is now defined as a `Coding` typ </meta> ``` -A `Coding` has to belong to some [CodeSystem](../fhir/codesystem.md). The DSF has a CodeSystem called [dsf-organization-role](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/CodeSystem/dsf-organization-role-1.0.0.xml). Before creating your own CodeSystem, it is worth taking a look at it to see if an appropriate role already exists for your organization. For demonstration purposes, we will be using the `DIC` role: +A `Coding` has to belong to some [CodeSystem](../fhir/codesystem.md). The DSF has a CodeSystem called [dsf-organization-role](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/CodeSystem/dsf-organization-role-1.0.0.xml). Before creating new CodeSystems, it is worth taking a look at it to see if an appropriate role already exists for an organization. The example will be using the `DIC` role: ```xml <meta> <tag> @@ -368,7 +368,7 @@ A `Coding` has to belong to some [CodeSystem](../fhir/codesystem.md). The DSF ha </meta> ``` -Now we only have two elements left in the `differential` statement: +Now there is only two elements left in the `differential` statement: ```xml <StructureDefinition xmlns="http://hl7.org/fhir"> @@ -387,7 +387,7 @@ Now we only have two elements left in the `differential` statement: </StructureDefinition> ``` -The `Extension.url` element tells us to add a url attribute to `meta.tag.extension`. The last element makes it so we must not add a `meta.tag.extension.value[x]` element. This leaves us with this final Read Access Tag: +The `Extension.url` element requires a url attribute to be added to `meta.tag.extension`. The last element defines that there must not be a `meta.tag.extension.value[x]` element. This results in this final Read Access Tag: ```xml <meta> @@ -412,4 +412,5 @@ The `Extension.url` element tells us to add a url attribute to `meta.tag.extensi </meta> ``` -You can follow the same method to configure the other types of Read Access Tags as well. \ No newline at end of file +## Related Topics +[Read Access Tag](../dsf/read-access-tag.md) diff --git a/docs/src/process-development/api-v1/guides/creating-activity-definitions.md b/docs/src/process-development/api-v1/guides/creating-activity-definitions.md index 163d47032..fe296007b 100644 --- a/docs/src/process-development/api-v1/guides/creating-activity-definitions.md +++ b/docs/src/process-development/api-v1/guides/creating-activity-definitions.md @@ -3,9 +3,9 @@ title: Creating ActivityDefinitions icon: creative --- -### Creating ActivityDefinitions +## Creating ActivityDefinitions -This guide will teach you how to create an ActivityDefinition based on the [dsf-activity-definition](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-activity-definition-1.0.0.xml) profile for your process plugin. +This guide will explain how to create an ActivityDefinition based on the [dsf-activity-definition](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-activity-definition-1.0.0.xml) profile for a process plugin. It is divided into steps for each of the main components of ActivityDefinitions: 1. Read Access Tag 2. Extension: process authorization @@ -14,17 +14,17 @@ It is divided into steps for each of the main components of ActivityDefinitions: *Regular elements* are all elements not part of the first 3 main components. -*We will assume you know how to translate [ElementDefinitions](https://www.hl7.org/fhir/R4/elementdefinition.html) to actual elements in a FHIR resource. If you do not, you might want to check out the guide on [creating Task resources](../guides/creating-task-resources-based-on-a-definition.md) first.* +*This guide assumes the reader knows how to translate [ElementDefinitions](https://www.hl7.org/fhir/R4/elementdefinition.html) to actual elements in a FHIR resource. If not, the guide on [creating Task resources](../guides/creating-task-resources-based-on-a-definition.md) includes explanations for this.* -#### 1. Read Access Tag -Let us start out with an empty [ActivityDefinition](../fhir/activitydefinition.md): +### 1. Read Access Tag +Start out with an empty [ActivityDefinition](../fhir/activitydefinition.md): ```xml <ActivityDefinition xmlns="http://hl7.org/fhir"> </ActivityDefinition> ``` -The first element in DSF FHIR resources is always the [Read Access Tag](../dsf/read-access-tag.md). It describes who is allowed to read this resource through the DSF FHIR server's REST API. You can learn more complex configurations of the [Read Access Tag](../dsf/read-access-tag.md) in [this guide](../dsf/read-access-tag.md). In this case, we will allow read access to everyone: +The first element in DSF FHIR resources is always the [Read Access Tag](../dsf/read-access-tag.md). It describes who is allowed to read this resource through the DSF FHIR server's REST API. More complex configurations of the [Read Access Tag](../dsf/read-access-tag.md) are explained in [this guide](../dsf/read-access-tag.md). For this example, everyone will be allowed to read the resource: ```xml <ActivityDefinition xmlns="http://hl7.org/fhir"> @@ -37,8 +37,8 @@ The first element in DSF FHIR resources is always the [Read Access Tag](../dsf/r </ActivityDefinition> ``` -#### 2. Extension: Process Authorization -This part of your ActivityDefinition will tell the DSF who is allowed to request and receive messages ([Task](../fhir/task.md) resources) for your BPMN process. If your plugin contains more than one BPMN process, you will have to create one [ActivityDefinition](../fhir/activitydefinition.md) for each BPMN process. It is important to note that you need to include authorization rules for **ALL** messages received in your BPMN process. This includes the message starting your BPMN process initially. You can find the extension [here](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-extension-process-authorization-1.0.0.xml). Let us continue by adding the [extension element](http://hl7.org/fhir/R4/extensibility.html#extension) with the correct URL. You can get the value for the URL from the `Extension.url` element: +### 2. Extension: Process Authorization +This part of the ActivityDefinition will tell the DSF who is allowed to request and receive messages ([Task](../fhir/task.md) resources) for BPMN process. If the plugin contains more than one BPMN process, there will have to be one [ActivityDefinition](../fhir/activitydefinition.md) for each BPMN process. It is important to note that authorization rules need to be included for **ALL** messages received in the BPMN process. This includes the messages starting the BPMN process initially. The extension containing all possible rules is found [here](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-extension-process-authorization-1.0.0.xml). Next up is adding the [extension element](http://hl7.org/fhir/R4/extensibility.html#extension) with the correct URL. The value for the URL is found in the `Extension.url` element: ```xml <ActivityDefinition xmlns="http://hl7.org/fhir"> ... @@ -47,7 +47,7 @@ This part of your ActivityDefinition will tell the DSF who is allowed to request </extension> </ActivityDefinition> ``` -*Elements not relevant to the current component are hidden with ... to increase readability.* +*Elements not relevant to the current component are hidden with `...` to increase readability.* The [differential](https://www.hl7.org/fhir/R4/profiling.html#snapshot) statement starts by defining the [slicing](https://www.hl7.org/fhir/R4/profiling.html#snapshot) for the `Extension.extension` element: @@ -74,9 +74,9 @@ The [differential](https://www.hl7.org/fhir/R4/profiling.html#snapshot) statemen </StructureDefinition> ``` -The above states that whenever this extension is used in a profile, the profile needs to include this extension at least once (`<min value="1" />`). The [slicing](https://www.hl7.org/fhir/R4/profiling.html#snapshot) on `Extension.extension` tells us that elements of this [slicing](https://www.hl7.org/fhir/R4/profiling.html#snapshot) are identified by the value of their URL (`<discriminator>`), which is always the case for extensions, and that other extensions can be added to the [slicing](https://www.hl7.org/fhir/R4/profiling.html#snapshot) (`<rules value="open" />`). Since there is a [slicing](https://www.hl7.org/fhir/R4/profiling.html#snapshot) on `Extension.extension`, we are dealing with a nested extension. +The above states that whenever this extension is used in a profile, the profile needs to include this extension at least once (`<min value="1" />`). The [slicing](https://www.hl7.org/fhir/R4/profiling.html#snapshot) on `Extension.extension` defines that elements of this [slicing](https://www.hl7.org/fhir/R4/profiling.html#snapshot) are identified by the value of their URL (`<discriminator>`), which is always the case for extensions, and that other extensions can be added to the [slicing](https://www.hl7.org/fhir/R4/profiling.html#snapshot) (`<rules value="open" />`). Since there is a [slicing](https://www.hl7.org/fhir/R4/profiling.html#snapshot) on `Extension.extension`, this is a nested extension. -After these initial element definitions come the elements relevant for your process plugin. The first one is the `message-name` slice: +After these initial element definitions come the elements relevant for the process plugin. The first one is the `message-name` slice: ```xml <StructureDefinition xmlns="http://hl7.org/fhir"> ... @@ -104,17 +104,17 @@ After these initial element definitions come the elements relevant for your proc </StructureDefinition> ``` -This section tells us that we need to include exactly one extension element from the `message-name` slice in our [ActivityDefinition](../fhir/activitydefinition.md). The extension element will have a URL value of `message-name`. If you remember the `discriminator` configuration, this URL value identifies the element to belong to the `message-name` slice on `Extension.extension`. Lastly, the extension element includes a `valueString` element. In case you are wondering how `value[x]` turned into `valueString`, FHIR does not allow using `value[x]` as actual element. The value in `value[x]` is always strictly bound to some kind of type. FHIR uses the `value[x].type.code` value to determine this type and replaces `[x]` with an uppercase version of `element.type.code`. This results in the following extension element we will add to our [ActivityDefinition](../fhir/activitydefinition.md): +This section defines that there has to be exactly one extension element from the `message-name` slice in the [ActivityDefinition](../fhir/activitydefinition.md). The extension element will have a URL value of `message-name`. This URL value identifies the element to belong to the `message-name` slice on `Extension.extension`, in accordance with the `discriminator`. Lastly, the extension element includes a `valueString` element. FHIR does not allow using `value[x]` as actual element. The value in `value[x]` is always strictly bound to some kind of type. FHIR uses the `value[x].type.code` value to determine this type and replaces `[x]` with an uppercase version of `element.type.code`. This results in the following extension element: ```xml <extension url="message-name"> <valueString value="myMessage"/> </extension> ``` -For your use case, you have to replace `myMessage` with the name of the [BPMN message event](../bpmn/messaging.md) that is expecting this message. +`myMessage` will have to be replaced with the name of the [BPMN message event](../bpmn/messaging.md) in a BPMN process that is expecting this message. <details> -<summary>This is how your ActivityDefinition should look like so far</summary> +<summary>This is how the ActivityDefinition should look like so far</summary> ```xml <ActivityDefinition xmlns="http://hl7.org/fhir"> @@ -161,7 +161,7 @@ The next slice is called `task-profile`: </StructureDefinition> ``` -This section has almost the same structure as `message-name`. The only difference is the value for `value[x].type.code`. This means that instead of `valueString`, we will have to use a `valueCanonical` element for `task-profile.value[x]`. Canonical values referring to [Task](../fhir/task.md) profiles in ActivityDefinitions have to conform to the rules outlined by the documentation on [URLs](../dsf/versions-placeholders-urls.md#urls). From the definition above, we will create the following extension element and add it to our [ActivityDefinition](../fhir/activitydefinition.md): +This section has almost the same structure as `message-name`. The only difference is the value for `value[x].type.code`. This means that instead of `valueString`, it requires using a `valueCanonical` element for `task-profile.value[x]`. Canonical values referring to [Task](../fhir/task.md) profiles in ActivityDefinitions have to conform to the rules outlined by the documentation on [URLs](../dsf/versions-placeholders-urls.md#urls). From the definition above, the following extension element is created and added to the [ActivityDefinition](../fhir/activitydefinition.md): ```xml <extension url="task-profile"> <valueCanonical value="http://dsf.dev/fhir/StructureDefinition/my-task|#{version}"/> @@ -169,7 +169,7 @@ This section has almost the same structure as `message-name`. The only differenc ``` <details> -<summary>This is how your ActivityDefinition should look like so far</summary> +<summary>This is how the ActivityDefinition should look like so far</summary> ```xml <ActivityDefinition xmlns="http://hl7.org/fhir"> @@ -230,7 +230,7 @@ The next slice is `requester`: </differential> </StructureDefinition> ``` -Instead of a `string` or `canonical` type for `value[x]` we now have a `Coding` type. See the [FHIR documentation on Codings](https://www.hl7.org/fhir/R4/datatypes.html#Coding) for more in-depth information. `Codings` are elements which contain, among other things, a `code` and the `system` the code belongs to. In the same way we transformed `value[x]` into `valueString` or `valueCanonical` before, we will also have to turn `value[x]` into `valueCoding`. To use `Codings` in `valueCoding` elements, they are usually bound to the element through a [ValueSet](../fhir/valueset.md). This is the responsibility of the `binding` element. You can also see that `value[x].type.profile` lists a number of profiles. Instead of defining the elements in the same file, they were defined in different files for better readability. Depending on your use case, you have to pick one of the profiles. +Instead of a `string` or `canonical` type for `value[x]` there now is a `Coding` type. See the [FHIR documentation on Codings](https://www.hl7.org/fhir/R4/datatypes.html#Coding) for more in-depth information. `Codings` are elements which contain, among other things, a `code` and the `system` the code belongs to. In the same way `value[x]` transformed into `valueString` or `valueCanonical` before, `value[x]` will be transformed into `valueCoding`. To use `Codings` in `valueCoding` elements, they are usually bound to the element through a [ValueSet](../fhir/valueset.md). This is the responsibility of the `binding` element. There is also a list of `value[x].type.profile` elements referencing other [StructureDefinitions](https://www.hl7.org/fhir/R4/structuredefinition.html). Instead of defining the elements in the same file, they were defined in different files for better readability. The use case decides which one to pick. Here is what they mean: - `local-all`: All local requests will be allowed. Local requests are identified by matching the requester's certificate to a thumbprint which was internally marked by the DSF FHIR server as belonging to a local organization. - `local-organization`: All local requests made from an organization with a specific `organization-identifier` will be allowed. @@ -238,11 +238,11 @@ Here is what they mean: - `remote` versions of the above rules work the same but the requester's certificate is instead required to match a thumbprint marked as a remote organization. - `practitioner` suffixes all work the same. They include the same rules as their prefixes but now additionally require the requester to match a certain `practitioner-role`. A list of them can be found [here](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/CodeSystem/dsf-practitioner-role-1.0.0.xml). This allows - for more granularity when defining authorization rules within an organization and can be integrated into local user management via [OpenID Connect](https://dsf.dev/operations/latest/fhir/access-control.html). + for more granularity when defining authorization rules within an organization and can be integrated into local user management via [OpenID Connect](https://dsf.dev/stable/maintain/fhir/access-control.html). -As you can see, there are no `practitioner` versions of `remote` authorization rules. From the perspective of the receiving DSF instance, remote requests are always issued by an organization. They do not hold any information about the local user management of the requesting organization. You can also find examples of all Codings from above [here](../dsf/requester-and-recipient.md). +There are no `practitioner` versions of `remote` authorization rules. From the perspective of the receiving DSF instance, remote requests are always issued by an organization. They do not hold any information about the local user management of the requesting organization. Examples of all Codings from above can be found [here](../dsf/requester-and-recipient.md). -It is also good to keep in mind that you are allowed to add any number of `requester` elements into your [ActivityDefinition](../fhir/activitydefinition.md). Let us start out by adding a `requester` element like we did for previous elements: +It is also good to keep in mind that any number of `requester` elements may be added to an [ActivityDefinition](../fhir/activitydefinition.md). Start out by adding a `requester` element like previous extensions: ```xml <extension url="requester"> @@ -252,7 +252,7 @@ It is also good to keep in mind that you are allowed to add any number of `reque </extension> ``` -We now have to look at the elements that are defined in one of the profiles to fill in the remaining elements since they are not defined by the `requester` extension. For demonstration purposes, we will choose the [dsf-coding-process-authorization-local-organization-practitioner](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-coding-process-authorization-local-organization-practitioner-1.0.0.xml) profile. Since all elements listed in the [Coding definition](https://www.hl7.org/fhir/R4/datatypes.html#codesystem) are optional, we only have to look at the `differential` element from the profile we just selected: +The remaining element definitions are found in one of the profiles. This example will use the [dsf-coding-process-authorization-local-organization-practitioner](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-coding-process-authorization-local-organization-practitioner-1.0.0.xml) profile. Since all elements listed in the [Coding definition](https://www.hl7.org/fhir/R4/datatypes.html#codesystem) are optional, only the `differential` elements from the profile are relevant: <a id="coding-differential"></a> ```xml <differential> @@ -288,7 +288,7 @@ We now have to look at the elements that are defined in one of the profiles to f </element> </differential> ``` -It defines an extension called `organization-practitioner` which is identified through its url attribute. Again, the extension is only referenced, its location is in a different file. You can find it [here](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-extension-process-authorization-organization-practitioner-1.0.0.xml). Let us look at its `differential` element in the extension file to see how we need to populate the extension: +It defines an extension called `organization-practitioner` which is identified through its url attribute. Again, the extension is only referenced, its location is in a [different file](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-extension-process-authorization-organization-practitioner-1.0.0.xml). Below is its `differential` element in order to see how the extension needs to be populated: ```xml <differential> <element id="Extension"> @@ -368,16 +368,16 @@ It defines an extension called `organization-practitioner` which is identified t </differential> ``` -This extension does not reference any other files. This means we reached the "deepest" level. So now we can start working our way back up again from here, by translating this definition into actual extension elements, then inserting it into the Coding we selected, translating the rest of the element definitions from the Coding resource and adding everything to our [ActivityDefinition](../fhir/activitydefinition.md). +This extension does not reference any other files. This means this is the "deepest" level. The process can now proceed by translating this definition into actual extension elements, inserting it into the selected Coding, translating the remaining element definitions from the Coding resource, and incorporating all components into the [ActivityDefinition](../fhir/activitydefinition.md). -We will start with the `Extension.url` element, since the `Extension` element is the parent element for all slices on the `Extension.extension` elements: +Start with the `Extension.url` element, since the `Extension` element is the parent element for all slices on the `Extension.extension` elements: ```xml <extension url="http://dsf.dev/fhir/StructureDefinition/extension-process-authorization-organization-practitioner"> </extension> ``` -Next, we will add the `organization` slice: +Next, add the `organization` slice: ```xml <extension url="http://dsf.dev/fhir/StructureDefinition/extension-process-authorization-organization-practitioner"> <extension url="organization"> @@ -388,7 +388,7 @@ Next, we will add the `organization` slice: </extension> </extension> ``` -Finally, we will add the `practitionerRole` slice: +Finally, add the `practitionerRole` slice: ```xml <extension url="http://dsf.dev/fhir/StructureDefinition/extension-process-authorization-organization-practitioner"> @@ -407,9 +407,9 @@ Finally, we will add the `practitionerRole` slice: </extension> ``` -Notice that there is no `binding` element specified for `practitionerRole.value[x]`. This is intentional. In the example we used a code from the [dsf-practitioner-role](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/CodeSystem/dsf-practitioner-role-1.0.0.xml) CodeSystem. This CodeSystem includes a standard set of codes which are often sufficient for DSF use cases. You can freely add other CodeSystems if you find these codes do not apply for your use case. The code you set here can be used in the [DSF role config](https://dsf.dev/operations/latest/fhir/access-control.html) to allow certain users with this `practitioner-role` to send requests. +There is no `binding` element specified for `practitionerRole.value[x]`. This is intentional. The example used a code from the [dsf-practitioner-role](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/CodeSystem/dsf-practitioner-role-1.0.0.xml) CodeSystem. This CodeSystem includes a standard set of codes which are often sufficient for DSF use cases. Other/new CodeSystems if may be added if these codes do not apply for a given use case. The code set here can be used in the [DSF role config](https://dsf.dev/stable/maintain/fhir/access-control.html) to allow certain users with this `practitioner-role` to send requests. -Working our way back up to the Coding we selected, we will now add the extension we just created as the `Coding.extension:organization-practitioner` element: +Now add the extension as the `Coding.extension:organization-practitioner` element: ```xml <extension url="requester"> <valueCoding> @@ -430,7 +430,7 @@ Working our way back up to the Coding we selected, we will now add the extension </valueCoding> </extension> ``` -Now might be a good time to look at the [differential](#coding-differential) from the Coding again. Our next elements to be added are `Coding.system` and `Coding.code`: +Look at the [differential](#coding-differential) from the Coding again. The next elements to be added are `Coding.system` and `Coding.code`: ```xml <extension url="requester"> <valueCoding> @@ -453,10 +453,10 @@ Now might be a good time to look at the [differential](#coding-differential) fro </valueCoding> </extension> ``` -Now we are finished with the `requester` extension and can add it to our [ActivityDefinition](../fhir/activitydefinition.md) under the [dsf-extension-process-authorization](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-extension-process-authorization-1.0.0.xml). +The `requester` extension is now finished and can be added it to the [ActivityDefinition](../fhir/activitydefinition.md) under the [dsf-extension-process-authorization](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-extension-process-authorization-1.0.0.xml). <details> -<summary>This is how your ActivityDefinition should look like so far</summary> +<summary>This is how the ActivityDefinition should look like so far</summary> ```xml <ActivityDefinition xmlns="http://hl7.org/fhir"> @@ -498,7 +498,7 @@ Now we are finished with the `requester` extension and can add it to our [Activi ``` </details> -Now we are back to looking at the [dsf-extension-process-authorization](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-extension-process-authorization-1.0.0.xml) again. The last slice for this extension is `recipient`: +Back to looking at the [dsf-extension-process-authorization](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-extension-process-authorization-1.0.0.xml) again. The last slice for this extension is `recipient`: ```xml <StructureDefinition xmlns="http://hl7.org/fhir"> ... @@ -532,10 +532,10 @@ Now we are back to looking at the [dsf-extension-process-authorization](https:// </StructureDefinition> ``` -The `recipient` will decide which DSF instance is allowed to process that message. That is the reason why you will not find any Codings for `remote` or `practitioner` here. For `requester`, we already decided that we will only allow users with a certain role from our own (local) organization to send this message. So now we will only allow the DSF instance run by that same local organization to process the message. The right Coding for this job is the [coding-process-authorization-local-organization](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-coding-process-authorization-local-organization-1.0.0.xml). The configuration of a local requester and local receiver is often used for the message that starts up the first BPMN process of the plugin. The process of adding the `recipient` slice is the exact same as it is for `requester`. You can follow the steps for the `requester` slice again but just use a different Coding. +The `recipient` will decide which DSF instance is allowed to process that message. That is the reason why there are no Codings for `remote` or `practitioner` here. For `requester`, it was decided to only allow users with a certain role from a local organization to send this message. The message should now also only be processable by that same local organization. The right Coding for this job is the [coding-process-authorization-local-organization](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-coding-process-authorization-local-organization-1.0.0.xml). The configuration of a local requester and local receiver is often used for the message that starts up the first BPMN process of the plugin. The process of adding the `recipient` slice is the exact same as it is for `requester`. It's possible to follow the same steps for the `requester` slice again but using a different Coding. <details> -<summary>Using the Coding we just decided on, this is how your ActivityDefinition should look like</summary> +<summary>This is how the ActivityDefinition should look like</summary> ```xml <ActivityDefinition xmlns="http://hl7.org/fhir"> @@ -589,7 +589,7 @@ The `recipient` will decide which DSF instance is allowed to process that messag ``` </details> -The last element defined in the [process authorization extension](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-extension-process-authorization-1.0.0.xml) is `Extension.url`. But since we added this element at the very beginning of the working through the extension, we are finished with it here. +The last element defined in the [process authorization extension](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-extension-process-authorization-1.0.0.xml) is `Extension.url`. This was already added at the very beginning of the working through the extension, so there is nothing more to add. #### 3. BPE Managed Elements @@ -597,11 +597,11 @@ Some elements of [ActivityDefinitions](../fhir/activitydefinition.md) are manage The following elements are managed by the DSF BPE: - `ActivityDefinition.version` should use the [placeholder](../dsf/versions-placeholders-urls.md#placeholders) `#{version}` -- `ActivityDefinition.date` is not required, but should you decide to include it, use the [placeholder](../dsf/versions-placeholders-urls.md#placeholders) `#{date}` +- `ActivityDefinition.date` is not required, but if it is included, it should use the [placeholder](../dsf/versions-placeholders-urls.md#placeholders) `#{date}` - `ActivityDefinition.status` must have a value of `unknown` <details> -<summary>Your ActivityDefinition should now look like this</summary> +<summary>The ActivityDefinition should now look like this</summary> ```xml <ActivityDefinition xmlns="http://hl7.org/fhir"> @@ -661,10 +661,10 @@ The following elements are managed by the DSF BPE: ``` </details> -#### 4. Regular Elements +### 4. Regular Elements -The only required elements in this set are `ActivityDefinition.url` and `ActivityDefinition.kind`. Check out the documentation on [URLs](../dsf/versions-placeholders-urls.md#urls) on how to choose the correct value for `ActivityDefinition.url`. `ActivityDefinition.kind` must have the value `Task`. -All other elements can technically be omitted. Still, we recommend you include the following elements: +The only required elements in this set are `ActivityDefinition.url` and `ActivityDefinition.kind`. `ActivityDefinition.url` expects a certain format. This is explained in detail in the [documentation on URLs](../dsf/versions-placeholders-urls.md#urls). `ActivityDefinition.kind` must have the value `Task`. +All other elements can technically be omitted. Still, the following elements are recommended to be populated: - `AcitivityDefinition.name` - `AcitivityDefinition.title` - `AcitivityDefinition.subtitle` @@ -674,7 +674,7 @@ All other elements can technically be omitted. Still, we recommend you include t - `AcitivityDefinition.description` <details> -<summary>Your finished ActivityDefinition should now look something like this</summary> +<summary>The finished ActivityDefinition should now look something like this</summary> ```xml <ActivityDefinition xmlns="http://hl7.org/fhir"> @@ -747,4 +747,7 @@ All other elements can technically be omitted. Still, we recommend you include t <description value="My Process processes information"/> </ActivityDefinition> ``` -</details> \ No newline at end of file +</details> + +## Related Topics +[ActivityDefinition](../fhir/activitydefinition.md), [Creating CodeSystems for DSF Processes](creating-codesystems-for-dsf-processes.md), [Creating ValueSets for DSF Processes](creating-valuesets-for-dsf-processes.md), [Task](../fhir/task.md) diff --git a/docs/src/process-development/api-v1/guides/creating-codesystems-for-dsf-processes.md b/docs/src/process-development/api-v1/guides/creating-codesystems-for-dsf-processes.md index 5ab6d87f1..c6e45e0d0 100644 --- a/docs/src/process-development/api-v1/guides/creating-codesystems-for-dsf-processes.md +++ b/docs/src/process-development/api-v1/guides/creating-codesystems-for-dsf-processes.md @@ -3,9 +3,9 @@ title: Creating CodeSystems for DSF Processes icon: creative --- -### Creating CodeSystems for DSF Processes +## Creating CodeSystems for DSF Processes -You might find yourself in a situation where you need to create a [CodeSystem](../fhir/codesystem.md). For example, when defining the type of an [Input Parameter](../fhir/task.md#task-input-parameters). [CodeSystems](../fhir/codesystem.md) for the DSF differ from regular [CodeSystems](../fhir/codesystem.md) in that some element's values are managed by the DSF BPE server. You can use the following XML as a template: +Sometimes it is necessary to create custom [CodeSystem](../fhir/codesystem.md) resources. For example, when defining the type of an [Input Parameter](../fhir/task.md#task-input-parameters). [CodeSystems](../fhir/codesystem.md) for the DSF differ from regular [CodeSystems](../fhir/codesystem.md) in that some element's values are managed by the DSF BPE server. The following template can be populated with custom values: ```xml <CodeSystem xmlns="http://hl7.org/fhir"> <meta> @@ -37,6 +37,9 @@ You might find yourself in a situation where you need to create a [CodeSystem](. </concept> </CodeSystem> ``` -Replace dummy values with appropriate values of your own. Do not change elements managed by the DSF BPE server. You can add as many codes as you like by defining more `concept` elements. +Dummy values should be replaced with appropriate values. Elements managed by the DSF BPE server should not be changed. More codes can be added by defining more `concept` elements. -The DSF BPE server will read your [CodeSystem](../fhir/codesystem.md) from `tutorial-process/src/main/resources/fhir/CodeSystem`. \ No newline at end of file +When building a plugin, the [CodeSystem](../fhir/codesystem.md) is expected to be in `src/main/resources/fhir/CodeSystem` of the Java project. + +## Related Topics +[Adding Task Input Parameters to Task Profiles](adding-task-input-parameters-to-task-profiles.md), [CodeSystem](../fhir/codesystem.md), [Creating ValueSets for DSF processes](creating-valuesets-for-dsf-processes.md), [ValueSet](../fhir/valueset.md) diff --git a/docs/src/process-development/api-v1/guides/creating-task-resources-based-on-a-definition.md b/docs/src/process-development/api-v1/guides/creating-task-resources-based-on-a-definition.md index 6306ab128..34a1c0092 100644 --- a/docs/src/process-development/api-v1/guides/creating-task-resources-based-on-a-definition.md +++ b/docs/src/process-development/api-v1/guides/creating-task-resources-based-on-a-definition.md @@ -3,27 +3,29 @@ title: Creating Task Resources Based on a Definition icon: creative --- -### Creating Task Resources Based on a Definition +## Creating Task Resources Based on a Definition -This short guide should help you understand how you can create [Task](../fhir/task.md) resources for use in [Starting A Process Via Task Resources](../guides/starting-a-process-via-task-resources.md). We will employ the use of the free version of [Forge](https://simplifier.net/forge?utm_source=firely-forge) to help with visualization. You are invited to create a free account and follow along, but we will include screenshots of relevant views either way. Remember that the free version of Forge [must not be used commercially](https://simplifier.net/pricing). As an example, we will create a [Task](../fhir/task.md) resource from the `task-start-dic-process.xml` profile. +This short guide provides an overview of how to create [Task](../fhir/task.md) resources for use in [Starting A Process Via Task Resources](../guides/starting-a-process-via-task-resources.md). The free version of [Forge](https://simplifier.net/forge?utm_source=firely-forge) is used to support visualization. A free account can be created to follow the process directly; however, screenshots of relevant views are included for reference. Note that the free version of Forge [must not be used commercially](https://simplifier.net/pricing). As an example, a [Task](../fhir/task.md) resource based on the [`task-start-dic-process.xml`](https://github.com/datasharingframework/dsf-process-tutorial/blob/main/tutorial-process/src/main/resources/fhir/StructureDefinition/task-start-dic-process.xml) profile is created. -#### 1st Step: Removing Placeholders -`task-start-dic-process.xml` includes placeholders for the `version` and `date` elements. For the duration of this guide, you can either remove or comment these elements, so Forge does not try to perform type checking on them, which would result in an error and Forge not loading the file. -#### 2nd Step: Differential Chain -If the resource profile is only available as a [differential](https://www.hl7.org/fhir/R4/profiling.html#snapshot), like in our case, we will want to aggregate the changes made to the base resource (in this case [Task](../fhir/task.md)) by all profiles to make it more readable. To do this, we first need all the profiles involved. We already have `task-start-dic-process.xml` in our `StructureDefinition` folder. It lists a resource called `task-base` in its `baseDefinition` element. This resource is part of the DSF and can be found [here](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-task-base-1.0.0.xml). Put it into the `StructureDefinition` folder. Since `task-base` has the original FHIR Task as its `baseDefinition` element, we are done with this chain. In forge, you should now be able to open the `StructureDefinition` folder and select the `task-start-dic-process.xml` profile. It should look something like this: +### 1st Step: Removing Placeholders +[`task-start-dic-process.xml`](https://github.com/datasharingframework/dsf-process-tutorial/blob/main/tutorial-process/src/main/resources/fhir/StructureDefinition/task-start-dic-process.xml) includes placeholders for the `version` and `date` elements. For the purpose of this guide, these elements can either be removed or commented out to prevent Forge from performing type checking on them, which would otherwise result in an error and cause Forge to not load the file. + +### 2nd Step: Differential Chain +If the resource profile is only available as a [differential](https://www.hl7.org/fhir/R4/profiling.html#snapshot), as in this case, it is helpful to aggregate the changes made to the base resource (in this case [Task](../fhir/task.md)) by all profiles to improve readability. To accomplish this, all relevant profiles are required. The [`task-start-dic-process.xml`](https://github.com/datasharingframework/dsf-process-tutorial/blob/main/tutorial-process/src/main/resources/fhir/StructureDefinition/task-start-dic-process.xml) file is already present. This file lists a resource called `task-base` in its `baseDefinition` element. The `task-base` resource is part of the DSF and can be found [here](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-task-base-1.0.0.xml). It should also be placed in the same folder as [`task-start-dic-process.xml`](https://github.com/datasharingframework/dsf-process-tutorial/blob/main/tutorial-process/src/main/resources/fhir/StructureDefinition/task-start-dic-process.xml). Since `task-base` uses the original FHIR Task as its `baseDefinition` element, no additional resources are needed to complete this chain. In Forge, opening the folder containing both resources and selecting the [`task-start-dic-process.xml`](https://github.com/datasharingframework/dsf-process-tutorial/blob/main/tutorial-process/src/main/resources/fhir/StructureDefinition/task-start-dic-process.xml) profile should display a view similar to the following: + ![Forge overview](/photos/developer-documentation/forge_overview.png) -#### 3rd Step: Building the Task Resource -We will now go through each element one by one and include it into our [Task](../fhir/task.md) resource, provided it is mandatory (cardinality at least `1..1`) according to the profile. It is important that you not use any placeholders like `#{version}` for resources not read by the DSF BPE server. This is the case if we want a [Task](../fhir/task.md) resource for use with [cURL](../guides/starting-a-process-via-task-resources.md#using-curl). But, placeholders should be used in [Draft Task Resources](../dsf/draft-task-resources.md) instead of actual values wherever possible, since those are read by the DSF BPE server. This guide will create a [Task](../fhir/task.md) resource without placeholders. We will start out with the base element for all [Task](../fhir/task.md) resources: +### 3rd Step: Building the Task Resource +Each element will now be reviewed and included in the [Task](../fhir/task.md) resource if it is mandatory (cardinality of at least `1..1`) according to the profile. Placeholders such as `#{version}` must not be used for resources that are not read by the DSF BPE server. This applies when creating a [Task](../fhir/task.md) resource intended for use with [cURL](../guides/starting-a-process-via-task-resources.md#using-curl). In contrast, placeholders should be used in [Draft Task Resources](../dsf/draft-task-resources.md) instead of actual values wherever possible, as these resources are read by the DSF BPE server. This guide demonstrates the creation of a [Task](../fhir/task.md) resource without placeholders, beginning with the base element required for all [Task](../fhir/task.md) resources: ```xml <Task xmlns="http://hl7.org/fhir"> </Task> ``` -Before we start adding any elements listed in Forge's element tree, we have to include the `Task.meta.profile` element. Its requirement cannot be seen here which is why we mention it specifically. This is the only instance you will not see it in the element tree. It should look like this: +Before adding any elements listed in Forge's element tree, the `Task.meta.profile` element must be included. Its requirement is not visible in the element tree, which is why it is mentioned explicitly. This is the only instance where it does not appear in the element tree. It should look like this: ```xml <Task xmlns="http://hl7.org/fhir"> <meta> @@ -32,7 +34,7 @@ Before we start adding any elements listed in Forge's element tree, we have to i </Task> ``` -The first element which can be found in the element tree is the `instantiatesCanonical` element. To add it, we will create an XML element with the same name and the value according to [URLs](../dsf/versions-placeholders-urls.md#urls): +The first element listed in the element tree is the `instantiatesCanonical` element. To add this element, an XML element with the same name should be created, using a value as specified in [URLs](../dsf/versions-placeholders-urls.md#urls): ```xml <Task xmlns="http://hl7.org/fhir"> <meta> @@ -43,7 +45,7 @@ The first element which can be found in the element tree is the `instantiatesCan ``` We can continue this process for all primitive elements like these. Just make sure you pay attention to use the correct data type (e.g. proper coding value for elements with `coding` type). -By now your [Task](../fhir/task.md) resources should look something like this: +The [Task](../fhir/task.md) resource should look something like this: <details> <summary>Suggested solution</summary> @@ -60,11 +62,11 @@ By now your [Task](../fhir/task.md) resources should look something like this: ``` </details> -Let us look at a more complex element like the `requester` element: +Now a more complex element like the `requester` element: ![Forge requester view](/photos/developer-documentation/forge_requester_view.png) -We will start the same way we started with primitive elements, by adding the `requester` element: +The beginning is the same as primitive elements, adding the `requester` element: ```xml <Task xmlns="http://hl7.org/fhir"> <meta> @@ -80,7 +82,7 @@ We will start the same way we started with primitive elements, by adding the `re </Task> ``` -Then, we will add primitive elements to `requester` like we did before for `Task`: +Then, primitive elements are added to `requester` like before for `Task`: ```xml <Task xmlns="http://hl7.org/fhir"> <meta> @@ -97,7 +99,7 @@ Then, we will add primitive elements to `requester` like we did before for `Task ``` *Important to note here that the value for the `status` will always be `requested` for Tasks being posted using cURL and the `type` element for `requester` and `recipient` will always have the value `Organization` in the DSF context.* -Next, we will add the `identifier` element and its primitive sub-elements just like we started out doing it for the `requester` element. The `identifier.value` in this case will be `dic.dsf.test`. To understand why, take a look at the topic on [organization identifiers](../dsf/organization-identifiers.md): +Next, the `identifier` element and its primitive sub-elements are added just like before. The `identifier.value` in this case will be `dic.dsf.test`. To understand why, take a look at the topic on [organization identifiers](../dsf/organization-identifiers.md): ```xml <Task xmlns="http://hl7.org/fhir"> <meta> @@ -116,9 +118,9 @@ Next, we will add the `identifier` element and its primitive sub-elements just l </requester> </Task> ``` -*Notice that `requester.identifier.system` has a `Fixed value` annotation. You can see what the value is supposed to be by clicking on the `system` element in Forge or looking at the XML for the right Task profile. The right side will have all information about that element, including the actual value for `Fixed value`.* +*The `requester.identifier.system` has a `Fixed value` annotation. Clicking on the `system` element in Forge or looking at the XML for the right Task profile reveals what the value is supposed to be. The right side will have all information about that element, including the actual value for `Fixed value`.* -You should now be able to fill out all elements in your [Task](../fhir/task.md) resource until you reach the [slicing](https://www.hl7.org/fhir/R4/profiling.html#slicing) for `Task.input`. Your [Task](../fhir/task.md) resource should look something like this: +Filling out all elements in the [Task](../fhir/task.md) resource is now the same until the [slicing](https://www.hl7.org/fhir/R4/profiling.html#slicing) for `Task.input`. The [Task](../fhir/task.md) resource should look something like this: <details> <summary>Suggested solution</summary> @@ -152,11 +154,11 @@ You should now be able to fill out all elements in your [Task](../fhir/task.md) </details> -[Slicings](https://www.hl7.org/fhir/R4/profiling.html#slicing) are a bit different from regular elements. Let us look at the slice `message-name`: +[Slicings](https://www.hl7.org/fhir/R4/profiling.html#slicing) are a bit different from regular elements. Starting with the slice `message-name`: ![Forge slice message name](/photos/developer-documentation/forge_slice_message_name.png) -If we were to continue including slices to the [Task](../fhir/task.md) resource like we did so far, we would add a `message-name` element to our XML like this: +Including slices to the [Task](../fhir/task.md) resource like previous element would add a `message-name` element to our XML like this: ```xml <Task xmlns="http://hl7.org/fhir"> @@ -169,7 +171,7 @@ If we were to continue including slices to the [Task](../fhir/task.md) resource </Task> ``` -This approach however, would not work. FHIR processors do not use the name of the slice to map entries in your [Task](../fhir/task.md) resource to the correct slice. They use [discriminators](https://www.hl7.org/fhir/R4/profiling.html#discriminator). Discriminators define the elements a processor needs to distinguish slices by. You can see how the discriminator is configured by selecting the `input` element in Forge. In our case, a processor would look at the values for `input.type.coding.system` and `input.type.coding.code` to determine which slice this element belongs to. This only works because `input.type.coding.system` and `input.type.coding.code` are present in all slices and have a `Fixed value`. You can learn more about discriminators [here](https://www.hl7.org/fhir/R4/profiling.html#discriminator). All this means is that we effectively ignore the name of the slice as an element and start adding elements like we did before: +This approach however, would not work. FHIR processors do not use the name of the slice to map entries in your [Task](../fhir/task.md) resource to the correct slice. They use [discriminators](https://www.hl7.org/fhir/R4/profiling.html#discriminator). Discriminators define the elements a processor needs to distinguish slices by. The discriminator configuration can be seen by selecting the `input` element in Forge. In this case, a processor would look at the values for `input.type.coding.system` and `input.type.coding.code` to determine which slice this element belongs to. This only works because `input.type.coding.system` and `input.type.coding.code` are present in all slices and have a `Fixed value`. More about discriminators can be read [here](https://www.hl7.org/fhir/R4/profiling.html#discriminator). This means effectively ignoring the name of the slice as an element and start adding elements like before: ```xml <Task xmlns="http://hl7.org/fhir"> @@ -186,7 +188,7 @@ This approach however, would not work. FHIR processors do not use the name of th </Task> ``` -Now you should be able to add all remaining mandatory elements to your [Task](../fhir/task.md) resource on your own. In the end, it should look something like this: +This covers all ways of adding elements. Adding the remaining elements is left as an exercise. In the end, it should look something like this: <details> <summary>Suggested solution</summary> @@ -228,4 +230,7 @@ Now you should be able to add all remaining mandatory elements to your [Task](.. ``` </details> -**Do not forget to restore the version and date placeholders in `task-start-dic-process.xml`!** \ No newline at end of file +**Do not forget to restore the version and date placeholders in [`task-start-dic-process.xml`](https://github.com/datasharingframework/dsf-process-tutorial/blob/main/tutorial-process/src/main/resources/fhir/StructureDefinition/task-start-dic-process.xml) when reusing the resource in a process plugin!** + +## Related Topics +[Draft Task Resources](../dsf/draft-task-resources.md), [Task](../fhir/task.md) diff --git a/docs/src/process-development/api-v1/guides/creating-valuesets-for-dsf-processes.md b/docs/src/process-development/api-v1/guides/creating-valuesets-for-dsf-processes.md index f273196ec..69f7744db 100644 --- a/docs/src/process-development/api-v1/guides/creating-valuesets-for-dsf-processes.md +++ b/docs/src/process-development/api-v1/guides/creating-valuesets-for-dsf-processes.md @@ -3,10 +3,10 @@ title: Creating ValueSets for DSF Processes icon: creative --- -### Creating ValueSets for DSF Processes +## Creating ValueSets for DSF Processes + +In some cases, it may be necessary to create a [ValueSet](../fhir/valueset.md). For example, when adding [Input Parameters](../fhir/task.md#task-input-parameters) to DSF [Task](../fhir/task.md) resources, a [ValueSet](../fhir/valueset.md) resource must also be referenced in the binding for `Task.input.type` to define the type of the [Input Parameter](../fhir/task.md#task-input-parameters). [ValueSets](../fhir/valueset.md) for the DSF differ from regular [ValueSets](../fhir/valueset.md) in that certain element values are managed by the DSF BPE server. The following template can be used for a [ValueSet](../fhir/valueset.md): -You might find yourself in the situation where you need to create a [ValueSet](../fhir/valueset.md). For example, when adding [Input Parameters](../fhir/task.md#task-input-parameters) to DSF [Task](../fhir/task.md) resources, you will also have to reference a [ValueSet](../fhir/valueset.md) resource in your binding for `Task.input.type` to be able to set the type of your [Input Parameter](../fhir/task.md#task-input-parameters). [ValueSets](../fhir/valueset.md) for the DSF differ from regular [ValueSets](../fhir/valueset.md) in that some element's values are managed by the DSF BPE server. You can use the following template for your -[ValueSet](../fhir/valueset.md): ```xml <ValueSet xmlns="http://hl7.org/fhir"> <meta> @@ -36,7 +36,7 @@ You might find yourself in the situation where you need to create a [ValueSet](. </compose> </ValueSet> ``` -Replace dummy values with appropriate values of your own. Do not change elements managed by the DSF BPE server. The `compose` element defines the codes included in this [ValueSet](../fhir/valueset.md). It holds at least one `include` element. Each `include` element refers to a [CodeSystem](../fhir/codesystem.md) and contains a list of `concept` elements which in turn contain the actual `code` element. Using one code from `my-code-system` and one code from `my-other-code-system` would result in the following `compose` element: +Dummy values should be replaced with appropriate, context-specific values. Elements managed by the DSF BPE server must not be modified. The `compose` element defines the codes included in this [ValueSet](../fhir/valueset.md) and contains at least one `include` element. Each `include` element references a [CodeSystem](../fhir/codesystem.md) and includes a list of `concept` elements, each containing an individual `code` element. The use of one code from `my-code-system` and one code from `my-other-code-system` results in the following `compose` element: ```xml <ValueSet xmlns="http://hl7.org/fhir"> ... @@ -58,6 +58,7 @@ Replace dummy values with appropriate values of your own. Do not change elements </compose> </ValueSet> ``` -The DSF BPE server will read your [ValueSet](../fhir/valueset.md) from `tutorial-process/src/main/resources/fhir/ValueSet`. +When building a plugin, the [ValueSet](../fhir/valueset.md) is expected to be in `src/main/resources/fhir/CodeSystem` of the Java project. -You might also want to check out [this guide](../guides/creating-codesystems-for-dsf-processes.md) on how to create [CodeSystems](../fhir/codesystem.md). \ No newline at end of file +## Related Topics +[CodeSystem](../fhir/codesystem.md), [Creating CodeSystems for DSF processes](creating-codesystems-for-dsf-processes.md), [ValueSet](../fhir/valueset.md) diff --git a/docs/src/process-development/api-v1/guides/managing-mutiple-incoming-messages-and-missing-messages.md b/docs/src/process-development/api-v1/guides/managing-mutiple-incoming-messages-and-missing-messages.md index a0c8f6120..a0cf72993 100644 --- a/docs/src/process-development/api-v1/guides/managing-mutiple-incoming-messages-and-missing-messages.md +++ b/docs/src/process-development/api-v1/guides/managing-mutiple-incoming-messages-and-missing-messages.md @@ -3,16 +3,20 @@ title: Managing Multiple Incoming Messages and Missing Messages icon: creative --- -### Managing Multiple Incoming Messages and Missing Messages +## Managing Multiple Incoming Messages and Missing Messages If an already running process instance is waiting for a message from another organization, the corresponding FHIR [Task](../fhir/task.md) may never arrive. Either because the other organization decides to never send the message or because some technical problem prohibits the [Task](../fhir/task.md) resource from being posted to the DSF FHIR server. This would result in stale process instances that never finish. -At the same time, you might also expect to receive one out of a number of different message types at once. +At the same time, it might also be expected to receive one out of a number of different message types at once. -In order to solve both problems we can add an [Event Based Gateway](../bpmn/gateways.md#event-based-gateway) to the process waiting for a response and then either handle a [Task](../fhir/task.md) resource with the response and finish the process in a success state or trigger a [Timer Intermediate Catching Event](../bpmn/timer-intermediate-catching-events.md) after a defined wait period and finish the process in an error state. The following BPMN collaboration diagram shows how the process at the first organization would look like if we wanted to react to multiple different messages or missing messages: +An [Event Based Gateway](../bpmn/gateways.md#event-based-gateway) can be used to solve both problems by adding it to the process waiting for a response and then either handling a [Task](../fhir/task.md) resource with the response and finish the process in a success state or triggering a [Timer Intermediate Catching Event](../bpmn/timer-intermediate-catching-events.md) after a defined wait period and finish the process in an error state. The following BPMN collaboration diagram shows how the process at the first organization would look like if we wanted to react to multiple different messages or missing messages: <picture> <source media="(prefers-color-scheme: dark)" srcset="/photos/developer-documentation/event_based_gateway_inverted.svg"> <source media="(prefers-color-scheme: light)" srcset="/photos/developer-documentation/event_based_gateway.svg"> <img alt="BPMN collaboration diagram with an Event Based Gateway" src="/photos/developer-documentation/event_based_gateway.svg"> </picture> + + +## Related Topics +[Gateways](../bpmn/gateways.md), [Message Correlation](../dsf/message-correlation.md), [Message Delegates](../dsf/message-delegates.md) \ No newline at end of file diff --git a/docs/src/process-development/api-v1/guides/setting-targets-for-message-events.md b/docs/src/process-development/api-v1/guides/setting-targets-for-message-events.md index 68db0b1e0..d5ea828e5 100644 --- a/docs/src/process-development/api-v1/guides/setting-targets-for-message-events.md +++ b/docs/src/process-development/api-v1/guides/setting-targets-for-message-events.md @@ -3,12 +3,10 @@ title: Setting Targets for Message Events icon: creative --- -### Setting Targets for Message Events +## Setting Targets for Message Events -Setting a target for a message event requires a `Target` object. To create one, you require a target's organization identifier, endpoint identifier and endpoint address. You can find these values by visiting the DSF FHIR server's web interface. In the top right corner, click the `Show Bookmarks` button, then select `Endpoint`. You will be taken to a list of all Endpoints available to the FHIR server. There are two ways of adding `targets` to the BPMN execution variables: -#### 1. Adding the target in the message event implementation -In your message event implementation (the class extending `AbstractTaskMessageSend`), you can override `AbstractTaskMessageSend#doExecute`, add your targets and then call the super-method. -#### 2. Adding the target in a service task right before the message event -This is the preferred method of this tutorial but both methods will work perfectly fine. For our use cases, we usually prefer this one since there is enough complexity to warrant putting it into a separate BPMN [Service Task](../bpmn/service-tasks.md). +Setting a target for a message event requires a `Target` object. Creating this object requires the target's organization identifier, endpoint identifier, and endpoint address. These values can be obtained from the DSF FHIR server's web interface or by querying the FHIR server via an instance of `FhirWebserviceClient`. By clicking the `Show Bookmarks` button in the top right corner and selecting `Endpoint`, a list of all Endpoints available to the FHIR server will be displayed. Instances of `FhirWebserviceClient` can be accessed via the [process plugin API](../dsf/process-plugin-api.md). +Targets should be added in a [Service Task](../bpmn/service-tasks.md) before a [Message Event](../bpmn/messaging.md). A `Variables` instance provides helper methods to set targets in a [Service Task's](../bpmn/service-tasks.md) `doExecute` method. -In both cases you can access methods to create and set `targets` through the `Variables` instance. +## Related Topics +[Process Plugin API](../dsf/process-plugin-api.md), [Message Correlation](../dsf/message-correlation.md), [Target and Targets](../dsf/target-and-targets.md) diff --git a/docs/src/process-development/api-v1/guides/starting-a-process-via-task-resources.md b/docs/src/process-development/api-v1/guides/starting-a-process-via-task-resources.md index baa36a7bb..aaf7287fd 100644 --- a/docs/src/process-development/api-v1/guides/starting-a-process-via-task-resources.md +++ b/docs/src/process-development/api-v1/guides/starting-a-process-via-task-resources.md @@ -3,20 +3,19 @@ title: Starting a Process via Task Resources icon: creative --- -### Starting a Process via Task Resources +## Starting a Process via Task Resources -To start a BPMN process, you need to create new a [Task](../fhir/task.md) resource in the DSF FHIR server by sending an HTTP request according to the [FHIR RESTful API](https://www.hl7.org/fhir/R4/http.html). Specifically, you need to [create](https://www.hl7.org/fhir/R4/http.html#create) -a resource for the first time. Also, remember that the [Task](../fhir/task.md) resource you are sending needs to comply to the [Task](../fhir/task.md) profile of the process you want to start and the [ActivityDefinition's](../fhir/activitydefinition.md) authorization rules. +To start a BPMN process, a new [Task](../fhir/task.md) resource must be created in the DSF FHIR server by sending an HTTP request in accordance with the [FHIR RESTful API](https://www.hl7.org/fhir/R4/http.html). Specifically, a [create](https://www.hl7.org/fhir/R4/http.html#create) operation is required to generate the resource for the first time. The [Task](../fhir/task.md) resource being sent must conform to the [Task](../fhir/task.md) profile of the intended process and adhere to the [ActivityDefinition's](../fhir/activitydefinition.md) authorization rules. There are two major ways of making this HTTP request: 1. Using cURL 2. Using the DSF FHIR server's web interface -#### Using cURL -In order to use cURL, you will have to create an appropriate [Task](../fhir/task.md) resource to post to the DSF FHIR server. There already is a file called `example-task.xml` located in `tutorial-process/src/main/resources/fhir`. You can use this as your starting point. You can try to follow [this guide](../guides/creating-task-resources-based-on-a-definition.md), or you can check the solution branches for this file if you need ideas on how to fill it out properly. +### Using cURL +To use cURL, an appropriate [Task](../fhir/task.md) resource must be created and posted to the DSF FHIR server. There is a guide on [creating Task Resources based on a StructureDefinition](../guides/creating-task-resources-based-on-a-definition.md). A file named `example-task.xml` is available in `tutorial-process/src/main/resources/fhir` in the [DSF Process Tutorial](https://github.com/datasharingframework/dsf-process-tutorial) and can serve as a starting point. The [solution branches of the tutorial](https://github.com/datasharingframework/dsf-process-tutorial/blob/solutions/exercise-1/tutorial-process/src/main/resources/fhir/Task/task-start-dic-process.xml) can be consulted for a full example. -Below are some cURL command skeletons. Replace all <>-Placeholders with appropriate values. Host name depends on the instance you want to address. +Below is a cURL command skeleton. All <>-Placeholders should be replaced with appropriate values. Host name depends on the instance that should be addressed. -##### Linux: +#### Linux: ```shell curl https://<instance-host-name>/fhir/Task \ --cacert <path/to/ca-certificate-file.pem> \ @@ -26,18 +25,12 @@ curl https://<instance-host-name>/fhir/Task \ -H "Accept: application/fhir+xml" \ -d @<path/to/example-task.xml> ``` -##### Windows CMD: -```shell -curl https://<instance-host-name>/fhir/Task ^ ---cacert <path/to/ca-certificate-file.pem> ^ ---cert <path/to/client-certificate-file.pem>:password ^ ---key <path/to/client-private-key-file.pem> ^ --H "Content-Type: application/fhir+xml" ^ --H "Accept: application/fhir+xml" ^ --d @<path/to/example-task.xml> -``` -*This may throw an error depending on which version of cURL Windows is using. If this is the case for you after making sure you entered everything correctly, you can try using Git's version of cURL instead by adding it to the very top of your system's PATH environment variable. Git's cURL is usually situated in C:\Program Files\Git\mingw64\bin.* -#### Using the DSF FHIR Server's Web Interface +### Using the DSF FHIR Server's Web Interface + +When accessing the web interface of a DSF FHIR server instance (e.g. https://instance-name/fhir), the DSF FHIR server can be queried using the [FHIR RESTful API](https://www.hl7.org/fhir/R4/http.html) to return a list of all [Draft Task Resources](../dsf/draft-task-resources.md). These [Task](../fhir/task.md) resources serve as templates for instantiating [Task](../fhir/task.md) resources that initiate BPMN processes. Instead of performing the query manually, a predefined bookmark can be used to navigate to the query URL. A list of bookmarks is available in the top right corner of the web interface. Selecting the bookmark referencing `?_sort=_profile,identifier&status=draft` under the `Task` section will display the list of all [Draft Task Resources](../dsf/draft-task-resources.md). From this list, the desired resource to start the BPMN process can be selected. A detailed view of the resource will be shown, allowing the specification of any necessary [Task Input Parameters](../fhir/task.md#task-input-parameters). If all required information is provided correctly, the process can be initiated by clicking `Start Process`. + +For [Draft Task Resources](../dsf/draft-task-resources.md) to be available, they must be included in the mapping for the BPMN process ID in `ProcessPluginDefinition#getFhirResourcesByProcessId`. Additional information can be found in [the Process Plugin Definition](../dsf/process-plugin-definition.md). -When visiting the web interface of a DSF FHIR server instance (e.g. https://instance-name/fhir), you can query the DSF FHIR server using the [FHIR RESTful API](https://www.hl7.org/fhir/R4/http.html) to return a list of all [Draft Task Resources](../dsf/draft-task-resources.md). These [Task](../fhir/task.md) resources act like a template you can use to instantiate [Task](../fhir/task.md) resources which start BPMN processes. Instead of querying the DSF FHIR server manually, you can use a predefined bookmark to navigate to the query URL. You can find a list of Bookmarks in the top right corner of the web interface. Simply select the bookmark referencing `?_sort=_profile,identifier&status=draft` under the `Task` section, and you will be taken to the list of all [Draft Task Resources](../dsf/draft-task-resources.md). Once there, you can select the one which starts your BPMN process. It will take you to a detailed view of the resource where you will also have the chance to fill any [Task Input Parameters](../fhir/task.md#task-input-parameters) you might need to specify. If everything is filled out correctly, you may start your process by clicking `Start Process`. Keep in mind that, for [Draft Task Resources](../dsf/draft-task-resources.md) to be available, you need to include them in your mapping for your BPMN process ID in `ProcessPluginDefinition#getFhirResourcesByProcessId`. Take a look at [the Process Plugin Definition](../dsf/process-plugin-definition.md) if you need a reminder. \ No newline at end of file +## Related Topics +[Task](../fhir/task.md) diff --git a/docs/src/process-development/api-v1/guides/user-tasks-in-the-dsf.md b/docs/src/process-development/api-v1/guides/user-tasks-in-the-dsf.md index 3c987de8a..78eee6bfe 100644 --- a/docs/src/process-development/api-v1/guides/user-tasks-in-the-dsf.md +++ b/docs/src/process-development/api-v1/guides/user-tasks-in-the-dsf.md @@ -5,11 +5,17 @@ icon: creative ### User Tasks in the DSF -Creating a [User Task](../bpmn/user-tasks.md) in a BPMN model, causes the DSF to automatically generate a [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html) resource according to a [Questionnaire](https://www.hl7.org/fhir/R4/questionnaire.html) you provided in the [User Task's](../bpmn/user-tasks.md) `Forms` field when the process execution reaches the [User Task](../bpmn/user-tasks.md). The `Forms` field needs to have a type of `Embedded or External Task Forms` with the `Form key` being the url of your [Questionnaire](https://www.hl7.org/fhir/R4/questionnaire.html) resource. The [Questionnaire](https://www.hl7.org/fhir/R4/questionnaire.html) resource needs to be put in the `src/main/resources/fhir/Questionnaire` directory. The generated [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html) can now be answered by locating the [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html) in the DSF FHIR server UI through `https://your.dsf.fhir.server/fhir/QuestionnaireResponse?_sort=-_lastUpdated&status=in-progress`. After filling out the [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html) and submitting it, the process execution will continue with the next BPMN element after the [User Task](../bpmn/user-tasks.md) and the updated [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html) will be available through the [Process Plugin Api's](../dsf/process-plugin-api.md) `Variables` instance by calling `getLatestReceivedQuestionnaireResponse()`. +Creating a [User Task](../bpmn/user-tasks.md) in a BPMN model causes the DSF to automatically generate a [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html) resource based on the [Questionnaire](https://www.hl7.org/fhir/R4/questionnaire.html) specified in the [User Task's](../bpmn/user-tasks.md) `Forms` field when process execution reaches the [User Task](../bpmn/user-tasks.md). The `Forms` field must have the type `Embedded or External Task Forms`, with the `Form key` set to the URL of the [Questionnaire](https://www.hl7.org/fhir/R4/questionnaire.html) resource. The [Questionnaire](https://www.hl7.org/fhir/R4/questionnaire.html) resource must be placed in the `src/main/resources/fhir/Questionnaire` directory. -You also have the option to register a [Task Listener](https://docs.camunda.org/manual/7.21/user-guide/process-engine/delegation-code/#task-listener) on the [User Task](../bpmn/user-tasks.md). This allows you to manipulate the [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html) before it is posted to the DSF FHIR server. You do this by extending the `DefaultUserTaskListener` class which provides overrides to interact with the [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html). Notice that dynamically changing the `item.text` value of an item in a [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html) (that is **NOT** of type `display`) is not allowed. For that, you would have to change the `item.text` value of the corresponding [Questionnaire](https://www.hl7.org/fhir/R4/questionnaire.html) resource as well. Instead, you should have an item of type `display` above the item whose text should change dynamically, like in the template, and change its `item.text` value. In this case, you may also leave out `item.text` element of the item below the display item. +The generated [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html) can be accessed and answered by navigating to `https://your.dsf.fhir.server/fhir/QuestionnaireResponse?_sort=-_lastUpdated&status=in-progress` in the DSF FHIR server UI. After completing and submitting the [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html), the process execution will proceed to the next BPMN element following the [User Task](../bpmn/user-tasks.md). The updated [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html) will then be accessible via the [Process Plugin Api's](../dsf/process-api.md) `Variables` instance by calling `getLatestReceivedQuestionnaireResponse()`. + +It is also possible to register a [Task Listener](https://docs.camunda.org/manual/7.21/user-guide/process-engine/delegation-code/#task-listener) on the [User Task](../bpmn/user-tasks.md). This enables manipulation of the [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html) before it is posted to the DSF FHIR server. This can be achieved by extending the `DefaultUserTaskListener` class, which provides overrides for interacting with the [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html). + +Dynamically changing the `item.text` value of an item in a [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html) (if the item is **not** of type `display`) is not permitted. To change text dynamically, the `item.text` value of the corresponding [Questionnaire](https://www.hl7.org/fhir/R4/questionnaire.html) resource must also be updated. As an alternative, an item of type `display` can be placed above the item requiring dynamic text, and its `item.text` value can be modified instead, as shown in the template. In this case, the `item.text` element of the item below the display item may be omitted. + + +Below is a template for a [Questionnaire](https://www.hl7.org/fhir/R4/questionnaire.html) resource. The placeholder `questionnaire-name` should be replaced with the actual name of the [Questionnaire](https://www.hl7.org/fhir/R4/questionnaire.html), and the file should be named accordingly. The items `business-key` and `user-task-id` are required by the DSF and must always be included. Additional items can be added to the [Questionnaire](https://www.hl7.org/fhir/R4/questionnaire.html) as needed. -Below you can find a template for a [Questionnaire](https://www.hl7.org/fhir/R4/questionnaire.html) resource. Replace `questionnaire-name` with the name of your [Questionnaire](https://www.hl7.org/fhir/R4/questionnaire.html) and have the file be named the same. The items `business-key` and `user-task-id` are required by the DSF and are always included. You can then add any amount of items of your choosing to the [Questionnaire](https://www.hl7.org/fhir/R4/questionnaire.html). ### Questionnaire Template ```xml @@ -54,4 +60,7 @@ Below you can find a template for a [Questionnaire](https://www.hl7.org/fhir/R4/ <required value="true"/> </item> </Questionnaire> -``` \ No newline at end of file +``` + +## Related Topics +[Questionnaire and QuestionnaireResponse](../fhir/questionnaire-and-questionnaireresponse.md) \ No newline at end of file diff --git a/docs/src/process-development/api-v2/dsf/bpmn-process-execution.md b/docs/src/process-development/api-v2/dsf/bpmn-process-execution.md index a7fe83109..d6c0277c5 100644 --- a/docs/src/process-development/api-v2/dsf/bpmn-process-execution.md +++ b/docs/src/process-development/api-v2/dsf/bpmn-process-execution.md @@ -5,4 +5,4 @@ icon: creative ## BPMN Process Execution -The BPMN process execution is the in-memory representation of a running BPMN process. BPMN processes have their executions structured as a tree hierarchy. Each BPMN process starts with the [process instance](https://docs.camunda.org/manual/7.21/user-guide/process-engine/process-engine-concepts/#process-instances) as its root level execution. If, for example, this root execution reaches a parallel gateway with two paths, it would spawn two child executions under itself for them to process all tasks along their paths on their own. Executions can access all the BPMN elements from the BPMN model as well as the [BPMN process variables](bpmn-process-variables.md). Access to this representation in your Java code is provided through the `variables` parameter when overriding certain methods in [Service](service-delegates.md) / [Message](message-delegates.md) Delegates like `execute` or `getAdditionalInputParameters`. +The BPMN process execution is the in-memory representation of a running BPMN process. BPMN processes have their executions structured as a tree hierarchy. Each BPMN process starts with the [process instance](https://docs.camunda.org/manual/7.21/user-guide/process-engine/process-engine-concepts/#process-instances) as its root level execution. If, for example, this root execution reaches a parallel gateway with two paths, it would spawn two child executions under itself for them to process all tasks along their paths on their own. Executions can access all the BPMN elements from the BPMN model as well as the [BPMN process variables](bpmn-process-variables.md). Limited access to this representation in the Java code is provided through the `variables` parameter when overriding certain methods in [Service](service-delegates.md) / [Message](message-delegates.md) Delegates like `execute` or `getAdditionalInputParameters`. \ No newline at end of file diff --git a/docs/src/process-development/api-v2/dsf/environment-variables.md b/docs/src/process-development/api-v2/dsf/environment-variables.md index 17612fa8a..4f0b5bd7e 100644 --- a/docs/src/process-development/api-v2/dsf/environment-variables.md +++ b/docs/src/process-development/api-v2/dsf/environment-variables.md @@ -7,4 +7,4 @@ icon: creative Environment variables offer a way to make configuration data available at the start of a [BPMN process execution](bpmn-process-execution.md). They are the same for all running process instances. They can be defined by adding a member variable with the [Spring-Framework @Value](https://docs.spring.io/spring-framework/docs/current/reference/html/core.html#beans-value-annotations) annotation to any Spring managed bean. For the DSF, the most prominent are classes annotated with [`@Configuration`](https://docs.spring.io/spring-framework/reference/core/beans/java/configuration-annotation.html). The value of the annotation uses the `${..}` notation and follows the form `${some.property:defaultValue}`, where each dot in the property name corresponds to an underscore in the equivalent environment variable. Environment variables are always written upper-case. The property `some.property` therefore corresponds to the environment variable `SOME_PROPERTY`. -The DSF provides a feature to automatically generate documentation of environment variables during the Maven build process. Use the `@ProcessDocumentation` annotation to automatically generate Markdown documentation for all fields with this annotation. Simply add [dsf-tools-documentation-generator](https://mvnrepository.com/artifact/dev.dsf/dsf-tools-documentation-generator) as a maven plugin. There is an example `pom.xml` for the `tutorial-process` submodule located on [GitHub](https://github.com/datasharingframework/dsf-process-tutorial/blob/main/tutorial-process/pom.xml) which uses the maven plugin. The `<workingPackage>` field has to point to the package where documentation is desired. +The DSF provides a feature to automatically generate documentation of environment variables during the Maven build process. The `@ProcessDocumentation` annotation can be used to automatically generate Markdown documentation for all fields with this annotation. This requires adding [dsf-tools-documentation-generator](https://mvnrepository.com/artifact/dev.dsf/dsf-tools-documentation-generator) as a maven plugin. There is an example `pom.xml` for the `tutorial-process` submodule located on [GitHub](https://github.com/datasharingframework/dsf-process-tutorial/blob/main/tutorial-process/pom.xml) which uses the maven plugin. The `<workingPackage>` field has to point to the package where documentation is desired. diff --git a/docs/src/process-development/api-v2/dsf/message-delegates.md b/docs/src/process-development/api-v2/dsf/message-delegates.md index f73513ab7..f5021e4d9 100644 --- a/docs/src/process-development/api-v2/dsf/message-delegates.md +++ b/docs/src/process-development/api-v2/dsf/message-delegates.md @@ -12,7 +12,8 @@ org.package.MyClass Message Delegates are only needed for [Message Send Events](../bpmn/messaging.md). Incoming messages will be resolved to the correct [BPMN process execution](bpmn-process-execution.md) automatically using [Message Correlation](message-correlation.md) and the message inputs will be added to that execution's [process variables](bpmn-process-variables.md). -To make a Message Delegate for [Message Send Events](../../concepts/bpmn/messaging.md), the Java class needs to implement the interface `MessageSendTask`. Most of the time, there will not be any processing logic inside Message Delegates, therefore the `execute` method will not be overridden like with [Service Delegates](../../concepts/dsf/service-delegates.md). Although there might be cases where this is necessary. Instead, Message Delegates should be used to aggregate previously computed data and attach it to the message. This is done by overriding the `getAdditionalInputParamters` method. The DSF translates BPMN messages into FHIR [Task](../../concepts/fhir/task.md) resources to execute the communication modeled in BPMN diagrams. The information being sent to another BPMN process is specified in the Task.input elements a.k.a. [Input Parameters](../../concepts/fhir/task.md#task-input-parameters), hence the name of the method. +To make a Message Delegate for [Message Send Events](../bpmn/messaging.md), the Java class needs to implement the interface `MessageSendTask`. Most of the time, there will not be any processing logic inside Message Delegates, therefore the `execute` method will not be overridden like with [Service Delegates](../dsf/service-delegates.md). Although there might be cases where this is necessary. Instead, Message Delegates should be used to aggregate previously computed data and attach it to the message. This is done by overriding the `getAdditionalInputParamters` method. The DSF translates BPMN messages into FHIR [Task](../fhir/task.md) resources to execute the communication modeled in BPMN diagrams. The information being sent to another BPMN process is specified in the Task.input elements a.k.a. [Input Parameters](../fhir/task.md#task-input-parameters), hence the name of the method. + ## Related Topics -[Messaging](../bpmn/messaging.md), [Input Parameters](../../concepts/fhir/task.md#task-input-parameters), [Adding Input Parameter to Task Profiles](../guides/adding-task-input-parameters-to-task-profiles.md) +[Messaging](../bpmn/messaging.md), [Input Parameters](../fhir/task.md#task-input-parameters), [Adding Input Parameter to Task Profiles](../guides/adding-task-input-parameters-to-task-profiles.md) \ No newline at end of file diff --git a/docs/src/process-development/api-v2/dsf/organization-identifiers.md b/docs/src/process-development/api-v2/dsf/organization-identifiers.md index d450b8b0c..dfb78a204 100644 --- a/docs/src/process-development/api-v2/dsf/organization-identifiers.md +++ b/docs/src/process-development/api-v2/dsf/organization-identifiers.md @@ -7,7 +7,7 @@ icon: creative DSF FHIR server instances can configure an `organization identifier`. It uniquely identifies the organization the DSF FHIR server instance belongs to for its [Allow-List mechanism](https://dsf.dev/intro/info/allowList.html). It is set as an [environment variable](https://dsf.dev/stable/maintain/fhir/configuration.html#dev-dsf-fhir-server-organization-identifier-value). A GET request to `https://domain/fhir/Organization` will return a list of all organizations for the DSF FHIR server instance running under `domain`. The results will also include the `organization identifier` of each organization. ### Organization Identifiers in Task Resources -[Task](../fhir/task.md) resources require a reference to an organization via its identifier as the `Task.requester` and `Task.restriction.recipient` elements. The exact values for these elements depend on the [ActivityDefinition](../fhir/activitydefinition.md) the [Task](../fhir/task.md) resource should conform to. As a general rule, the identifier of your own organization should be used as the `Task.requester` and `Task.restriction.recipient` elements for [Task](../fhir/task.md) resources which initially start processes. All other cases depend on the context of the message being sent during process execution. +[Task](../fhir/task.md) resources require a reference to an organization via its identifier as the `Task.requester` and `Task.restriction.recipient` elements. The exact values for these elements depend on the [ActivityDefinition](../fhir/activitydefinition.md) the [Task](../fhir/task.md) resource should conform to. As a general rule, the identifier of your own organization should be used as the `Task.requester` and `Task.restriction.recipient` elements for [Task](../fhir/task.md) resources which initially start processes. All other cases depend on the context of the message being sent during process execution. An easy way to generalize this in [Draft Task Resources](draft-task-resources.md) is to use the `#{organization}` [placeholder](versions-placeholders-urls.md#placeholders). ## Related Topics -[Allow-List](https://dsf.dev/intro/info/allowList.html), [ActivityDefinition](../fhir/activitydefinition.md), [Environment Variables](environment-variables.md), [Requester and Recipient](requester-and-recipient.md), [Task](../fhir/task.md) +[Allow-List](https://dsf.dev/intro/info/allowList.html), [ActivityDefinition](../fhir/activitydefinition.md), [Environment Variables](environment-variables.md), [Requester and Recipient](requester-and-recipient.md), [Task](../fhir/task.md) \ No newline at end of file diff --git a/docs/src/process-development/api-v2/dsf/process-plugin-api.md b/docs/src/process-development/api-v2/dsf/process-plugin-api.md index 42a66f9c2..60f968aaf 100644 --- a/docs/src/process-development/api-v2/dsf/process-plugin-api.md +++ b/docs/src/process-development/api-v2/dsf/process-plugin-api.md @@ -21,7 +21,7 @@ Maven Dependency: ``` ### Process Plugin Api -[Service Delegates](service-delegates.md) or [Message Delegates](message-delegates.md) expose a `ProcessPluginApi` instance when overriding their `execute` and `getAdditionalInputParameters` methods. This API instance the following utility classes: +[Service Delegates](service-delegates.md) or [Message Delegates](message-delegates.md) expose a `ProcessPluginApi` instance when overriding their `execute` and `getAdditionalInputParameters` methods. This API instance provides the following utility classes: - `FhirClientProvider`**:** Provides access to a generic, configurable FHIR web client. Used for connections to FHIR servers that are not the DSF FHIR server. - `DsfClientProvider`**:** Provides access to preconfigured FHIR web client to access DSF FHIR server including utility methods. - `TaskHelper`**:** Provides utility methods to interact with Task resource. Namely, Input and Output Parameters. diff --git a/docs/src/process-development/api-v2/dsf/spring-framework-integration.md b/docs/src/process-development/api-v2/dsf/spring-framework-integration.md index 49a2eb158..f4abaea72 100644 --- a/docs/src/process-development/api-v2/dsf/spring-framework-integration.md +++ b/docs/src/process-development/api-v2/dsf/spring-framework-integration.md @@ -16,9 +16,61 @@ The DSF uses some of the [Spring Framework's](https://spring.io/projects/spring- - `ServiceTask` - `UserTaskListener` -Examples can be found in the guide on [registering prototype Beans](../../guides/registering-prototype-beans.md). - A [Spring-Framework configuration class](https://docs.spring.io/spring-framework/docs/current/reference/html/core.html#beans-java-basic-concepts) located in the `spring/config` directory is expected to provide the Spring Beans. If you are unfamiliar with the Spring Framework, you can find more information in [Java-based Container Configuration](https://docs.spring.io/spring-framework/reference/core/beans/java.html) of the Spring Framework documentation, specifically the topics [Using the @Bean Annotation](https://docs.spring.io/spring-framework/reference/core/beans/java/bean-annotation.html) and [Using the @Configuration Annotation](https://docs.spring.io/spring-framework/reference/core/beans/java/configuration-annotation.html). +Below is an example of a Spring configuration class: +```java +@Configuration +public class TutorialConfig +{ + @Value("${dev.dsf.process.tutorial.loggingEnabled:false}") + @ProcessDocumentation(description = "Set to true to enable logging", required = false, processNames = PROCESS_NAME_FULL_DIC) + private boolean loggingEnabled; //environment variable + + @Value("${dev.dsf.process.tutorial.userVote:false}") + @ProcessDocumentation(description = "Set to true to enable users to vote", required = false, processNames = PROCESS_NAME_FULL_VOTING_PROCESS) + private boolean userVote; //environment variable + + //register classes with default constructor as prototype beans + @Bean + public static ActivityPrototypeBeanCreator activityPrototypeBeanCreator() + { + return new ActivityPrototypeBeanCreator(HelloCosMessage.class, CosTask.class, HelloHrpMessage.class, + HrpTask.class, GoodbyeDicMessage.class, StartVotingProcess.class, SelectTargets.class, StartVote.class, + SaveUserVote.class, AutomatedVote.class, PrepareReturnVote.class, ReturnVote.class, + SaveVotingResult.class, SaveTimeoutResult.class, AggregateResults.class); + } + + //register classes with custom constructor as prototype beans + @Bean + @Scope(ConfigurableBeanFactory.SCOPE_PROTOTYPE) + public DicTask dicTask() + { + return new DicTask(loggingEnabled); + } + + @Bean + @Scope(ConfigurableBeanFactory.SCOPE_PROTOTYPE) + public DecideWhetherUserVote decideWhetherUserVote() + { + return new DecideWhetherUserVote(userVote); + } + + @Bean + @Scope(ConfigurableBeanFactory.SCOPE_PROTOTYPE) + public UserVoteListener userVoteListener() + { + return new UserVoteListener(); + } + + @Bean + @Scope(ConfigurableBeanFactory.SCOPE_PROTOTYPE) + public SetCorrelationKeyListener setCorrelationKeyListener() + { + return new SetCorrelationKeyListener(); + } +} +``` + ## Related Topics [Environment Variables](environment-variables.md), [Message Delegates](message-delegates.md), [Service Delegates](service-delegates.md) diff --git a/docs/src/process-development/api-v2/fhir/activitydefinition.md b/docs/src/process-development/api-v2/fhir/activitydefinition.md index b5fbb1b31..ae4e64c9a 100644 --- a/docs/src/process-development/api-v2/fhir/activitydefinition.md +++ b/docs/src/process-development/api-v2/fhir/activitydefinition.md @@ -16,11 +16,9 @@ The most important elements in ActivityDefinitions are: The `message-name` element contains the name of the [BPMN message start event](../bpmn/messaging.md#message-start-event) or [BPMN message intermediate catching event](../bpmn/messaging.md#message-intermediate-catching-event) which expects a [Task](task.md) resource complying to the profile defined by `task-profile`. -The `requester` and `recipient` elements define the organisation(s) or person(s) who are allowed to request or receive the message specified by `message-name`. The receiving DSF instance is the one who will execute the process connected to the message. +The `requester` and `recipient` elements define the organisation(s) or person(s) who are allowed to request or receive the message specified by `message-name`. The receiving DSF instance is the one who will execute the process connected to the message. A list of examples for all possible `requester` and `recipient` elements is located [here](../dsf/requester-and-recipient.md). -Creating [ActivityDefinitions](activitydefinition.md) is part of developing a process plugin. Readers fluent in understanding XML FHIR definitions and translating them into resources may take a look at the DSF's profile for ActivityDefinitions [here](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-activity-definition-1.0.0.xml). ActivityDefinitions also reference other resource definitions. Depending on the resource they are located in one of [these folders](https://github.com/datasharingframework/dsf/tree/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir). FHIR beginners can read the guide on [creating ActivityDefinitions](../guides/creating-activity-definitions.md). - -There is also a list of examples for all possible `requester` and `recipient` elements located [here](../dsf/requester-and-recipient.md). +Creating [ActivityDefinitions](activitydefinition.md) is part of developing a process plugin. Readers fluent in understanding XML FHIR definitions and translating them into resources may take a look at the DSF's profile for ActivityDefinitions [here](https://github.com/datasharingframework/dsf/blob/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-activity-definition-1.0.0.xml). ActivityDefinitions also reference other resource definitions. Depending on the resource they are located in one of [these folders](https://github.com/datasharingframework/dsf/tree/main/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir). There is also the guide on [creating ActivityDefinitions](../guides/creating-activity-definitions.md) for more in-depth information. ## Related Topics [Requester and Recipient](../dsf/requester-and-recipient.md), [Read Access Tag](../dsf/read-access-tag.md), [Task](task.md) diff --git a/docs/src/process-development/api-v2/guides/accessing-bpmn-process-variables.md b/docs/src/process-development/api-v2/guides/accessing-bpmn-process-variables.md index 420700c86..2c809593c 100644 --- a/docs/src/process-development/api-v2/guides/accessing-bpmn-process-variables.md +++ b/docs/src/process-development/api-v2/guides/accessing-bpmn-process-variables.md @@ -8,5 +8,7 @@ icon: creative Access to retrieve data from or store data in the [BPMN process variables](../dsf/bpmn-process-variables.md) can be acquired via the `Variables` class. An instance is usually available when overriding methods in [Service Delegates](../dsf/service-delegates.md) and [Message Delegates](../dsf/message-delegates.md). If an instance is missing in a place where it should be accessible, please [let us know](https://dsf.dev/community/contribute/). The `Variables` class provides lots of utility methods to read or write certain types -of [BPMN process variables](../concepts/dsf/bpmn-process-variables.md). If for some reason you find the methods provided by the `Variables` class insufficient to solve your problem, we would like to learn how the current API of the `Variables` class is limiting you. Again, please [let us know](https://dsf.dev/community/contribute/). +of [BPMN process variables](../dsf/bpmn-process-variables.md). If the methods provided by the `Variables` class are insufficient to solve a problem, we would like to learn in what way the current API of the `Variables` class is limiting. Again, please [let us know](https://dsf.dev/community/contribute/). +## Related Topics +[BPMN Process Variables](../dsf/bpmn-process-variables.md), [Message Delegates](../dsf/message-delegates.md), [Service Delegates](../dsf/service-delegates.md) \ No newline at end of file diff --git a/docs/src/process-development/api-v2/guides/accessing-task-resources-during-execution.md b/docs/src/process-development/api-v2/guides/accessing-task-resources-during-execution.md index 89a36f5a3..f5cbf1e50 100644 --- a/docs/src/process-development/api-v2/guides/accessing-task-resources-during-execution.md +++ b/docs/src/process-development/api-v2/guides/accessing-task-resources-during-execution.md @@ -10,3 +10,7 @@ In principle, this is sufficient to access all information in a [Task](../fhir/t Instead of navigating the [Task](../fhir/task.md) resource's element tree, it is recommended to use the [ProcessPluginApi's](../dsf/process-plugin-api.md) `TaskHelper` in conjunction with the method above. The `TaskHelper` class offers specific methods related to [Task](../fhir/task.md) resources. The most common use case for this is retrieving data from a [Task's](../fhir/task.md) [Input Parameter](../fhir/task.md#task-input-parameters) or creating a new [Input Parameter](../fhir/task.md#task-input-parameters) for a [Message Delegate's](../dsf/message-delegates.md) `getAdditionalInputParameters` method. When retrieving data from a [Task's](../fhir/task.md) Input Parameter one first has to get to the [Input Parameter](../fhir/task.md#task-input-parameters) one is looking to extract data from. The `TaskHelper's` getters for [Input Parameters](../fhir/task.md#task-input-parameters) are useful to find the right one. The methods will try to match the provided [CodeSystem](../fhir/codesystem.md) and Code to any [Input Parameter](../fhir/task.md#task-input-parameters) of the provided [Task](../fhir/task.md) resource. Depending on the method it is possible to receive all matches or just the first one. To create new [Input Parameters](../fhir/task.md#task-input-parameters) to attach to a [Task](../fhir/task.md) resource, one may invoke the `TaskHelper#createInput` method. This is most often used when overriding the `getAdditionalInputParameters` method of a [Message Delegate](../dsf/message-delegates.md). + + +## Related Topics +[Accessing BPMN Process Variables](accessing-bpmn-process-variables.md), [Message Delegates](../dsf/message-delegates.md), [Service Delegates](../dsf/service-delegates.md), [Task](../fhir/task.md) \ No newline at end of file diff --git a/docs/src/process-development/api-v2/guides/creating-codesystems-for-dsf-processes.md b/docs/src/process-development/api-v2/guides/creating-codesystems-for-dsf-processes.md index 8bf34ac10..c6e45e0d0 100644 --- a/docs/src/process-development/api-v2/guides/creating-codesystems-for-dsf-processes.md +++ b/docs/src/process-development/api-v2/guides/creating-codesystems-for-dsf-processes.md @@ -39,7 +39,7 @@ Sometimes it is necessary to create custom [CodeSystem](../fhir/codesystem.md) r ``` Dummy values should be replaced with appropriate values. Elements managed by the DSF BPE server should not be changed. More codes can be added by defining more `concept` elements. -The DSF BPE server will read the [CodeSystem](../fhir/codesystem.md) from `tutorial-process/src/main/resources/fhir/CodeSystem`. +When building a plugin, the [CodeSystem](../fhir/codesystem.md) is expected to be in `src/main/resources/fhir/CodeSystem` of the Java project. ## Related Topics [Adding Task Input Parameters to Task Profiles](adding-task-input-parameters-to-task-profiles.md), [CodeSystem](../fhir/codesystem.md), [Creating ValueSets for DSF processes](creating-valuesets-for-dsf-processes.md), [ValueSet](../fhir/valueset.md) diff --git a/docs/src/process-development/api-v2/guides/creating-valuesets-for-dsf-processes.md b/docs/src/process-development/api-v2/guides/creating-valuesets-for-dsf-processes.md index ef94cf488..69f7744db 100644 --- a/docs/src/process-development/api-v2/guides/creating-valuesets-for-dsf-processes.md +++ b/docs/src/process-development/api-v2/guides/creating-valuesets-for-dsf-processes.md @@ -58,7 +58,7 @@ Dummy values should be replaced with appropriate, context-specific values. Eleme </compose> </ValueSet> ``` -The DSF BPE server will read the [ValueSet](../fhir/valueset.md) from `tutorial-process/src/main/resources/fhir/ValueSet` inside the process plugin. +When building a plugin, the [ValueSet](../fhir/valueset.md) is expected to be in `src/main/resources/fhir/CodeSystem` of the Java project. ## Related Topics [CodeSystem](../fhir/codesystem.md), [Creating CodeSystems for DSF processes](creating-codesystems-for-dsf-processes.md), [ValueSet](../fhir/valueset.md) diff --git a/docs/src/process-development/api-v2/guides/managing-mutiple-incoming-messages-and-missing-messages.md b/docs/src/process-development/api-v2/guides/managing-mutiple-incoming-messages-and-missing-messages.md index b93703762..a0cf72993 100644 --- a/docs/src/process-development/api-v2/guides/managing-mutiple-incoming-messages-and-missing-messages.md +++ b/docs/src/process-development/api-v2/guides/managing-mutiple-incoming-messages-and-missing-messages.md @@ -16,3 +16,7 @@ An [Event Based Gateway](../bpmn/gateways.md#event-based-gateway) can be used to <source media="(prefers-color-scheme: light)" srcset="/photos/developer-documentation/event_based_gateway.svg"> <img alt="BPMN collaboration diagram with an Event Based Gateway" src="/photos/developer-documentation/event_based_gateway.svg"> </picture> + + +## Related Topics +[Gateways](../bpmn/gateways.md), [Message Correlation](../dsf/message-correlation.md), [Message Delegates](../dsf/message-delegates.md) \ No newline at end of file diff --git a/docs/src/process-development/api-v2/guides/user-tasks-in-the-dsf.md b/docs/src/process-development/api-v2/guides/user-tasks-in-the-dsf.md index e5e9908c2..78eee6bfe 100644 --- a/docs/src/process-development/api-v2/guides/user-tasks-in-the-dsf.md +++ b/docs/src/process-development/api-v2/guides/user-tasks-in-the-dsf.md @@ -1,10 +1,15 @@ +--- +title: User Tasks in the DSF +icon: creative +--- + ### User Tasks in the DSF -Creating a [User Task](../concepts/bpmn/user-tasks.md) in a BPMN model causes the DSF to automatically generate a [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html) resource based on the [Questionnaire](https://www.hl7.org/fhir/R4/questionnaire.html) specified in the [User Task's](../concepts/bpmn/user-tasks.md) `Forms` field when process execution reaches the [User Task](../concepts/bpmn/user-tasks.md). The `Forms` field must have the type `Embedded or External Task Forms`, with the `Form key` set to the URL of the [Questionnaire](https://www.hl7.org/fhir/R4/questionnaire.html) resource. The [Questionnaire](https://www.hl7.org/fhir/R4/questionnaire.html) resource must be placed in the `src/main/resources/fhir/Questionnaire` directory. +Creating a [User Task](../bpmn/user-tasks.md) in a BPMN model causes the DSF to automatically generate a [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html) resource based on the [Questionnaire](https://www.hl7.org/fhir/R4/questionnaire.html) specified in the [User Task's](../bpmn/user-tasks.md) `Forms` field when process execution reaches the [User Task](../bpmn/user-tasks.md). The `Forms` field must have the type `Embedded or External Task Forms`, with the `Form key` set to the URL of the [Questionnaire](https://www.hl7.org/fhir/R4/questionnaire.html) resource. The [Questionnaire](https://www.hl7.org/fhir/R4/questionnaire.html) resource must be placed in the `src/main/resources/fhir/Questionnaire` directory. -The generated [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html) can be accessed and answered by navigating to `https://your.dsf.fhir.server/fhir/QuestionnaireResponse?_sort=-_lastUpdated&status=in-progress` in the DSF FHIR server UI. After completing and submitting the [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html), the process execution will proceed to the next BPMN element following the [User Task](../concepts/bpmn/user-tasks.md). The updated [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html) will then be accessible via the [Process Plugin Api's](../concepts/dsf/process-api.md) `Variables` instance by calling `getLatestReceivedQuestionnaireResponse()`. +The generated [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html) can be accessed and answered by navigating to `https://your.dsf.fhir.server/fhir/QuestionnaireResponse?_sort=-_lastUpdated&status=in-progress` in the DSF FHIR server UI. After completing and submitting the [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html), the process execution will proceed to the next BPMN element following the [User Task](../bpmn/user-tasks.md). The updated [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html) will then be accessible via the [Process Plugin Api's](../dsf/process-api.md) `Variables` instance by calling `getLatestReceivedQuestionnaireResponse()`. -It is also possible to register a [Task Listener](https://docs.camunda.org/manual/7.21/user-guide/process-engine/delegation-code/#task-listener) on the [User Task](../concepts/bpmn/user-tasks.md). This enables manipulation of the [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html) before it is posted to the DSF FHIR server. This can be achieved by extending the `DefaultUserTaskListener` class, which provides overrides for interacting with the [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html). +It is also possible to register a [Task Listener](https://docs.camunda.org/manual/7.21/user-guide/process-engine/delegation-code/#task-listener) on the [User Task](../bpmn/user-tasks.md). This enables manipulation of the [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html) before it is posted to the DSF FHIR server. This can be achieved by extending the `DefaultUserTaskListener` class, which provides overrides for interacting with the [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html). Dynamically changing the `item.text` value of an item in a [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html) (if the item is **not** of type `display`) is not permitted. To change text dynamically, the `item.text` value of the corresponding [Questionnaire](https://www.hl7.org/fhir/R4/questionnaire.html) resource must also be updated. As an alternative, an item of type `display` can be placed above the item requiring dynamic text, and its `item.text` value can be modified instead, as shown in the template. In this case, the `item.text` element of the item below the display item may be omitted. @@ -55,4 +60,7 @@ Below is a template for a [Questionnaire](https://www.hl7.org/fhir/R4/questionna <required value="true"/> </item> </Questionnaire> -``` \ No newline at end of file +``` + +## Related Topics +[Questionnaire and QuestionnaireResponse](../fhir/questionnaire-and-questionnaireresponse.md) \ No newline at end of file From 3945c50faae2f282e3e4861178bd6c267e98dfe8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20B=C3=B6hringer?= <jan.boehringer@hs-heilbronn.de> Date: Mon, 23 Jun 2025 16:42:12 +0200 Subject: [PATCH 09/12] Fixed index and readme being in same directory --- docs/src/process-development/api-v1/index.md | 4 ++++ docs/src/process-development/api-v2/README.md | 8 -------- docs/src/process-development/api-v2/index.md | 5 +++++ 3 files changed, 9 insertions(+), 8 deletions(-) delete mode 100644 docs/src/process-development/api-v2/README.md diff --git a/docs/src/process-development/api-v1/index.md b/docs/src/process-development/api-v1/index.md index 436fda63f..42f7ff6cd 100644 --- a/docs/src/process-development/api-v1/index.md +++ b/docs/src/process-development/api-v1/index.md @@ -3,6 +3,10 @@ title: API v1 icon: code --- +## Overview +- [About API1](description) +- [Implementation Guide](implementation) + ## BPMN - [Conditions](bpmn/conditions.md) - [Gateways](bpmn/gateways.md) diff --git a/docs/src/process-development/api-v2/README.md b/docs/src/process-development/api-v2/README.md deleted file mode 100644 index 24fc603c0..000000000 --- a/docs/src/process-development/api-v2/README.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: API v2 -icon: code ---- -## Overview -- [About API2](description) -- [Implementation Guide](implementation) -- [Migration Guide](migration) \ No newline at end of file diff --git a/docs/src/process-development/api-v2/index.md b/docs/src/process-development/api-v2/index.md index f70012ebd..5895c862e 100644 --- a/docs/src/process-development/api-v2/index.md +++ b/docs/src/process-development/api-v2/index.md @@ -3,6 +3,11 @@ title: API 2 (alpha) Overview icon: code --- +## Overview +- [About API2](description) +- [Implementation Guide](implementation) +- [Migration Guide](migration) + ## BPMN - [Conditions](bpmn/conditions.md) - [Gateways](bpmn/gateways.md) From a216aaf03807a7431312aadbce3783f1e90a6906 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20B=C3=B6hringer?= <jan.boehringer@hs-heilbronn.de> Date: Mon, 23 Jun 2025 16:45:58 +0200 Subject: [PATCH 10/12] Revert "Fixed index and readme being in same directory" This reverts commit 3945c50faae2f282e3e4861178bd6c267e98dfe8. --- docs/src/process-development/api-v1/index.md | 4 ---- docs/src/process-development/api-v2/README.md | 8 ++++++++ docs/src/process-development/api-v2/index.md | 5 ----- 3 files changed, 8 insertions(+), 9 deletions(-) create mode 100644 docs/src/process-development/api-v2/README.md diff --git a/docs/src/process-development/api-v1/index.md b/docs/src/process-development/api-v1/index.md index 42f7ff6cd..436fda63f 100644 --- a/docs/src/process-development/api-v1/index.md +++ b/docs/src/process-development/api-v1/index.md @@ -3,10 +3,6 @@ title: API v1 icon: code --- -## Overview -- [About API1](description) -- [Implementation Guide](implementation) - ## BPMN - [Conditions](bpmn/conditions.md) - [Gateways](bpmn/gateways.md) diff --git a/docs/src/process-development/api-v2/README.md b/docs/src/process-development/api-v2/README.md new file mode 100644 index 000000000..24fc603c0 --- /dev/null +++ b/docs/src/process-development/api-v2/README.md @@ -0,0 +1,8 @@ +--- +title: API v2 +icon: code +--- +## Overview +- [About API2](description) +- [Implementation Guide](implementation) +- [Migration Guide](migration) \ No newline at end of file diff --git a/docs/src/process-development/api-v2/index.md b/docs/src/process-development/api-v2/index.md index 5895c862e..f70012ebd 100644 --- a/docs/src/process-development/api-v2/index.md +++ b/docs/src/process-development/api-v2/index.md @@ -3,11 +3,6 @@ title: API 2 (alpha) Overview icon: code --- -## Overview -- [About API2](description) -- [Implementation Guide](implementation) -- [Migration Guide](migration) - ## BPMN - [Conditions](bpmn/conditions.md) - [Gateways](bpmn/gateways.md) From e0e464b07bf05d38f1d52af927aa89f8dfa3b840 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20B=C3=B6hringer?= <jan.boehringer@hs-heilbronn.de> Date: Mon, 23 Jun 2025 18:01:17 +0200 Subject: [PATCH 11/12] Fixed index and readme being in one directory. This time deleting index, because its contents are already present in "concept.md". Also, some more minor fixes to things like broken links --- docs/src/process-development/api-v1/README.md | 7 +++ .../src/process-development/api-v1/concept.md | 1 + .../api-v1/dsf/service-delegates.md | 2 +- .../api-v1/dsf/target-and-targets.md | 19 ++++++++ .../api-v1/guides/user-tasks-in-the-dsf.md | 2 +- docs/src/process-development/api-v1/index.md | 47 ------------------- .../src/process-development/api-v2/concept.md | 1 + .../api-v2/dsf/service-delegates.md | 2 +- .../api-v2/guides/user-tasks-in-the-dsf.md | 2 +- docs/src/process-development/api-v2/index.md | 47 ------------------- 10 files changed, 32 insertions(+), 98 deletions(-) create mode 100644 docs/src/process-development/api-v1/README.md create mode 100644 docs/src/process-development/api-v1/dsf/target-and-targets.md delete mode 100644 docs/src/process-development/api-v1/index.md delete mode 100644 docs/src/process-development/api-v2/index.md diff --git a/docs/src/process-development/api-v1/README.md b/docs/src/process-development/api-v1/README.md new file mode 100644 index 000000000..66b21f9b4 --- /dev/null +++ b/docs/src/process-development/api-v1/README.md @@ -0,0 +1,7 @@ +--- +title: API v1 +icon: code +--- +## Overview +- [About API1](description) +- [Implementation Guide](implementation) \ No newline at end of file diff --git a/docs/src/process-development/api-v1/concept.md b/docs/src/process-development/api-v1/concept.md index 426420d67..230d86bdc 100644 --- a/docs/src/process-development/api-v1/concept.md +++ b/docs/src/process-development/api-v1/concept.md @@ -36,6 +36,7 @@ This site is work in progress, please come back later. - [Requester and Recipient](dsf/requester-and-recipient.md) - [Service Delegates](dsf/service-delegates.md) - [Spring Framework Integration](dsf/spring-framework-integration.md) +- [Target and Targets](dsf/target-and-targets.md) - [Versions, Placeholders and URLs](dsf/versions-placeholders-urls.md) ## Guides diff --git a/docs/src/process-development/api-v1/dsf/service-delegates.md b/docs/src/process-development/api-v1/dsf/service-delegates.md index 1a9bd18cd..09c86ecdb 100644 --- a/docs/src/process-development/api-v1/dsf/service-delegates.md +++ b/docs/src/process-development/api-v1/dsf/service-delegates.md @@ -7,7 +7,7 @@ icon: creative Service Delegates are the Java representation of the [Service Tasks](../bpmn/service-tasks.md) in a BPMN model. Service Delegates are linked to a certain [Service Task](../bpmn/service-tasks.md) by selecting the [Service Task](../bpmn/service-tasks.md) in the [Camunda Modeler](https://camunda.com/download/modeler/) and adding a Java class to the `Implementation` field. This uses the fully qualified class name: ``` -org.package.myClass +org.package.MyClass ``` Java classes need to extend `AbstractServiceDelegate` and override the `doExecute` method. This method holds the actual business logic. The method will be called when the [BPMN process execution](../dsf/bpmn-process-execution.md) arrives at the [Service Task](../bpmn/service-tasks.md) a Service Delegate is linked to. The constructor of delegate classes also has to forward a `ProcessPluginApi` instance to its superclass constructor. An instance of the API can be [autowired](https://docs.spring.io/spring-framework/reference/core/beans/annotation-config/autowired.html) in the plugin's Spring configuration class when registering the delegate as a [Spring Bean](https://docs.spring.io/spring-framework/reference/core/beans/introduction.html). diff --git a/docs/src/process-development/api-v1/dsf/target-and-targets.md b/docs/src/process-development/api-v1/dsf/target-and-targets.md new file mode 100644 index 000000000..8b8df62db --- /dev/null +++ b/docs/src/process-development/api-v1/dsf/target-and-targets.md @@ -0,0 +1,19 @@ +--- +title: Target and Targets +icon: creative +--- + +## Target + +A target is a container for all information necessary to send messages to other DSF instances. This information includes: +- **Organization Identifier:** Identifier of an [Organization Resource](https://www.hl7.org/fhir/R4/organization.html). Can be acquired through the API's `OrganizationProvider` or by querying a FHIR server (usually the DSF FHIR server) using a `FhirWebserviceClient` provided by the API's `FhirWebserviceProvider`. +- **Endpoint Identifier:** Identifier of an [Endpoint Resource](https://www.hl7.org/fhir/R4/endpoint.html) with the `managingOrganization` being the same organization as the one from the `Organization Identifier` above. Can be acquired through the API's `EndpointProvider` or by querying a FHIR server (usually the DSF FHIR server) using a `FhirWebserviceClient` provided by the API's `FhirWebserviceProvider`. +- **Endpoint URL:** The URL of the endpoint. The [Endpoint Resource](https://www.hl7.org/fhir/R4/endpoint.html) provides this value through its `address` field. +- **Correlation Key:** A value used to correlate messages, that are sent to this target, to their correct process instances. More information on this mechanism can be found in [Message Correlation](message-correlation.md). + +## Targets + +Targets is a container class for a collection of [Target](#target) objects. It also provides utility methods for manipulating the underlying collection. + +## Related Topics +[Message Correlation](message-correlation.md), [Setting Targets for Message Events](../guides/setting-targets-for-message-events.md) \ No newline at end of file diff --git a/docs/src/process-development/api-v1/guides/user-tasks-in-the-dsf.md b/docs/src/process-development/api-v1/guides/user-tasks-in-the-dsf.md index 78eee6bfe..c13bee63b 100644 --- a/docs/src/process-development/api-v1/guides/user-tasks-in-the-dsf.md +++ b/docs/src/process-development/api-v1/guides/user-tasks-in-the-dsf.md @@ -7,7 +7,7 @@ icon: creative Creating a [User Task](../bpmn/user-tasks.md) in a BPMN model causes the DSF to automatically generate a [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html) resource based on the [Questionnaire](https://www.hl7.org/fhir/R4/questionnaire.html) specified in the [User Task's](../bpmn/user-tasks.md) `Forms` field when process execution reaches the [User Task](../bpmn/user-tasks.md). The `Forms` field must have the type `Embedded or External Task Forms`, with the `Form key` set to the URL of the [Questionnaire](https://www.hl7.org/fhir/R4/questionnaire.html) resource. The [Questionnaire](https://www.hl7.org/fhir/R4/questionnaire.html) resource must be placed in the `src/main/resources/fhir/Questionnaire` directory. -The generated [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html) can be accessed and answered by navigating to `https://your.dsf.fhir.server/fhir/QuestionnaireResponse?_sort=-_lastUpdated&status=in-progress` in the DSF FHIR server UI. After completing and submitting the [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html), the process execution will proceed to the next BPMN element following the [User Task](../bpmn/user-tasks.md). The updated [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html) will then be accessible via the [Process Plugin Api's](../dsf/process-api.md) `Variables` instance by calling `getLatestReceivedQuestionnaireResponse()`. +The generated [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html) can be accessed and answered by navigating to `https://your.dsf.fhir.server/fhir/QuestionnaireResponse?_sort=-_lastUpdated&status=in-progress` in the DSF FHIR server UI. After completing and submitting the [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html), the process execution will proceed to the next BPMN element following the [User Task](../bpmn/user-tasks.md). The updated [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html) will then be accessible via the [Process Plugin Api's](../dsf/process-plugin-api.md) `Variables` instance by calling `getLatestReceivedQuestionnaireResponse()`. It is also possible to register a [Task Listener](https://docs.camunda.org/manual/7.21/user-guide/process-engine/delegation-code/#task-listener) on the [User Task](../bpmn/user-tasks.md). This enables manipulation of the [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html) before it is posted to the DSF FHIR server. This can be achieved by extending the `DefaultUserTaskListener` class, which provides overrides for interacting with the [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html). diff --git a/docs/src/process-development/api-v1/index.md b/docs/src/process-development/api-v1/index.md deleted file mode 100644 index 436fda63f..000000000 --- a/docs/src/process-development/api-v1/index.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: API v1 -icon: code ---- - -## BPMN -- [Conditions](bpmn/conditions.md) -- [Gateways](bpmn/gateways.md) -- [Messaging](bpmn/messaging.md) -- [Sequence Flow](bpmn/sequence-flow.md) -- [Service Tasks](bpmn/service-tasks.md) -- [Timer Intermediate Catching Events](bpmn/timer-intermediate-catching-events.md) - -## FHIR -- [ActivityDefinition](fhir/activitydefinition.md) -- [Codesystem](fhir/codesystem.md) -- [Task](fhir/task.md) -- [ValueSet](fhir/valueset.md) - -## DSF -- [BPMN Process Execution](dsf/bpmn-process-execution.md) -- [BPMN Process Variables](dsf/bpmn-process-variables.md) -- [Draft Task Resources](dsf/draft-task-resources.md) -- [Environment Variables](dsf/environment-variables.md) -- [Message Correlation](dsf/message-correlation.md) -- [Message Delegates](dsf/message-delegates.md) -- [Organization Identifiers](dsf/organization-identifiers.md) -- [Process Plugin API](dsf/process-plugin-api.md) -- [Process Plugin Definition](dsf/process-plugin-definition.md) -- [Read Access Tag](dsf/read-access-tag.md) -- [Requester and Recipient](dsf/requester-and-recipient.md) -- [Service Delegates](dsf/service-delegates.md) -- [Spring Framework Integration](dsf/spring-framework-integration.md) -- [Versions, Placeholders and URLs](dsf/versions-placeholders-urls.md) - -## Guides -- [Accessing BPMN Process Variables](guides/accessing-bpmn-process-variables.md) -- [Accessing Task Resources During Execution](guides/accessing-task-resources-during-execution.md) -- [Adding Task Input Parameters to Task Profiles](guides/adding-task-input-parameters-to-task-profiles.md) -- [Configuring Read Access Tags](guides/configuring-read-access-tags.md) -- [Creating ActivityDefinitions](guides/creating-activity-definitions.md) -- [Creating CodeSystems for DSF Processes](guides/creating-codesystems-for-dsf-processes.md) -- [Creating Task Resources Based on a Definition](guides/creating-task-resources-based-on-a-definition.md) -- [Creating ValueSets for DSF Processes](guides/creating-valuesets-for-dsf-processes.md) -- [Managing Multiple Incoming Messages and Missing Messages](guides/managing-mutiple-incoming-messages-and-missing-messages.md) -- [Setting Targets for Message Events](guides/setting-targets-for-message-events.md) -- [Starting a Process via Task Resources](guides/starting-a-process-via-task-resources.md) \ No newline at end of file diff --git a/docs/src/process-development/api-v2/concept.md b/docs/src/process-development/api-v2/concept.md index 76b9a46c6..51df57969 100644 --- a/docs/src/process-development/api-v2/concept.md +++ b/docs/src/process-development/api-v2/concept.md @@ -37,6 +37,7 @@ This site is work in progress, please come back later. - [Requester and Recipient](dsf/requester-and-recipient.md) - [Service Delegates](dsf/service-delegates.md) - [Spring Framework Integration](dsf/spring-framework-integration.md) +- [Target and Targets](dsf/target-and-targets.md) - [Versions, Placeholders and URLs](dsf/versions-placeholders-urls.md) ## Guides diff --git a/docs/src/process-development/api-v2/dsf/service-delegates.md b/docs/src/process-development/api-v2/dsf/service-delegates.md index a121f53b2..bc6d24f9a 100644 --- a/docs/src/process-development/api-v2/dsf/service-delegates.md +++ b/docs/src/process-development/api-v2/dsf/service-delegates.md @@ -7,7 +7,7 @@ icon: creative Service Delegates are the Java representation of the [Service Tasks](../bpmn/service-tasks.md) in a BPMN model. Service Delegates are linked to a certain [Service Task](../bpmn/service-tasks.md) by selecting the [Service Task](../bpmn/service-tasks.md) in the [Camunda Modeler](https://camunda.com/download/modeler/) and adding a Java class to the `Implementation` field. This uses the fully qualified class name: ``` -org.package.myClass +org.package.MyClass ``` Java classes need to implement the `ServiceTask` interface and override the `execute` method. This method holds the actual business logic. The method will be called when the [BPMN process execution](../dsf/bpmn-process-execution.md) arrives at the [Service Task](../bpmn/service-tasks.md) a Service Delegate is linked to. diff --git a/docs/src/process-development/api-v2/guides/user-tasks-in-the-dsf.md b/docs/src/process-development/api-v2/guides/user-tasks-in-the-dsf.md index 78eee6bfe..c13bee63b 100644 --- a/docs/src/process-development/api-v2/guides/user-tasks-in-the-dsf.md +++ b/docs/src/process-development/api-v2/guides/user-tasks-in-the-dsf.md @@ -7,7 +7,7 @@ icon: creative Creating a [User Task](../bpmn/user-tasks.md) in a BPMN model causes the DSF to automatically generate a [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html) resource based on the [Questionnaire](https://www.hl7.org/fhir/R4/questionnaire.html) specified in the [User Task's](../bpmn/user-tasks.md) `Forms` field when process execution reaches the [User Task](../bpmn/user-tasks.md). The `Forms` field must have the type `Embedded or External Task Forms`, with the `Form key` set to the URL of the [Questionnaire](https://www.hl7.org/fhir/R4/questionnaire.html) resource. The [Questionnaire](https://www.hl7.org/fhir/R4/questionnaire.html) resource must be placed in the `src/main/resources/fhir/Questionnaire` directory. -The generated [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html) can be accessed and answered by navigating to `https://your.dsf.fhir.server/fhir/QuestionnaireResponse?_sort=-_lastUpdated&status=in-progress` in the DSF FHIR server UI. After completing and submitting the [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html), the process execution will proceed to the next BPMN element following the [User Task](../bpmn/user-tasks.md). The updated [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html) will then be accessible via the [Process Plugin Api's](../dsf/process-api.md) `Variables` instance by calling `getLatestReceivedQuestionnaireResponse()`. +The generated [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html) can be accessed and answered by navigating to `https://your.dsf.fhir.server/fhir/QuestionnaireResponse?_sort=-_lastUpdated&status=in-progress` in the DSF FHIR server UI. After completing and submitting the [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html), the process execution will proceed to the next BPMN element following the [User Task](../bpmn/user-tasks.md). The updated [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html) will then be accessible via the [Process Plugin Api's](../dsf/process-plugin-api.md) `Variables` instance by calling `getLatestReceivedQuestionnaireResponse()`. It is also possible to register a [Task Listener](https://docs.camunda.org/manual/7.21/user-guide/process-engine/delegation-code/#task-listener) on the [User Task](../bpmn/user-tasks.md). This enables manipulation of the [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html) before it is posted to the DSF FHIR server. This can be achieved by extending the `DefaultUserTaskListener` class, which provides overrides for interacting with the [QuestionnaireResponse](https://www.hl7.org/fhir/R4/questionnaireresponse.html). diff --git a/docs/src/process-development/api-v2/index.md b/docs/src/process-development/api-v2/index.md deleted file mode 100644 index f70012ebd..000000000 --- a/docs/src/process-development/api-v2/index.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: API 2 (alpha) Overview -icon: code ---- - -## BPMN -- [Conditions](bpmn/conditions.md) -- [Gateways](bpmn/gateways.md) -- [Messaging](bpmn/messaging.md) -- [Sequence Flow](bpmn/sequence-flow.md) -- [Service Tasks](bpmn/service-tasks.md) -- [Timer Intermediate Catching Events](bpmn/timer-intermediate-catching-events.md) - -## FHIR -- [ActivityDefinition](fhir/activitydefinition.md) -- [Codesystem](fhir/codesystem.md) -- [Task](fhir/task.md) -- [ValueSet](fhir/valueset.md) - -## DSF -- [BPMN Process Execution](dsf/bpmn-process-execution.md) -- [BPMN Process Variables](dsf/bpmn-process-variables.md) -- [Draft Task Resources](dsf/draft-task-resources.md) -- [Environment Variables](dsf/environment-variables.md) -- [Message Correlation](dsf/message-correlation.md) -- [Message Delegates](dsf/message-delegates.md) -- [Organization Identifiers](dsf/organization-identifiers.md) -- [Process Plugin API](dsf/process-plugin-api.md) -- [Process Plugin Definition](dsf/process-plugin-definition.md) -- [Read Access Tag](dsf/read-access-tag.md) -- [Requester and Recipient](dsf/requester-and-recipient.md) -- [Service Delegates](dsf/service-delegates.md) -- [Spring Framework Integration](dsf/spring-framework-integration.md) -- [Versions, Placeholders and URLs](dsf/versions-placeholders-urls.md) - -## Guides -- [Accessing BPMN Process Variables](guides/accessing-bpmn-process-variables.md) -- [Accessing Task Resources During Execution](guides/accessing-task-resources-during-execution.md) -- [Adding Task Input Parameters to Task Profiles](guides/adding-task-input-parameters-to-task-profiles.md) -- [Configuring Read Access Tags](guides/configuring-read-access-tags.md) -- [Creating ActivityDefinitions](guides/creating-activity-definitions.md) -- [Creating CodeSystems for DSF Processes](guides/creating-codesystems-for-dsf-processes.md) -- [Creating Task Resources Based on a Definition](guides/creating-task-resources-based-on-a-definition.md) -- [Creating ValueSets for DSF Processes](guides/creating-valuesets-for-dsf-processes.md) -- [Managing Multiple Incoming Messages and Missing Messages](guides/managing-mutiple-incoming-messages-and-missing-messages.md) -- [Setting Targets for Message Events](guides/setting-targets-for-message-events.md) -- [Starting a Process via Task Resources](guides/starting-a-process-via-task-resources.md) \ No newline at end of file From c49af417810ccda2561e4517e57ee5dc9f042ded Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20B=C3=B6hringer?= <jan.boehringer@hs-heilbronn.de> Date: Mon, 21 Jul 2025 18:36:29 +0200 Subject: [PATCH 12/12] Added redirect urls for fat ping and initial troubleshooting pages to point to --- .../common-http-status-codes.md | 9 +++++++++ .../troubleshooting/connection-refused.md | 4 ++++ .../troubleshooting/connection-timeout.md | 13 +++++++++++++ .../operations/troubleshooting/read-timeout.md | 12 ++++++++++++ docs/src/operations/troubleshooting/ssl.md | 18 ++++++++++++++++++ .../operations/troubleshooting/unknown-host.md | 6 ++++++ docs/src/s/connection-refused.md | 2 ++ docs/src/s/connection-timeout.md | 2 ++ docs/src/s/error-http.md | 2 ++ docs/src/s/error-ssl.md | 2 ++ docs/src/s/read-timeout.md | 2 ++ docs/src/s/unknown-host.md | 2 ++ 12 files changed, 74 insertions(+) create mode 100644 docs/src/operations/troubleshooting/common-http-status-codes.md create mode 100644 docs/src/operations/troubleshooting/connection-refused.md create mode 100644 docs/src/operations/troubleshooting/connection-timeout.md create mode 100644 docs/src/operations/troubleshooting/read-timeout.md create mode 100644 docs/src/operations/troubleshooting/ssl.md create mode 100644 docs/src/operations/troubleshooting/unknown-host.md create mode 100644 docs/src/s/connection-refused.md create mode 100644 docs/src/s/connection-timeout.md create mode 100644 docs/src/s/error-http.md create mode 100644 docs/src/s/error-ssl.md create mode 100644 docs/src/s/read-timeout.md create mode 100644 docs/src/s/unknown-host.md diff --git a/docs/src/operations/troubleshooting/common-http-status-codes.md b/docs/src/operations/troubleshooting/common-http-status-codes.md new file mode 100644 index 000000000..9f3348159 --- /dev/null +++ b/docs/src/operations/troubleshooting/common-http-status-codes.md @@ -0,0 +1,9 @@ +--- +title: Common HTTP Status Codes +icon: support +--- + +# 403 Forbidden +This HTTP status code may be encountered in many different way in the context of the DSF: +- Process plugin is not installed at FHIR server where the Task resource was posted +- Client certificate of the FHIR server where the Task resource was posted is invalid \ No newline at end of file diff --git a/docs/src/operations/troubleshooting/connection-refused.md b/docs/src/operations/troubleshooting/connection-refused.md new file mode 100644 index 000000000..16c201d83 --- /dev/null +++ b/docs/src/operations/troubleshooting/connection-refused.md @@ -0,0 +1,4 @@ +--- +title: Connection Refused +icon: cog +--- \ No newline at end of file diff --git a/docs/src/operations/troubleshooting/connection-timeout.md b/docs/src/operations/troubleshooting/connection-timeout.md new file mode 100644 index 000000000..84b9d1036 --- /dev/null +++ b/docs/src/operations/troubleshooting/connection-timeout.md @@ -0,0 +1,13 @@ +--- +title: Connection Timeout +icon: time +--- + +A connection timeout happens when a connection attempt is made but there is no response from the endpoint in a certain timeframe. +There are many possible reasons for why this happens: +- The server is currently down or unreachable due to network configuration +- The server is under heavy load and thus unresponsive +- Firewalls might be blocking outgoing connections to the server +- Arbitrary network issues + +If this is happens during the execution of a DSF process, it is recommended to try starting the process again to see if the issue persists. If the issue persists, it is recommended to ensure no firewall settings are blocking the outgoing connection attempt. If this is not the root of the issue, further troubleshooting has to take place that may have to include someone knowledgeable about the process plugin or someone from the team maintaining the server or a combination of both. \ No newline at end of file diff --git a/docs/src/operations/troubleshooting/read-timeout.md b/docs/src/operations/troubleshooting/read-timeout.md new file mode 100644 index 000000000..b732b01f5 --- /dev/null +++ b/docs/src/operations/troubleshooting/read-timeout.md @@ -0,0 +1,12 @@ +--- +title: Read Timeout +icon: time +--- + +A read timeout is a network error that usually happens when a resource is read from a server but the resource takes too long to arrive at the client. +There are many possible reasons for why this happens: +- The server unexpectedly went down during transmission +- The server is under heavy load and unable to process the request in a timely manner +- Arbitrary network issues + +If this is happens during the execution of a DSF process, it is recommended to try starting the process again to see if the issue persists. If the issue persists, further troubleshooting has to take place that may have to include someone knowledgeable about the process plugin or someone from the team maintaining the server or a combination of both. \ No newline at end of file diff --git a/docs/src/operations/troubleshooting/ssl.md b/docs/src/operations/troubleshooting/ssl.md new file mode 100644 index 000000000..b6e5db3e7 --- /dev/null +++ b/docs/src/operations/troubleshooting/ssl.md @@ -0,0 +1,18 @@ +--- +title: SSL +icon: lock +--- + +SSL issues arise if there is a misconfiguration of client/server certificates. +Client certificates may: +- Be expired +- Have an untrusted root +- Be revoked + +Server certificates may: +- Be expired +- Have an untrusted root +- Be revoked +- Have the wrong host as the subject + +It is recommended to use [OpenSSL](https://openssl.org/) for further debugging. \ No newline at end of file diff --git a/docs/src/operations/troubleshooting/unknown-host.md b/docs/src/operations/troubleshooting/unknown-host.md new file mode 100644 index 000000000..9dc7d09ef --- /dev/null +++ b/docs/src/operations/troubleshooting/unknown-host.md @@ -0,0 +1,6 @@ +--- +title: Unknown Host +icon: question +--- + +This error occurs if a host name cannot be mapped to an IP address. Either because of a spelling mistake of the host name or because of DNS problems. If this happens in the context of a DSF process, it is recommended to review the configuration of the process plugin or contact the process plugin's maintainers in case of the former. DNS problems have a wide variety of sources and usually have to be resolved on the side of the sender. \ No newline at end of file diff --git a/docs/src/s/connection-refused.md b/docs/src/s/connection-refused.md new file mode 100644 index 000000000..430733123 --- /dev/null +++ b/docs/src/s/connection-refused.md @@ -0,0 +1,2 @@ +<meta http-equiv="refresh" content="0; url=../operations/troubleshooting/connection-refused" /> +<p>If you are not redirected, <a href="../operations/troubleshooting/connection-refused">click here</a>.</p> \ No newline at end of file diff --git a/docs/src/s/connection-timeout.md b/docs/src/s/connection-timeout.md new file mode 100644 index 000000000..0bf792197 --- /dev/null +++ b/docs/src/s/connection-timeout.md @@ -0,0 +1,2 @@ +<meta http-equiv="refresh" content="0; url=../operations/troubleshooting/connection-timeout" /> +<p>If you are not redirected, <a href="../operations/troubleshooting/connection-timeout">click here</a>.</p> \ No newline at end of file diff --git a/docs/src/s/error-http.md b/docs/src/s/error-http.md new file mode 100644 index 000000000..eafe21f8f --- /dev/null +++ b/docs/src/s/error-http.md @@ -0,0 +1,2 @@ +<meta http-equiv="refresh" content="0; url=../operations/troubleshooting/common-http-status-codes" /> +<p>If you are not redirected, <a href="../operations/troubleshooting/common-http-status-codes">click here</a>.</p> \ No newline at end of file diff --git a/docs/src/s/error-ssl.md b/docs/src/s/error-ssl.md new file mode 100644 index 000000000..81a550c66 --- /dev/null +++ b/docs/src/s/error-ssl.md @@ -0,0 +1,2 @@ +<meta http-equiv="refresh" content="0; url=../operations/troubleshooting/ssl" /> +<p>If you are not redirected, <a href="../operations/troubleshooting/ssl">click here</a>.</p> \ No newline at end of file diff --git a/docs/src/s/read-timeout.md b/docs/src/s/read-timeout.md new file mode 100644 index 000000000..3db57d51d --- /dev/null +++ b/docs/src/s/read-timeout.md @@ -0,0 +1,2 @@ +<meta http-equiv="refresh" content="0; url=../operations/troubleshooting/read-timeout" /> +<p>If you are not redirected, <a href="../operations/troubleshooting/read-timeout">click here</a>.</p> \ No newline at end of file diff --git a/docs/src/s/unknown-host.md b/docs/src/s/unknown-host.md new file mode 100644 index 000000000..1f5a46177 --- /dev/null +++ b/docs/src/s/unknown-host.md @@ -0,0 +1,2 @@ +<meta http-equiv="refresh" content="0; url=../operations/troubleshooting/unknown-host" /> +<p>If you are not redirected, <a href="../operations/troubleshooting/unknown-host">click here</a>.</p> \ No newline at end of file