Vacation requests

Vacation requests example illustrates the human centric use case combined with data base records use case. Vacation requests are placed by individual employees and are automatically tracked as complete set of requests. This enables clear visibility from employee point of view to see all his/her requests regardless of their status. It also keeps track of how many days are used and still eligible for further use.

At he same time, vacation requests require approval by manager and thus a tasks are assigned to employee’s manager on each newly submitted vacation request.

Employee has an option to cancel request as long as the date when the vacation should start has not been reached yet.

examples vacation

This service also allows to onboard new employees by assigning eligible vacation days and a manager based on department employee is in.

As part of onboarding following will take place directly:

calculate eligible vacation days
assign manager

Above data is derived from decision tables that look as follows

Table 1. Assign manager
Manager	Department
john@email.com	finance
mary@email.com	it
joe@email.com	hr

Table 2. Vacation days eligibility
Year of start	Number of days
< 2000	25
< 2010	20
< 2015	18
< 2015	10

Note that this example is currently not equipped with user facing UI

Run it

This example is self container for simplicity meaning it uses H2 data base so there is no need for additional components to run this example.

docker run -p 8080:8080 automatiko/vacation-requests

Alternatively there is also a option to run this service with email notifications enabled. This requires some extra environment variables to be set when starting the container

docker run -p 8080:8080 -e QUARKUS_PROFILE=withemail -e EMAIL_TO=TO -e EMAIL_FROM=FROM -e EMAIL_HOST=HOST -e EMAIL_PORT=PORT -e EMAIL_USER=USER -e EMAIL_PASSWORD=PASSWORD automatiko/vacation-requests

You need to set following environment variables with proper email server data

Table 3. Environment variables for email notifications
Name	Value	Example
EMAIL_TO	email address where all notifications should be sent to	user@gmail.com
EMAIL_FROM	email address the the emails are sent from	user@gmail.com
EMAIL_HOST	host name of SMTP server	smtp.gmail.com
EMAIL_PORT	port number of SMTP server	587
EMAIL_USER	username to be used to authenticate on SMTP server	user@gmail.com
EMAIL_PASSWORD	password to be used to authenticate on SMTP server	secret_password

With above configuration email notifications for user tasks are going to be sent out. Using default template for email addresses that will look like this

once this is done you can see the fully described service at http://localhost:8080/swagger-ui/#/

You can open your browser http://localhost:8080/management/processes/ui to visualize your running service

There are multiple paths that can be taken during given order

First top level (public) workflow defines the onboarding and overall tracking for every employee - every instance is identified as employee’s email

Second workflow is responsible for managing individual requests for a given employee, from the submission to either cancelation or its start date.

Authorization

This service is fully secured and requires authentication to be able to interact with it. Below table represents available users in the service

Table 4. Users available
User name	Password	Roles
john@email.com	john	employee
mary@email.com	mary	employee
mark@email.com	mark	employee
joe@email.com	joe	employee
admin@email.com	admin	admin

There is also instance level security that is based on participants access policy. This means that given instance will be visible to the owner of it (the employee) and the assignees of currently active user tasks - for example manager who has at least one approval task awaiting.

Note that there is simple UI for manager to see incoming approval tasks. Just open browser at http://localhost:8080 and connect using john@email.com. You can also use this UI for employees to see the cancelation of vacation requests, connect using mary@email.com to receive tasks assigned to mary as employee.

The happy path

Happy path consists of steps that will onboard the employee and submit single vacation request that is approved and is not cancelled by the employee.

Try it

Follow steps in the Details section to see the happy path in action.

Here are the steps to try out with happy path

Onboard employee
- Http Method: POST
- Endpoint: http://localhost:8080/vacations
- Payload

{
  "employee": {
    "email": "mary@email.com",
    "firstName": "Mary",
    "lastName": "Jane",
    "startedAt": "2000-12-01",
    "department": "finance"
  }
}

complete curl command for this request is as follows

curl -u mary@email.com:mary -X POST "http://localhost:8080/vacations" -H  "accept: application/json" -H  "Content-Type: application/json" -d "{\"employee\":{\"email\":\"mary@email.com\",\"firstName\":\"Mary\",\"lastName\":\"Jane\",\"startedAt\":\"2020-12-26\",\"department\":\"finance\"}}"

This will create new instance identified as mary@email.com.

Submit a vacation request
- Http Method: POST
- Endpoint: http://localhost:8080/vacations/mary@email.com/submit
- Payload

{
  "from": "2020-10-01",
  "length": 15,
  "to": "2020-10-15",
  "key": "vacation"
}

complete curl command for this request is as follows

