Merge branch 'dev'

# Conflicts: # README.md # docs/setup.md # docs/userGuide.md # mkdocs.yml # package-lock.json # package.json
KatjaGlassConsulting · Feb 21, 2022 · b7ab594 · b7ab594
2 parents e270325 + 8367202
commit b7ab594
Show file tree

Hide file tree

Showing 70 changed files with 8,313 additions and 3,433 deletions.
diff --git a/README.md b/README.md
@@ -2,15 +2,17 @@
 
 This WebApplication is designed to allow the tracking of working hours in Excel which can then be uploaded to the Kimai Timetracking application.
 
+![Screenshot of login screen](./docs/img/timesheet_to_kimai_01.gif)
+
 [Kimai](https://www.kimai.org/) is an open-source free time-tracking application which comes with a lot of functionality and capabilities. There might be situations where the times should be tracked in Excel and finally be uploaded to Kimai. TimeKex is designed to support this process.
 
 The documentation of TimeKex as well as a running demonstration instance is accessible [here](https://katjaglassconsulting.github.io/TimeKex/).
 
 ## Status
 
-This repository is under development. The first release is planned for Q1-2022. In this repository the source code and documentation for TimeKex will be made available.
+TimeKex is available in the current version which does not contain tests. The source code is available under the MIT license which allows a flexible and generic usage and modifications without warrenty.
 
-![Under Construction image](./docs/img/under_constructions.png)
+The demonstration is running on the stable Kimai demo instance. Be aware that this demo instances is regularily rebuild.
 
 ## License
 
@@ -24,7 +26,7 @@ The content files like documentation are released under [CC-BY-4.0](https://crea
 
 ## Contribution
 
-Contributions are very welcome. Be aware that your contribution is under the above licenses. If you would like to contribute for tests, please do so using Cypress.
+Contributions are very welcome. Be aware that your contribution is under the above licenses. If you would like to contribute for tests, I would recommend Cypress which is my personal preference. 
 
 ## Re-use
 

diff --git a/docs/adminGuide.md b/docs/adminGuide.md
@@ -0,0 +1,37 @@
+# Admin Panel
+
+Via the Admin Panel it is possible to create Customer, Projects and Activities via an Excel file. If you need to import Customer and Projects together with a lot of other fields, I recommend to use the Kimai command line functionality as in the [documentation](https://www.kimai.org/documentation/imports.html){target=_blank}. For a quick creation, e.g. for test data, this API based approach can be used.
+
+## Excel File
+
+Customer, Projects and Activities can automatically be created through an Excel file. An example file is available under "./exampleFiles/TimeKex_createData.xlsx"
+
+![Example Excel File](./img/example_admin_create_00.png)
+
+## Create DB Data
+
+To actually create the Customer, Projects and Activities, the "Admin" panel can be used. Depending on the configuration, this panel might not be visible for the currently logged in user.
+
+When the "adminUser" configration is set, then only these users mentioned there will have the "Admin" panel available. If the config does not contain any user, the Admin panel is visible for all.
+
+```
+    "adminUser" : ["anna_admin","susan_super"]
+```
+
+By clicking "Create DB Data" the excel file with the specific structure can be selected to create the corresponding entries.
+
+![Screenshot to perform "Create DB Data"](./img/example_admin_create_01.png)
+
+## DB Data creation successful
+
+After loading the Excel file, the Customers, Projects and Activities are created via the Kimai API. The success messages can be reviewed on the screen.
+
+![Screenshot of status messages](./img/example_admin_create_02.png)
+
+**Issues:** When something should be created which already exists, it is not created. Other issues could be available, e.g. the user does not have admin access. This will be printed. Also when a project cannot be created, for example as no customer had been provided, an issue message will appear.
+
+## Check back in Kimai
+
+You can log into Kimai to see that these projects, customers and activities has been created.
+
+![Screenshot of Kimai created activities](./img/example_admin_create_03.png)
diff --git a/docs/img/example_admin_create_00.png b/docs/img/example_admin_create_00.png
diff --git a/docs/img/example_admin_create_01.png b/docs/img/example_admin_create_01.png
diff --git a/docs/img/example_admin_create_02.png b/docs/img/example_admin_create_02.png
diff --git a/docs/img/example_admin_create_03.png b/docs/img/example_admin_create_03.png
diff --git a/docs/img/folder_structure_build.png b/docs/img/folder_structure_build.png
diff --git a/docs/img/layout_excel_sheet.png b/docs/img/layout_excel_sheet.png
diff --git a/docs/img/layout_main_bar.png b/docs/img/layout_main_bar.png
diff --git a/docs/img/layout_week_display.png b/docs/img/layout_week_display.png
diff --git a/docs/img/layout_week_display_issues.png b/docs/img/layout_week_display_issues.png
diff --git a/docs/img/layout_week_selection.png b/docs/img/layout_week_selection.png
diff --git a/docs/img/login_screen.png b/docs/img/login_screen.png
diff --git a/docs/img/timesheet_to_kimai_01.gif b/docs/img/timesheet_to_kimai_01.gif
diff --git a/docs/index.md b/docs/index.md
@@ -12,15 +12,11 @@ This WebApplication is designed to allow the tracking of working hours in Excel
 
 <a href="https://www.kimai.org/" target="_blank">Kimai</a> is an open-source free time-tracking application which comes with a lot of functionality and capabilities. There might be situations where the times should be tracked in Excel and finally be uploaded to Kimai. TimeKex is designed to support this process.
 
-## Status
-
-This repository is under development. The first release is planned for Q1-2022. In this repository the source code and documentation for TimeKex will be made available.
+![Screenshot of login screen](./img/timesheet_to_kimai_01.gif)
 
-![Under Construction image](./img/under_constructions.png)
-
-## Prerequisites:
+## Status
 
-To be able to run TimeKex, a running instance of Kimai is required together with a user and an API key of this user. The API password can be set in Kimai via "profile", "API" and then "API Password".
+TimeKex is available in the current version which does not contain tests. The source code is available under the MIT license which allows a flexible and generic usage and modifications without warrenty.
 
-There is a stable demonstration version available for Kimai which can be used for demonstration purposes (<a href="https://demo-stable.kimai.org/de/login" target="_blank">linked here</a>). To checkout demo users and specifically the API password of a demo user, check the <a href="https://www.kimai.org/demo/" target="_blank">demo information page</a>.
+The demonstration is running on the stable Kimai demo instance. Be aware that this demo instances is regularily rebuild.
 
diff --git a/docs/setup.md b/docs/setup.md
@@ -1,5 +1,11 @@
 # Setup
 
+## Prerequisites
+
+To be able to run TimeKex, a running instance of Kimai is required together with a user and an API key of this user. The API password can be set in Kimai via "profile", "API" and then "API Password".
+
+There is a stable demonstration version available for Kimai which can be used for demonstration purposes (<a href="https://demo-stable.kimai.org/de/login" target="_blank">linked here</a>). To checkout demo users and specifically the API password of a demo user, check the <a href="https://www.kimai.org/demo/" target="_blank">demo information page</a>.
+
 ## Local Development and Compilation
 
 TimeKex is a ReactJS Web Application. To run a local development version, you can use NPM to install all dependencies and start or build the app. 
@@ -13,16 +19,16 @@ TimeKex is a ReactJS Web Application. To run a local development version, you ca
 
 ## Deployment
 
-The TimeKex web application is a simple static HTML fileset which can run locally or on any Webserver. If you are not familar with NPM, you simply can copy the application from the GitHub branch `"gh-deploy"`. Copy all files from the "app" folder to any location (local PC or webserver) and start the app by open "index.html".
+The TimeKex web application is a simple static HTML fileset which can run locally or on any Webserver. When you have build the app, it can simply be started by opening "index.html".
+
+The final build folder contains next to the config.js also additional example configurations files which you might want to try. Just copy the content as config.js to apply the corresponding configuration. The current configuration files are using the Kimai demonstration server and users.
 
-TODO: Image of folder structure and arrow to index.html
+![Folder Structure](./img/folder_structure_build.png)
 
 ## Configuration
 
 There are some configurations possible which are set through a `config.json` file in the root folder of the application. Possible settings are explained here.
 
-TODO: clarify with Kimai to include exmaples from demo-stable
-
 ```json
 var config = {
     "kimaiAPI" : "https://XXX/api/",
@@ -40,8 +46,12 @@ ignoreActivities | No | Activities which should be ignored (not copied to Kimai,
 adminUser | No | The `admin` tab of the app is only displayed when the logged in user is in this list. When this item is not available, the corresponding tab is visible for everyone.
 username and password | No | When this is provided through the config, then there is no `Login` screen. This is only recommended for development purposes or when this application is run just locally by one person.
 
-## Excel Structure
+## Excel Structure Timesheets
+
+![Excel Sheet Structure](./img/layout_excel_sheet.png)
 
 The Excel file is expected in a specific format. When the Excel file should contain a different structure, for example different column names, this can be changed by a source code updated and re-compiling the app. The file `src/features/excelImport/ExcelSchema` is responsible to read in and map the corresponding Excel file to the specific object required for the application. Feel free to update the column names from the Excel file.
 
-The package [read-excel-file](https://gitlab.com/catamphetamine/read-excel-file) is used to read in the Excel file and use the corresponding schema for mapping. Please look into the package details to apply a different schema.
+The package [read-excel-file](https://gitlab.com/catamphetamine/read-excel-file) is used to read in the Excel file and use the corresponding schema for mapping. Please look into the package details to apply a different schema.
+
+For the Excel file it is very important that the first sheet contains the time data and that the first row starts with the column names. There can be additional sheets and additional columns in the Excel file. The column order is also not relevant. Example file is available under "./exampleFiles"
diff --git a/docs/userGuide.md b/docs/userGuide.md
@@ -1,3 +1,92 @@
-# User Guide
+# User Panel
+
+## Login
+
+Typically there will be a login required. This login needs the user name and API passwort. Please make sure to use the API password for Kimai and not the login password.
+
+The login can also be done automatically through the configuration. This can be used for testing purposes, when just one user should use the web application or when the application should be located for each user locally.
+
+```
+var config = {
+    "username" : "anna_admin",
+    "password" : "<PASSWORD>",
+    "kimaiAPI" : "https://demo-stable.kimai.org/api/",
+    ...
+}
+```
+
+If there is no automatic login, the login screen is displayed:
+
+![Screenshot of login screen](./img/login_screen.png)
+
+If invalid credentials are used, a modal is displayed to show this.
+
+## Process Flow
+
+The web application is designed to load times from Excel to Kimai. With the "Choose File" box, the timesheet Excel file can be selected. Data from the excel and from Kimai is loaded and compared. The main screen displays always week data starting with the last one from Excel and containing only those in the Excel file.
+
+The weeks can be changed easily with a forth and back button. After checking the content the "Send" button sends the update to Kimai. Additional time entries are added and if entries are available in Kimai which are not in the Excel file, these entries are deleted. Before deletion in Kimai is done, there is an extra confirmation screen to make sure not to delete entries which should not have been deleted.
+
+The following animation shows an example flow. Please see below for additional details.
+
+![Screenshot of login screen](./img/timesheet_to_kimai_01.gif)
+
+## Main Bar
+
+The main bar contains a button to load the timesheet data excel file and three status boxes. The first status box show the Excel File Status. In case of any issues, this box will be red. When the file is loaded successfully, it will be green.
+
+The "Kimai General Data Status" shows the status of the access to Kimai and when read in the general information, e.g. about customers, projects and activities. When there is an issue, the box will be red, this means the Kimai API is not set correctly or the server is currently not reachable. In case of issues, you might want to check the development console which shows the exact error.
+
+After loading general data, the time sheet data for the user is loaded. The status of this loading is shown through the "Kimai Timesheet Status".
+
+![Screenshot of main bar](./img/layout_main_bar.png)
+
+## Excel File
+
+The Excel file should contain at least the following columns which must be on the first sheet and starting in the first row (order of columns irrelevant): Line number, Date, Client, Project, Activity, chargeable, chargeable (correction), Tasks, Start, End
+
+The chargeable (correction) is optional and can also be omitted.
+
+An example could look like the following:
+
+![Excel Sheet Screenshot](./img/layout_excel_sheet.png)
+
+## Per Week Display
+
+When the Excel file is loaded, the per-week display is shown. The week can easily be changed via the week-selection-box. Only weeks available in the Excel file are included.
+
+![Screenshot of week selection box](./img/layout_week_selection.png)
+
+The main information box of the week displey shows a button to send the timesheet data to kimai and a summary of the hours of this week and how much of those hours are billable.
+
+![Screenshot of week display](./img/layout_week_display.png)
+
+Below is the list of entries which are in the Excel file and in Kimai. The "Line" is coming from the Excel file line number. "ID" is the internal Kimai ID of that timesheet item. If a row has no ID, that means this row is not in Kimai. The action which is also displayed in the very first column for such a case is to "add" this entry.
+
+There could also be entries in Kimai which are not in the Excel file (missing line, but available ID), in such a case the action would be "delete". 
+
+Some entries should be ignored, for example there could be "vacations" which should not be included in Kimai or which should not be deleted from Kimai as this might be included differenty. Such "ignore" items are maintained in the configuration file of the web application.
+
+```
+var config = {
+    "ignoreActivities" : ["Vacation","Public Holiday"],
+    ...
+}
+```
+
+Whenever there is something special, there is an "i"nformation icon. With the mouse over effect additional hints are printed.
+
+After clicking the "Send to Kimai" button, the actions are performed. When the action was succcessful, the complete row becomes green and the action text changed from "add" to "added" and from "delete" to "deleted". If issues appeared, the row will be red and issue information can be displayed via the mouseover effect for the "i".
+
+## Invalid Data
+
+The web application is checking some typical errors, that these are available before sending time entries to Kimai. The most common issue is that the Project or Activity does not exist in Kimai. In such cases the lines will be marked as "error" lines which displays an additional error text hint hidden behind the "i". Time overlaps should ideally also not be available and are highlighted. As such issues are not critical, these still can be added.
+
+![Screenshot of week display](./img/layout_week_display_issues.png)
+
+When clicking the "Send to Kimai" button, only "add" and "delete" actions are executed.
+
+
+
+
 
-TODO
diff --git a/exampleFiles/TimeKex_createData.xlsx b/exampleFiles/TimeKex_createData.xlsx
diff --git a/exampleFiles/TimeKex_timeData.xlsx b/exampleFiles/TimeKex_timeData.xlsx
diff --git a/exampleFiles/TimeKex_timeDataChanged.xlsx b/exampleFiles/TimeKex_timeDataChanged.xlsx
diff --git a/exampleFiles/TimeKex_timeDataInvalids.xlsx b/exampleFiles/TimeKex_timeDataInvalids.xlsx
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -8,8 +8,10 @@ copyright: Copyright &copy; 2021 Katja Glaß
 
 nav:
   - Home: index.md
-  - User Guide: userGuide.md
-  - Setup: setup.md
+  - Documentation: 
+    - User Panel: userGuide.md
+    - Admin Panel: adminGuide.md
+    - Setup: setup.md
   - Live Demo:
     - ./app/index.html
 
@@ -43,4 +45,5 @@ markdown_extensions:
   - pymdownx.highlight
   - pymdownx.superfences
   - pymdownx.snippets:
-      base_path: .
+      base_path: .
+  - attr_list