diff --git a/docs/src/process-development/api-v2/bpmn/execution-listeners.md b/docs/src/process-development/api-v2/bpmn/execution-listeners.md new file mode 100644 index 000000000..5d28f551e --- /dev/null +++ b/docs/src/process-development/api-v2/bpmn/execution-listeners.md @@ -0,0 +1,8 @@ +--- +title: Execution Listeners +icon: creative +--- + +## Execution Listeners + +Execution Listeners can be registered to various flow elements like process, events, tasks, gateways and sequence flows. They are called when the process execution arrives at the flow element they are registered to. See [Activities] \ 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 4c0726281..bf21b1b23 100644 --- a/docs/src/process-development/api-v2/bpmn/gateways.md +++ b/docs/src/process-development/api-v2/bpmn/gateways.md @@ -5,16 +5,16 @@ 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. +[Gateways](https://docs.operaton.org/docs/documentation/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/), 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). +[Exclusive Gateways](https://docs.operaton.org/docs/documentation/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.operaton.org/docs/documentation/reference/bpmn20/gateways/exclusive-gateway) themselves. They are set through the sequence flow exiting the [Exclusive Gateway](https://docs.operaton.org/docs/documentation/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 -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. +The [Event-based Gateway](https://docs.operaton.org/docs/documentation/reference/bpmn20/gateways/event-based-gateway) models a decision in the workflow. But instead of [conditions](./conditions.md), the [Event-based Gateway](https://docs.operaton.org/docs/documentation/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](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. +[Parallel Gateways](https://docs.operaton.org/docs/documentation/reference/bpmn20/gateways/parallel-gateway/) model concurrent workflows. Their outgoing flows can be joined together again with another [Parallel Gateway](https://docs.operaton.org/docs/documentation/reference/bpmn20/gateways/parallel-gateway/). This makes process execution wait for both flows to arrive at the gateway before continuing. diff --git a/docs/src/process-development/api-v2/bpmn/index.md b/docs/src/process-development/api-v2/bpmn/index.md index d74ae074d..7b06e6848 100644 --- a/docs/src/process-development/api-v2/bpmn/index.md +++ b/docs/src/process-development/api-v2/bpmn/index.md @@ -8,6 +8,7 @@ The DSF uses BPMN 2.0 to model processes. Specifically, the [Camunda 7](https:// ## Details - [Conditions](conditions.md) +- [Execution Listeners](execution-listeners.md) - [Gateways](gateways.md) - [Messaging](messaging.md) - [Sequence Flow](sequence-flow.md) diff --git a/docs/src/process-development/api-v2/bpmn/messaging.md b/docs/src/process-development/api-v2/bpmn/messaging.md index 10657a006..226e5ef9a 100644 --- a/docs/src/process-development/api-v2/bpmn/messaging.md +++ b/docs/src/process-development/api-v2/bpmn/messaging.md @@ -6,19 +6,25 @@ icon: creative ## Messaging -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. +Enabling communication with other lanes, pools or even entirely separate processes requires the ability to exchange information. In BPMN, [Message Events](https://docs.operaton.org/docs/documentation/reference/bpmn20/events/message-events/) and [Message Send Tasks](https://docs.operaton.org/docs/documentation/reference/bpmn20/tasks/send-task) are used to model this information exchange. Using them to model communication 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, 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 Start Events](https://docs.operaton.org/docs/documentation/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, it is mandatory to include a [Message Start Event](https://docs.operaton.org/docs/documentation/reference/bpmn20/events/message-events#message-start-event) at the beginning of all DSF 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 Throwing Event +[Message Intermediate Throwing Events](https://docs.operaton.org/docs/documentation/reference/bpmn20/events/message-events#message-intermediate-throwing-event) are used to send messages during process execution. Message intermediate throwing events that are used to communicate with DSF instances via FHIR Task resources, should implement the DSF API v2 interface `dev.dsf.bpe.v2.activity.MessageIntermediateThrowEvent`. -### 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 Intermediate Catching Event +[Message Intermediate Catching Events](https://docs.operaton.org/docs/documentation/reference/bpmn20/events/message-events#message-intermediate-catching-event) serve as the counterpart to [Message Intermediate Throwing Events](messaging.md#message-intermediate-throwing-event). They are used 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 +#### Message End Event +The [Message End Event](https://docs.operaton.org/docs/documentation/reference/bpmn20/events/message-events#message-end-event) will stop the execution of a BPMN process and finish by sending a message.Message end events that are used to communicate with DSF instances via FHIR Task resources, should implement the API v2 interface `dev.dsf.bpe.v2.activity.MessageEndEvent`. + +#### Message Send Task +Same as the [Message Intermediate Throwing Event](#message-intermediate-throwing-event), the [Message Send Task](https://docs.operaton.org/docs/documentation/reference/bpmn20/tasks/send-task/) is used to send messages during process execution but is also intended to execute some kind of business logic at the same time. Message send tasks that are used to communicate with DSF instances via FHIR Task resources, should implement the API v2 interface `dev.dsf.bpe.v2.activity.MessageSendTask`. + +## Related Topics +[Activities](../dsf/activities.md), [Message Activities](../dsf/message-activities.md) \ No newline at end of file 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 4128d5a2e..6704e9fc6 100644 --- a/docs/src/process-development/api-v2/bpmn/service-tasks.md +++ b/docs/src/process-development/api-v2/bpmn/service-tasks.md @@ -5,4 +5,4 @@ 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 BPMN processes. +One of the most common types of BPMN Tasks used for modeling DSF processes is the [Service Task](https://docs.operaton.org/docs/documentation/reference/bpmn20/tasks/service-task). They are different from regular BPMN Tasks in that they offer the ability to link a Java class to the [Service Task](https://docs.operaton.org/docs/documentation/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 and their associated code. Java service tasks must implement the API v2 interface `dev.dsf.bpe.v2.activity.ServiceTask`. \ 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 ff19cb3a8..d3ca7a6ec 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 @@ -5,4 +5,4 @@ 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 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). +A [Timer Intermediate Catching Event](https://docs.operaton.org/docs/documentation/reference/bpmn20/events/timer-events#timer-intermediate-catching-event) allows 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.operaton.org/docs/documentation/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.operaton.org/docs/documentation/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 a34f257f7..b553876d8 100644 --- a/docs/src/process-development/api-v2/bpmn/user-tasks.md +++ b/docs/src/process-development/api-v2/bpmn/user-tasks.md @@ -5,4 +5,7 @@ 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 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). +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. Operaton supports three kinds of forms: [Embedded Forms](https://docs.operaton.org/docs/documentation/user-guide/task-forms/#embedded-task-forms), [Operaton Forms](https://docs.operaton.org/docs/documentation/user-guide/task-forms/#embedded-task-forms) and [External Task Forms](https://docs.operaton.org/docs/documentation/user-guide/task-forms/#external-task-forms). The DSF uses `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. + +## Related Topics +[Questionnaire and QuestionnaireResponse](../fhir/questionnaire-and-questionnaireresponse.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/concept.md b/docs/src/process-development/api-v2/concept.md index 02af1c12f..f2fc47464 100644 --- a/docs/src/process-development/api-v2/concept.md +++ b/docs/src/process-development/api-v2/concept.md @@ -5,6 +5,7 @@ icon: info ## BPMN - [Conditions](bpmn/conditions.md) +- [Execution Listener](bpmn/execution-listeners.md) - [Gateways](bpmn/gateways.md) - [Messaging](bpmn/messaging.md) - [Sequence Flow](bpmn/sequence-flow.md) @@ -14,22 +15,23 @@ icon: info ## FHIR - [ActivityDefinition](fhir/activitydefinition.md) - [Codesystem](fhir/codesystem.md) +- [Questionnaire and QuestionnaireResponse](fhir/questionnaire-and-questionnaireresponse.md) - [Task](fhir/task.md) - [ValueSet](fhir/valueset.md) ## DSF -- [BPMN Process Execution](dsf/bpmn-process-execution.md) +- [Activities](dsf/activities.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) +- [Message Activities](dsf/message-activities.md) +- [Messaging](dsf/messaging.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) - [Target and Targets](dsf/target-and-targets.md) - [Versions, Placeholders and URLs](dsf/versions-placeholders-urls.md) @@ -37,12 +39,11 @@ icon: info ## 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) +- [Adding Task Parameters to Task Profiles](guides/adding-task-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/dsf/activities.md b/docs/src/process-development/api-v2/dsf/activities.md new file mode 100644 index 000000000..f0b7a36bb --- /dev/null +++ b/docs/src/process-development/api-v2/dsf/activities.md @@ -0,0 +1,37 @@ +--- +title: Activities +icon: creative +--- + +### Activities + +Activities are Java interfaces in the DSF API v2 that represent certain BPMN elements which can/need to specify a Java class as their `Implementation` value. Implementing Activity interfaces and [registering them as Spring beans](spring-framework-integration.md) causes the DSF to execute the code provided by the implementation when the process execution reaches the corresponding flow element. The value for the `Implementation` field of BPMN elements expects the fully qualified class name: +``` +org.package.myClass +``` + +### List of Activities +- ExecutionListener +- MessageEndEvent +- MessageIntermediateThrowEvent +- MessageSendTask +- ServiceTask +- UserTaskListener + +### ExecutionListener +`ExecutionListener` is the interface to be implemented for a class set as the Java implementation for [Execution Listeners](../bpmn/execution-listeners.md) attached to certain flow elements. + +### MessageEndEvent +`MessageEndEvent` is the interface to be implemented for a class set as the Java implementation for Message End Events. It inherits from the `MessageActivity` interface which specifies additional methods specific to [messaging](messaging.md). + +### MessageIntermediateThrowEvent +`MessageIntermediateThrowEvent` is the interface to be implemented for a class set as the Java implementation for Message Intermediate Throw Events. It inherits from the `MessageActivity` interface which specifies additional methods specific to [messaging](messaging.md). + +### MessageSendTask +`MessageSendTask` is the interface to be implemented for a class set as the Java implementation for Message Send Tasks. It inherits from the `MessageActivity` interface which specifies additional methods specific to [messaging](messaging.md). + +### ServiceTask +`ServiceTask` is the interface to be implemented for a class set as the Java implementation for Service Tasks. + +### UserTaskListener +`ServiceTask` is the interface to be implemented for a class set as the Java implementation for Service Tasks's Task Listener. Task Listeners have properties that separate them from [Execution Listeners](../bpmn/execution-listeners.md). More on Task Listeners in the guide on [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 index d6c0277c5..b2942c1d5 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,7 @@ 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). 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 +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 implementing/overriding certain methods in [Activities](activities.md) like `execute` or `getAdditionalInputParameters`. + +## Related Topics +[Activities](activities.md) \ 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 index cd2baf68e..e05e012d7 100644 --- a/docs/src/process-development/api-v2/dsf/bpmn-process-variables.md +++ b/docs/src/process-development/api-v2/dsf/bpmn-process-variables.md @@ -5,6 +5,7 @@ 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. +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. Certain [Activities](activities.md) expose an instance of the `Variables` class which gives access to BPMN process variables. -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). +## Related Topics +[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 index c8ed0e4f4..e565de823 100644 --- a/docs/src/process-development/api-v2/dsf/draft-task-resources.md +++ b/docs/src/process-development/api-v2/dsf/draft-task-resources.md @@ -5,17 +5,18 @@ 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: +[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 the `.../src/main/resources/fhir/Task` subdirectory of a project. 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: ```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. +`task-name` may be any String to identify this task with. E.g. 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). +Complete examples can be found in existing process plugins like [Ping Pong](https://github.com/datasharingframework/dsf-process-ping-pong/blob/main/src/main/resources/fhir/Task/dsf-task-stop-ping-autostart.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. +## Related Topics +[Creating Task Resources Based On a Definition](../guides/creating-task-resources-based-on-a-definition.md) \ 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 4f0b5bd7e..fcf4e3c4e 100644 --- a/docs/src/process-development/api-v2/dsf/environment-variables.md +++ b/docs/src/process-development/api-v2/dsf/environment-variables.md @@ -5,6 +5,47 @@ 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`. +Environment variables offer a way to make configuration data available at the start of a process. They are the same for all 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 a configuration class (a class annotated with the [Spring-Framework @Configuration](https://docs.spring.io/spring-framework/reference/core/beans/java/configuration-annotation.html) annotation). 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. 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 `` field has to point to the package where documentation is desired. +```java +@Configuration +public class MyConfiguration +{ + @Value("${example.org.my.value}") + private String myValue; +} +``` + +The DSF provides a feature to automatically generate documentation of environment variables during the Maven build process. The `@ProcessDocumentation` annotation causes the build process to automatically generate Markdown documentation for all fields with this annotation. +```java +@Configuration +public class MyConfiguration +{ + @ProcessDocumentation(processNames = "myorg_MyProcess", description = "My process description", required = true, recommendation = "Foo") + @Value("${example.org.my.value}") + private String myValue; +} +``` + This requires the DSF Maven Plugin to be configured in the `pom.xml` file of the project. A configuration to generate documentation for a package `example.org.spring.config` containing all Spring configuration classes looks like this: +```xml + + dev.dsf + dsf-maven-plugin + 2.0.2 + + + + generate-config-doc + + + + + dev.dsf.bpe.config + + +``` + +Maven build plugins will be executed during the build phase and should be configured in the `` element from the `pom.xml`. + +## Related Topics +[Spring Framework Integration](spring-framework-integration.md) \ 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 index f70d7104e..63d6f9d6f 100644 --- a/docs/src/process-development/api-v2/dsf/index.md +++ b/docs/src/process-development/api-v2/dsf/index.md @@ -4,17 +4,18 @@ icon: creative --- ## Details +- [Activities](activities.md) - [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 Activities](message-activities.md) - [Message Correlation](message-correlation.md) -- [Message Delegates](message-delegates.md) +- [Messaging](messaging.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-activities.md b/docs/src/process-development/api-v2/dsf/message-activities.md new file mode 100644 index 000000000..69d8b643f --- /dev/null +++ b/docs/src/process-development/api-v2/dsf/message-activities.md @@ -0,0 +1,15 @@ +--- +title: Message Activities +icon: creative +--- + +### Message Activities + +Compared to other [Activities](activities.md), Message Activities additionally extend the [Message Activity](https://github.com/datasharingframework/dsf/blob/release/2.0.2/dsf-bpe/dsf-bpe-process-api-v2/src/main/java/dev/dsf/bpe/v2/activity/MessageActivity.java) interface. It provides additional methods which are specific to messaging: + +- `getTaskSender`: Overriding this method allows fine control over how the message should be sent as a [Task](../fhir/task.md) resource by returning a custom [`TaskSender`](https://github.com/datasharingframework/dsf/blob/release/2.0.2/dsf-bpe/dsf-bpe-process-api-v2/src/main/java/dev/dsf/bpe/v2/activity/task/TaskSender.java) implementation +- `getBusinessKeyStrategy`: Overriding this method allows setting a different [`BusinessKeyStrategy`](https://github.com/datasharingframework/dsf/blob/release/2.0.2/dsf-bpe/dsf-bpe-process-api-v2/src/main/java/dev/dsf/bpe/v2/activity/task/BusinessKeyStrategies.java) +- `getAdditionalInputParameters`: If the message should contain additional information beyond what the DSF automatically sets, like the `business-key`, this method needs to be overridden to return that information in the form of [Task Input Parameters](../fhir/task.md#task-input-parameters) + +## Related Topics +[Messaging](messaging.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 index 2c7ba5a10..22f4670a5 100644 --- a/docs/src/process-development/api-v2/dsf/message-correlation.md +++ b/docs/src/process-development/api-v2/dsf/message-correlation.md @@ -5,6 +5,6 @@ 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. +Having messages arrive at the correct process instance requires a mechanism to link them to their rightful process instance. This mechanism is called Message Correlation and attaches 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. A message can then be sent back to the organization which initiated the communication and have it arrive at the same process instance that initially sent the message since the returning message will have the same `business-key` attached. -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. +It is possible that the `business-key` is insufficient to map messages to the correct process instance. Like when using subprocesses in the 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 attachable to all messages if they need to arrive at a specific subprocess. The [`Variables`](bpmn-process-variables.md) class provides methods to create `Targets` with a `correlation-key` value. The value is usually given as a UUID. When using the [Process Plugin API's](process-plugin-api.md) `TargetProvider` to create targets for messages, its builder offers the option to decide whether a `correlation-key` should be part of each `Target` instance. If set, the [Task](../fhir/task.md) will automatically have a `correlation-key` set when it is sent to the target. \ 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 deleted file mode 100644 index f5021e4d9..000000000 --- a/docs/src/process-development/api-v2/dsf/message-delegates.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -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](../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](../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/messaging.md b/docs/src/process-development/api-v2/dsf/messaging.md new file mode 100644 index 000000000..f01aca556 --- /dev/null +++ b/docs/src/process-development/api-v2/dsf/messaging.md @@ -0,0 +1,15 @@ +--- +title: Messaging +icon: creative +--- + +### Messaging + +BPMN does not provide an implementation for its [messaging](../bpmn/messaging.md) model, nor does the Business Process Engines the DSF is currently built upon. The DSF implements messaging through FHIR [Task](../fhir/task.md) resources. Sending a message is thus equivalent to making an HTTP POST request including a [Task](../fhir/task.md) resource to another (DSF) FHIR server. This step is done by the DSF automatically if the required prerequisites are met. + +### Messaging Prerequisites + +After modelling communication using [BPMN message elements](../bpmn/messaging.md), the DSF will create a [Task](../fhir/task.md) resource based on the field injection values `profile`, `messageName` and `instantiatesCanonical` of the [BPMN message element](../bpmn/messaging.md) and the additional input parameters provided by the [activity's](message-activities.md) `getAdditionalInputParameters` method. The [Task](../fhir/task.md) is then sent to the recipient specified by the [Target](target-and-targets.md) instance set in the current process execution as a [process variable](bpmn-process-variables.md). + +## Related Topics +[Activities](activities.md), [Message Activities](message-activities.md), [Process Plugin API](process-plugin-api.md), [Task](../fhir/task.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 dfb78a204..39a9d838d 100644 --- a/docs/src/process-development/api-v2/dsf/organization-identifiers.md +++ b/docs/src/process-development/api-v2/dsf/organization-identifiers.md @@ -4,7 +4,7 @@ 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. +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://example.org/fhir/Organization` will return a list of all organizations for the DSF FHIR server instance running under `example.org`. 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. 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). 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 60f968aaf..437a9186c 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,20 +21,27 @@ 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 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. -- `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). +[Activities](activities.md) usually provide access to an instance of `ProcessPluginApi` when implementing/overriding their methods. +This API instance provides a variety of utility classes: +- `ProcessPluginDefinition`**:** access to the plugin's [`ProcessPluginDefinition`](process-plugin-definition.md) +- `ProxyConfig`**:** forward proxy configuration +- `EndpointProvider`**:** access to Endpoint resources +- `FhirContext`**:** HAPI FHIR Context for parsing/serializing +- `DsfClientProvider`**:** Webservice client to access a DSF FHIR server +- `FhirClientProvider`**:** Webservice client to access a generic FHIR server +- `OidcClientProvider`**:** Webservice client for OIDC +- `MailService`**:** for sending automatic E-Mails (if configured) +- `MimeTypeService`**:** utility for validating MIME types +- `ObjectMapper`**:** ObjectMapper instance to serialize/deserialize POJOs to/from formats like JSON. ObjectMapper should not be used for FHIR resources. The parser provided by the FhirContext should be used instead +- `OrganizationProvider`**:** access to Organization resources +- `ProcessAuthorizationHelper`**:** utility for process authorization in [ActivityDefinitions](../fhir/activitydefinition.md) +- `QuestionnaireResponseHelper`**:** utility for manipulating [QuestionnaireResponse](../guides/user-tasks-in-the-dsf.md) resources +- `ReadAccessHelper`**:** utility for adding and validating [Read Access Tags](read-access-tag.md) in FHIR resources +- `TaskHelper`**:** utility for reading and creating [Input and Output Parameters](../fhir/task.md) in Task resources +- `CompressionService`**:** utility to compress/decompress data using various compression methods +- `CryptoService`**:** utility for cryptography like creating RSA key pairs +- `TargetProvider`**:** utility to create [Target instances](messaging.md) e.g. based on the identifier of a parent organization +- `Variables`**:** access to BPMN execution variables ## Related Topics -[Service Delegates](service-delegates.md), [Message Delegates](message-delegates.md) +[Activities](activities.md), [Input and Output Parameters](../fhir/task.md), [ProcessPluginDefinition](process-plugin-definition.md), [Read Access Tags](read-access-tag.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 index 498ae2514..3c25003d3 100644 --- a/docs/src/process-development/api-v2/dsf/process-plugin-definition.md +++ b/docs/src/process-development/api-v2/dsf/process-plugin-definition.md @@ -13,7 +13,8 @@ In order for the DSF BPE server to load a plugin properly, it needs to provide t * 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/). +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.v2.ProcessPluginDefinition` file. An example of this can be found in the [process plugin tutorial](https://github.com/datasharingframework/dsf-process-tutorial/). +It is recommended to extend the [`AbstractProcessPluginDefinition`](https://github.com/datasharingframework/dsf/blob/release/2.0.2/dsf-bpe/dsf-bpe-process-api-v2/src/main/java/dev/dsf/bpe/v2/AbstractProcessPluginDefinition.java) class which already implements some of the methods required by the interface and forces a configuration of the plugin that wards against potential inconsistencies between the Java code and `pom.xml`, while also setting the foundation for reproducible builds. ## Related Topics [Spring Integration](spring-framework-integration.md), [Versions, Placeholders and URLs](versions-placeholders-urls.md) 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 index 90aad4ced..046d05dc0 100644 --- a/docs/src/process-development/api-v2/dsf/read-access-tag.md +++ b/docs/src/process-development/api-v2/dsf/read-access-tag.md @@ -15,9 +15,9 @@ Axiomatically, nobody is allowed to write FHIR resources (except [Task](../fhir/ ``` -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). +All codes for the Read Access Tag can be found in its [CodeSystem](https://github.com/datasharingframework/dsf/blob/release/2.0.2/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/CodeSystem/dsf-read-access-tag-2.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. +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/release/2.0.2/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-extension-process-authorization-2.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). 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 index 0aa1a7e9d..59c318994 100644 --- a/docs/src/process-development/api-v2/dsf/requester-and-recipient.md +++ b/docs/src/process-development/api-v2/dsf/requester-and-recipient.md @@ -5,20 +5,20 @@ 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). +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/release/2.0.2/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-extension-process-authorization-2.0.0.xml). CodeSystems referenced in the examples can be found [here](https://github.com/datasharingframework/dsf/tree/release/2.0.2/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 @@ -194,9 +194,9 @@ The `requester` element uses one of the following Codings: ### Recipient The `recipeint` element uses one of the following Codings: ```xml - - - + + + ``` #### Local All diff --git a/docs/src/process-development/api-v2/dsf/service-delegates.md b/docs/src/process-development/api-v2/dsf/service-delegates.md deleted file mode 100644 index bc6d24f9a..000000000 --- a/docs/src/process-development/api-v2/dsf/service-delegates.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -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) 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 f4abaea72..5fd8d0299 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 @@ -73,4 +73,4 @@ public class TutorialConfig ``` ## Related Topics -[Environment Variables](environment-variables.md), [Message Delegates](message-delegates.md), [Service Delegates](service-delegates.md) +[Activities](activities.md), [Environment Variables](environment-variables.md) 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 index 8b8df62db..adb38f4e5 100644 --- a/docs/src/process-development/api-v2/dsf/target-and-targets.md +++ b/docs/src/process-development/api-v2/dsf/target-and-targets.md @@ -6,14 +6,24 @@ 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`. +- **Organization Identifier:** Identifier of an [Organization Resource](https://www.hl7.org/fhir/R4/organization.html). It can be acquired through the API's `OrganizationProvider` or by querying a FHIR server. Querying the DSF FHIR server should be done using the `DsfClient` provided by the API's `DsfClientProvider` while a `FhirClient` provided by the API's `FhirClientProvider` may be used for other types of FHIR servers. +- **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. It can be acquired through the API's `OrganizationProvider` or by querying a FHIR server. Querying the DSF FHIR server should be done using the `DsfClient` provided by the API's `DsfClientProvider` while a `FhirClient` provided by the API's `FhirClientProvider` may be used for other types of FHIR servers. - **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). +- **Correlation Key:** Optional 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. +## Creating Target/Targets + +Creating Target instances 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 can be created by using the [`Variables'`](bpmn-process-variables.md) `createTarget` method or by using [Process Plugin API's](process-plugin-api.md) `TargetProvider` instance. The methods provided by [`Variables`](bpmn-process-variables.md) allow creating specific Target instances and Targets instances based on collections of Target instances. For cases where for example, all member organizations of a particular parent organization should be targeted, the [Process Plugin API's](process-plugin-api.md) `TargetProvider` instance offers various different utility methods. + +## Setting Target/Targets + +Targets should be set in a [Service Task](../bpmn/service-tasks.md) before a [Message Activity](message-activities.md). +Targets should be set either through the [`Variables'`](bpmn-process-variables.md) `setTarget` or `setTargets` methods. When modelling parallel subprocesses where each execution sends messages to its own target, the Target can be set automatically for each execution by using `${targets.entries}` as the `Collection` value for the parallel subprocess and `target` as the `Element variable` value in the [Camunda Modeler](https://camunda.com/download/modeler/). This requires having called `setTargets` before entering the parallel subprocess. + ## 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 +[Message Activities](message-activities.md), [Message Correlation](message-correlation.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 index 1fb0ecf0c..af82ef36d 100644 --- a/docs/src/process-development/api-v2/dsf/versions-placeholders-urls.md +++ b/docs/src/process-development/api-v2/dsf/versions-placeholders-urls.md @@ -22,18 +22,18 @@ To avoid specifying the version and release date in multiple files, the placehol 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 +^[-a-zA-Z0-9]+_[-a-zA-Z0-9]+$ Example: exampleorg_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 +http://example.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 +http://example.org/bpe/Process/processKey ``` This will be the value for the `ActivityDefinition.url` element with `#{version}` as the value for the `ActivityDefinition.version` element. diff --git a/docs/src/process-development/api-v2/fhir/activitydefinition.md b/docs/src/process-development/api-v2/fhir/activitydefinition.md index ae4e64c9a..4a4bf43b9 100644 --- a/docs/src/process-development/api-v2/fhir/activitydefinition.md +++ b/docs/src/process-development/api-v2/fhir/activitydefinition.md @@ -5,7 +5,7 @@ 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. +[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/release/2.0.2/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-activity-definition-2.0.0.xml) profile. The most important elements in ActivityDefinitions are: @@ -18,7 +18,7 @@ The `message-name` element contains the name of the [BPMN message start event](. 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). There is also the guide on [creating ActivityDefinitions](../guides/creating-activity-definitions.md) for more in-depth information. +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/release/2.0.2/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-activity-definition-2.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/release/2.0.2/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/fhir/codesystem.md b/docs/src/process-development/api-v2/fhir/codesystem.md index ec31894dd..89f5567c3 100644 --- a/docs/src/process-development/api-v2/fhir/codesystem.md +++ b/docs/src/process-development/api-v2/fhir/codesystem.md @@ -8,7 +8,7 @@ icon: creative [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). +1. Using existing [DSF CodeSystems](https://github.com/datasharingframework/dsf/tree/release/2.0.2/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/release/2.0.2/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-extension-process-authorization-2.0.0.xml). 2. Creating custom CodeSystem to add additional [Input Parameters](task.md#task-input-parameters) to [Task](task.md) profiles. ## Related Topics diff --git a/docs/src/process-development/api-v2/fhir/index.md b/docs/src/process-development/api-v2/fhir/index.md index f09084455..065b7f8e3 100644 --- a/docs/src/process-development/api-v2/fhir/index.md +++ b/docs/src/process-development/api-v2/fhir/index.md @@ -4,7 +4,7 @@ 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). +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/release/2.0.2/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir). ## Details - [ActivityDefinition](activitydefinition.md) diff --git a/docs/src/process-development/api-v2/fhir/task.md b/docs/src/process-development/api-v2/fhir/task.md index 53503e18c..4a9d5dff4 100644 --- a/docs/src/process-development/api-v2/fhir/task.md +++ b/docs/src/process-development/api-v2/fhir/task.md @@ -5,16 +5,19 @@ 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): +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 definition](https://github.com/datasharingframework/dsf/blob/release/2.0.2/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-task-2.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`. +When creating a process plugin, it is usually necessary to create new profiles based on the [DSF Task base definition](https://github.com/datasharingframework/dsf/blob/release/2.0.2/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-task-2.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. +Task Input Parameters allow adding additional information to [Task](task.md#task) resources before they are starting a process. For example, if a particular process requires an additional string value, one would add a slice to the Task profile in the same way the [DSF Task base definition](https://github.com/datasharingframework/dsf/blob/release/2.0.2/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-task-2.0.0.xml) adds slices to the original [FHIR Task](https://www.hl7.org/fhir/R4/task.html) resource in the `message-name` slice. 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. + +### Task Output Parameter +Task Output Parameters function the same way as Input Parameters but are used to add information when a process has finished executing. This is usually used to display the result of the executed process. If the process fails because an uncaught exception is thrown, the DSF will update a Task to status `failed` and include the exception as an Output Parameter. ## Related Topics -[ActivityDefinition](activitydefinition.md), [Adding Task Input Parameter to Task Profiles](../guides/adding-task-input-parameters-to-task-profiles.md) +[ActivityDefinition](activitydefinition.md), [Adding Task Parameters to Task Profiles](../guides/adding-task-parameters-to-task-profiles.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 2c809593c..231639917 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 @@ -5,10 +5,10 @@ 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/). +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/implementing methods in [Activities](../dsf/activities.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 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 +[BPMN Process Variables](../dsf/bpmn-process-variables.md), [Activities](../dsf/activities.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 f5cbf1e50..3ba162135 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 @@ -5,12 +5,41 @@ 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. +Access to the [Task](../fhir/task.md) resources in [Activities](../dsf/activities.md) 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). +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 Activity's](../dsf/message-activities.md) `getAdditionalInputParameters` method. +### Retrieving Data from Input Parameters +1. Know the [CodeSystem](../fhir/codesystem.md) and Code of the `type` element of the [Input Parameter](../fhir/task.md#task-input-parameters) to extract data from. This depends on the [Task's](../fhir/task.md) [StructureDefinition](https://www.hl7.org/fhir/R4/structuredefinition.html). Example: +```xml + + + + + + + + + + + + + + + + +``` +2. Know the [FHIR Datatype](https://www.hl7.org/fhir/R4/datatypes.html) of the [Input Parameter](../fhir/task.md#task-input-parameters) defined by its `value[x]` element. This also depends on the [Task's](../fhir/task.md) [StructureDefinition](https://www.hl7.org/fhir/R4/structuredefinition.html). Example: +```xml + + + + + + +``` +3. The `TaskHelper's` getters for [Input Parameters](../fhir/task.md#task-input-parameters) should be used depending on the information available. 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. There are also methods immediately returning the value of the [Input Parameter](../fhir/task.md#task-input-parameters) if the [FHIR Datatype](https://www.hl7.org/fhir/R4/datatypes.html) is provided. The `string` datatype is used often enough to have its own method immediately returning the String value of the matched [Input Parameter](../fhir/task.md#task-input-parameters). ## 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 +[Accessing BPMN Process Variables](accessing-bpmn-process-variables.md), [Activities](../dsf/activities.md), [Task](../fhir/task.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-parameters-to-task-profiles.md similarity index 91% rename from docs/src/process-development/api-v2/guides/adding-task-input-parameters-to-task-profiles.md rename to docs/src/process-development/api-v2/guides/adding-task-parameters-to-task-profiles.md index 1480ee8f8..54891fae0 100644 --- 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-parameters-to-task-profiles.md @@ -1,9 +1,10 @@ --- -title: Adding Task Input Parameters to Task Profiles +title: Adding Task Parameters to Task Profiles icon: creative --- -## Adding Task Input Parameters to Task Profiles +## Adding Task Parameters to Task Profiles +This guide will demonstrate adding Input Parameters to a Task profile but can be used analogously for Output Parameters as well by replacing instances of `input` with `output` 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). @@ -31,7 +32,7 @@ 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)* +*The resource can be found [here](https://github.com/datasharingframework/dsf/blob/release/2.0.2/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-task-2.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). @@ -70,7 +71,7 @@ Next up is the binding for `Task.input:example-input.type`. Because `Task.input. - + @@ -94,7 +95,7 @@ Since the [discriminator](https://www.hl7.org/fhir/R4/profiling.html#discriminat - + @@ -122,7 +123,7 @@ The beginning mentioned how `Task.input.type.coding.system` and `Task.input.type - + @@ -132,7 +133,7 @@ The beginning mentioned how `Task.input.type.coding.system` and `Task.input.type - + @@ -152,7 +153,7 @@ The `type.coding.system` element references a [CodeSystem](../fhir/codesystem.md - + @@ -180,7 +181,7 @@ Adding a slice in a different use case will also require to reference an existin - + @@ -190,7 +191,7 @@ Adding a slice in a different use case will also require to reference an existin - + 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 index 7ac655e5a..220abe9f2 100644 --- 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 @@ -5,7 +5,7 @@ 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: +Before starting to configure anything, it is advised to take a look at the [CodeSystem](https://github.com/datasharingframework/dsf/blob/release/2.0.2/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/CodeSystem/dsf-read-access-tag-2.0.0.xml) defined for the [Read Access Tag](../dsf/read-access-tag.md) and choose one of the codes from it: ```xml ... @@ -54,7 +54,7 @@ Now to configure a Read Access Tag whose code uses an extension. This example wi ``` -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 `definition` element of the `ROLE` code references an extension called [dsf-extension-read-access-parent-organization-role](https://github.com/datasharingframework/dsf/blob/release/2.0.2/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-extension-read-access-parent-organization-role-2.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 @@ -344,7 +344,7 @@ Instead of `Identifier`, the `value[x]` element is now defined as a `Coding` typ ``` -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: +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/release/2.0.2/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/CodeSystem/dsf-organization-role-2.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 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 index fe296007b..daf122fae 100644 --- a/docs/src/process-development/api-v2/guides/creating-activity-definitions.md +++ b/docs/src/process-development/api-v2/guides/creating-activity-definitions.md @@ -5,7 +5,7 @@ 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. +This guide will explain how to create an ActivityDefinition based on the [dsf-activity-definition](https://github.com/datasharingframework/dsf/blob/release/2.0.2/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-activity-definition-2.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 @@ -16,7 +16,7 @@ It is divided into steps for each of the main components of ActivityDefinitions: *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 +### 1. Profile and Read Access Tag Start out with an empty [ActivityDefinition](../fhir/activitydefinition.md): ```xml @@ -24,11 +24,12 @@ Start out with an empty [ActivityDefinition](../fhir/activitydefinition.md): ``` -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: +The first elements in DSF FHIR resources are always the profile the resources corresponds to and the [Read Access Tag](../dsf/read-access-tag.md). The profile usually has a [DSF base resource](https://github.com/datasharingframework/dsf/tree/release/2.0.2/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition) as its value. The [Read Access Tag](../dsf/read-access-tag.md) 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 + @@ -38,7 +39,7 @@ The first element in DSF FHIR resources is always the [Read Access Tag](../dsf/r ``` ### 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: +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/release/2.0.2/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-extension-process-authorization-2.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 ... @@ -119,6 +120,7 @@ This section defines that there has to be exactly one extension element from the ```xml + @@ -164,7 +166,7 @@ The next slice is called `task-profile`: 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 - + ``` @@ -174,6 +176,7 @@ This section has almost the same structure as `message-name`. The only differenc ```xml + @@ -184,7 +187,7 @@ This section has almost the same structure as `message-name`. The only differenc - + @@ -211,19 +214,19 @@ The next slice is `requester`: - - - - - - - - - + + + + + + + + + - + ... @@ -237,7 +240,7 @@ Here is what they mean: - `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 + can be found [here](https://github.com/datasharingframework/dsf/blob/release/2.0.2/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/CodeSystem/dsf-practitioner-role-2.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). @@ -252,7 +255,7 @@ It is also good to keep in mind that any number of `requester` elements may be a ``` -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: +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/release/2.0.2/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-coding-process-authorization-local-organization-practitioner-2.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 @@ -273,7 +276,7 @@ The remaining element definitions are found in one of the profiles. This example - + @@ -288,7 +291,7 @@ The remaining element definitions are found in one of the profiles. This example ``` -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: +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/release/2.0.2/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-extension-process-authorization-organization-practitioner-2.0.0.xml). Below is its `differential` element in order to see how the extension needs to be populated: ```xml @@ -407,7 +410,7 @@ Finally, add the `practitionerRole` slice: ``` -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. +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/release/2.0.2/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/CodeSystem/dsf-practitioner-role-2.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 @@ -453,7 +456,7 @@ Look at the [differential](#coding-differential) from the Coding again. The next ``` -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). +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/release/2.0.2/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-extension-process-authorization-2.0.0.xml).
This is how the ActivityDefinition should look like so far @@ -461,6 +464,7 @@ The `requester` extension is now finished and can be added it to the [ActivityDe ```xml + @@ -471,7 +475,7 @@ The `requester` extension is now finished and can be added it to the [ActivityDe - + @@ -498,7 +502,7 @@ The `requester` extension is now finished and can be added it to the [ActivityDe ```
-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/release/2.0.2/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-extension-process-authorization-2.0.0.xml) again. The last slice for this extension is `recipient`: ```xml ... @@ -518,13 +522,13 @@ Back to looking at the [dsf-extension-process-authorization](https://github.com/ - - - + + + - + ... @@ -532,7 +536,7 @@ Back to looking at the [dsf-extension-process-authorization](https://github.com/ ``` -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. +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/release/2.0.2/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-coding-process-authorization-local-organization-2.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 @@ -540,6 +544,7 @@ The `recipient` will decide which DSF instance is allowed to process that messag ```xml + @@ -550,7 +555,7 @@ The `recipient` will decide which DSF instance is allowed to process that messag - + @@ -589,7 +594,7 @@ The `recipient` will decide which DSF instance is allowed to process that messag ```
-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. +The last element defined in the [process authorization extension](https://github.com/datasharingframework/dsf/blob/release/2.0.2/dsf-fhir/dsf-fhir-validation/src/main/resources/fhir/StructureDefinition/dsf-extension-process-authorization-2.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 @@ -606,6 +611,7 @@ The following elements are managed by the DSF BPE: ```xml + @@ -616,7 +622,7 @@ The following elements are managed by the DSF BPE: - + @@ -679,6 +685,7 @@ All other elements can technically be omitted. Still, the following elements are ```xml + @@ -689,7 +696,7 @@ All other elements can technically be omitted. Still, the following elements are - + @@ -730,7 +737,7 @@ All other elements can technically be omitted. Still, the following elements are - + @@ -741,7 +748,7 @@ All other elements can technically be omitted. Still, the following elements are <name value="DSF"/> <telecom> <system value="email"/> - <value value="noreply@dsf.dev"/> + <value value="noreply@example.org"/> </telecom> </contact> <description value="My Process processes information"/> 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 c6e45e0d0..116c11601 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 @@ -9,12 +9,13 @@ Sometimes it is necessary to create custom [CodeSystem](../fhir/codesystem.md) r ```xml <CodeSystem xmlns="http://hl7.org/fhir"> <meta> + <profile value="http://dsf.dev/fhir/StructureDefinition/code-system" /> <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--> + <url value="http://example.org/fhir/CodeSystem/my-code-system" /> <!--dummy value--> <!-- version managed by bpe --> <version value="#{version}" /> <name value="My CodeSystem" /> <!--dummy value--> @@ -42,4 +43,4 @@ Dummy values should be replaced with appropriate values. Elements managed by the 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) +[Adding Task Input Parameters to Task Profiles](adding-task-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-task-resources-based-on-a-definition.md b/docs/src/process-development/api-v2/guides/creating-task-resources-based-on-a-definition.md index 34a1c0092..2a1a4832b 100644 --- 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 @@ -5,139 +5,23 @@ 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> +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). 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. +Like all Task resources created for process plugins, 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) is based on the [DSF's base definition for Task resources](https://dsf.dev/fhir/ImplementationGuide/dev.dsf/StructureDefinition-task.html). This base definition specifies mandatory elements for all Tasks in the DSF. This results in the following base template for all Tasks: ```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"/> + <profile value="http://example.org/fhir/StructureDefinition/my-task|1.0"/> <!-- dummy value --> </meta> - <instantiatesCanonical value="http://dsf.dev/bpe/Process/dicProcess|1.0" /> - <status value="requested"/> + <instantiatesCanonical value="http://example.org/bpe/Process/myProcess|1.0"/> <!-- dummy value --> + <status value="draft"/> <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" /> + <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" /> + <value value="example.org" /> <!-- dummy value --> </identifier> </requester> <restriction> @@ -145,37 +29,10 @@ Filling out all elements in the [Task](../fhir/task.md) resource is now the same <type value="Organization"/> <identifier> <system value="http://dsf.dev/sid/organization-identifier" /> - <value value="dic.dsf.test" /> + <value value="example.org" /> <!-- dummy value --> </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> @@ -183,24 +40,22 @@ This approach however, would not work. FHIR processors do not use the name of th <code value="message-name" /> </coding> </type> - <valueString value="dicProcess" /> + <valueString value="myMessage"/> <!-- dummy value --> </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> +Start out by replacing dummy values with values appropriate for 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): ```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" /> + <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" /> + <authoredOn value="#{date}"/> <requester> <type value="Organization"/> <identifier> @@ -224,13 +79,31 @@ This covers all ways of adding elements. Adding the remaining elements is left a <code value="message-name" /> </coding> </type> - <valueString value="dicProcess"/> + <valueString value="startDicProcess"/> </input> </Task> ``` -</details> +The `profile` will be the StructureDefinition the Task is based on, which in this case is the url of 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) including the version of the plugin that should be targeted. + +The `instantiatesCanonical` value is the same value as the one defined by the StructureDefinition [`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): +```xml +<element id="Task.instantiatesCanonical"> + <path value="Task.instantiatesCanonical" /> + <fixedCanonical value="http://dsf.dev/bpe/Process/dicProcess|#{version}" /> +</element> +``` + +The `requester` element usually holds the identifier of the local organization but may be replaced by the `http://dsf.dev/sid/practitioner-identifier` CodeSystem, `requester.type` with value `Practitioner` and a practitioner identifier while the `recipient` element always holds the identifier of an organization. + +The StructureDefinition [`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) also mandates the string value for the [input](../fhir/task.md#task-input-parameters) to be fixed as `startDicProcess`: +```xml +<element id="Task.input:message-name.value[x]"> + <path value="Task.input.value[x]" /> + <fixedString value="startDicProcess" /> +</element> +``` -**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!** +Depending on the StructureDefinition of the [Task](../fhir/task.md) resource, there may be more [input parameters](../fhir/task.md#task-input-parameters) of varying [FHIR data types](https://hl7.org/fhir/R4/datatypes.html) and including extensions. ## Related Topics [Draft Task Resources](../dsf/draft-task-resources.md), [Task](../fhir/task.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 69f7744db..021c71897 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 @@ -10,12 +10,13 @@ In some cases, it may be necessary to create a [ValueSet](../fhir/valueset.md). ```xml <ValueSet xmlns="http://hl7.org/fhir"> <meta> + <profile value="http://dsf.dev/fhir/StructureDefinition/value-set" /> <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--> + <url value="http://example.org/fhir/ValueSet/my-value-set"/> <!--dummy value--> <!-- version managed by bpe --> <version value="#{version}" /> <name value="My ValueSet"/> <!--dummy value--> @@ -25,12 +26,12 @@ In some cases, it may be necessary to create a [ValueSet](../fhir/valueset.md). <experimental value="false"/> <!-- date managed by bpe --> <date value="#{date}"/> - <publisher value="DSF"/> <!--dummy value--> + <publisher value="My Org"/> <!--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--> + <system value="http://example.org/fhir/CodeSystem/my-code-system"/> <!--dummy value--> <version value="#{version}"/> </include> </compose> @@ -42,14 +43,14 @@ Dummy values should be replaced with appropriate, context-specific values. Eleme ... <compose> <include> - <system value="http://dsf.dev/fhir/CodeSystem/my-code-system"/> + <system value="http://example.org/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"/> + <system value="http://example.org/fhir/CodeSystem/my-other-code-system"/> <version value="#{version}"/> <concept> <code value="my-other-code"/> diff --git a/docs/src/process-development/api-v2/guides/index.md b/docs/src/process-development/api-v2/guides/index.md index 2841de106..929e31116 100644 --- a/docs/src/process-development/api-v2/guides/index.md +++ b/docs/src/process-development/api-v2/guides/index.md @@ -6,12 +6,11 @@ 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) +- [Adding Task Input Parameters to Task Profiles](adding-task-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 index a0cf72993..ce92b3322 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 @@ -19,4 +19,4 @@ An [Event Based Gateway](../bpmn/gateways.md#event-based-gateway) can be used to ## Related Topics -[Gateways](../bpmn/gateways.md), [Message Correlation](../dsf/message-correlation.md), [Message Delegates](../dsf/message-delegates.md) \ No newline at end of file +[Gateways](../bpmn/gateways.md), [Message Correlation](../dsf/message-correlation.md), [Message Activities](../dsf/message-activities.md) \ No newline at end of file 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 deleted file mode 100644 index 6d4156962..000000000 --- a/docs/src/process-development/api-v2/guides/setting-targets-for-message-events.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -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) 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 c13bee63b..e763a90b0 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-plugin-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://example.org/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). @@ -21,13 +21,13 @@ Below is a template for a [Questionnaire](https://www.hl7.org/fhir/R4/questionna ```xml <Questionnaire xmlns="http://hl7.org/fhir"> <meta> - <profile value="http://dsf.dev/fhir/StructureDefinition/questionnaire|1.5.0"/> + <profile value="http://dsf.dev/fhir/StructureDefinition/questionnaire"/> <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 --> + <url value="http://example.org/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 -->