README.md

# Stock Asset Review
> **_BPT - Assignment 3:_**  Partly automated Workflows with Camunda 

## Table of Contents
1. [Set up Application](#set-up-application)
2. [Set up Camunda Modeler](#set-up-camunda-modeler)
3. [Claim API Key](#claim-api-key)
4. [Create Process](#create-process)
5. [Run Application (MAVEN)](#run-application-maven)
6. [Run Application (DOCKER)](#run-application-docker)
6. [How to use Application](#how-to-use-application)

## Set up Application
Camunda Spring Boot Application created with [Camunda Platform Initializr].
| Settings | Version |
| ------ | ------ |
| Camunda Platform Version | 7.16.0 |
| Spring Boot Version | 7.5.4 |
| Java Version | 11 |

| Dependencies | 
| ------ | 
| REST API |
| Webapps | 
| Spin (XML & JSON) |

| Credentials | Value |
| ------ | ------ | 
| Admin Username | demo |
| Admin Password | demo |

### Additional Dependencies
Also added [GSON] dependency for parsing JSON objects to `pom.xml`. 
> **_INFO:_**  Required new clean build to include the GSON JAR file automatically to the classpath of the application.

```sh
<dependency>
      <groupId>com.google.code.gson</groupId>
      <artifactId>gson</artifactId>
      <version>2.8.4</version>
</dependency>
```
> **_INFO:_**  Used version `2.8.4`, because other failed with spring boot.

### Additional Settings
Enabled process application to disables the `SpringProcessEngineConfiguration` auto-deploy feature. 
> **_INFO:_**  Without `@EnableProcessApplication` using embedded forms always failed.

```sh
@EnableProcessApplication
```

### IDE
Used development enviroment is [Visual Studio Code].
 - Version `1.62.3`

## Set up Camunda Modeler
Downloaded [Camunda Modeler], unziped the file and ran `Camunda Modeler.exe`.
 - Version `4.11.1`

## Claim API Key
Got free [Alpha Vantage] API Key:
> **_KEY:_**  VPNHOQPE0AOJ8BEP

## Create Process
Created camunda BPMN process as described in [BPT Moodle Course]. 
- Start Event
  - End of month as manually triggered Start-Event
- First User Task
  - User enters into a dialog (HTML form: [company_form.html]) a company name, of which their company own stocks. 
  - The step stores the name in a process variable `stock`.
- First Service Task
  - System queries a REST-WebService at https://www.alphavantage.co/query?function=SYMBOL_SEARCH&keywords=IBM&apikey=VPNHOQPE0AOJ8BEP 
    - The Search Endpoint for `stock`. 
  - The step stores the resulting symbol in a process variable `symbol`.
  - Used the `Java Delegate` class for implementation.
    - Connecting the delegate class [SymbolSearchDelegate.java] with the service task takes place selecting `Java Class` instead of `Expression` and entering the full classpath.
- Second Service Task
  - System queries a REST-WebService at https://www.alphavantage.co/query?function=GLOBAL_QUOTE&symbol=IBM&apikey=VPNHOQPE0AOJ8BEP
    - The Quote Endpoint stores the current price in a process variable `price` and the change in a process variable `change`.
  - Used the `Java Delegate` class for implementation.
    - Connecting the delegate class [GlobalQuoteDelegate.java] with the service task takes place selecting `Java Class` instead of `Expression` and entering the full classpath.
- Gateway
  - Gateway decides by price and change for a sell recommendation 
    - if `price<1 and change negative`, the system should execute the second user task.
    - else, the system leads to second end event
- Second User Task
  - System displays to the user a dialog (HTML form: [sell_form.html]) with `symbol`, `price`, `change` and a button `Sell` and a button `Cancel`.
  - There are no functions implemented for the buttons!
- First End Event
  - The process terminates.
- Second End Event
  - The process terminates.
  - Set to `default` sequence flow.

### BPMN Process
Saved process model in application resource folder: [process.bpmn].
![process][process]

## Run Application (MAVEN)
Clone Repository:
```sh
git clone https://transfer.hft-stuttgart.de/gitlab/kebidge/stock-asset-review.git
```
Build Application:
```sh
mvn clean install
```
Run Spring-Boot Application:
```sh
mvn spring-boot:run
```
Application starts on port `9999`. Open in Browser:
```sh
localhost:9999
```

## Run Application (DOCKER)
Run Docker Image
```sh
docker run -p 9999:9999 kebidge/stock-asset-review:jib
```
> **_INFO:_**  Do not run container in detached mode! Otherwise you will not see application logs.

Application starts on port `9999`. Open in Browser:
```sh
localhost:9999
```

### Image Details
Type: [Google Jib]\
Size: `302MB`\
Compressed Size: `133.38MB`\
OS/ARCH: `linux/amd64`

| Description | Size | Comment |
| ------ | ------ | ------ | 
| jib-maven-plugin:3.1.4  | 4.32kB | jvm arg files | 
| jib-maven-plugin:3.1.4  | 2.38kB | classes | 
| jib-maven-plugin:3.1.4  | 3.06kB | resources | 
| jib-maven-plugin:3.1.4  | 57.7MB | dependencies | 
| /bin/sh -c #(nop)  ENV JAVA_HOME=/opt/java/o… | 0B |  | 
| /bin/sh -c set -eux;     ARCH="$(dpkg --prin… | 128MB |  | 
| /bin/sh -c #(nop)  ENV JAVA_VERSION=jdk-11.0… | 0B |  | 
| /bin/sh -c apt-get update     && apt-get ins… | 43.2MB |  | 
| /bin/sh -c #(nop)  ENV LANG=en_US.UTF-8 LANG… | 0B |  | 
| /bin/sh -c #(nop)  CMD ["bash"] | 0B |  | 
| /bin/sh -c #(nop) ADD file:8d2f4a45a58b3f542… | 72.8MB |  | 


## How to use Application
### Use Real Data
##### Login to Camunda Platform:
| Username | Password |
| ------ | ------ | 
| demo | demo |

##### Open `Tasklist` and start new process:
![start-new-process][start-new-process]
##### Select `Stock Review Process`:
![select-process][select-process]
##### Start `Stock Review Process`:
![start-process][start-process]
##### Refresh Website and click on appeared user task `Set Company Name`:
![view-process][view-process]
##### Switch to `Cockpit` view and click on `Running Process Instances`:
![cockpit][cockpit]
##### Select `Stock Review Process`:
![select-running-process][select-running-process]
##### Process stops at `UserTask_1` as expected:
![show-user-task-1][show-user-task-1]
##### Now go back to `Tasklist` view, set value (e.g. `IBM`), first click on `Save` and afterwards on `Complete`: 
![complete-user-task-1][complete-user-task-1]
> **_INFO:_**  After completing the user task `Set Company Name` the process `Stock Review Process` ends. Usually the requested stock price will be greater than `1.0`, so the process will not run into second user task `Sell Stock`. To see second user task run application with the help of dummy data!

##### Take a look at the application logs:
![real-data-logs][real-data-logs]

### Use Dummy Data
> **_INFO:_** Force second user task `Sell Stock` with the help of dummy data.

##### Disable real data! Comment out line 125 and line 126 of `GlobalQuoteDelegate` class.
![disable-real-data][disable-real-data]

##### Build, run and open application in browser! Then do same steps as in the case of [Use Real Data](#use-real-data):
 - Login to Camunda Platform
 - Open `Tasklist` and start new process
 - Select `Stock Review Process`
 - Start `Stock Review Process`
 - Refresh Website and click on appeared user task `Set Company Name`
 - Switch to `Cockpit` view and click on `Running Process Instances`
 - Select `Stock Review Process`
 - Process stops at `UserTask_1` as expected
 - Now go back to `Tasklist` view, set value (e.g. `IBM`), first click on `Save` and afterwards on `Complete`

##### After completing `UserTask_1` the system runs both service tasks and stops at `UserTask_2` as expected. Take a look in `Cockpit` view:
![show-user-task-2][show-user-task-2]
##### Go back to `Tasklist` view, review the stock data (`stock`, `price` and `change`) and complete the task by clicking on `Complete`:
![complete-user-task-2][complete-user-task-2]
> **_INFO:_** Buttons `Sell` and `Cancel` are not implemented.

##### Take a look at the application logs:
![dummy-data-logs][dummy-data-logs]


[//]: # (reference links)

   [Camunda Platform Initializr]: <https://start.camunda.com/>
   [GSON]: <http://tutorials.jenkov.com/java-json/gson-installation.html>
   [Visual Studio Code]: <https://code.visualstudio.com/download>
   [Camunda Modeler]: <https://camunda.com/download/modeler/>
   [Alpha Vantage]: <https://www.alphavantage.co/support/#api-key>
   [company_form.html]: <https://transfer.hft-stuttgart.de/gitlab/kebidge/stock-asset-review/-/blob/master/src/main/resources/static/forms/company_form.html>
   [BPT Moodle Course]: <https://moodle.hft-stuttgart.de/course/view.php?id=1192#section-3>
   [SymbolSearchDelegate.java]: <https://transfer.hft-stuttgart.de/gitlab/kebidge/stock-asset-review/-/blob/master/src/main/java/de/kebidge/camunda/SymbolSearchDelegate.java>
   [GlobalQuoteDelegate.java]: <https://transfer.hft-stuttgart.de/gitlab/kebidge/stock-asset-review/-/blob/master/src/main/java/de/kebidge/camunda/GlobalQuoteDelegate.java>
   [sell_form.html]: <https://transfer.hft-stuttgart.de/gitlab/kebidge/stock-asset-review/-/blob/master/src/main/resources/static/forms/sell_form.html>
   [process.bpmn]: <https://transfer.hft-stuttgart.de/gitlab/kebidge/stock-asset-review/-/blob/master/src/main/resources/process.bpmn>
   [Google Jib]: <https://cloud.google.com/java/getting-started/jib>
   [process]: assets/process.png "BPMN process"
   [start-new-process]: assets/real-data_01_start-process.png "start new process"
   [select-process]: assets/real-data_02_select-process.png "select process"
   [start-process]: assets/real-data_03_start.png "start selected process"
   [view-process]: assets/real-data_04_view-process.png "view process"
   [cockpit]: assets/real-data_05_cockpit.png "cockpit"
   [select-running-process]: assets/real-data_06_select-running-process.png "select running process"
   [show-user-task-1]: assets/real-data_07_show-running-process.png "show user task 1"
   [complete-user-task-1]: assets/real-data_08_complete-process.png "complete user task 1"
   [real-data-logs]: assets/real-data_09_logs.png "application real data logs"
   [disable-real-data]: assets/dummy-data_01_disable-real-data.png "disable real data"
   [show-user-task-2]: assets/dummy-data_02_show-user-task2.png "show user task 2"
   [complete-user-task-2]: assets/dummy-data_03_complete-user-task2.png "complete user task 2"
   [dummy-data-logs]: assets/dummy-data_04_logs.png "application dummy data logs"