Digital Vacation Management

An Electronic Vacation Management System for Karlstad Municipality

Heidi Pykäläinen

Faculty of Health, Science and Technology Computer Science Bachelor of Science Supervisor: Karl-Johan Grinnemo Examiner: Johan Eklund Date: 2020-06-02

Abstract

The digitization of manual handling of paper forms is an ongoing project at Karlstad municipality, and their management of vacation exchanges is one of the first business processes to be digitized. This process involves applicants printing and filling in a vacation exchange paper form, which is submitted to a department manager for processing, and then forwarded to a payroll administrator for registering. The goal of this thesis was to develop a Proof-of-Concept (PoC) e-service for vacation exchange management at Karlstad municipality. The design of the PoC is based on requirements gathered by interviewing end-users and investigating technical constraints imposed by current systems in place at Karlstad municipality. The PoC is designed as a Web application managing resources from an object database, and an account directory. The implementation was carried out using open source and standardized frameworks. Open source tools were used for the object database and the account directory. The PoC was evaluated against set requirements. Avenues for future work include a more thorough investigation of the account directory at Karlstad municipality.

Contents

1 Introduction 1 1.1 Goal ...... 2 1.2 Disposition ...... 2

2 Preliminaries 3 2.1 Basic Technologies ...... 3 2.1.1 HTML ...... 3 2.1.2 CSS ...... 4 2.1.3 JavaScript ...... 4 2.2 The MERN Stack ...... 4 2.2.1 MongoDB ...... 5 2.2.2 Express ...... 8 2.2.3 React ...... 9 2.2.4 Node.js ...... 10 2.3 Axios ...... 11 2.4 LDAP ...... 12 2.4.1 OpenDJ ...... 13 2.5 Passport ...... 13

3 Requirements 15

iii iv CONTENTS

3.1 Requirements Gathering ...... 15 3.2 Researching Integration Possibilities ...... 16 3.3 Discussing the Usual Method of Creating E-services ...... 18 3.4 Interviews ...... 19 3.5 Current Systems ...... 22 3.6 Requirements for the PoC ...... 22

4 Design 25 4.1 System Architecture ...... 25 4.2 REST API ...... 26 4.3 Front-end ...... 27 4.3.1 User Interfaces ...... 27 4.4 Back-end ...... 30 4.5 Application Database ...... 30 4.5.1 Applications ...... 30 4.6 Login and Authorization ...... 31 4.7 Heroma ...... 32

5 Implementation 33 5.1 Application Database ...... 34 5.1.1 Storing Applications ...... 36 5.1.2 Fetching Applications ...... 37 5.1.3 Updating Applications ...... 38 5.2 Account Directory ...... 39 5.3 Passport ...... 40 5.4 Front-end Client ...... 42 5.4.1 Front-End to Back-End Communication ...... 44 CONTENTS v

5.4.2 Managing Users ...... 45 5.4.3 Submitting Applications ...... 46 5.4.4 Processing Applications ...... 47

6 Evaluation 49 6.1 Understanding the Process ...... 49 6.2 Requirements Gathering ...... 50 6.3 Comparison Against Requirements ...... 51 6.4 PoC Demonstration ...... 53

7 Conclusions 55

List of Figures

2.1 Overview of the MERN stack [39] ...... 5 2.2 Replication in MongoDB [36] ...... 6 2.3 LDAP directory information tree example [43] ...... 12

4.1 The pages in the AUI and the MUI ...... 27

5.1 Overview of the system architecture ...... 34 5.2 Account directory information tree in OpenDJ ...... 40 5.3 The front-end components ...... 44

vii

List of Tables

3.1 General requirements...... 23 3.2 Requirements for submitting applications...... 23 3.3 Requirements for processing applications...... 24

6.1 Unmet requirements for submitting applications...... 51 6.2 Unmet requirements for processing applications...... 52

Chapter 1

Introduction

At Karlstad municipality, vacation exchange is today carried out through paper forms. The paper forms are processed by the department managers and manually registered into Heroma, their personnel administrative system, by the payroll administrators. Vacation exchange entails exchanging vacation pay for additional vacation days with pay. The processing and handling of the vacation exchange paper forms once a year might not have a big impact on smaller departments, where the employees, department managers and the payroll department are located in close proximity to each other. However, in larger departments, in which employees might not have a designated work space, or in which a hundreds of applications are submitted, the issues regarding the handling of paper forms are more prominent.

When applying for vacation exchange, the applicants are required to download and print a paper form found on the municipality’s intranet. The form is thereafter to be filled in, and forwarded to their department manager. Inorder to be approved for vacation exchange, the applicant needs to meet the criteria for vacation exchange. In addition to the criteria, the department manager also decides whether an applicant is approved or denied vacation exchange, based on the department’s projected workload and need for personnel.

1 2 CHAPTER 1. INTRODUCTION

Karlstad municipality has launched a project to investigate the usage and manual handling of paper forms, to which the present project could provide valuable insight. Because a vacation exchange application needs to be printed and filled in by an applicant, processed by a department manager as well as registered by a payroll administrator, digitizing the process should aid all roles involved.

1.1 Goal

The goal of this thesis is to compile requirements for, design, and implement a Proof-of-Concept (PoC) e-service for vacation exchange at Karlstad municipality, in order to investigate a possible solution for digitizing the vacation exchange process.

1.2 Disposition

In Chapter 2, the dissertation starts by presenting the tools and terms used in this project. Next, Chapter 3 details the requirements gathering process and its final goal, the requirements specification. On the basis of the requirements specification, Chapters 4 and 5 present a design and implementation of aPoC.The PoC implementation is evaluated in Chapter 6. Finally, Chapter 7 concludes the thesis by summarizing the thesis work and compiling conclusions, and proposing avenues for future work. Chapter 2

Preliminaries

In this chapter, the relevant techniques used in this bachelor thesis project are described. To start with, the basic technologies HTML, CSS and JavaScript are introduced. Next, the MERN stack and an overview of it’s components are presented in Section 2.2 and its following subsections. After this, the HTTP client Axios is presented. Finally, the Lightweight Directory Access Protocol (LDAP) is described together with the software used to simulate Karlstad municipality’s account directory, OpenDJ and the Node.js middleware Passport.

2.1 Basic Technologies

2.1.1 HTML

The standard markup language for documents to be displayed in a Web browser is Hypertext Markup Language (HTML) [15] [40] [59] [62]. HTML is used to define the structure and semantics of the document by using a tree of elements and text. The HTML elements are usually denoted by a start and an end tag, e.g., as the start tag and as the end tag [60].

3 4 CHAPTER 2. PRELIMINARIES

2.1.2 CSS

Cascading Style Sheets (CSS) [15] [57] is a style sheet language which allows applying of styles to and specifying the layout of HTML documents. Styles are applied selectively using rules, which specify the groups of styles that are applied to elements or groups of elements on the Web [5] [11] [32]. Using CSS the documents font, color, size, and spacing can be altered, as well as splitting the content into columns, adding animations and other decorative features [30]. Within the scope of this project, CSS styles are applied manually and generated using Material-UI [27], a React UI framework.

2.1.3 JavaScript

JavaScript is used as the scripting language for Web pages as well as in many non- browser environments. JavaScript is a lightweight, interpreted, object-oriented language with first-class functions, meaning that functions are treated likeany other variable [1] [20] [29]. Functions can be passed as arguments to, and returned by other functions, and may also be assigned as a value to a variable [28]. EC- MAScript is the standard for JavaScript. The sixth major version, published in 2015 by ECMA International, officially called ECMAScript 2015, is referred toas ECMAScript 6 or ES6. ES6 introduced classes and ES6 modules to JavaScript [61].

2.2 The MERN Stack

The MERN stack [22] [56] is a combination of four technologies, namely: Mon- goDB, Express, React, and Node.js [63]. The MERN stack is a variant of the MEAN stack [24], which is an open source stack for the development of web applications. The difference between the MEAN and MERN stack is that MERN uses 2.2. THE MERN STACK 5

React instead of Angular as the front-end framework. One of the main advantages of using these stacks is that they are end-to-end JavaScript stacks, meaning that every part of the stack uses the same language. While React is used as the front- end framework, Express is used as the Web framework for the back-end Node.js platform, as illustrated in Figure 2.1.

Figure 2.1: Overview of the MERN stack [39]

Using the MERN stack, also a common object representation is used every- where within the project, i.e., in the server, on the client, and in the database. This object representation is JSON (JavaScript Object Notation) [6] [56]. In the following subsections, each part of the MERN stack is described in further detail.

2.2.1 MongoDB

