fixed broken links

Author: Simon Schweizer

docs/src/process-development/api-v2/bpmn/conditions.md

@@ -0,0 +1,8 @@
+---
+title: Conditions
+icon: creative
+---
+
+### Conditions
+
+[Conditions](https://docs.camunda.org/manual/7.21/user-guide/process-engine/expression-language/#conditions) allow you to change the behaviour of BPMN processes during execution. There are two ways you are able to add decision logic to Conditions. The [Camunda Modeler](https://camunda.com/download/modeler/) refers to them as `Type`. You can find them in the ``Condition`` tab of certain BPMN elements. The first one is `Script`. This allows you to add arbitrary complexity to your decisions logic and is rarely used for process plugins. The more common Type is `Expression`. Expressions have the following syntax: `${expression}`. An example of a simple expression would be a boolean condition like `var == true`. For this to work during BPMN process execution, the variable you want to use for the boolean condition must be available in the BPMN process variables before [Sequence Flow](sequence-flow.md) reaches the evaluation of the expression. You can learn more advanced features of Expressions [here](https://docs.camunda.org/manual/7.21/user-guide/process-engine/expression-language/).

docs/src/process-development/api-v2/bpmn/gateways.md

@@ -0,0 +1,16 @@
+---
+title: Gateways
+icon: creative
+---
+
+### Gateways
+
+[Gateways](https://docs.camunda.org/manual/7.21/reference/bpmn20/gateways/) allow you to control the [Sequence Flow](sequence-flow.md). Different types of gateways are useful for different scenarios.
+
+#### Exclusive Gateways
+
+[Exclusive Gateways](https://docs.camunda.org/manual/7.21/reference/bpmn20/gateways/exclusive-gateway/) allow you to decide which [Sequence Flow](sequence-flow.md) should be followed based on [conditions](https://docs.camunda.org/manual/7.21/user-guide/process-engine/expression-language/#conditions). [Conditions](https://docs.camunda.org/manual/7.21/user-guide/process-engine/expression-language/#conditions) are not part of the [Exclusive Gateways](https://docs.camunda.org/manual/7.21/reference/bpmn20/gateways/exclusive-gateway/) themselves. You set them through the sequence flow exiting the [Exclusive Gateway](https://docs.camunda.org/manual/7.21/reference/bpmn20/gateways/exclusive-gateway/).  In the [Camunda Modeler](https://camunda.com/download/modeler/), you can add conditions to [Sequence Flow](sequence-flow.md) by selecting a [Sequence Flow](sequence-flow.md) and opening the `Condition` tab. You can find more information on how to use Conditions [here](conditions.md).
+
+#### Event-based Gateway
+
+The [Event-based Gateway](https://docs.camunda.org/manual/7.21/reference/bpmn20/gateways/event-based-gateway/) allows you model scenarios where you are expecting one out of a number of events to occur. 

docs/src/process-development/api-v2/bpmn/index.md

@@ -0,0 +1,15 @@
+---
+title: BPMN
+icon: creative
+---
+
+## Introduction
+The DSF uses BPMN 2.0 to model processes. Specifically, the [Camunda 7](https://docs.camunda.org/manual/7.21/) dialect from the [Camunda Modeler](https://camunda.com/de/download/modeler/). Modeling processes for the DSF requires this modeler or any other modeler which is able to produce the correct Camunda dialect.
+
+## Details
+- [Conditions](conditions.md)
+- [Gateways](gateways.md)
+- [Messaging](messaging.md)
+- [Sequence Flow](sequence-flow.md)
+- [Service Tasks](service-tasks.md)
+- [Timer Intermediate Catching Events](timer-intermediate-catching-events.md)

docs/src/process-development/api-v2/bpmn/messaging.md

@@ -0,0 +1,24 @@
+---
+title: Messaging
+icon: creative
+---
+
+
+### Messaging
+
+In order to enable communication with other lanes, pools or even entirely separate processes you need to be able to exchange information. In BPMN, you can use [Message Events](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/message-events/) to model this information exchange. Modeling communication with [Message Events](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/message-events/) in the same diagram uses Message Flow. Message Flow is typically represented by a dashed line arrow between BPMN elements with a black (send) or white (receive) envelope icon. The following BPMN collaboration diagram shows message exchange between two processes.
+
+![BPMN collaboration diagram with two processes using message flow to exchange information between two organizations](/photos/developer-documentation/message_flow.svg)
+
+#### Message Start Event
+
+[Message Start Events](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/message-events/#message-start-event) allow a BPMN process to be started by an incoming message. In the DSF, all BPMN processes are started via messages. Therefore, you will have to include a [Message Start Event](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/message-events/#message-start-event) at the beginning of all of your BPMN models.
+
+#### Message Intermediate Throwing Event
+[Message Intermediate Throwing Events](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/message-events/#message-intermediate-throwing-event) are used to send messages during process execution.
+
+#### Message Intermediate Catching Event
+[Message Intermediate Catching Events](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/message-events/#message-intermediate-catching-event) serve as the counterpart to [Message Intermediate Throwing Events](messaging.md#message-intermediate-throwing-event). Use them whenever you expect to receive a message from another process or organization during execution.
+
+#### Message End Event
+The [Message End Event](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/message-events/#message-end-event) will stop the execution of a BPMN process and finish by sending a message.

docs/src/process-development/api-v2/bpmn/sequence-flow.md

@@ -0,0 +1,7 @@
+---
+title: Sequence Flow
+icon: creative
+---
+
+### Sequence Flow
+BPMN 2.0 calls the continuous arrows connecting the BPMN elements in BPMN models, Sequence Flow. Sequence Flow exits one BPMN element and points at the next BPMN element to be processed.

docs/src/process-development/api-v2/bpmn/service-tasks.md

@@ -0,0 +1,8 @@
+---
+title: Service Tasks
+icon: creative
+---
+
+### Service Tasks
+
+One of the most common types of BPMN Tasks used for modeling DSF processes is the [Service Task](https://docs.camunda.org/manual/7.21/reference/bpmn20/tasks/service-task/). They are different from regular BPMN Tasks in that they offer the ability to link an implementation to the [Service Task](https://docs.camunda.org/manual/7.21/reference/bpmn20/tasks/service-task/) which can be called and executed by a BPMN engine. The BPE (Business Process Engine) server of the DSF leverages this engine to execute your BPMN processes.

docs/src/process-development/api-v2/bpmn/timer-intermediate-catching-events.md

@@ -0,0 +1,8 @@
+---
+title: Timer Intermediate Catching Events
+icon: creative
+---
+
+### Timer Intermediate Catching Events
+
+A [Timer Intermediate Catching Event](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/timer-events/#timer-intermediate-catching-event) allows you to model stopwatch behavior. A timer is started once the BPMN execution arrives at the event. The duration until the timer runs out is specified using the [ISO 8601 Durations](http://en.wikipedia.org/wiki/ISO_8601#Durations) format. Examples can be found [here](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/timer-events/#time-duration). After running out, the BPMN process executes the [Sequence Flow](sequence-flow.md) following the [Timer Intermediate Catching Event](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/timer-events/#timer-intermediate-catching-event).

docs/src/process-development/api-v2/bpmn/user-tasks.md

@@ -0,0 +1,8 @@
+---
+title: User Tasks
+icon: creative
+---
+
+### User Tasks
+
+User Tasks define a process step that requires some kind of human interaction. Usually this is done by providing some kind of form the user can fill out. The Camunda Modeler allows to configure these forms as either a propriatary format called [Camunda Forms](https://docs.camunda.io/docs/guides/utilizing-forms/) or custom forms called `Embedded or External Task Forms`. The DSF uses such `External Task Forms` in the form of [Questionnaire](https://www.hl7.org/fhir/R4/questionnaire.html) and [Questionnaire Response](https://www.hl7.org/fhir/R4/questionnaireresponse.html) resources. This mechanism is further expanded upon in [User Tasks in the DSF](../guides/user-tasks-in-the-dsf.md).

docs/src/process-development/api-v2/dsf/bpmn-process-execution.md

@@ -0,0 +1,8 @@
+---
+title: BPMN Process Execution
+icon: creative
+---
+
+### BPMN Process Execution
+
+The BPMN process execution is the in-memory representation of a running BPMN process. BPMN processes have their executions structured as a tree hierarchy. Each BPMN process starts with the [process instance](https://docs.camunda.org/manual/7.21/user-guide/process-engine/process-engine-concepts/#process-instances) as its root level execution. If, for example, this root execution reaches a parallel gateway with two paths, it would spawn two child executions under itself for them to process all tasks along their paths on their own. Executions can access all the BPMN elements from the BPMN model as well as the [BPMN process variables](bpmn-process-variables.md). You have access to this representation in your Java code through the `execution` parameter when overriding certain methods in [Service](service-delegates.md) / [Message](message-delegates.md) Delegates like `execute` or `getAdditionalInputParameters` through the `variables` parameter.

docs/src/process-development/api-v2/dsf/bpmn-process-variables.md

@@ -0,0 +1,10 @@
+---
+title: BPMN Process Variables
+icon: creative
+---
+
+### BPMN Process Variables
+
+BPMN process variables hold additional information which has to be available during BPMN process execution. Variables can be directly related to BPMN elements like the boolean value for [Conditions](../bpmn/conditions.md), but do not have to be. BPMN process variables are stored as key-value pairs with the key being the variable name. They are accessible during the entirety of the execution to all [Service](service-delegates.md) / [Message](message-delegates.md) Delegates.
+
+You can learn how to access to the BPMN process variables [here](../guides/accessing-bpmn-process-variables.md).

docs/src/process-development/api-v2/dsf/draft-task-resources.md

@@ -0,0 +1,21 @@
+---
+title: Draft Task Resources
+icon: creative
+---
+
+### Draft Task Resources
+
+[Task](../fhir/task.md) resources with status `draft` are used to create the DSF FHIR server's functionality of starting processes via its web interface. They are stored in `.../tutorial-process/src/main/resources/fhir/Task`. Compared to regular [Task](../fhir/task.md) resources used to start BPMN processes, this type of [Task](../fhir/task.md) resource requires the status `draft` instead the usual `requested`. It also replaces the value for `authoredOn` with the placeholder `#{date}`, the values of organization identifiers with the placeholder `#{organization}` and all instances of version numbers with `#{version}`. Additionally, it requires setting the `Task.identifier` element. It should look something like this:
+
+```xml
+<identifier>
+     <system value="http://dsf.dev/sid/task-identifier" />
+     <value value="http://dsf.dev/bpe/Process/processKey/#{version}/task-name" />
+</identifier>
+```
+`processKey` should be the same one used in [URLs](versions-placeholders-urls.md#urls).  
+`task-name` can be any String you wish to identify this task with. E.g. you can use the file name of the Draft Task.
+
+For a complete example you can take a look at the Draft Task Resource in one of the solution branches and compare it to the one needed for cURL. The [Task](../fhir/task.md) resource created for cURL can be found at `.../tutorial-process/src/main/resources/example-task.xml`.
+
+You might also want to check out [this guide](../guides/creating-task-resources-based-on-a-definition.md) if you do not know how to create [Task](../fhir/task.md) resources in general.

docs/src/process-development/api-v2/dsf/environment-variables.md

@@ -0,0 +1,10 @@
+---
+title: Environment Variables
+icon: creative
+---
+
+### Environment Variables
+
+Environment variables offer a way to make configuration data available at the start of a [BPMN process execution](bpmn-process-execution.md). They are the same for all running process instances. They can be defined by adding a member variable with the [Spring-Framework @Value](https://docs.spring.io/spring-framework/docs/current/reference/html/core.html#beans-value-annotations) annotation to the configuration class `TutorialConfig`. The value of the annotation uses the `${..}` notation and follows the form `${some.property:defaultValue}`, where each dot in the property name corresponds to an underscore in the equivalent environment variable. Environment variables are always written upper-case. The property `some.property` therefore corresponds to the environment variable `SOME_PROPERTY`.
+
+The DSF provides a feature to automatically generate documentation of environment variables during the Maven build process. You can use the `@ProcessDocumentation` annotation to automatically generate Markdown documentation for all fields with this annotation. You simply have to add [dsf-tools-documentation-generator](https://mvnrepository.com/artifact/dev.dsf/dsf-tools-documentation-generator) as a maven plugin. You can take a look at the `pom.xml` for the `tutorial-process` submodule [here](https://github.com/datasharingframework/dsf-process-tutorial/blob/main/tutorial-process/pom.xml) to see how you can add it to your own project. Keep in mind to point the `<workingPackage>` field to the package you want documentation for.

docs/src/process-development/api-v2/dsf/index.md

@@ -0,0 +1,20 @@
+---
+title: DSF
+icon: creative
+---
+
+## Details
+- [BPMN Process Execution](bpmn-process-execution.md)
+- [BPMN Process Variables](bpmn-process-variables.md)
+- [Draft Task Resources](draft-task-resources.md)
+- [Environment Variables](environment-variables.md)
+- [Message Correlation](message-correlation.md)
+- [Message Delegates](message-delegates.md)
+- [Organization Identifiers](organization-identifiers.md)
+- [Process Plugin API](process-plugin-api.md)
+- [Process Plugin Definition](process-plugin-definition.md)
+- [Read Access Tag](read-access-tag.md)
+- [Requester and Recipient](requester-and-recipient.md)
+- [Service Delegates](service-delegates.md)
+- [Spring Framework Integration](spring-framework-integration.md)
+- [Versions, Placeholders and URLs](versions-placeholders-urls.md)

docs/src/process-development/api-v2/dsf/message-correlation.md

@@ -0,0 +1,10 @@
+---
+title: Message Correlation
+icon: creative
+---
+
+### Message Correlation
+
+In order for messages to be able to be sent back and forth between organizations with potentially multiple of the same process plugin instances running at the same time and still arriving at the correct process instance, we need some mechanism to map messages to their rightful process instance. This mechanism is called Message Correlation and requires attaching a unique identifier to every process instance. This identifier is called the `business-key`. The `business-key` will get attached to every outgoing message automatically.
+
+It is possible that the `business-key` is insufficient to map messages to the correct process instance. This happens when you use subprocesses in your BPMN model which all expect messages to be sent to them, not the parent process. To solve this issue, [Task](../fhir/task.md) resources also come with an [Input Parameter](../fhir/task.md#task-input-parameters) called `correlation-key`. This is a secondary identifier you can attach to all messages if you need them to arrive at a specific subprocess. You can learn more about how `correlation-keys` are used by studying the [Ping-Pong Process](https://github.com/datasharingframework/dsf-process-ping-pong).

docs/src/process-development/api-v2/dsf/message-delegates.md

@@ -0,0 +1,15 @@
+---
+title: Message Delegates
+icon: creative
+---
+
+### Message Delegates
+
+Message Delegates are the Java representation of the [Message Events](../bpmn/messaging.md) in your BPMN model. You link a Message Delegate to a certain [Message Event](../bpmn/messaging.md) by selecting the Message Event in the [Camunda Modeler](https://camunda.com/download/modeler/) and adding a Java class to the `Implementation` field. Make sure you use the fully qualified class name. Like this:
+```
+org.package.myClass
+```
+
+You will only need Message Delegates for [Message Send Events](../bpmn/messaging.md). Incoming messages will be resolved to the correct [BPMN process execution](bpmn-process-execution.md) automatically using [Message Correlation](message-correlation.md) and the message inputs will be added to that execution's [process variables](bpmn-process-variables.md).
+
+To make a Message Delegate for [Message Send Events](../bpmn/messaging.md), your Java class needs to extend `AbstractTaskMessageSend`. Most of the time, you will not be adding any processing logic to your Message Delegates, therefore you usually won't be overwriting the `doExecute` method like with [Service Delegates](service-delegates.md). Instead, you most likely want to aggregate the information you processed in earlier steps and attach it to a message. For this you need to overwrite the `getAdditionalInputParamters` method. The DSF translates BPMN messages into FHIR [Task](../fhir/task.md) resources to execute the communication modeled by your BPMN diagrams. The information you are sending to another BPMN process is specified in the Task.input elements a.k.a. [Input Parameters](../fhir/task.md#task-input-parameters), hence the name of the method. The constructor of your delegate class should also forward a `ProcessPluginApi` instance to its superclass constructor. You can learn more about the `ProcessPluginApi` [here](process-plugin-api.md).

docs/src/process-development/api-v2/dsf/organization-identifiers.md

@@ -0,0 +1,10 @@
+---
+title: Organization Identifiers
+icon: creative
+---
+
+### Organization Identifiers
+DSF FHIR server instances always have something called an `organization identifer`. It uniquely identifies the organization the DSF FHIR server instance belongs to for its [Allow-List mechanism](https://dsf.dev/intro/info/allowList.html). It is configured as an [environment variable](https://dsf.dev/stable/maintain/fhir/configuration.html#dev-dsf-fhir-server-organization-identifier-value). You can make a GET request to `https://domain/fhir/Organization` to get a list of all organizations for the DSF FHIR server instance running under `domain`. The results will also include the `organization identifier` of each organization.  
+
+#### Organization Identifiers in Task Resources
+[Task](../fhir/task.md) resources require you to reference an organization via its identifier as the `Task.requester` and `Task.restriction.recipient` elements. The exact values for these elements depend on the [ActivityDefinition](../fhir/activitydefinition.md) the [Task](../fhir/task.md) resource should conform to. As a general rule, you will want to put the identifier of your own organization as the `Task.requester` and `Task.restriction.recipient` elements for [Task](../fhir/task.md) resources which initially start processes. All other cases depend on the context of the message being sent during process execution.