curl -u mary@email.com:mary -X POST "http://localhost:8080/vacations/mary%40email.com/submit" -H  "accept: application/json" -H  "Content-Type: application/json" -d "{\"from\":\"2020-10-01\",\"length\":15,\"to\":\"2020-10-15\",\"key\":\"vacation\"}"

Fetch approval tasks as manager
- Http Method: GET
- Endpoint: http://localhost:8080/vacations/mary@email.com/request/vacation/tasks

complete curl command for this request is as follows

curl -u john@email.com:john -X GET "http://localhost:8080/vacations/mary%40email.com/requests/vacation/tasks" -H  "accept: application/json"

Make note of the id returned from the above request as it will be used to complete the approval task

Approve vacation request
- Http Method: POST
- Endpoint: http://localhost:8080/vacations/mary@email.com/requests/vacation/approval/ID
- Payload

{
  "approved": true
}

Replace the {ID} at the end of endpoint with ID from the previous call. Same is required in the below curl command.

There is also option to look at the UI based form to work on the approval task. When getting task list for manager there are formLink returned that can be easily used to open a form in a browser window. Just prepend the host name of the service before the form link and open in the browser which should look like this

complete curl command for this request is as follows

curl -u john@email.com:john -X POST "http://localhost:8080/vacations/mary@email.com/requests/vacation/approval/ID" -H  "accept: application/json" -H  "Content-Type: application/json" -d "{\"approved\":true}"

Now the workflow instance will wait until the first day of vacation request or until it is cancelled by the employee.

Verify access policy restricting access to instances

Each employee has his/her instance completely secured. That means only that employee can see it or manager - when it has approval task assigned. To verify this working try to access mary’s instance by joe.

Http Method: GET
Endpoint: http://localhost:8080/vacations/mary@email.com

complete curl command for this request is as follows

curl -u joe@email.com:joe -X GET "http://localhost:8080/vacations/mary%40email.com" -H  "accept: application/json"

Clean the state

This is completely for test purpose to allow to use same data for other paths

Http Method: DELETE
Endpoint: http://localhost:8080/vacations/mary@email.com

complete curl command for this request is as follows

curl -u mary@email.com:mary -X DELETE "http://localhost:8080/vacations/mary%40email.com" -H  "accept: application/json"

The rejection path

Rejection path consists of steps that will onboard the employee and submit single vacation request that is rejected by manager.

Try it

Follow steps in the Details section to see the rejection path in action.

Here are the steps to try out with happy path

Onboard employee
- Http Method: POST
- Endpoint: http://localhost:8080/vacations
- Payload

{
  "employee": {
    "email": "mary@email.com",
    "firstName": "Mary",
    "lastName": "Jane",
    "startedAt": "2000-12-01",
    "department": "finance"
  }
}

complete curl command for this request is as follows

curl -u mary@email.com:mary -X POST "http://localhost:8080/vacations" -H  "accept: application/json" -H  "Content-Type: application/json" -d "{\"employee\":{\"email\":\"mary@email.com\",\"firstName\":\"Mary\",\"lastName\":\"Jane\",\"startedAt\":\"2020-12-26\",\"department\":\"finance\"}}"

This will create new instance identified as mary@email.com.

Submit a vacation request
- Http Method: POST
- Endpoint: http://localhost:8080/vacations/mary@email.com/submit
- Payload

{
  "from": "2020-10-01",
  "length": 15,
  "to": "2020-10-15",
  "key": "vacation"
}

complete curl command for this request is as follows

curl -u mary@email.com:mary -X POST "http://localhost:8080/vacations/mary%40email.com/submit" -H  "accept: application/json" -H  "Content-Type: application/json" -d "{\"from\":\"2020-10-01\",\"length\":15,\"to\":\"2020-10-15\",\"key\":\"vacation\"}"

Fetch approval tasks as manager
- Http Method: GET
- Endpoint: http://localhost:8080/vacations/mary@email.com/request/vacation/tasks

complete curl command for this request is as follows

curl -u john@email.com:john -X GET "http://localhost:8080/vacations/mary%40email.com/requests/vacation/tasks" -H  "accept: application/json"

Make note of the id returned from the above request as it will be used to complete the approval task

Approve vacation request
- Http Method: POST
- Endpoint: http://localhost:8080/vacations/mary@email.com/requests/vacation/approval/ID
- Payload

{
  "approved": false
}

Replace the {ID} at the end of endpoint with ID from the previous call. Same is required in the below curl command.

complete curl command for this request is as follows