MongoDB [10] [14] is a NoSQL (“non relational”) document database. This means that the data records stored in MongoDB are documents, which are composed of field and value pairs [34]. Documents are stored as BSON (Binary JSON) objects, which are similar to JSON objects, but contain more data types [12]. In comparison to relational databases, the documents are stored in collections instead 6 CHAPTER 2. PRELIMINARIES of tables [34]. A document stored in a collection does not have to contain the same set of fields and corresponding data types, as other documents within thatsame collection [33].

Replication

In MongoDB, replication is achieved using replica sets [36]. The instances within a replica set maintain the same data set to provide redundancy and increase data availability. Replica sets contain a single primary node, which receives all write operations. Secondary nodes in the replica set replicate the primary nodes changes to its data sets, so that the secondaries’ data sets are identical to the primary’s data set, as shown in Figure 2.2. A non-data holding node may also be added to replica sets, these are called arbiters. Arbiters may vote in elections, which are used to select a new primary node.

Figure 2.2: Replication in MongoDB [36]

Atomicity

Write operations are atomic for single documents in MongoDB, meaning that all fields within a document will be updated before a read operation seesthe 2.2. THE MERN STACK 7 updated fields. When modifying multiple documents with one write operation, the operation as a whole is not atomic. Newer versions of MongoDB (versions 4.0 and 4.2) do, however, provide support for atomicity of reads and writes to multiple documents with multi-document transactions [35].

Mongoose

Mongoose [21] [37], an object modeling library for MongoDB and Node.js, is used to define the employed data model. Schemas are an essential part of Mongoose, since they define the shape of the documents within the MongoDB collection theyare mapped to. By creating compiled versions of schemas, i.e., models in Mongoose, CRUD operations can be performed, meaning that documents in the underlying MongoDB database can be created, read, updated and deleted [37]. In other words, the data structure can be defined in JSON inside the project [21]. A schema is defined as shown in Listing 2.1.

1 var mongoose = require('mongoose'); 2 var Schema = mongoose.Schema;

4 var documentSchema = new Schema({ 5 title: String, 6 ... 7 }); Listing 2.1: Schema definition using Mongoose

The schema keys, in Listing 2.1 title, define properties in the documents and the associated schema type, in this case String. Schema types are the types a property can be saved as in MongoDB. Supported schema types include e.g. strings and numbers [38]. A model can then be created in a single line using: var Document = mongoose.model('Document', documentSchema); 8 CHAPTER 2. PRELIMINARIES

2.2.2 Express

Express [2] [7] is a Web server framework which simplifies Node.js server code writing. Using the Express framework, routes can be defined to specify how arriv- ing HTTP requests matching a certain pattern should be handled and responded to. Express parses request URLs, headers, and parameters. The parsed HTTP request can then be passed to one or more handler functions, which are executed when the route is matched [56]. Routes are defined using the structure of app.method(path, handler), where app is an instance of Express, followed by an HTTP request method, a path on the server, and a handler function [18].

REST API

Application programming interfaces (API) make it possible for a client to access resources on a server. REST API’s are API’s conforming to the Representational State Transfer (REST) architectural style [16] [26]. As detailed in [54], the constraints that apply to the REST architectural style are:

• Client-server constraint: The client-server constraint concerns separating the user interface from the data storage.

• Stateless constraint: The stateless constraint means that the clients requests to the server need to contain all the information needed for the request to be understood, context cannot be stored on the server.

• Cache constraint: The cache constraint requires the labeling of data within a response from the server to the client as cacheable or non-cacheable.

• Uniform interface constraint: The uniform interface constraint requires the interfaces between the components to be uniform and follow the interface constraints of REST. 2.2. THE MERN STACK 9

• Layered system constraint: The layered system constraint adds the hierarchical layers of systems to the REST architectural style, in which the layers provide services to the layer above them and use the services of the layers below them.

• Code-on-demand constraint: The code-on-demand constraint is an optional constraint regarding the possibility to extend client functionality by down- loading and executing code as applets or scripts.

REST API’s make it possible to use CRUD operations in web applications. CRUD stands for Create, Retrieve, Update, and Delete operations. In the HTTP protocol, these operations correspond to the POST, GET, PUT and DELETE methods [53].

2.2.3 React

React [4] [23] [49] [55] is an open source JavaScript library created by Facebook for building user interfaces [48]. The main concepts of React are components, states and properties. React components are a way to divide the user interface into separate reusable segments. In React, two types of components can be used: class components and functional components. The difference is that class components are defined with ES6 classes, while functional components are basically JavaScript functions [47]. When class components are defined, they need to extend the React.Component class and include a render() function [50]. Properties (props), are the inputs for components. React has one strict rule: “All React components must act like pure functions with respect to their props” [47]. This means that a component should never change it’s input. States in React, as well as props, are plain JavaScript objects. While props are the input to a component, states are similar to variables declared within a function. Unlike props, states 10 CHAPTER 2. PRELIMINARIES are allowed to be modified using this.setState(). Components are re-rendered when setState() is called [46]. Components return React elements which de- scribe what should appear in the user interface. React elements are produced by writing JSX code, a syntax extension for JavaScript, which makes it possible to use HTML elements in JavaScript code [52]. Listing 2.2 shows a minimal example of a React application.

1 import React from 'react'; 2 import ReactDOM from 'react-dom';

4 class HelloMessage extends React.Component { 5 render() { 6 return ( 7

8 Hello {this.props.name} 9

10 ); 11 } 12 }

14 ReactDOM.render( 15 , document.getElementById(' hello-example') 16 ); Listing 2.2: React app example [49]

2.2.4 Node.js

As most of the code on the server side in this project is created using the Express framework, the description of Node.js is kept brief. Node.js [58] is a JavaScript environment, which means that Node.js runtime runs JavaScript programs using Chrome’s V8 JavaScript engine [13] [41] [56]. In this project, Node.js is used as the platform for the back-end server. Normally, when running JavaScript in a browser, 2.3. AXIOS 11

JavaScript files cannot refer to each other, but with Node.js, the code can besplit into multiple JavaScript files and included using require [56], as demonstrated in Listing 2.1. The default package manager used to install third-party libraries and manage dependencies within Node.js projects is npm [42]. The dependencies are saved in a package.json file in the root of the project folder.

2.3 Axios

Axios [3] is an HTTP client for the browser and Node.js. In this project, Axios is used in the front-end client, i.e., the browser, to make XMLHttpRequests to the server. Axios is promise based, which means that promises can be used to execute asynchronous operations back to back. When a request is made, an object representing the completion or failure of the asynchronous operation is returned. The returned object is a promise [31]. Listing 2.3 shows an example of a GET request performed with Axios.

1 const axios = require('axios');

3 // Make a request for a user with a given ID 4 axios.get('/user',{ params:{ ID: 12345 }}) 5 .then(function (response){ 6 // handle success 7 console.log(response); 8 }) 9 .catch(function (error){ 10 // handle error 11 console.log(error); 12 }) 13 .then(function () { 14 // always executed 15 }); Listing 2.3: Axios GET request example [3] By attaching callback functions to the promise using then(), callbacks are ex- 12 CHAPTER 2. PRELIMINARIES ecuted sequentially once the promise is returned. Executing several asynchronous operations in a sequence once the previous operation succeeds, is called promise chaining [31]. If an operation returns a promise representing rejection with an error, the error is handled using catch().

2.4 LDAP

Lightweight Directory Access Protocol (LDAP) [8] [9] [65] [17] is a protocol allowing clients to for instance store, retrieve, and search for data in a directory server. For this project, important terms to understand regarding LDAP are entry, directory information tree, and distinguished name. While the records stored in MongoDB are called documents, as mentioned in Section 2.2.1, records in a directory are called entries. Entries are structured in directory information trees (DIT), which are a hierarchical structures of entries, see Figure 2.3. In order to be able to find and identify specific entries, each entry has a distinguished name(DN) from which the entry’s position in the DIT can be revealed [64]. For instance, in Figure 2.3 the DN for the entry ”Billie Holiday” is: cn=Billie Holiday,ou=people,dc=Example,dc=com [43].

Figure 2.3: LDAP directory information tree example [43] 2.5. PASSPORT 13

2.4.1 OpenDJ

OpenDJ [19] is an LDAPv3 compliant, open source directory service. Directories are databases designed specifically for searching and browsing. The choice of OpenDJ as the LDAP compliant directory within the present project was based on the simplicity of installation and setup, as well as the possibility of populating the directory with auto generated entries. In addition to this, OpenDJ community edition is also free to download and use.

2.5 Passport

Passport [45] is a middleware for Express-based Node.js applications. Passport provides a number of authentication strategies, e.g., username and password, Face- book, Google (OAuth). In this project, passport is used to authenticate requests using the LDAP strategy, which enables authentication against an LDAP server. Requests are authenticated by calling passport.authenticate(). Authentication using the passport-ldapauth strategy [44] in an Express application is demonstrated in Listing 2.4.

