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

examples vacation request form email

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

vacations workflow

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

vacation request workflow

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

{
  "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.

{
  "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\"}"

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
{
  "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

examples vacation request form approval

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.

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

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

{
  "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.

{
  "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\"}"

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
{
  "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

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

{
  "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.

{
  "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\"}"

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
{
  "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

examples vacation request form approval

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.

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
{}
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

examples vacation request form cancel

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

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