curl -u john@email.com:john -X POST "http://localhost:8080/vacations/mary@email.com/requests/vacation/approval/ID" -H  "accept: application/json" -H  "Content-Type: application/json" -d "{\"approved\":false}"

At this point this request is completed and no longer available for any modification

Clean the state

This is completely for test purpose to allow to use same data for other paths

Http Method: DELETE
Endpoint: http://localhost:8080/vacations/mary@email.com

complete curl command for this request is as follows

curl -u mary@email.com:mary -X DELETE "http://localhost:8080/vacations/mary%40email.com" -H  "accept: application/json"

The cancelled request path

Cancelled request path consists of steps that will onboard the employee and submit single vacation request that is approved by manager but later cancelled by employee.

Try it

Follow steps in the Details section to see the cancelled request path in action.

Here are the steps to try out with happy path

Onboard employee
- Http Method: POST
- Endpoint: http://localhost:8080/vacations
- Payload

{
  "employee": {
    "email": "mary@email.com",
    "firstName": "Mary",
    "lastName": "Jane",
    "startedAt": "2000-12-01",
    "department": "finance"
  }
}

complete curl command for this request is as follows

curl -u mary@email.com:mary -X POST "http://localhost:8080/vacations" -H  "accept: application/json" -H  "Content-Type: application/json" -d "{\"employee\":{\"email\":\"mary@email.com\",\"firstName\":\"Mary\",\"lastName\":\"Jane\",\"startedAt\":\"2020-12-26\",\"department\":\"finance\"}}"

This will create new instance identified as mary@email.com.

Submit a vacation request
- Http Method: POST
- Endpoint: http://localhost:8080/vacations/mary@email.com/submit
- Payload

{
  "from": "2020-10-01",
  "length": 15,
  "to": "2020-10-15",
  "key": "vacation"
}

complete curl command for this request is as follows

curl -u mary@email.com:mary -X POST "http://localhost:8080/vacations/mary%40email.com/submit" -H  "accept: application/json" -H  "Content-Type: application/json" -d "{\"from\":\"2020-10-01\",\"length\":15,\"to\":\"2020-10-15\",\"key\":\"vacation\"}"

Fetch approval tasks as manager
- Http Method: GET
- Endpoint: http://localhost:8080/vacations/mary@email.com/request/vacation/tasks

complete curl command for this request is as follows

curl -u john@email.com:john -X GET "http://localhost:8080/vacations/mary%40email.com/requests/vacation/tasks" -H  "accept: application/json"

Make note of the id returned from the above request as it will be used to complete the approval task

Approve vacation request
- Http Method: POST
- Endpoint: http://localhost:8080/vacations/mary@email.com/requests/vacation/approval/ID
- Payload

{
  "approved": true
}

Replace the {ID} at the end of endpoint with ID from the previous call. Same is required in the below curl command.

complete curl command for this request is as follows

curl -u john@email.com:john -X POST "http://localhost:8080/vacations/mary@email.com/requests/vacation/approval/ID" -H  "accept: application/json" -H  "Content-Type: application/json" -d "{\"approved\":false}"

At this point this request is approved and waiting for the start of vacation.

Fetch approval tasks as manager
- Http Method: GET
- Endpoint: http://localhost:8080/vacations/mary@email.com/request/vacation/tasks

complete curl command for this request is as follows

curl -u mary@email.com:mary -X GET "http://localhost:8080/vacations/mary%40email.com/requests/vacation/tasks" -H  "accept: application/json"

Make note of the id returned from the above request as it will be used to complete the cancel task

Cancel vacation request
- Http Method: POST
- Endpoint: http://localhost:8080/vacations/mary@email.com/requests/vacation/cancel/ID
- Payload

{}

Replace the {ID} at the end of endpoint with ID from the previous call. Same is required in the below curl command.

There is also option to look at the UI based form to work on the cancel task. When getting task list for employee there are formLinks returned that can be easily used to open a form in a browser window. Just prepend the host name of the service before the form link and open in the browser which should look like this

complete curl command for this request is as follows

curl -u mary@email.com:mary -X POST "http://localhost:8080/vacations/mary@email.com/requests/vacation/cancel/ID" -H  "accept: application/json" -H  "Content-Type: application/json" -d "{}"

After vacation request has been cancelled the used days are deducted with request’s length

Clean the state

This is completely for test purpose to allow to use same data for other paths

Http Method: DELETE
Endpoint: http://localhost:8080/vacations/mary@email.com

complete curl command for this request is as follows

curl -u mary@email.com:mary -X DELETE "http://localhost:8080/vacations/mary%40email.com" -H  "accept: application/json"

Source code

Complete source code of this example can be found in GitHub