1 app.post('/login', passport.authenticate('ldapauth',{ session: false}), function(req, res){ 2 res.send({status: 'ok'}); 3 }); Listing 2.4: Passport authentication example [44]

Chapter 3

Requirements

Gathering the requirements was a part of the initial stages of the project. The requirements for the PoC were gathered by meeting with Karlstad municipality and conducting a series of interviews. During the present project, another study regarding the vacation exchange process was conducted at Karlstad municipality. The structured interviews were prepared and conducted in collaboration, meaning that the interviews consisted of interview questions providing data for both studies.

3.1 Requirements Gathering

To begin with, a start up meeting with one of the operational planners at the city management at Karlstad municipality was set up in order to get a basic understanding of the client’s expectations and discuss the goals of the project, as well as what the project should result in. During the start up meeting, the client expressed their need to digitize the applying and handling of vacation exchange. The client’s initial goal was that instead of applying for vacation exchange using the current paper form, the employees at Karlstad municipality should be able to

15 16 CHAPTER 3. REQUIREMENTS apply for vacation exchange online, preferably without any additional login details. Additional documentation including the criteria and conditions for vacation exchange as well as the current vacation exchange application paper form were provided.

3.2 Researching Integration Possibilities

At the outset, the client wished the administrative handling of the vacation exchange applications to be integrated with their current personnel administrative system Heroma. This would have meant that when an application is submitted, the manager should receive a ticket in Heroma and be able to process the vacation exchange application within Heroma. After this, the necessary adjustments should be done automatically and the manual adjusting of the vacation pay by the payroll department would thereby be eliminated. Researching the possibilities of integrating the vacation exchange e-service with Heroma revealed an ongoing project in which Heroma would be migrated to cloud and become a so-called software as a service (SaaS) application. This meant the technical requirements for integrating the e-service with Heroma would change after the migration. Implementing the PoC within the present project based on the current technical requirements of Heroma would render the PoC obsolete as soon as the migration of Heroma was completed. Due to this, it was not possible to investigate any automation of the payroll departments tasks within the scope of the present project. Instead, the PoC was decided to only focus on the following aspects:

1. Providing decision support and digitizing the processing of the applications for the department manager

2. Providing decision support for the payroll administrator 3.2. RESEARCHING INTEGRATION POSSIBILITIES 17

3. Digitizing the submission of vacation exchange applications

4. Informing employees of Karlstad municipality of the criteria and conditions for vacation exchange

The initial start up meeting and integration research resulted in the following requirements:

• The PoC should be an e-service reachable from the intranet web page from which the vacation exchange paper form currently is acquired.

• The PoC should not require any additional login details.

• Employees should be able to submit vacation exchange applications.

• Department managers should be able to approve or reject vacation exchange applications.

• The PoC should present the criteria and conditions for vacation exchange.

• The PoC should present the applicants information from Heroma to the department managers and payroll administrators.

The documentation and paper form for vacation exchange provided the following additional requirements:

• Employees should fill in their name and personal identity number when applying for vacation exchange.

• Employees should be able to submit only one vacation exchange application every year.

• Applications should be submitted by the deadline of December 1st.

• Applications should concern the coming year. 18 CHAPTER 3. REQUIREMENTS

• Employees should agree to the criteria and conditions for vacation exchange before submitting an application.

3.3 Discussing the Usual Method of Creating E-services

To further investigate the technical requirements for the PoC, a phone meeting with personnel at the city management involved in developing public e-services was conducted. Karlstad municipality currently provides a number of public e- services, which are created and managed within an e-service platform with an integrated database. Using the e-service platform, e-services can be created with default modules and customized using JavaScript and Python. Thus, in view of this, and with regards to future maintenance and administration of the system, it was decided that the PoC should be implemented in JavaScript. When enquiring about ways of eliminating the need of additional login detail, ideas of using the current intranet account directory were discussed. The intranet account directory could also be used in routing of applications to the correct department manager. There have previously been no integration with Heroma. Based on the phone meeting, the following requirements were gathered:

• The PoC should use the central account directory of the Karlstad municipality for user authentication and authorization.

• The PoC should determine which department manager an application is sent to using the central account directory of the Karlstad municipality.

• The PoC should be implemented using JavaScript. 3.4. INTERVIEWS 19 3.4 Interviews

In order to gather user requirements, interviews were conducted with three respondents, each with a different role in the vacation exchange process: an applicant, a department manager and a payroll administrator. During each interview session, the respondent was presented with three different prototypes of the user interface for the PoC. The prototypes created using HTML were clickable, but did not contain any further functionality beyond nav- igation. The purpose of the prototypes was to gather the respondents’ opinions on the presentation of information in the user interface. To this end, the prototypes differed in their flow of interaction, the number of mandatory clicks, andthe amount of information presented. All respondents are eligible to apply for a vacation exchange, and thereby participate in the vacation exchange process in the role of an applicant, despite any other roles of theirs. Thus, although only prototypes of the submission process were implemented prior to the interviews, all respondents had the opportunity to review the prototypes. The department manager and the payroll administrator could also provide valuable input on factors in the submission process that could minimize the amount of submitted applications that eventually are rejected. The first prototype (P1) was the simplest of the three prototypes. It consisted only of one page showing a digital version of the current paper form with input fields for the applicants name, personal identity number, and check boxes bywhich the applicant confirms his or hers understanding of the criteria, and accepts the conditions of vacation exchange. The second prototype (P2) consisted of three pages in addition to the application form: a landing page, a criteria page and a conditions page. The landing page included links to the pages for criteria and conditions, but the user could imme- diately navigate to the application form by clicking the “Apply” button, without 20 CHAPTER 3. REQUIREMENTS first viewing the criteria or conditions. The conditions page presented information regarding the conditions for vacation exchange, and the criteria page included a short quiz the user could fill out to check if he or she meets the criteria for vacation exchange. The rationale behind the short quiz was to suggest a more in- teractive way to present the information as a means of ensuring that the applicant understands the criteria. In the third prototype (P3), the pages were structured to be navigated in a sequential order, meaning that the user was required to enter each page in a specific order to reach the vacation exchange application form. This approach ensured that all users were presented with both the criteria and conditions for vacation exchange before being allowed to submit their applications. After presenting the prototypes, the respondents were asked to express which of the three they preferred, and if there were any specific details of parts of any other prototype they would like to include in the preferred one. All the respondents individually came to the conclusion that P3 was the most preferable prototype, and this since it essentially forced the user to view the criteria and condition pages. The quiz for checking if the user meets the criteria in P2 was also appreciated, but could not be included as a required step in the sequential layout of P3. The employees might not know by heart all the information required to be filled in, making it impossible for them to proceed to the vacation exchange application form. Since no prototypes of the processing of the applications were presented, the department manager and payroll administrative respondents were asked to think about what could aid them in their respective tasks of processing and registering the vacation exchange applications. They were also asked to explain what information they use in order to make a decision and to check if the applicant meets the criteria. Both the department manager and the payroll administrator suggested 3.4. INTERVIEWS 21 the same information as decision support, namely: the applicant’s form of employment, number of saved vacation days, and whether the applicant has other types of extended leaves planned, such as, but not limited to, parental or sick leave. In conclusion, the interviews provided the following requirements:

• The PoC should present the criteria and conditions for vacation exchange before allowing the user to submit an application.

• Employees should be able to follow the processing of their application.

• When processing an application, the applicants form of employment, number of saved vacation days, and planned extended leaves should be displayed.

• Department managers and payroll administrators should be able to view which applicants are approved for vacation exchange during the current application period.

• Department managers should be notified by e-mail when an application is submitted.

• Department managers should receive reminders by e-mail about unprocessed applications.

• Payroll administrators should only be able to process applications approved by the managers in their department.

• Department managers should only be able to process applications submitted by employees in their department.

• The PoC should keep a history of previously approved and rejected applications. 22 CHAPTER 3. REQUIREMENTS 3.5 Current Systems

With the gathered requirements in mind, it was evident that the PoC would need to communicate with the systems currently in place at the Karlstad municipality. Information would have to be fetched from the employees’ profiles in Heroma to be displayed in the PoC. Considering that the technical requirements for accessing Heroma were about to be changed due to the conversion of the system to SaaS, the integration with Heroma was included in the design but not realized in the implementation of the PoC. Authentication and authorization of users was to be carried out through the central account directory of the Karlstad municipality. Since there was no access to the account directory of Karlstad municipality during the present project, the account directory was simulated. The simulated account directory, like the account directory of Karlstad municipality, supports and is accessed using LDAP.

3.6 Requirements for the PoC

