Skip to content

exercise-2.md

Latest commit

 

History

History
115 lines (84 loc) · 9.29 KB

exercise-2.md

File metadata and controls

115 lines (84 loc) · 9.29 KB

Prerequisites • Exercise 0 • Exercise 1 • Exercise 1.1 • Exercise 2 • Exercise 3 • Exercise 4 • Exercise 5 • Exercise 6 • Exercise 7

Exercise 2 - Environment Variables and Input Parameters

In this exercise you will pass additional information into a running process in two different ways: via an environment variable (configured outside the process, at deployment time) and via a FHIR Task Input Parameter (supplied at the start of every process).

Both values will be accessible inside the execute method of your DicTask service class.

Solutions to this exercise are found on the branch solutions/exercise-2.

Background reading (documentation links for this exercise)

Exercise Tasks

  1. Add a new boolean variable to the TutorialConfig class. It will enable/disable logging and have its value injected from an environment variable. Add the annotation and specify the default value as false. You may freely choose a name for your environment variable here. Just make sure you follow the naming convention explained in Environment Variables.

  2. Modify the constructor of the DicTask class to use the newly created variable. Don't forget to change the DicTask bean in TutorialConfig. If you previously registered it through ActivityPrototypeBeanCreator you now have to register it as a separate Bean because ActivityPrototypeBeanCreator can only create beans through default constructors (scope has to be prototype).

    Don't know how to register prototype beans?

    Take a look at the documentation on Spring Integration.

  3. Use the value of the environment variable in the DicTask class to decide whether the log message from exercise 1 should be printed.

  4. Add the new environment variable to the dic-bpe service in dev-setup/docker-compose.yml and set the value to "true".

  5. Create a new CodeSystem with url http://example.org/fhir/CodeSystem/tutorial having a concept with code tutorial-input and name the file tutorial.xml. Don't forget to add the read-access-tag.

    Don't know how to create a CodeSystem?

    Check out this guide.

    Don't know where to put the CodeSystem?

    tutorial-process/src/main/resources/fhir/CodeSystem.

  6. Create a new ValueSet with url http://example.org/fhir/ValueSet/tutorial that includes all concepts from the CodeSystem and name the file tutorial.xml. Don't forget to add the read-access-tag.

    Don't know how to create a ValueSet?

    Check out this guide.

    Don't know where to put the ValueSet?

    tutorial-process/src/main/resources/fhir/ValueSet.

  7. Add a new input parameter of type tutorial-input with Task.input.value[x] as a string to the StructureDefinition profile file tutorial-process/src/main/resources/fhir/StructureDefinition/task-start-dic-process.xml.

    Note: The task-start-dic-process.xml exists both under the StructureDefinition and Task directories under resources. In terms of Object Oriented Programming, the StructureDefinition is the class and the Task resource is an instance.

    Don't know how to add a new input parameter?

    Check out this guide.

  8. Make sure the return value for TutorialProcessPluginDefinition#getFhirResourcesByProcessId also includes the new CodeSystem and ValueSet resources for the exampleorg_dicProcess. The process exampleorg_dicProcess now requires these additional FHIR resources because task-start-dic-process references them — without registering them here, the DSF BPE server will reject the StructureDefinition (and thus process deployment) because it can't find the resources referenced in it.

  9. Read the new input parameter in the DicTask class from the start Task and add the value to the log message from exercise 1.

    Don't know how to get the input parameter?

    The TaskHelper instance will prove useful here. Use it in conjunction with variables to get the right Task resource from the BPMN process execution.

  10. We just changed the elements a Task resource has to include. So you need to change example-task.xml for cURL or Task/task-start-dic-process.xml, if you want to use the web interface, to include the new input parameter. The actual value may be any arbitrary string. This also means that we need to change the plugin version, since a Task made according to the old StructureDefinition won't be valid for processes still expecting the old StructureDefinition. The new resource version shall be 1.1. If your ProcessPluginDefinition implementation is implementing the ProcessPluginDefinition interface, you have to change the version in both the getVersion method of your ProcessPluginDefinition and the pom.xml file of the tutorial-process module. If your implementation is inheriting from AbstractProcessPluginDefinition and has a plugin.properties file configured at the resource root with the version=${project.version} entry, changing the version in the pom.xml is sufficient. The latter way is recommended.

Solution Verification

Maven Build and Automated Tests

Execute a maven build of the dsf-process-tutorial parent module via:

mvn clean install -Pexercise-2

Verify that the build was successful and no test failures occurred.

Process Execution and Manual Tests

To verify the exampleorg_dicProcess can be executed successfully, we need to deploy it into a DSF instance and execute the process. The maven install build is configured to create a process jar file with all necessary resources and copy the jar to the appropriate locations of the docker dev setup.

  1. Start the DSF FHIR server for the dic.dsf.test organization in a console at location .../dsf-process-tutorial/dev-setup:

    docker compose up dic-fhir

    Verify the DSF FHIR server started successfully at https://dic/fhir.

  2. Start the DSF BPE server for the dic.dsf.test organization in second console at location .../dsf-process-tutorial/dev-setup:

    docker compose up dic-bpe

    Verify the DSF BPE server started successfully and deployed the exampleorg_dicProcess.

  3. Start the exampleorg_dicProcess by posting an appropriate FHIR Task resource to the DSF FHIR server of the dic.dsf.test organization using either cURL or the DSF FHIR server's web interface. Check out Starting A Process Via Task Resources again if you are unsure.

    Verify that the exampleorg_dicProcess was executed by the DSF BPE server. The BPE server should:

    • Print a message showing that the process was started.
    • If logging is enabled - print the log message and the value of the input parameter you added to the DicTask implementation.
    • Print a message showing that the process finished.

Check that you can disable logging of your message by modifying the docker-compose.yml file and configuring your environment variable with the value "false" or removing the environment variable.
Note: Changes to environment variable require recreating the docker container.

Prerequisites • Exercise 0 • Exercise 1 • Exercise 1.1 • Exercise 2 • Exercise 3 • Exercise 4 • Exercise 5 • Exercise 6 • Exercise 7