This section contains the complete requirements list separated by general requirements for the PoC in Table 3.1, followed by requirements for submission in Table 3.2 and the requirements for processing of vacation exchange applications in Table 3.3. Each requirement is given an ID consisting of the first letter in their section (G for general, S for submitting and P for processing), R for requirement and a number. These IDs will be used in the rest of the dissertation to reference specific requirements. 3.6. REQUIREMENTS FOR THE POC 23

Table 3.1: General requirements. ID Requirement GR1 The PoC should be an e-service reachable from the intranet web page from which the vacation exchange paper form currently is acquired. GR2 The PoC should not require any additional login details. GR3 The PoC should use the central account directory of Karlstad municipality for user authentication and authorization. GR4 The PoC should determine which department manager an application is sent to using the central account directory of Karlstad municipality. GR5 The PoC should be implemented using Javascript.

Table 3.2: Requirements for submitting applications. ID Requirement SR1 Employees should be able to submit vacation exchange applications. SR2 The PoC should present the criteria and conditions for vacation exchange. SR3 Employees should fill in their name and personal identity number when applying for vacation exchange. SR4 Employees should be able to submit only one vacation exchange application every year. SR5 Applications should be submitted by the deadline of December 1st. SR6 Applications should concern the coming year. SR7 Employees should agree to the conditions and criteria for vacation exchange before submitting an application SR8 The PoC should present the criteria and conditions for vacation exchange before allowing the user to submit an application. SR9 Employees should be able to follow the processing of their submitted application. 24 CHAPTER 3. REQUIREMENTS

Table 3.3: Requirements for processing applications. ID Requirement PR1 Department managers should be able to approve or reject vacation exchange applications. PR2 The PoC should present the applicants information from Heroma to the department managers and payroll administrators. PR3 When processing an application, the applicants form of employment, number of saved vacation days and planned extended leaves should be displayed. PR4 Department managers and payroll administrators should be able to view which applicants are approved for vacation exchange during the current application period. PR5 When an application is submitted, department managers should be notified by e-mail. PR6 Department managers should receive reminders by e-mail about unprocessed applications. PR7 Payroll administrators should only be able to process applications approved by the managers in their department. PR8 Department managers should only be able to process applications submitted by employees in their department. PR9 The PoC should keep a history of previously approved and rejected applications. Chapter 4

Design

Throughout this chapter, requirements will be referenced in order to emphasize the connection between the design and the requirements. The requirements will be referenced by their IDs which are found in the requirements specification in Section 3.5.

4.1 System Architecture

With GR1 and GR5 in mind, the PoC is designed as a web application. The design of the PoC consists of five main components: the front-end client, the back-end server, a database, a simulation of Karlstad municipality’s account directory, and Heroma, the personnel administrative system. The e-service will be used by three different types of users represented by three different roles in the vacation exchange process. These roles arethe applicant, the department manager and the payroll administrator. The applicant uses the e- service to submit an application for vacation exchange. The department manager receives the application and either approves or rejects it. Applications approved by the department manager are forwarded to payroll administrators for registra-

25 26 CHAPTER 4. DESIGN tion into Heroma. The requirements imposed by the three different roles on the PoC differ based on their usage and information needs, which is apparent inthe requirements specification.

4.2 REST API

The front-end client and the back-end server communicate by the client sending requests to the server. The requests transmit, e.g., the user input from the client to the server, and the server responds by providing the client with resources from the connected databases. Requests are sent from the client to the server when a user logs in, when an application is submitted, and when applications are to be retrieved from the application database. The server has different REST API endpoints configured to respond to the aforementioned requests:

• the /users endpoint is used to authenticate users

• the /applications endpoint is used to store applications

• the /application endpoint is used to retrieve a specific application

In the event of a user logging in, the client sends a POST request to the server’s /users endpoint in order to authenticate the user. When a form is submitted the client sends a POST request to the server’s /applications endpoint in order to store the submitted application in the application database. When multiple applications are to be retrieved from the application database, the client sends a GET request to the server’s /applications endpoint. When a specific application is to be retrieved, the client sends a GET request to the /application endpoint. 4.3. FRONT-END 27 4.3 Front-end

The front-end component serves as the web application client which is responsible for relaying user input to the back-end server, and for displaying responses to the user through user interfaces.

4.3.1 User Interfaces

The front-end includes two different user interfaces: the applicant user interface (AUI) and the admin user interface (MUI). The AUI is a general user interface used to submit vacation exchange applications (SR1), and the MUI is used to process the submitted applications (PR1). Figure 4.1 provides an overview of the two user interfaces. The access to the different user interfaces is based on the role of the currently logged in user. The AUI is not restricted to any specific type of user, and is thereby accessible to all logged in users. The MUI is, however, only accessible to users assigned specific roles. Login and authorization is further discussed in Section 4.6. In the following subsections, the respective interfaces for the three roles in the vacation exchange process are explained in detail.

Figure 4.1: The pages in the AUI and the MUI 28 CHAPTER 4. DESIGN

Applicant User Interface

The AUI consists of a series of pages in a predefined order that present the criteria and conditions for vacation exchange. The user is required to view all the pages of information in a sequential order before reaching the form through which the user may submit their application (SR2 & SR8). In order to submit an application, the user needs to fill in their name and personal identity number (SR3). They also need to confirm that they have understood the criteria and agree to the conditions for vacation exchange (SR7). Users may only submit one vacation exchange application a year (SR4), and therefore once they have submitted an application during the current application period, they will be redirected to an overview of the processing of the application. In other words, if a user has previously submitted an application and logs in to the e-service, the AUI will only show the current status of the application (SR9). If a user has not submitted an application during the current application period and logs in to the e-service after December 1st (SR5), they will be notified that the current application period has ended.

Admin User Interface

The MUI is accessible provided the currently logged in user is a department manager or a payroll administrator. As previously mentioned, both department managers and payroll administrators are eligible to apply for vacation exchange. There- fore, when either a department manager or a payroll administrator logs in to the e-service, they are redirected to a landing page from which they may choose to apply for vacation exchange (access the AUI) or process applications (access the MUI). If the currently logged in user is a department manager and he or she wants to process applications, the MUI is presented and displays the submitted vacation 4.3. FRONT-END 29 exchange applications within the department managers department (PR8). The department manager may select an application and make decision on the basis of the information displayed. In addition to the applicant’s name and personal identity number, the applicant’s form of employment, number of saved vacation days and planned extended leaves are displayed (PR3). In sum, the department manager may approve or reject applications using the MUI. When applications are submitted, the department manager responsible for processing the application receives an e-mail notification (PR5). Department managers also receive reminders by e-mail about unprocessed applications (PR6). Because applications approved by department managers are not linked to any specific payroll administrator within the department, the applications approved by a department manager are not displayed to a specific user. Instead, they are displayed to any user currently logged in with a payroll administrative account within the department (PR7). When selecting an application, payroll administrators are also displayed the same information about the applicant as the department managers. Payroll administrators may use the presented information as an aid when controlling whether the applicant meets the criteria for vacation exchange, and then manually adjust the vacation pay in Heroma. When the payroll administrator has successfully finished processing the application, they mark the application as completed. If the applicant does not meet the criteria for vacation exchange, the payroll administrator can mark the application as failed, in which case the application is sent back to the department manager for further discussion with the applicant and revision of the decision. Both users with department manager accounts and payroll administrative accounts may view any previously processed and registered applications to check whether they have been approved or rejected (PR4 & PR9). The applicant’s information retrieved from Heroma is not displayed when viewing a previously 30 CHAPTER 4. DESIGN processed and registered application.

4.4 Back-end

The back-end is a server which receives the input data from the front-end form, and retrieves resources from the account directory and the application database. When a user logs in, the server receives a request from the client and connects to the account directory in order to perform a search using the user’s username and password. If the user is found, the server sends a response containing the user data to the client. If the user is not found, the client receives a response containing the error status. When applications are submitted, the server connects to the application database in order to create and store applications. The data stored within the applications are provided by the client. The server also retrieves applications from the application database and sends them to the client for display in the MUI. The server connects to the account directory to check to which department manager the applications are to be presented. Before the server returns the applications, the server also retrieves the applicants’ information from Heroma to add it to the response to the client.

4.5 Application Database

The applications are stored and retrieved from an object database. The application database stores submitted vacation exchange applications.

4.5.1 Applications

The following data is stored in the applications in the application database: 4.6. LOGIN AND AUTHORIZATION 31

• the applicant’s name,

• the applicant’s personal identity number,

• the year which the application concerns (SR6),

• the status of the application,

• the applicant’s username.

When the application is first stored in the database, the status of the application is set to ”submitted”. When the department manager has processed the application, the status is changed to either “approved” or “rejected”. When the payroll administrator has finished registering the application, the status is setto “completed” or “failed”. When the status is set to “failed” the application is to be reviewed again by the department manager. An application is only considered completed when the status is either “completed” or “rejected”. The applicants username is stored in the application in order to connect the application to the corresponding department manager using the account directory.

4.6 Login and Authorization

The intranet account directory contains the login accounts for personnel at Karl- stad municipality. The same accounts are used in the PoC to identify the applicant and connect them to their respective department manager. The intranet account directory is also used to control the access to the MUI (GR2, GR3 & GR4). In order to verify that the user is authorized to use the vacation exchange e-service, the user needs to log in with their intranet account username and password. As previously mentioned, if the user is a department manager or a payroll administrator, they are directed to the MUI. If the user does not belong to any of these two roles, he or she is directed to the AUI. 32 CHAPTER 4. DESIGN 4.7 Heroma

Heroma is the personnel and payroll management system at the Karlstad municipality, and contains details about the personnel at Karlstad municipality. Each employee has their own profile in Heroma. When a department manager ora payroll administrator views an application in the MUI, the applicant’s data is retrieved from Heroma and displayed in the MUI in order to aid in decision making and control of the criteria (PR2). Chapter 5

Implementation

In this chapter, the implementation of the PoC according to the design presented in Chapter 4 is explained. The different components of the implementation are presented in Figure 5.1. The numbering of the components is used throughout this chapter when referring to the components in the system architecture. The implementation of PoC is based on the MERN stack which includes MongoDB(10), Express(6), React.js(1) and Node.js(4). Axios(2) is used to handle HTTP-request from the front-end to the back-end and Passport(5) is used for user authentication and authorization. MongoDB(10) is used for storing applications while OpenDJ(9) is used to simulate the user account directory.

33 34 CHAPTER 5. IMPLEMENTATION

Figure 5.1: Overview of the system architecture

5.1 Application Database

A connection to MongoDB(10) is set up using Mongoose(7) and its .connect function, as shown in Listing 5.1. The first parameter, process.env.DB, is the URL to the MongoDB and is configured in the .env file using the dotenv package. The other parameters provided are used to configure Mongoose to work around deprecation in the Node.js MongoDB driver. 5.1. APPLICATION DATABASE 35

1 const mongoose = require("mongoose"); 2 require("dotenv").config();

4 mongoose 5 .connect(process.env.DB,{ 6 useNewUrlParser: true, 7 useUnifiedTopology: true, 8 useFindAndModify: false, 9 }) 10 .then(() => console.log(`Database connected successfully`) ) 11 .catch((err) => console.log(err));

12 Listing 5.1: Connecting Mongoose to MongoDB

Mongoose(7) is also used to define the schema for the application documents in MongoDB(10). The schema defines keys for the application document in order to store the applicant’s username, name, personal identity number (pid), the year the application concerns, the status of the application, and the manager of the applicant. A shortened version of creating a schema can be seen in Listing 5.2. All the keys are defined with the SchemaType String, except the year and the pid keys, which have the SchemaType Number. 36 CHAPTER 5. IMPLEMENTATION

1 const mongoose = require("mongoose"); 2 const Schema = mongoose.Schema;

4 const ApplicationSchema = new Schema({ 5 username:{ 6 type: String, 7 required:[true, "The username field is required"], 8 }, 9 ... 10 year:{ 11 type: Number, 12 required:[true, "The year field is required"], 13 }, 14 ... 15 });

17 const Application = mongoose.model("application", ApplicationSchema);

19 module.exports = Application;

20 Listing 5.2: Creating a schema with Mongoose

Once the schema is created, it is used to compile a model in order to perform CRUD operations in the MongoDB database(10). The model is used by the API endpoints(6) in the back-end server(8) in order to be able to respond to the front- end client’s(3) requests with the appropriate data. The model is created in the in the api.js file with const Applications = require("../models/applicationSchema");

5.1.1 Storing Applications

In order for the back-end server to handle requests from the front-end, REST API endpoints are set up with Express Router(6). When an application is submitted in 5.1. APPLICATION DATABASE 37 the front-end client(3), a POST request is sent to the server’s(8) /applications endpoint(6) (see Listing 5.3). The request is checked to contain a name and a personal identity number. If the request does not contain these fields, a response containing an error message is sent back to the front-end. If the request contains a name and a personal identity number, a document is created in the MongoDB database(10) using the Mongoose(7) model Applications and the create() function. The created application document contains the data from the request. If the creation of the document succeeds, the document is then sent as a JSON response to the caller. If the condition is not met, the error is passed to Express.

1 router.post("/applications",(req, res, next) => { 2 if (req.body.name && req.body.pid){ 3 Applications.create(req.body) 4 .then((data) => res.json(data)) 5 .catch(next); 6 } else { 7 res.json({ 8 error: "The name or pid field is empty", 9 }); 10 } 11 }); Listing 5.3: The POST /applications endpoint

5.1.2 Fetching Applications

The server(8) is set up with three different endpoints(6) for fetching documents from the MongoDB database(10). All three endpoints use the find() function to search for and return documents from the database. The /applications/manager endpoint shown in Listing 5.4, is used to fetch documents for the department manager by matching the managers username against the manager field in the documents, as well as matching the provided status with the documents’ status 38 CHAPTER 5. IMPLEMENTATION field. The documents matching the search criteria are returned as a JSON object.

1 router.get("/applications/manager",(req, res, next) => { 2 Applications.find({ manager: req.query.username, status: req.query.status }) 3 .then((data) => res.json(data)) 4 .catch(next); 5 }); Listing 5.4: The GET /applications/manager endpoint

The remaining two endpoints are implemented similarly, but with different search criteria used in the find() function. When a GET request is sent to the /applications/payroll endpoint, the documents are searched for using only a specific status. When sending a GET request tothe /application endpoint, documents matching a specific username are returned.

5.1.3 Updating Applications

In order to change the status of an application in the database(10), a PUT request is sent to the /application endpoint(6), shown in Listing 5.5. The request needs to contain the _id of the document to be updated, as well as the new value for the status filed. The function findOneAndUpdate() is used to update the specified document with the new status in the database. The updated document is returned in the response. 5.2. ACCOUNT DIRECTORY 39

1 router.put("/application",(req, res, next) => { 2 Applications.findOneAndUpdate( 3 { _id: req.body.id }, 4 { status: req.body.status } 5 ) 6 .then((data) => res.json(data)) 7 .catch(next); 8 }); Listing 5.5: The PUT /application endpoint

5.2 Account Directory

The account directory(9) was set up using OpenDJ. For simulation purposes, auto- generated entries were created and modified. In total, 14 users were created and structured in a DIT. The structure of the DIT was based on the city management organizational diagram [25], and as can be seen in Figure 5.2, the departments included in the DIT were the HR department and the Economics department. The HR department contained two nested departments. Six out of the 14 users were employees within departments at the city management, three were users outside of the city management, three were department managers, and two were payroll administrators. For simplicity, each department included one manager, which was set as the manager of the employees within that specific department. The managers were also included in the group “Managers”, to assign them their role as manager. 40 CHAPTER 5. IMPLEMENTATION

Figure 5.2: Account directory information tree in OpenDJ

5.3 Passport

When a user enters the e-service, they are required to log in by entering their username and password. The server(8) receives a request containing the username and password from the client(3), and connects to the account directory(9) using Passport(5). When setting up Passport, the authentication strategy needs to be defined. In this case, as authentication is performed using LDAP, an LdapStrategy is defined as shown in Listing 5.6. 5.3. PASSPORT 41

1 passport.use( 2 new LdapStrategy({ 3 server:{ 4 url: process.env.LDAP_URL, 5 bindDN: process.env.LDAP_BIND_DN, 6 bindCredentials: process.env.LDAP_BIND_PASS, 7 searchBase: process.env.LDAP_SEARCH_BASE, 8 searchFilter: "uid={{username}}", 9 searchAttributes:["isMemberOf", "manager", "dn"], 10 }, 11 }) 12 ); Listing 5.6: Passport LDAP Strategy

As with the URL for MongoDB, the bind information for the LDAP strategy is defined in the .env file. The search base specifies the base node for thesearch in the DIT. The search filter is used to define what data is used in the searchand what field it should match. In this case, the search is based onthe uid field of the entries. The search attributes define what data is to be fetched from the directory. In this case, the relevant data is group memberships, the manager of the user, and the user’s DN in the account directory. The passport.authenticate function is used in the /users endpoint (see Listing 5.7) to perform the authentication against the account directory, providing the chosen strategy ldapauth as the first argument. 42 CHAPTER 5. IMPLEMENTATION

1 router.post( 2 "/users", 3 passport.authenticate("ldapauth",{ 4 session: false, 5 }), 6 function (req, res){ 7 res.json(req.user); 8 } 9 ); Listing 5.7: The POST /users endpoint If the user is successfully authenticated, i.e., their credentials are found to match a user in the account directory, the user data from the directory is returned to the client.

5.4 Front-end Client

The parent component in the front-end client(3) is the ES6 class App. It’s constructor defines the state of the component. The state includes the fields inListing 5.8.

1 constructor(props){ 2 super(props); 3 this.state = { 4 page: -1, // The currently loaded page ID 5 message: "", // Dynamic string for elements 6 name: "", // Name on application 7 pid: "", // Personal identity number 8 year: new Date().getFullYear() + 1, 9 username: "", // The user's username 10 manager: "", // The user's manager 11 group: "", // The user's groups 12 application: {}, // The user's application 13 }; Listing 5.8: The constructor of the App component The render() function, which is called every time the state changes, returns 5.4. FRONT-END CLIENT 43 the elements which are displayed in the user interface. The code can be simplified by omitting most of the properties of each element to the elements shown in Listing 5.9.

{this.loadPage()}

3 4 5

Listing 5.9: Rendered elements in the App component

As can be understood from the simplified code in Listing 5.9, the App component essentially renders three elements wrapped in a container element, since only a single element can be returned from the render() function. The three elements are: two buttons for navigating to the previous and next page respec- tively, and the infoBox element, in which the appropriate child component is loaded using the loadPage() function. The loadPage() function is essentially a switch statement which returns the correct component based on the value of this.state.page. As shown in Figure 5.3, the front-end consists of an additional nine child components. The components to the left of the parent component, i.e., the Information, Criteria, Conditions, ApplicationForm, and Status components are all part of the submission of applications, and are therefore considered to belong to the AUI(1). The components to the right of the parent component, i.e., AdminLanding, ProcessApplications, and History are part of the MUI(1). The first child component rendered within the parent App component is the Login component. 44 CHAPTER 5. IMPLEMENTATION

Figure 5.3: The front-end components

There is no need to keep states in the Information, Criteria and Conditions components, since these components consist purely of elements containing text to be displayed. Therefore, the aforementioned components were implemented as functions rather than ES6 classes. Furthermore, managing the loading of components could also been achieved using a routing library, e.g., React Router [51], but the prototype is for an internal e-service, the pages are navigated in a sequential order, and there is no need to use the URL of the current page for other purposes like bookmarking. Thus keeping the pages numbered and stored in the state of the App class sufficed.

5.4.1 Front-End to Back-End Communication

The front-end(3) needs to send a request to the back-end(8) when a user logs in in order to authenticate the user, and when storing and retrieving applications from the MongoDB database(10). Both the Login and the ApplicationForm components contain HTML forms. In this implementation, Axios(2) is used to create and send requests from the front-end client to the back-end server. 5.4. FRONT-END CLIENT 45

5.4.2 Managing Users

When a user first enters the e-service, the child Login component is rendered in the infoBox in the parent App component. When the login form is submitted, the handleLogin function is called, in which an XMLHttpRequest is made to the server using the .post method in Axios(2). The first parameter is the specific endpoint URI to which the data in the second parameter is posted. In this case, the POST request is sent to the /users endpoint of the back-end server. After a successful authentication of the user, the user data is returned in a response to the front-end client. The Login component passes the manager of the user as well as the DN to the state of the App component, using the function onLogin passed through the props from the parent App component. If the user is a member of any groups, the DN of the group is also stored in the App component state using the setGroup function, which is also passed to the child Login component using props. When the user data has been handled, the checkAuthorization function is called to check the role of the logged in user, using the group and the DN of the user. If the user is determined to be a department manager or a payroll administrator, the Login component will call the nextPage function, also passed through props, in order to trigger the App component to render the AdminLanding component. If the user is determined not to be authorized to access the MUI, the getApplication method is called. In getApplication, a GET request is sent using Axios(2) to the server(8) to check if there is a previously submitted application containing the DN of the currently logged in user. If an application is found in the document database, the nextPage function is called to set the App component to render the Status component. If no application has been submitted, the page is instead set to render the Information component. 46 CHAPTER 5. IMPLEMENTATION

5.4.3 Submitting Applications

When the application form is submitted, the handleSubmit function is called. As with the login form, a POST request is sent using Axios(2), but this time the request is sent to the /applications endpoint of the server API(6). A request object containing the name, personal identity number and year in the state of the App component is created and the status is set to “submitted”, as shown in Listing 5.10.

1 handleSubmit(event){ 2 event.preventDefault();

4 Axios.post(postAPI,{ 5 username: this.state.username, 6 name: this.state.name, 7 pid: this.state.pid, 8 year: this.state.year, 9 status: "submitted", 10 manager: this.state.manager, 11 }) 12 .then((res) => { 13 if (res.status === 200) { 14 alert("Din ansökan har skickats!"); 15 this.setState({ application: res.data }); 16 this.setState({ page: 5 }); 17 } 18 }) 19 .catch((err) => { 20 this.setState({ 21 error: "Ett fel inträffade när din ansökan skulle skickas.", 22 }); 23 }); 24 } Listing 5.10: The handleSubmit function If the back-end server(8) returns a response with the status 200, a success 5.4. FRONT-END CLIENT 47 message is displayed in the browser. The submitted application is stored in the state of the App component and the page is set to render the Status component. If the server responds with an error, the state is set to show an error message.

5.4.4 Processing Applications

Once a logged in department manager chooses to process applications from the admin landing page, a GET request is sent from the client(3) to the server’s /applications/manager endpoint(6). The request contains the user’s DN and the status the applications should match, i.e., ”submitted”. All documents matching the managers DN and having the status ”submitted” are returned from the database by the server to the client as a JSON object. The client maps the array of documents into a table and adds buttons for approving or rejecting each of the applications. If the department manager presses either of the buttons related to an application, the function handleApplicationStatus is triggered by the event. The handleApplicationStatus function calls for two parameters, the _id of the application document and the new status the application should be updated to. In this function, a PUT request is sent to the server containing the _id of the document to be changed, as well as the new status it should be set to. Once an application is approved or rejected, i.e., the status of the document is changed to “approved” or “rejected” in the document database, the document will no longer match the search query for applications with the status ”submitted”. Therefore, the applications that have already received a decision from the department manager are not returned from the database when the application list is re-rendered. The registering of applications as a payroll administrator is nearly identical to the processing of applications as a department manager. The only differences are in which applications are fetched and displayed, and in the statuses to which 48 CHAPTER 5. IMPLEMENTATION the applications are set once they have been processed or registered. The application documents are fetched with a GET request to the /applications/payroll endpoint. The request contains the status of the applications that should be returned, i.e., ”approved”, since only applications approved by the department manager should be registered by a payroll administrator. If the payroll administrator confirms an application, the status argument for the handleApplicationStatus is ”completed”, and if the application is not confirmed, the status argument is instead ”failed”. Chapter 6

Evaluation

In this chapter, the bachelor thesis project is evaluated. First, the investigation of the vacation exchange process and it’s impact on the project as a whole is reviewed. Next, aspects affecting the requirements gathering phase are discussed, followed by a comparison of the implementation with the requirements specification. The chapter ends with a summary of the demonstration and client evaluation of the PoC.

6.1 Understanding the Process

Having a clear understanding of how the physical paper forms are currently handled, facilitated the design decisions regarding the handling of the application documents in the PoC. Knowing what part each role plays in the process, and what should happen when an application is submitted, processed or registered, was essential in the design development. The flow of the application documents within the PoC, is based on information gathered from the interviews (cf. Section 3.4) and information obtained through a collaboration with another bachelor student at Karlstad University. The combined

49 50 CHAPTER 6. EVALUATION effort in the requirements gathering process provided a more thorough understanding of the current process, which in turn served as a basis for the design of the PoC. For instance, it was made clear that applicants might not be aware of the last stage of the application processing, i.e., the registration of the application performed by the payroll administrator. By making the stages of the application processing visible for the applicant on the status page in the PoC, the applicant is made aware of the stages in the process in which their application might be rejected.

6.2 Requirements Gathering

The requirements were first and foremost gathered by interviewing the future end- users of the e-service, followed by an investigation of the technical requirements and constraints. This meant that during the initial stages of the project, the time spent and work done was highly dependent on how well I managed to schedule my meetings with the respondents of the interviews as well as meetings with other departments at the Karlstad municipality. Investigating the technical constraints imposed by current systems and prac- tices was challenging. Since several departments within the Karlstad municipality needed to be contacted in order to map the technical requirements, and at times realizing that one should talk to someone else all together, the phase from having a set user requirement specification to beginning implementation was rather un- clear. The investigation of technical requirements and constraints was based on the requirements imposed by the end-users. The aim of the investigation was to find possible technical solutions to realize the end-users’ requirements. The communication with the client was carried out through e-mail and meetings in the initial stages of the project. After the interviews with the three different 6.3. COMPARISON AGAINST REQUIREMENTS 51 roles involved in the process (applicant, department manager and payroll administrator) were conducted, the COVID-19 pandemic constricted the physical meetings with the client. While building the requirement specification and during the design development and implementation phases of the project, the communication with the client was carried out through e-mail only. However, the constraints placed on physical meetings did not have a large impact on the project, since the work carried out during the project was not planned to take place on-site at Karlstad municipality to begin with. As gathering requirements was part of the project scope, the chosen development tools and techniques were not set until the implementation stage started. Moreover, realizing that more information needed to be retrieved to be able to implement the gathered requirements, delayed the implementation process and forced the documentation process to be carried out in parallel with the implementation.

6.3 Comparison Against Requirements

Out of the, in total 22 requirements, one requirement on the submission of applications and four requirements on the processing of applications were not met. Requirement SR5 (see Table 6.1) was not met, because no check for December 1st was implemented.

Table 6.1: Unmet requirements for submitting applications. ID Requirement SR5 Applications should be submitted by the deadline of December 1st.

In order to meet the requirement, two issues needed to be considered. First, not being able to submit applications after December 1st. Second, enabling new applications in consecutive application periods. The second issue could be solved 52 CHAPTER 6. EVALUATION by creating a new collection to which the applications are stored in the application database for each application period. The applicant is only restricted to the status page when there is an application matching their credentials in the database collection. Another way to solve this is adding another search attribute when performing a query for the applicants previously submitted application, i.e., the search could return the application for the current application period. However, since the application period ends December 1st, and not at the end of the year, additional controls for not allowing applicants to submit their applications after the deadline needed to be implemented. Requirements PR2 and PR3 (see Table 6.2) were not met due to the ongoing migration of Heroma to the cloud. There was no possibility to implement the retrieval of data in a way that would mimic the future behaviour of Heroma. The lack of available knowledge of the future functionality of Heroma led to PR2 and PR3 not being realized in the PoC. Requirements PR5 and PR6 were not implemented due to lack of time.

Table 6.2: Unmet requirements for processing applications. ID Requirement PR2 The PoC should present the applicants information from Heroma to the department managers and payroll administrators. PR3 When processing an application, the applicants form of employment, number of saved vacation days and planned extended leaves should be displayed. PR5 When an application is submitted, department managers should be notified by e-mail. PR6 Department managers should receive reminders by e-mail about unprocessed applications. 6.4. POC DEMONSTRATION 53

All the remaining requirements were met. Still, in retrospect, I can see that the storing of the DN of the department manager as well as that of the applicant together within the application documents could cause issues in the future. For instance, if an applicant changes departments, or is appointed a new department manager, the data stored in the application will be obsolete. The application will not be fetched and displayed to the new department manager with the current implementation. There was no investigation on how these situations should be handled currently, in the manual processing of the physical paper applications.

6.4 PoC Demonstration

After the implementation period, the PoC was demonstrated and evaluated in a video meeting with the client. The evaluation of the prototype was carried out on the basis of the set requirements (cf. Section 3.6). The client had the opportunity to review the final version of the PoC and determine whether it complies withset requirements or not. The demonstration was performed in a video meeting, rather than on site at Karlstad municipality, due to the COVID-19 pandemic limiting possibilities to meet in person. The current situation rendered on-site evaluation, demonstration, as well as testing impossible to conduct. The client expressed that the current prototype provides valuable insight to the on going project of digitizing the handling of paper forms, in which the vacation exchange process is one of the first to be investigated. In addition to the implementation, suggestions brought up during the realization of the PoC, the gathering and specification of the requirements on a digital vacation management system were also perceived as valuable contributions to future digitization projects.

Chapter 7

Conclusions

The goal of this thesis was to propose a possible solution for digitizing the vacation exchange process at Karlstad municipality. On the basis of requirements gathered by interviewing the future end-users, as well as investigating technical constraints imposed by current systems in place at Karlstad municipality, a PoC was designed. The PoC was implemented according to the design and thereby conforms to the requirements specification, however, five out of the 22 set requirements werenot implemented in the PoC. Still, the developed PoC provides Karlstad municipality with a feasible way to digitize its vacation management system. As mentioned in Section 5.2, the account directory hierarchy was based on the organizational diagram of the city management at Karlstad municipality. Before carrying out any further developments of the e-service, I strongly suggest a thorough scrutiny of the account directory in place at Karlstad municipality. In addition, I suggest that more frequent checks against the account directory are made. In other words, when the department manager logs into the vacation exchange e- service to process applications, and the applications are to be fetched, the name or personal identity number in the application could be matched against the account directory. Another possible improvement could be to carry out the matching of the

55 56 CHAPTER 7. CONCLUSIONS application against the correct manager already during the retrieval, rather than storing the data within the application document in the application database. Bibliography

[1] Ved Antani. Mastering JavaScript. Community Experience Distilled. Birm- ingham, UK: Packt Publishing, 2016. isbn: 978-1-78528-134-1. url: http: //search.ebscohost.com/login.aspx?direct=true&db=nlebk&AN= 1163841&site=ehost-live. [2] Ben Augarten. Express.js Blueprints. Community Experience Distilled. Birm- ingham: Packt Publishing, 2015. isbn: 978-1-78398-302-5. url: https:// login.bibproxy.kau.se:8443/login?url=https://search.ebscohost. com/login.aspx?direct=true&db=nlebk&AN=993081&lang=sv&site= eds-live. [3] axios. axios/axios. original-date: 2014-08-18T22:30:27Z. Apr. 29, 2020. url: https://github.com/axios/axios (visited on 04/29/2020). [4] Alex Banks and Eve Porcello. Learning React: Functional Web Development with React and Redux. O’Reilly Media, Inc., 2017. [5] Bert Bos. Cascading Style Sheets. url: https://www.w3.org/Style/CSS/ Overview.en.html (visited on 04/20/2020). [6] Tim Bray. The JavaScript Object Notation (JSON) Data Interchange For- mat. Library Catalog: tools.ietf.org. url: https://tools.ietf.org/html/ rfc8259 (visited on 05/14/2020). [7] Ethan Brown. Web Development with Node and Express. O’Reilly Media, Inc., 2014. [8] Matt Butcher. Mastering OpenLDAP : Configuring, Securing and Integrating Directory Services. From Technologies to Solutions. Birmingham: Packt Pub- lishing, 2007. isbn: 978-1-84719-102-1. url: http://search.ebscohost. com/login.aspx?direct=true&db=nlebk&AN=265385&site=ehost-live. [9] Gerald Carter. LDAP System Administration. O’Reilly, 2003. [10] Subhashini Chellappan and Dharanitharan Ganesan. MongoDB Recipes: With Data Modeling and Query Building Strategies. Apress, 2020.

57 58 BIBLIOGRAPHY

[11] MDN contributors. CSS basics. MDN Web Docs. url: https://developer. mozilla.org/en-US/docs/Learn/Getting_started_with_the_web/CSS_ basics (visited on 04/20/2020). [12] MongoDB contributors. Documents — MongoDB Manual. Documents - Mon- goDB Manual. url: https://docs.mongodb.com/manual/core/document (visited on 04/21/2020). [13] Bruno Joseph D’Mello, Mithun Satheesh, and Jason Krol. Web Development with MongoDB and Node - Third Edition. Vol. Third edition. Birmingham, UK: Packt Publishing, 2017. isbn: 978-1-78839-508-3. url: https://login. bibproxy.kau.se:8443/login?url=https://search.ebscohost.com/ login.aspx?direct=true&db=nlebk&AN=1610531&lang=sv&site=eds- live. [14] Cyrus Dasadia and Amol Nayak. MongoDB Cookbook - Second Edition. Vol. Second edition. Quick Answers to Common Problems. Birmingham: Packt Publishing, 2016. isbn: 978-1-78528-998-9. url: https : / / login . bibproxy.kau.se:8443/login?url=https://search.ebscohost.com/ login.aspx?direct=true&db=nlebk&AN=1151010&lang=sv&site=eds- live. [15] John Dean. Web Programming with HTML5, CSS, and JavaScript. Jones & Bartlett Learning, 2019. [16] Fernando Doglio. REST API Development with Node.js. Apress, 2018. [17] Clayton Donley. LDAP programming management and integration. Pearson Education, 2003. [18] Express contributors. Express basic routing. Library Catalog: expressjs.com. url: https://expressjs.com/en/starter/basic-routing.html (visited on 04/21/2020). [19] ForgeRock. OpenDJ Community Edition. url: https://forgerock.github. io/opendj-community-edition/ (visited on 04/21/2020). [20] Marijn Haverbeke. Eloquent JavaScript. Third edition. No Starch Press, 2018. [21] Simon Holmes. Mongoose for Application Development. Packt Publishing Ltd., 2013. isbn: 978-1-78216-819-5. [22] Shama Hoque. Full-Stack React Projects. 2nd Edition. 2020. BIBLIOGRAPHY 59

[23] Adam Horton and Ryan Vice. Mastering React. Community Experience Dis- tilled. Birmingham, UK: Packt Publishing, 2016. isbn: 978-1-78355-856-8. url: https : / / login . bibproxy . kau . se : 8443 / login ? url = https : //search.ebscohost.com/login.aspx?direct=true&db=nlebk&AN= 1183988&lang=sv&site=eds-live. [24] IBM. MEAN Stack: A Complete Guide | IBM. Library Catalog: www.ibm.com. Dec. 16, 2019. url: https://www.ibm.com/cloud/learn/mean-stack- explained (visited on 05/03/2020). [25] Karlstads kommun. Kommunledningskontorets organisation. Last Modified: 2012-08-27 Library Catalog: karlstad.se Publisher: Karlstads kommun. Feb. 25, 2019. url: https://karlstad.se/Kommun- och- politik/Kommunens- organisation/Forvaltningar-och-namnder/Kommunledningskontoret/ Organisation/ (visited on 05/08/2020). [26] Mark Massé. REST API Design Rulebook. O’Reilly Media, Inc., 2012. [27] Material-UI. Material-UI: A popular React UI framework. Library Catalog: material-ui.com. url: https://material-ui.com/ (visited on 04/21/2020). [28] MDN contributors. First-class Function. MDN Web Docs. Library Catalog: developer.mozilla.org. url: https://developer.mozilla.org/en- US/ docs/Glossary/First-class_Function (visited on 04/20/2020). [29] MDN contributors. JavaScript. MDN webbdokument. Library Catalog: developer.mozilla.org. url: https://developer.mozilla.org/sv-SE/docs/ Web/JavaScript (visited on 04/20/2020). [30] MDN contributors. Learn to style HTML using CSS. MDN Web Docs. Li- brary Catalog: developer.mozilla.org. url: https://developer.mozilla. org/en-US/docs/Learn/CSS (visited on 04/20/2020). [31] MDN contributors. Using Promises. MDN Web Docs. Library Catalog: developer.mozilla.org. url: https://developer.mozilla.org/en-US/docs/ Web/JavaScript/Guide/Using_promises (visited on 05/07/2020). [32] MDN contributors. What is CSS? MDN Web Docs. Library Catalog: developer.mozilla.org. url: https://developer.mozilla.org/en-US/docs/ Learn/CSS/First_steps/What_is_CSS (visited on 04/20/2020). [33] MongoDB contributors. Databases and Collections — MongoDB Manual. Databases and Collections - MongoDB Manual. url: https://docs.mongodb. com/manual/core/databases-and-collections (visited on 04/21/2020). [34] MongoDB contributors. Introduction to MongoDB — MongoDB Manual. In- troduction to MongoDB - MongoDB Manual. url: https://docs.mongodb. com/manual/introduction (visited on 04/21/2020). 60 BIBLIOGRAPHY

[35] MongoDB contributors. Read Isolation, Consistency, and Recency — Mon- goDB Manual. url: https://docs.mongodb.com/manual/core/read- isolation-consistency-recency (visited on 05/07/2020). [36] MongoDB contributors. Replication — MongoDB Manual. url: https : / / docs . mongodb . com / manual / core / read - isolation - consistency - recency (visited on 05/07/2020). [37] Mongoose. Mongoose v5.9.10: API docs. url: https://mongoosejs.com/ docs/api.html#schematype_SchemaType (visited on 04/21/2020). [38] Mongoose. Mongoose v5.9.10: Schemas. url: https://mongoosejs.com/ docs/guide.html (visited on 04/21/2020). [39] Andrew Morgan. The Modern Application Stack – Part 1: Introducing The MEAN Stack | MongoDB Blog. MongoDB. Sept. 5, 2017. url: https:// www.mongodb.com/blog/post/the-modern-application-stack-part-1- introducing-the-mean-stack (visited on 05/03/2020). [40] Robin Nixon. Learning PHP, MySQL, JavaScript, CSS & HTML5. 2nd Edi- tion. O’Reilly, 2012. [41] Node.js. Node.js. Node.js. Library Catalog: nodejs.org. url: https://nodejs. org/en/ (visited on 04/21/2020). [42] npm. About npm | npm Documentation. url: https://docs.npmjs.com/ about-npm/ (visited on 04/21/2020). [43] Oracle. Chapter 4 The Directory Information Tree. url: https://docs. oracle.com/cd/E19901-01/817-7607/dit.html (visited on 05/07/2020). [44] Passport.js. passport-ldapauth. Passport.js. url: http://www.passportjs. org/packages/passport-ldapauth/ (visited on 05/07/2020). [45] Passport.js. Passport.js. Passport.js. url: http://www.passportjs.org/ (visited on 04/27/2020). [46] React. Component State – React. Library Catalog: reactjs.org. url: https: //reactjs.org/docs/faq-state.html (visited on 04/21/2020). [47] React. Components and Props – React. Library Catalog: reactjs.org. url: https://reactjs.org/docs/components- and- props.html (visited on 04/21/2020). [48] React. How to Contribute – React. Library Catalog: reactjs.org. url: https: //reactjs.org/docs/how-to-contribute.html (visited on 04/21/2020). [49] React. React – A JavaScript library for building user interfaces. Library Catalog: reactjs.org. url: https://reactjs.org/ (visited on 04/21/2020). BIBLIOGRAPHY 61

[50] React. React.Component – React. Library Catalog: reactjs.org. url: https: //reactjs.org/docs/react-component.html (visited on 04/21/2020). [51] React Training. ReactTraining/react-router. GitHub. url: https://github. com/ReactTraining/react-router (visited on 05/08/2020). [52] ReactEnlightenment.com. JSX - What Is a JSX? & Introduction to Ad- vanced. Library Catalog: www.reactenlightenment.com Section: 1. url: https: / / www . reactenlightenment . com / react - jsx / 5 . 1 . html (visited on 04/21/2020). [53] RESTfulAPI.net. HTTP Methods – REST API Verbs – REST API Tutorial. Library Catalog: restfulapi.net. url: https : / / restfulapi . net / http - methods/ (visited on 05/03/2020). [54] Fielding Roy Thomas. Fielding Dissertation: CHAPTER 5: Representational State Transfer (REST). 2000. url: https://www.ics.uci.edu/~fielding/ pubs/dissertation/rest_arch_style.htm (visited on 04/22/2020). [55] Cássio de Sousa Antonio. Pro React. Apress, 2015. [56] Vasan Subramanian. Pro MERN Stack: Full Stack Web App Development with Mongo, Express, React, and Node. Apress, 2017. isbn: 978-1-4842-2653- 7. [57] W3. CSS current work & how to participate. url: https://www.w3.org/ Style/CSS/current-work (visited on 05/12/2020). [58] Marc Wandschneider. Learning Node.js A Hands-On Guide to Building Web Applications in JavaScript. Addison-Wesley, 2013. [59] WHATWG. HTML Standard. url: https : / / html . spec . whatwg . org/ (visited on 05/12/2020). [60] WHATWG. HTML Standard. url: https : / / html . spec . whatwg . org / multipage/introduction.html#a-quick-introduction-to-html (visited on 04/20/2020). [61] Wikipedia contributors. ECMAScript. In: Wikipedia. Apr. 10, 2020. url: https://en.wikipedia.org/w/index.php?title=ECMAScript&oldid= 950091697 (visited on 04/20/2020). [62] Wikipedia contributors. HTML - Wikipedia. url: https://en.wikipedia. org/wiki/HTML (visited on 04/20/2020). [63] Eddy Wilson and Iriarte Koroliova. MERN Quick Start Guide: Build web applications with MongoDB, Express.js, React, and Node. Packt Publishing, 2018. 62 BIBLIOGRAPHY

[64] Neil Wilson. Glossary of LDAP Terms. LDAP.com. Library Catalog: ldap.com. Apr. 27, 2018. url: https://ldap.com/glossary-of-ldap-terms/ (visited on 04/21/2020). [65] Neil Wilson. Learn About LDAP. LDAP.com. Library Catalog: ldap.com. Apr. 24, 2018. url: https://ldap.com/learn-about-ldap/ (visited on 04/21/2020).