diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..80ac31f --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,9 @@ +version: 2 +updates: + - package-ecosystem: npm + directory: "/" + schedule: + interval: daily + time: "06:00" + timezone: Europe/Berlin + open-pull-requests-limit: 99 \ No newline at end of file diff --git a/docs/demo-app/demoApp.md b/docs/demo-app/demoApp.md index 7f2cc8f..5ae9903 100644 --- a/docs/demo-app/demoApp.md +++ b/docs/demo-app/demoApp.md @@ -4,7 +4,7 @@ sidebar_position: 1 # Demo App -While our main focus remains ob the backend of KADAI, we additionaly provide an example frontend in form of a Demo App. This is only an example, as KADAI frontend can be implemented differently for specific use cases. Here is what the demo app looks like: +While our main focus remains ob the backend of KADAI, we additionally provide an example frontend in form of a Demo App. This is only an example, as KADAI frontend can be implemented differently for specific use cases. Here is what the demo app looks like: ![Demo App](static/demo-app.png) ### [Click here to go to the Demo App](https://kadai-io.azurewebsites.net/kadai) @@ -15,7 +15,7 @@ In order to login as admin, you need to use the following credentials: > > password: admin -Then, you will be forwarded to the **KADAI Administration**. There are also other users available. +Then, you will be forwarded to the **KADAI Administration**. There are other users available. ### Navigation in the Demo App To navigate between different pages, select the menu using the three point icon on the upper left. Then, you can choose between the categories shown in the bucket list below. diff --git a/docs/demo-app/static/demo-app.png b/docs/demo-app/static/demo-app.png index 17ce255..65780ac 100644 Binary files a/docs/demo-app/static/demo-app.png and b/docs/demo-app/static/demo-app.png differ diff --git a/docs/user-guide/adapter/_category_.json b/docs/user-guide/adapter/_category_.json index f535be3..eacbe1a 100644 --- a/docs/user-guide/adapter/_category_.json +++ b/docs/user-guide/adapter/_category_.json @@ -3,6 +3,6 @@ "position": 7, "link": { "type": "generated-index", - "description": "Learn more about KADAI Adapter, an application used to connect KADAI to other systenms." + "description": "Learn more about KADAI Adapter, an application used to connect KADAI to other systems." } } \ No newline at end of file diff --git a/docs/user-guide/adapter/gettingStarted.md b/docs/user-guide/adapter/gettingStarted.md index f785395..c67be4f 100644 --- a/docs/user-guide/adapter/gettingStarted.md +++ b/docs/user-guide/adapter/gettingStarted.md @@ -1,5 +1,5 @@ # Getting Started -In this article, the set up of the Adapter is explained step by step. Additionally, you can try out some of the functionalities of the Adapter following the instructions in this article. +In this article, the set-up of the Adapter is explained step by step. Additionally, you can try out some of the functionalities of the Adapter following the instructions in this article. ## What you'll need @@ -8,7 +8,7 @@ In this article, the set up of the Adapter is explained step by step. Additional - maven - Camunda Modeler - Postgres or Docker (to set up postgres database) -- optional: postman (makes REST API requests easier) +- optional: Postman (makes REST API requests easier) - Working KADAI application (see [here](../getting-started/exampleSpringBoot.md) for instructions) Note: Please name your packages, folders and files exactly like in the example! @@ -31,12 +31,12 @@ Add following dependencies to the dependencies section of your pom: io.kadai kadai-adapter-camunda-outbox-rest-spring-boot-starter - 3.1.0 + 9.0.0 org.jboss.resteasy resteasy-servlet-spring-boot-starter - 6.1.1.Final + 6.2.0.Final org.camunda.spin @@ -70,7 +70,7 @@ Then, add a repository to the pom: ``` -Add the following file to your resources folder: +Add the following file to your "resources" folder: ### kadai-outbox.properties ``` @@ -194,17 +194,17 @@ Add following dependencies to the dependencies section of your pom (if they don' io.kadai kadai-adapter - 3.1.0 + 9.0.0 io.kadai kadai-adapter-camunda-system-connector - 3.1.0 + 9.0.0 io.kadai kadai-adapter-kadai-connector - 3.1.0 + 9.0.0 com.ibm.db2 @@ -316,7 +316,7 @@ kadai.jobs.enabled=false ## Step 4: Add SPIs to your Adapter application SPIs need to be additionally specified in the Adapter application. You can read more about SPIs [here](../features/howToUseServiceProviderInterfaces.md). -The necessary SPI for the Adapter application can be build as follows: First, create a new package with the name taskrouting. Then, create a class in the package taskrouting with the name ExampleTaskRouter. It should look like this: +The necessary SPI for the Adapter application can be built as follows: First, create a new package with the name `taskrouting`. Then, create a class in the package `taskrouting` with the name ExampleTaskRouter. It should look like this: ``` package com.example.demo.taskrouting; //or your own path depending on your packages import io.kadai.common.api.KadaiEngine; @@ -354,27 +354,27 @@ Then, start your KADAI application. Start your camunda app next, and login. Last ## Step 6: Try out different functionalities of Adapter. -1. Start a process with a User Task in Camunda. The User Task should be imported to KADAI automatically. You can check it by first knowing the name of the user task from the started process, then make a postgres GET request to KADAI using the following request, entering the name (or just substring of the name) of the user task for the "name-like" attribute +1. Start a process with a User Task in Camunda. The User Task should be imported to KADAI automatically. You can check it by first knowing the name of the user task from the started process, then make a postgres GET request to KADAI using the following request, entering the name (or just substring of the name) of the user task for the "name-like" attribute. ``` GET http://localhost:8080/kadai/api/v1/tasks?name-like=Say hello ``` Here we assume that the name of the user task is "Say hello to demo", but you can set the name differently by opening the `process.bpmn` file in the camunda application and set the name attribute in ``differently. - Make sure that the correct port number is used for KADAI request. You can check the port number in `application.properties` of KADAI under `server.port`. If not specified, then the default port is 8080. You have to authenticate yourself using Basic Auth: In postman, go to the "Authorization" tab. There, select basicAuth and type "admin" as user and "admin" as password. Make sure enableCsrf is set to false in the properties of the KADAI application. + Make sure that the correct port number is used for KADAI request. You can check the port number in `application.properties` of KADAI under `server.port`. If not specified, then the default port is 8080. You have to authenticate yourself using Basic Auth: In Postman, go to the "Authorization" tab. There, select basicAuth and type "admin" as user and "admin" as password. Make sure enableCsrf is set to false in the properties of the KADAI application. The output of the request in Postman should look like this: ![Local Image](../static/adapter/show-tasks.png) -2. Claim the KADAI Task from the previous step using postman. Make sure you add the following property to the `application.properties` file of the adapter application: ``kadai.adapter.camunda.claiming.enabled=true``, then restart the adapter. To send the POST request, use the same authorization as in the previous step. The Task should get claimed in Camunda automatically. +2. Claim the KADAI Task from the previous step using Postman. Make sure you add the following property to the `application.properties` file of the adapter application: ``kadai.adapter.camunda.claiming.enabled=true``, then restart the adapter. To send the POST request, use the same authorization as in the previous step. The Task should get claimed in Camunda automatically. ``` POST http://localhost:8080/kadai/api/v1/tasks/{taskid}/claim ``` You can check that the task in KADAI is also claimed by making the same GET Request as in Step 1 and see the `claimed` attribute. -3. Complete the KADAI Task from previous step using postman. To send the POST request, use the same authorization as in the previous step. The Task should disappear from Camunda Tasklist. +3. Complete the KADAI Task from the previous step using Postman. To send the POST request, use the same authorization as in the previous step. The Task should disappear from Camunda Tasklist. ``` POST http://localhost:8080/kadai/api/v1/tasks/{taskid}/complete ``` -More functionalities like the cancelling of a claimed task and their URLs can be found in the [full documentation of the REST-API](https://kadai-io.azurewebsites.net/kadai/docs/rest/rest-api.html). \ No newline at end of file +More functionalities like the cancelling of a claimed task and their URLs can be found in the [full documentation of the REST-API](https://kadai-io.azurewebsites.net/kadai/swagger-ui/index.html). \ No newline at end of file diff --git a/docs/user-guide/configuration/classificationAndServiceLevel.md b/docs/user-guide/configuration/classificationAndServiceLevel.md index ee5e8ac..63e5a6c 100644 --- a/docs/user-guide/configuration/classificationAndServiceLevel.md +++ b/docs/user-guide/configuration/classificationAndServiceLevel.md @@ -7,9 +7,9 @@ sidebar_position: 4 The configuration of these parameters is in the file ```kadai.properties```. Some parameters allow multiple values specified as a list. In this case, individual values are separated by a configurable separator. Use the *propertiesSeparator* parameter to specify it. If none is provided, the default is "|". If you specify a propertiesSeparator, no list item in the properties file can contain any character from the propertiesSeparator. -| Parameter | Description | Sample Value | -|----------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------|--------------------------------------------| -| kadai.domains | A list of domains for Classifications and Workbaskets | DOMAIN_C \| DOMAIN_TEST | -| kadai.classification.types | A list of Classification types (case insensitive) | TASK \| document | +| Parameter | Description | Sample Value | +|-------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------|--------------------------------------------| +| kadai.domains | A list of domains for Classifications and Workbaskets | DOMAIN_C \| DOMAIN_TEST | +| kadai.classification.types | A list of Classification types (case insensitive) | TASK \| document | | kadai.classification.categories.\ (for example kadai.classification.categories.document) | A list of classification categories for each type | EXTERNAL \| manual \| autoMAtic \| Process | -| kadai.servicelevel.validation.enforce | allows user to create Tasks with date-attributes independent of the serviceLevel of the Classifications | true | +| kadai.servicelevel.validation.enforce | allows user to create Tasks with date-attributes independent of the serviceLevel of the Classifications | true | diff --git a/docs/user-guide/configuration/database.md b/docs/user-guide/configuration/database.md index 668693a..ec0889e 100644 --- a/docs/user-guide/configuration/database.md +++ b/docs/user-guide/configuration/database.md @@ -4,11 +4,11 @@ sidebar_position: 1 # Database -In order to use KADAI, you need to create a database yourself, and then specify it through the [DataSource](#datasource). You can see the list of the supported databases [here](../getting-started/supportedEnvironments.md). -The recommended page size for the database is 32 k. It's needed to create the database schema. The sort order of query results can be changed by the collating sequence that is specified at database creation. The default for the most databases is a case sensitive sort order. If you want query results to be sorted case insensitively, you should specify an appropriate collating sequence. +To use KADAI, you need to create a database yourself, and then specify it through the [DataSource](#datasource). You can see the list of the supported databases [here](../getting-started/supportedEnvironments.md). +The recommended page size for the database is 32 k. It's necessary to create the database schema. The sort order of query results can be changed by the collating sequence specified in database creation. The default for most databases is a case-sensitive sort order. If you want query results to be sorted case insensitively, you should specify an appropriate collating sequence. - Page size: 32k -- Encoding: UTF-8 +- Encoding: UTF-8 - Collating sequence examples: - db2 (case sensitive): IDENTITY - postgres (case sensitive): de_DE.UTF-8 @@ -26,7 +26,7 @@ CREATE DATABASE WITH ENCODING 'UTF8' LC_COLLATE='de_DE.UTF-8'; ### DataSource -KADAI connects to the database via a DataSource. It does not support XADataSources for connections to databases. The DataSource can be specified during the creation of KadaiConfiguration. For example as following: +KADAI connects to the database via a DataSource. It does not support XADataSources for connections to databases. The DataSource can be specified during the creation of KadaiConfiguration. For example, as following: ``` new KadaiConfiguration.Builder(dataSource, true, schemaName, false) .initKadaiProperties(propertiesFileName, delimiter) @@ -41,12 +41,18 @@ spring.datasource.password=sa ``` ### SchemaName and Prefilling the Database -Additionally to the DataSource, you can also configure the schemaName. It can be specified during the creation of KadaiConfiguration, as seen in the example above. The default schemaName is "KADAI". The schemaName can also be changed by setting the parameter "kadai.schemaName" in the ```application.properties``` file: +Additionally to the DataSource, you can also configure the schemaName. +It can be specified during the creation of KadaiConfiguration, as seen in the example above. +The default schemaName is `KADAI. +The schemaName can also be changed by setting the parameter "kadai.schemaName" +in the ```application.properties``` file: ``` kadai.schemaName=KADAI ``` -Additionaly to that, you can configure KADAI so that it prefills the database with sample data. You can find sample data in the folder ```common/kadai-common-data/src/main/resources/sql/sample-data```. To do that, set the "generateSampleData" property in the ```application.properties``` file to true: +Additionally to that, you can configure KADAI so that it prefills the database with sample data. +You can find sample data in the folder ```common/kadai-common-data/src/main/resources/sql/sample-data```. +To do that, set the "generateSampleData" property in the ```application.properties``` file to true: ``` generateSampleData=true ``` @@ -61,8 +67,8 @@ KadaiEngine buildKadaiEngine (KadaiConfiguration configuration, ConnectionManage The default mode is PARTICIPATE. -| mode | description | -|--------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| PARTICIPATE | KADAI participates in surrounding global transactions. It acquires and releases connections at begin / end of each API call and relies on the infrastructure to do the commit. | -| AUTOCOMMIT | KADAI commits each single API call separately. | -| EXPLICIT | KADAI doesn't acquire, commit or close connections. The client is responsible for opening a connection, passing it to KADAI, committing or rolling it back. In order to close a connection, the client has to call either KadaiEngine.closeConnection() or KadaiEngine.setConnection(null). | +| mode | description | +|-------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| PARTICIPATE | KADAI participates in surrounding global transactions. It acquires and releases connections at begin / end of each API call and relies on the infrastructure to do the commit. | +| AUTOCOMMIT | KADAI commits each single API call separately. | +| EXPLICIT | KADAI doesn't acquire, commit or close connections. The client is responsible for opening a connection, passing it to KADAI, committing or rolling it back. In order to close a connection, the client has to call either KadaiEngine.closeConnection() or KadaiEngine.setConnection(null). | diff --git a/docs/user-guide/configuration/holidaysAndWorkingDays.md b/docs/user-guide/configuration/holidaysAndWorkingDays.md index 0956fd7..e0094e3 100644 --- a/docs/user-guide/configuration/holidaysAndWorkingDays.md +++ b/docs/user-guide/configuration/holidaysAndWorkingDays.md @@ -19,9 +19,9 @@ Holidays can be customized. This is relevant because time on a holiday doesn't c ## Working time -- `kadai.workingTime.schedule.MONDAY` : Working time on Monday, e. g. 09:00-18:00 -- ``kadai.workingTime.schedule.TUESDAY`` : Working time on Tuesday, e. g. 09:00-18:00 -- ``kadai.workingTime.schedule.WEDNESDAY`` : Working time on Wednesday, e. g. 09:00-18:00 -- ``kadai.workingTime.schedule.THURSDAY`` : Working time on Thursday, e. g. 09:00-18:00 -- ``kadai.workingTime.schedule.FRIDAY`` : Working time on Friday, e. g. 09:00-18:00 +- ``kadai.workingTime.schedule.MONDAY`` : Working time on Monday, e.g., 09:00–18:00 +- ``kadai.workingTime.schedule.TUESDAY`` : Working time on Tuesday, e.g., 09:00–18:00 +- ``kadai.workingTime.schedule.WEDNESDAY`` : Working time on Wednesday, e.g., 09:00–18:00 +- ``kadai.workingTime.schedule.THURSDAY`` : Working time on Thursday, e.g., 09:00–18:00 +- ``kadai.workingTime.schedule.FRIDAY`` : Working time on Friday, e.g., 09:00–18:00 - ``kadai.workingTime.timezone`` : Time zone, e. g. UTC diff --git a/docs/user-guide/configuration/kadaiJobs.md b/docs/user-guide/configuration/kadaiJobs.md index 964faaf..f97217a 100644 --- a/docs/user-guide/configuration/kadaiJobs.md +++ b/docs/user-guide/configuration/kadaiJobs.md @@ -17,77 +17,77 @@ There is an example job configuration and execution at the end of this article. You can also configure the scheduler. The scheduler will initialize the first schedule for the jobs. Each run, the scheduler looks up which jobs are past their due date. These jobs get executed. The behavior of jobs and the scheduler in KADAI can be customized in the configuration file ```kadai.properties``` with the following parameters: ## Scheduler Configuration -| Parameter | Description | Default Value | -|------------------------------------------|----------------------------------------------------------------|---------------| +| Parameter | Description | Default Value | +|----------------------------------------|----------------------------------------------------------------|---------------| | kadai.jobs.scheduler.enabled | Enabling automated scheduling of jobs | true | | kadai.jobs.scheduler.initialStartDelay | Start delay before the first job gets scheduled | 100 | | kadai.jobs.scheduler.period | The time interval between the individual runs of the scheduler | 5 | | kadai.jobs.scheduler.periodTimeUnit | The unit for scheduler.initialStartDelay and scheduler.period | MINUTES | ## General Jobs Configuration -This configuration options are overwritten by job specific configuration options +These configuration options are overwritten by job-specific configuration options -| Parameter | Description | Default Value | -|-------------------------|-----------------------------------------------------------------------------|----------------------| -| kadai.jobs.maxRetries | number of automatic retries after a job has failed | 3 | -| kadai.jobs.batchSize | upper bound of how many tasks can be processed by one job | 100 | -| kadai.jobs.runEvery | period of time between the executions of jobs (Duration in ISO 8601 format) | P1D | -| kadai.jobs.firstRunAt | first time the job is run (DateTime n ISO 8601 format) | 2023-01-01T00:00:00Z | -| kadai.jobs.lockExpirationPeriod | period of time the lock is valid (Duration in ISO 8601 format). Should be longer than the longest possible job execution time | P2D | PT30M | +| Parameter | Description | Default Value | +|---------------------------------|-------------------------------------------------------------------------------------------------------------------------------|----------------------| +| kadai.jobs.maxRetries | number of automatic retries after a job has failed | 3 | +| kadai.jobs.batchSize | upper bound of how many tasks can be processed by one job | 100 | +| kadai.jobs.runEvery | period of time between the executions of jobs (Duration in ISO 8601 format) | P1D | +| kadai.jobs.firstRunAt | first time the job is run (DateTime n ISO 8601 format) | 2023-01-01T00:00:00Z | +| kadai.jobs.lockExpirationPeriod | period of time the lock is valid (Duration in ISO 8601 format). Should be longer than the longest possible job execution time | P2D | PT30M | ## TaskCleanupJob Configuration -| Parameter | Description | Default Value | -|--------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|---------------| -| kadai.jobs.cleanup.task.enable | Enabling automated cleanup of completed tasks after a period of time specified by job.runEvery | true | -| kadai.jobs.cleanup.task.minimumAge | the completed task can be deleted by the cleanup only after this period of time or later (Duration in ISO 8601 format) | P14D | -| kadai.jobs.cleanup.task.allCompletedSameParentBusiness | Prevent deletion of tasks if other tasks with same parent business process ID are not yet completed | true | -| kadai.jobs.cleanup.task.lockExpirationPeriod | period of time the lock is valid (Duration in ISO 8601 format). Should be longer than the longest possible job execution time | PT30M | +| Parameter | Description | Default Value | +|--------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------|---------------| +| kadai.jobs.cleanup.task.enable | Enabling automated cleanup of completed tasks after a period of time specified by job.runEvery | true | +| kadai.jobs.cleanup.task.minimumAge | the completed task can be deleted by the cleanup only after this period of time or later (Duration in ISO 8601 format) | P14D | +| kadai.jobs.cleanup.task.allCompletedSameParentBusiness | Prevent deletion of tasks if other tasks with same parent business process ID are not yet completed | true | +| kadai.jobs.cleanup.task.lockExpirationPeriod | period of time the lock is valid (Duration in ISO 8601 format). Should be longer than the longest possible job execution time | PT30M | ## WorkbasketCleanupJob Configuration -| Parameter | Description | Default Value | -|--------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|---------------| -| kadai.jobs.cleanup.workbasket.enable | Enable WorkbasketCleanupJob to cleanup completed workbaskets after a period of time if no pending tasks | true | -| kadai.jobs.cleanup.workbasket.lockExpirationPeriod | period of time the lock is valid (Duration in ISO 8601 format). Should be longer than the longest possible job execution time | PT30M | +| Parameter | Description | Default Value | +|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------|---------------| +| kadai.jobs.cleanup.workbasket.enable | Enable WorkbasketCleanupJob to cleanup completed workbaskets after a period of time if no pending tasks | true | +| kadai.jobs.cleanup.workbasket.lockExpirationPeriod | period of time the lock is valid (Duration in ISO 8601 format). Should be longer than the longest possible job execution time | PT30M | ## HistoryCleanupJob Configuration -| Parameter | Description | Default Value | -|--------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|---------------| +| Parameter | Description | Default Value | +|------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|---------------| | kadai.jobs.cleanup.history.simple.enable | Enables the HistoryCleanupJob to delete history events | false | -| kadai.jobs.cleanup.history.simple.minimumAge | a history event may only be deleted by the cleanup after this period of time or later (Duration in ISO 8601 format) | P14D | +| kadai.jobs.cleanup.history.simple.minimumAge | a history event may only be deleted by the cleanup after this period of time or later (Duration in ISO 8601 format) | P14D | | kadai.jobs.cleanup.history.simple.batchSize | upper bound of how many history events can be processed by one history cleanup job | 100 | | kadai.jobs.cleanup.history.simple.allCompletedSameParentBusiness | Prevent deletion of Task History Events if other Task History Events with same parent business process ID have types other than "CREATED" | true | -| kadai.jobs.cleanup.history.simple.lockExpirationPeriod | period of time the lock is valid (Duration in ISO 8601 format). Should be longer than the longest possible job execution time | PT30M | +| kadai.jobs.cleanup.history.simple.lockExpirationPeriod | period of time the lock is valid (Duration in ISO 8601 format). Should be longer than the longest possible job execution time | PT30M | ## TaskUpdatePriorityJob Configuration -| Parameter | Description | Default Value | -|---------------------------------------|--------------------------------------------------------------------------------------------------|-----------------------| -| kadai.jobs.priority.task.enable | Enabling automated recalculation of priority of each tasks that is not in an endstate | false | -| kadai.jobs.priority.task.batchSize | upper bound of how many tasks can be processed by one TaskUpdatePriorityJob | 100 | -| kadai.jobs.priority.task.runEvery | period of time between the executions of the TaskUpdatePriorityJob (Duration in ISO 8601 format) | P1D | -| kadai.jobs.priority.task.firstRunAt | first time the job is executed (DateTime in ISO 8601 format) | 2023-01-01T00:00:00Z | -| kadai.jobs.priority.task.lockExpirationPeriod | period of time the lock is valid (Duration in ISO 8601 format). Should be longer than the longest possible job execution time | PT30M | +| Parameter | Description | Default Value | +|-----------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------|----------------------| +| kadai.jobs.priority.task.enable | Enabling automated recalculation of priority of each tasks that is not in an endstate | false | +| kadai.jobs.priority.task.batchSize | upper bound of how many tasks can be processed by one TaskUpdatePriorityJob | 100 | +| kadai.jobs.priority.task.runEvery | period of time between the executions of the TaskUpdatePriorityJob (Duration in ISO 8601 format) | P1D | +| kadai.jobs.priority.task.firstRunAt | first time the job is executed (DateTime in ISO 8601 format) | 2023-01-01T00:00:00Z | +| kadai.jobs.priority.task.lockExpirationPeriod | period of time the lock is valid (Duration in ISO 8601 format). Should be longer than the longest possible job execution time | PT30M | ## UserInfoRefreshJob Configuration -| Parameter | Description | Default Value | -|--------------------------------------|-----------------------------------------------------------------------------------------------|----------------------| -| kadai.jobs.refresh.user.enable | Enable job to refresh all user info after a period of time | false | -| kadai.jobs.refresh.user.runEvery | period of time between the executions of the UserInfoRefreshJob (Duration in ISO 8601 format) | P1D | -| kadai.jobs.refresh.user.firstRunAt | first time the job is executed (DateTime in ISO 8601 format) | 2023-01-01T23:00:00Z | -| kadai.jobs.refresh.user.lockExpirationPeriod | period of time the lock is valid (Duration in ISO 8601 format). Should be longer than the longest possible job execution time | PT30M | +| Parameter | Description | Default Value | +|----------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------|----------------------| +| kadai.jobs.refresh.user.enable | Enable job to refresh all user info after a period of time | false | +| kadai.jobs.refresh.user.runEvery | period of time between the executions of the UserInfoRefreshJob (Duration in ISO 8601 format) | P1D | +| kadai.jobs.refresh.user.firstRunAt | first time the job is executed (DateTime in ISO 8601 format) | 2023-01-01T23:00:00Z | +| kadai.jobs.refresh.user.lockExpirationPeriod | period of time the lock is valid (Duration in ISO 8601 format). Should be longer than the longest possible job execution time | PT30M | ## CustomJobs Configuration -| Parameter | Description | Default Value | -|-------------------------|--------------------------------------------------------|---------------| +| Parameter | Description | Default Value | +|-----------------------|--------------------------------------------------------|---------------| | kadai.jobs.customJobs | Initialize custom jobs by specifying path to job class | | ## Example @@ -102,6 +102,6 @@ kadai.jobs.refresh.user.firstRunAt=2017-04-05T18:00:00Z kadai.jobs.refresh.user.runEvery=P4H ``` -**Result** (assuming refresh user job is the only active job): +**Result** (assuming the refresh user job is the only active job): ![Local Image](../static/configuration/Timeline.drawio.png) \ No newline at end of file diff --git a/docs/user-guide/configuration/ldap.md b/docs/user-guide/configuration/ldap.md index b91e893..b7c2219 100644 --- a/docs/user-guide/configuration/ldap.md +++ b/docs/user-guide/configuration/ldap.md @@ -6,35 +6,35 @@ sidebar_position: 3 KADAI provides [LDAP](https://ldap.com/learn-about-ldap/) support by showing LDAP-usage in its example module ```kadai-rest-spring-example-boot```. If you do not create an LdapContextSource bean, KADAI will create one for you using the parameters specified on this documentation page. If you want to create your LdapContextSource bean to be used in KADAI, please use as qualifier the constant ```io.kadai.common.rest.ldap.KADAI_LDAP_CONTEXT_SOURCE```. -In order to configure LDAP for usage with KADAI, you need an .ldif file. Additionaly, you need to configure LDAP in the ``application.properties`` file using following parameters: +To configure LDAP for usage with KADAI, you need an .ldif file. Additionally, you need to configure LDAP in the ``application.properties`` file using the following parameters: -|Parameter |Description |Sample Value | -|---------------------------------|---------------------------------------------------------|----------------------| -|kadai.ldap.serverUrl |The url of the ldap server used by KADAI. | ldap://localhost:10389 -|kadai.ldap.bindDn |The bind dn when connecting.|uid=admin -|kadai.ldap.bindPassword |The password for connecting with the bind dn.|secret -|kadai.ldap.baseDn |The base dn of the ldap server.|ou=Test,O=KADAI -|kadai.ldap.userSearchBase |The base dn of each use.|cn=users -|kadai.ldap.userSearchFilterName |Name of the attribute for filtering users.|objectclass -|kadai.ldap.userSearchFilterValue |Value of the attribute for filtering users.|person -|kadai.ldap.userFirstnameAttribute |Name of the attribute that is used to specify the first name of the user in the ldif file. |givenName -|kadai.ldap.userLastnameAttribute |Name of the attribute that is used to specify the last name of the user in the ldif file.|sn -|kadai.ldap.userFullnameAttribute |Name of the attribute that is used to specify the full name of the user in the ldif file.|cn -|kadai.ldap.userPhoneAttribute |Name of the attribute that is used to specify the phone of the user in the ldif file.|phoneNumber -|kadai.ldap.userMobilePhoneAttribute |Name of the attribute that is used to specify the mobile phone of the user in the ldif file.|mobileNumber -|kadai.ldap.userEmailAttribute |Name of the attribute that is used to specify the email of the user in the ldif file.|email -|kadai.ldap.userOrglevel1Attribute |Name of the attribute that is used to specify the first organization level of the user in the ldif file.|orgLevel1 -|kadai.ldap.userOrglevel2Attribute |Name of the attribute that is used to specify the second organization level of the user in the ldif file.|orgLevel2 -|kadai.ldap.userOrglevel3Attribute |Name of the attribute that is used to specify the third organization level of the user in the ldif file.|orgLevel3 -|kadai.ldap.userOrglevel4Attribute |Name of the attribute that is used to specify the fourth organization level of the user in the ldif file.|orgLevel4 -|kadai.ldap.userIdAttribute |Name of the attribute that is used to specify the id of the user in the ldif file.|uid -|kadai.ldap.userMemberOfGroupAttribute |Name of the attribute that is used to specify groups of the user in the ldif file.|memberOf -|kadai.ldap.groupSearchBase |The base dn of each group -|kadai.ldap.groupSearchFilterName |Name of the attribute for filtering groups.|objectclass -|kadai.ldap.groupSearchFilterValue |Value of the attribute for filtering goups.|groupOfUniqueNames| -|kadai.ldap.groupNameAttribute |Name of the attribute that is used to specify the name of the group in the ldif file.|cn -|kadai.ldap.minSearchForLength
(optional) ||3| -|kadai.ldap.maxNumberOfReturnedAccessIds
(optional)||50| -|kadai.ldap.groupsOfUser
(optional) |deprecated. Please use kadai.ldap.groupsOfUser.name instead. |uniquemember| -|kadai.ldap.groupsOfUser.name
(optional) |Name of the attribute in a group object, which specifies the member of the group. |uniquemember| -|kadai.ldap.groupsOfUser.type
(optional) |Type of the attribute in a group object, which specifies the member of the group.If you specify ‘dn’ as the type, KADAI assumes that this field contains exactly the full dn of the member.|dn| +| Parameter | Description | Sample Value | +|---------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------| +| kadai.ldap.serverUrl | The url of the ldap server used by KADAI. | ldap://localhost:10389 | +| kadai.ldap.bindDn | The bind dn when connecting. | uid=admin | +| kadai.ldap.bindPassword | The password for connecting with the bind dn. | secret | +| kadai.ldap.baseDn | The base dn of the ldap server. | ou=Test,O=KADAI | +| kadai.ldap.userSearchBase | The base dn of each use. | cn=users | +| kadai.ldap.userSearchFilterName | Name of the attribute for filtering users. | objectclass | +| kadai.ldap.userSearchFilterValue | Value of the attribute for filtering users. | person | +| kadai.ldap.userFirstnameAttribute | Name of the attribute that is used to specify the first name of the user in the ldif file. | givenName | +| kadai.ldap.userLastnameAttribute | Name of the attribute that is used to specify the last name of the user in the ldif file. | sn | +| kadai.ldap.userFullnameAttribute | Name of the attribute that is used to specify the full name of the user in the ldif file. | cn | +| kadai.ldap.userPhoneAttribute | Name of the attribute that is used to specify the phone of the user in the ldif file. | phoneNumber | +| kadai.ldap.userMobilePhoneAttribute | Name of the attribute that is used to specify the mobile phone of the user in the ldif file. | mobileNumber | +| kadai.ldap.userEmailAttribute | Name of the attribute that is used to specify the email of the user in the ldif file. | email | +| kadai.ldap.userOrglevel1Attribute | Name of the attribute that is used to specify the first organization level of the user in the ldif file. | orgLevel1 | +| kadai.ldap.userOrglevel2Attribute | Name of the attribute that is used to specify the second organization level of the user in the ldif file. | orgLevel2 | +| kadai.ldap.userOrglevel3Attribute | Name of the attribute that is used to specify the third organization level of the user in the ldif file. | orgLevel3 | +| kadai.ldap.userOrglevel4Attribute | Name of the attribute that is used to specify the fourth organization level of the user in the ldif file. | orgLevel4 | +| kadai.ldap.userIdAttribute | Name of the attribute that is used to specify the id of the user in the ldif file. | uid | +| kadai.ldap.userMemberOfGroupAttribute | Name of the attribute that is used to specify groups of the user in the ldif file. | memberOf | +| kadai.ldap.groupSearchBase | The base dn of each group | | +| kadai.ldap.groupSearchFilterName | Name of the attribute for filtering groups. | objectclass | +| kadai.ldap.groupSearchFilterValue | Value of the attribute for filtering goups. | groupOfUniqueNames | +| kadai.ldap.groupNameAttribute | Name of the attribute that is used to specify the name of the group in the ldif file. | cn | +| kadai.ldap.minSearchForLength
(optional) | | 3 | +| kadai.ldap.maxNumberOfReturnedAccessIds
(optional) | | 50 | +| kadai.ldap.groupsOfUser
(optional) | deprecated. Please use kadai.ldap.groupsOfUser.name instead. | uniquemember | +| kadai.ldap.groupsOfUser.name
(optional) | Name of the attribute in a group object, which specifies the member of the group. | uniquemember | +| kadai.ldap.groupsOfUser.type
(optional) | Type of the attribute in a group object, which specifies the member of the group.If you specify ‘dn’ as the type, KADAI assumes that this field contains exactly the full dn of the member. | dn | diff --git a/docs/user-guide/configuration/priorityReport.md b/docs/user-guide/configuration/priorityReport.md index 5e39dea..1c69146 100644 --- a/docs/user-guide/configuration/priorityReport.md +++ b/docs/user-guide/configuration/priorityReport.md @@ -8,14 +8,18 @@ KADAI provides the possibility to customize Priority Reports in the UI. To confi ![setting](../static/configuration/UISettings.png) -Currently the UI supports the following types of parameters: +Currently, the UI supports the following types of parameters: -|Type | What the UI shows |Usage -|---------|------------------------------------------------------------|----- -|text |an input field where text can be typed in |Priority names -|interval |two input fields for numbers, a lower and an upper boundary |Priority intervals -|color |a color picker |Priority colors -|json |a text area where a string in json format can be typed in. |Filter values +| Type | What the UI shows | Usage | +|----------|-------------------------------------------------------------|--------------------| +| text | an input field where text can be typed in | Priority names | +| interval | two input fields for numbers, a lower and an upper boundary | Priority intervals | +| color | a color picker | Priority colors | +| json | a text area where a string in json format can be typed in. | Filter values | ### Placement of this configuration in KADAI -The parameters described above are saved in the CONFIGURATION table under CUSTOM_ATTRIBUTES. The data structure is divided in two parts: The fields with their corresponding values and a field named “schema”. That field contains all information which is needed in the UI to display those parameters. The default values can be found there. +The parameters described above are saved in the CONFIGURATION table under CUSTOM_ATTRIBUTES. +The data structure is divided in two parts: +The fields with their corresponding values and a field named `schema`. +That field contains all information needed in the UI to display those parameters. +The default values can be found there. diff --git a/docs/user-guide/configuration/security.md b/docs/user-guide/configuration/security.md index 3002f71..a4e5831 100644 --- a/docs/user-guide/configuration/security.md +++ b/docs/user-guide/configuration/security.md @@ -8,23 +8,25 @@ sidebar_position: 2 The configuration of the user-related parameters is in the file ```kadai.properties```. Some parameters allow multiple values specified as a list. In this case, individual values are separated by a configurable separator. Use the *propertiesSeparator* parameter to specify it. If none is provided, the default is "|". If you specify a propertiesSeparator, no list item in the properties file can contain any character from the propertiesSeparator. -| Parameter | Description | Sample Value | -|------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------| - | EXTERNAL \| manual \| autoMAtic \| Process | -| kadai.user.minimalPermissionsToAssignDomains | The list of minimal Workbasket permissions of a user needed to belong to the domain. Needed to determine the domains of a user, which are aggregated in the getUser() method of the UserService. Values have to match the Enum values of WorkbasketPermission. If this property is not defined the dynamic computation of the domain attribute will not be executed. | READ \| OPEN | -| kadai.addAdditionalUserInfo | Add attributes of the user from the USER_INFO table, for example during a Task request or Task Query, the default value is false | true +| Parameter | Description | Sample Value | +|----------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------| + | EXTERNAL \| manual \| autoMAtic \| Process | | | +| kadai.user.minimalPermissionsToAssignDomains | The list of minimal Workbasket permissions of a user needed to belong to the domain. Needed to determine the domains of a user, which are aggregated in the getUser() method of the UserService. Values have to match the Enum values of WorkbasketPermission. If this property is not defined the dynamic computation of the domain attribute will not be executed. | READ \| OPEN | +| kadai.addAdditionalUserInfo | Add attributes of the user from the USER_INFO table, for example during a Task request or Task Query, the default value is false | true | ### Roles Mapping -KADAI Roles and their meaning can be looked up [here](../core-concepts/securityAndPermissions#security-roles-in-kadai). For each role, a list of access ids that refer to users or groups can be specified using following keywords: +KADAI's Roles and their meaning can be looked up [here](../core-concepts/securityAndPermissions#security-roles-in-kadai). +For each role, +a list of access ids that refer to users or groups can be specified using the following keywords: -| Role | Keyword | -|----------------|-----------------------------| -| user | kadai.roles.user | +| Role | Keyword | +|----------------|----------------------------| +| user | kadai.roles.user | | business_admin | kadai.roles.business_admin | | task_admin | kadai.roles.task_admin | -| admin | kadai.roles.admin | -| monitor | kadai.roles.monitor | +| admin | kadai.roles.admin | +| monitor | kadai.roles.monitor | | task_router | kadai.roles.task_router | The access ids are separated by a configurable separator. If none is provided, the default is "|". The assignment of roles to users or groups can look like this: @@ -38,11 +40,18 @@ kadai.roles.task_admin=taskadmin ## REST Service Security -As described in [security](../core-concepts/securityAndPermissions.md), kadai-core uses JAAS Subjects for authentication. However, when using the REST service of KADAI, you need to provide a mapping to the JAAS Subjects. KADAI shows how to do that in the class BootWebSecurityConfigurer in the ```kadai-rest-spring-example-boot``` module using LDAP. There, you can also lookup additional configuration of KADAI on REST level. This way, KADAI provides LDAP support for its REST Service. You can read more about LDAP Configuration [here](ldap.md). - -Following additional security parameters can be configured in the ```application.properties```: - -|Parameter |Description |Sample Value |Optional| -|---------------------------------|---------------------------------------------------------|----------------------|--------| -|devMode |When using frontend with devMode set to true and enablCsrf to false, you will be automatically logged in as admin. The default value is false.|false|true -|enableCsrf |This property enables the support of CSRF tokens. This will not work together with devMode. You need to set it to false in order to use Basic Auth, for example in Postman.The default value is false.|true|true +As described in [security](../core-concepts/securityAndPermissions.md), +kadai-core uses JAAS Subjects for authentication. +However, when using the REST service of KADAI, you need to provide a mapping to the JAAS Subjects. +KADAI shows +how to do that in the class BootWebSecurityConfigurer in the ```kadai-rest-spring-example-boot``` module using LDAP. +There, you can also look up additional configuration of KADAI on REST level. +This way, KADAI provides LDAP support for its REST Service. +You can read more about LDAP Configuration [here](ldap.md). + +The following additional security parameters can be configured in the ```application.properties```: + +| Parameter | Description | Sample Value | Optional | +|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------|----------| +| devMode | When using frontend with devMode set to true and enableCsrf to false, you will be automatically logged in as admin. The default value is false. | false | true | +| enableCsrf | This property enables the support of CSRF tokens. This will not work together with devMode. You need to set it to false in order to use Basic Auth, for example in Postman.The default value is false. | true | true | diff --git a/docs/user-guide/configuration/ui.md b/docs/user-guide/configuration/ui.md index 3273634..1f91c46 100644 --- a/docs/user-guide/configuration/ui.md +++ b/docs/user-guide/configuration/ui.md @@ -6,14 +6,18 @@ sidebar_position: 9 ## Environment Configuration -The environment information defined below can be configured using the json file `/environments/data-sources/environment-information.json`. The file can for example be placed in the sources of the frontend of your KADAI application or placed into the resources/static folder of your REST application. It will be loaded on initial request. +The environment information defined below can be configured +using the JSON file `/environments/data-sources/environment-information.json`. +The file can, for example, +be placed in the sources of the frontend of your KADAI application or placed into the resources/static folder of your REST application. +It will be loaded on initial request. The environment-information.json contains two parameters: -| Property | Description | -| -----------------|--------------------------------------------| -| kadaiRestUrl |The root path of the REST Service. It has to end with "/api" -| kadaiLogoutUrl |The location a user is redirected to when a logout is triggered. +| Property | Description | +|----------------|------------------------------------------------------------------| +| kadaiRestUrl | The root path of the REST Service. It has to end with "/api" | +| kadaiLogoutUrl | The location a user is redirected to when a logout is triggered. | Here is an example: @@ -24,11 +28,16 @@ Here is an example: } ``` -In this case, KADAI is deployed on localhost, port 8080 using the context root ‘/kadai’. The default environment-information.json file can be found in our GitHub repository [here](https://github.com/Kadai/kadai/blob/81b28274e77ee412cf85a8e3294f1f2285bdf9fa/web/src/environments/data-sources/environment-information.json#L3). +In this case, KADAI is deployed on localhost, port 8080 using the context root `/kadai`. +The default environment-information.json file can be found in our GitHub repository [here](https://github.com/kadai-io/kadai/blob/master/web/src/environments/data-sources/environment-information.json). ## UI Customization -Some KADAI UI elements, such as custom properties, can be configured in the json file `/environments/data-sources/kadai-customization.json`. The file can for example be placed in the sources of the frontend of your KADAI application or placed into the resources/static folder of your REST application. They will be loaded on initial request. +Some KADAI UI elements, such as custom properties, +can be configured in the JSON file `/environments/data-sources/kadai-customization.json`. +The file can, for example, +be placed in the sources of the frontend of your KADAI application or placed into the resources/static folder of your REST application. +They will be loaded on initial request. The default kadai-customization.json will be found in our GitHub repository. diff --git a/docs/user-guide/core-concepts/_category_.json b/docs/user-guide/core-concepts/_category_.json index 5865b12..806d3ed 100644 --- a/docs/user-guide/core-concepts/_category_.json +++ b/docs/user-guide/core-concepts/_category_.json @@ -3,6 +3,6 @@ "position": 3, "link": { "type": "generated-index", - "description": "Learn about the main fuctionality of KADAI." + "description": "Learn about the main functionality of KADAI." } } \ No newline at end of file diff --git a/docs/user-guide/core-concepts/javaApiUsage.md b/docs/user-guide/core-concepts/javaApiUsage.md index cb9ff4a..b7ea579 100644 --- a/docs/user-guide/core-concepts/javaApiUsage.md +++ b/docs/user-guide/core-concepts/javaApiUsage.md @@ -6,18 +6,26 @@ sidebar_position: 3 import Drawio from '@theme/Drawio' import simpleGraph from '!!raw-loader!../static/core-concepts/lib-structure.drawio'; -The following article describes the practical implementation of main concepts of KADAI, explained in the [Overview](./overview.md). Please be familiar with the contents of the Overview in order to understand this article. +The following article describes the practical implementation of KADAI's main concepts, +explained in the [Overview](./overview.md). +Please be familiar with the contents of the Overview to understand this article. ## Where to find entities and operations on them The Overview describes [entities](./overview.md#kadai-entities) and [operations on them](./overview.md#operations-on-entities). The Task, Classification and Workbasket as well as related entities can be found in ``io.kadai.task.api.models``, ``io.kadai.classification.api.models``, ``io.kadai.workbasket.api.models``. Besides Tasks, Classifications and Workbaskets, KADAI also operates using summary objects: TaskSummaries, ClassificationSummaries and WorkbasketSummaries. They represent the same concepts as Tasks, Classifications and Workbaskets. Each summary object refers to a full entity, but only contains the most important information. For example, a TaskSummary with id 1234 refers to the Task with the id 1234. However, the TaskSummary does not contain the Attachment of the Task as well as some other information. The summary objects can be found in the same package as the complete entity interfaces. -Creating, Deleting and Updating can be done using TaskService, ClassificationService and WorkbasketService. The Services can be found in`` io.kadai.task.api``, ``io.kadai.classification.api``, ``io.kadai.workbasket.api``. The corresponding queries can be also found in these packages. They are called TaskQuery, ClassificationQuery and WorkbasketQuery. +Creating, Deleting and Updating can be done using TaskService, +ClassificationService and WorkbasketService. +The Services can be found in`` io.kadai.task.api``, +``io.kadai.classification.api``, ``io.kadai.workbasket.api``. +The corresponding queries can be also found in these packages. +They are called TaskQuery, ClassificationQuery and WorkbasketQuery. ## The core of the Java-API -Below is the diagramm that shows different packages that make up the Java-API of KADAI. They can be found in the ``lib/kadai-core`` folder +Below is the diagram that shows different packages that make up the Java-API of KADAI. +They can be found in the ``lib/kadai-core`` folder
@@ -63,12 +71,12 @@ Below is the diagramm that shows different packages that make up the Java-API of - Used Exceptions - ``io.kadai.spi``: - - contains all Service Provider Interfaces (SPIs) of KADAI. An SPI allows the client to change the behavior of KADAI by implementing the SPI. More about SPIs can be found here (link) + - contains all Service Provider Interfaces (SPIs) of KADAI. An SPI allows the client to change the behavior of KADAI by implementing the SPI. More about SPIs can be found [here](../features/howToUseServiceProviderInterfaces.md). ### How to create an Entity using the Java-API? #### Example Task -1. First create a Task object that is not in the database yet with method +1. First create a Task object not persisted in the database yet with method ```TaskService.newTask``` 2. Then set some properties of that Task via its setter methods. 3. Finally, persist this Task to the database via ```TaskSerivce.createTask``` @@ -76,9 +84,17 @@ Below is the diagramm that shows different packages that make up the Java-API of You can find corresponding functions ```WorkbasketService.newWorkbasket```, ```ClassificationService.newClassification``` ```WorkbasketService.createWorkbasket``` and ```ClassificationService.createClassification``` in other Services. They can be used to create other entities. ### How to manipulate an Entity using the Java-API? -Some properties of an entity can be set via the entity interface (e.g. the Task interface) in the KADAI Java-API. For example, the method `` Task.setDescription`` can be used to set the description of a Task. However, some properties of entities cannot be set this way. For example, a Workbasket has to be specified during the creation of a Task. You can change the Workbasket by transferring the Task using ``TaskService.transfer``. The state of a Task can only be modified by corresponding TaskService methods ``claim``, ``forceClaim``, ``cancelClaim`` etc. You can read more about the status changes here (link). - -### How to integrate the Java API of KADAI- into your application? +Some properties of an entity can be set via the entity interface +(e.g., the Task interface) in the KADAI Java-API. +For example, the method `` Task.setDescription`` can be used to set the description of a Task. +However, some properties of entities cannot be set this way. +For example, a Workbasket has to be specified during the creation of a Task. +You can change the Workbasket by transferring the Task using ``TaskService.transfer``. +The state of a Task can only be modified by corresponding TaskService methods ``claim``, +``forceClaim``, +``cancelClaim`` etc. You can read more about the status changes [here](./taskLifecycle.md). + +### How to integrate the Java API of KADAI into your application? - Find out the DataSource for your KADAI database. You can read here (link) about setting it up - Pass the DataSource to the constructor of ``io.kadai.configuration.KadaiEngineConfiguration``. diff --git a/docs/user-guide/core-concepts/overview.md b/docs/user-guide/core-concepts/overview.md index d889ae8..d836e34 100644 --- a/docs/user-guide/core-concepts/overview.md +++ b/docs/user-guide/core-concepts/overview.md @@ -10,46 +10,82 @@ import architecture from '!!raw-loader!../static/core-concepts/architecture.draw KADAI is an open source Task Management System. It includes defining and creating tasks and keeping track of their execution, as well as distributing them to their responsible users. KADAI also offers options for detailed descriptions of each task using attachments, object references, and many other properties. In the following article, the basic entities of KADAI and related concepts are explained. -In order to provide its functionality, KADAI consists of different components. They are shown in the diagram below. As different components provide different features, the description of relevant modules can be found [here](../reference/modules.md). You can read more about the Java Library and its usage [here](./javaApiUsage). +To provide its functionality, KADAI consists of different components. +They are shown in the diagram below. +As different components provide different features, +the description of relevant modules can be found [here](../reference/modules.md). +You can read more about the Java Library and its usage [here](./javaApiUsage). ## KADAI Entities All KADAI Entities can be found in the Java API. You can read more about our Java API [here](./javaApiUsage.md). For better readability, entities are capitalized in the documentation. -KADAI operates using Tasks, Classifications and Workbaskets. Additional entities are Attachments, ObjectReferences and WorkbasketAccessIds. The entities are stored in the [configured database](../configuration/database.md). You can see the detailed data model [here](../reference/dataModel.md). +KADAI operates using Tasks, Classifications, and Workbaskets. +Additional entities are Attachments, ObjectReferences, and WorkbasketAccessIds. +The entities are stored in the [configured database](../configuration/database.md). +You can see the detailed data model [here](../reference/dataModel.md). ### Task -The Task entity represents a human task that should be worked on by one of the resposible users. A Task is identified by unique id that cannot be changed after creation. +The Task entity represents a human task that should be worked on by one of the responsible users. +A Task is identified by unique id that cannot be changed after creation. Each Task has exactly one Classification and an arbitrary number of Attachments. Each Attachment also has a Classification. These Classifications categorize the Task and the Attachment. They also determine some of their properties. For example, you can prioritize Tasks differently by using different Classifications. To compute the priority of a Task, take the greatest priority of the Classification of the Task and the Classifications of its Attachments. The Task is assigned to exactly one Workbasket. A Workbasket describes the group of people who can work on this Task. This way, different users have access to different Tasks. -A Task goes through different states during its existence. The states and their transitions are described by the Task Lifecycle. You can read more about it [here](./taskLifecycle.md) +A Task goes through different states during its existence. +The Task Lifecycle describes the states and their transitions. +You can read more about it [here](./taskLifecycle.md) ### ObjectReference ObjectReference refers to a Task related document or any other real world object that the Task is about. The document is identified by the value field of ObjectReference. Each Task must have one primary ObjectReference. The primary ObjectReference defines the main involved document. A Task can have several secondary ObjectReferences that are also relevant for the Task. ### Attachment -Similar to ObjectReference, an Attachment describes a Task related document. While an ObjectReference only refers to an object, an Attachment describes it using different attributes. That's why an Attachment has a Classification and an ObjectReference. An example Attachment can describe a letter that lead to the Task creation. In this case, the ObjectReference of the Attachment will refer to the letter that is stored in a different system. +Similar to ObjectReference, an Attachment describes a Task related document. +While an ObjectReference only refers to an object, +an Attachment describes it using different attributes. +That's why an Attachment has a Classification and an ObjectReference. +An example Attachment can describe a letter that leads to the Task creation. +In this case, +the ObjectReference of the Attachment will refer to the letter + stored in a different system. ### Classification -The Classification entity represents a category of Tasks. The Tasks with the same Classification have some common attributes. For example, the due date and priority of a Task is computed using its Classification. A Classification can be identified by its id. Alternatively, a Classification has a key which identifies it in a certain domain. This way, the Classification can be determined using the (key, domain) pair. There can be multiple Classification with the same key in different domains. For each key, there is a master Classification. A master Classification has a domain value "" (empty String). If a Classification is not found in a given domain, then the master Classification with the same key is returned. The successful deletion of the master Classification means the deletion of all Classifications with that key. +The Classification entity represents a category of Tasks. +The Tasks with the same Classification have some common attributes. +For example, the due date and priority of a Task is computed using its Classification. +A Classification can be identified by its id. +Alternatively, a Classification has a key which identifies it in a certain domain. +This way, the Classification can be determined using the (key, domain) pair. +There can be multiple Classifications with the same key in different domains. +For each key, there is a master Classification. +A master Classification has a domain value "" (empty String). +If a Classification is not found in a given domain, +then the master Classification with the same key is returned. +The successful deletion of the master Classification means the deletion of all Classifications with that key. ### Workbasket - A Workbasket is a list of Tasks. It's used to manage the group of people who can work on the Tasks in this list. Each user has access to a set of Workbaskets. For example, each team member has access to the Workbasket of the team. Similar to a Classification, a Workbasket can be identified either by an id or by the (key, domain) pair. There can be multiple Workbaskets with the same key but different domains. + A Workbasket is a list of Tasks. + It's used to manage the group of people who can work on the Tasks in this list. + Each user has access to a set of Workbaskets. + For example, each team member has access to the Workbasket of the team. + Similar to a Classification, + a Workbasket can be identified either by id or by the (key, domain) pair. + There can be multiple Workbaskets with the same key but different domains. There are different options for accessing a Workbasket. You can read more about them and other permissions [here](./securityAndPermissions#access-to-workbaskets). -KADAI provides different options for choosing a Workbasket for a specific Task. For example, there is the Task Routing feature. Task Routing allows to implement custom logic for determining the Workbasket for a Task. +KADAI provides different options for choosing a Workbasket for a specific Task. +For example, there is the Task Routing feature. +Task Routing allows implementing custom logic for determining the Workbasket for a Task. ### WorkbasketAccessItem @@ -61,11 +97,11 @@ KADAI provides the possibility to add large attributes to the entities. To minim ## Operations on entities -KADAI provides following operations on its entities: +KADAI provides the following operations on its entities: - Creating - Updating - Deleting - - [Querying](../features/queriesFilteringAndSorting.md) (additionaly allows filtering and sorting entities by properties) + - [Querying](../features/queriesFilteringAndSorting.md) (additionally allows filtering and sorting entities by properties) You can read technical details about operating on entities [using the Java-API](./javaApiUsage.md) and [using the REST-API](./restApi.md). diff --git a/docs/user-guide/core-concepts/restApi.md b/docs/user-guide/core-concepts/restApi.md index 948aa70..af88692 100644 --- a/docs/user-guide/core-concepts/restApi.md +++ b/docs/user-guide/core-concepts/restApi.md @@ -5,7 +5,8 @@ sidebar_position: 4 # REST-API import Drawio from '@theme/Drawio' -KADAI provides a REST-API to interact with the KADAI entities. For example, you can get metadata of Workbaskets, create new Tasks, update Tasks etc.. +KADAI provides a REST API to interact with the KADAI entities. +For example, you can get metadata of Workbaskets, create new Tasks, update Tasks, etc. The path for all requests to KADAI starts with the following: ``` http://localhost:8080/kadai/api/v1/ @@ -14,9 +15,11 @@ You can make your request by specifying the correct path with the corresponding ``` GET http://localhost:8080/kadai/api/v1/tasks/TKI:100000000000000000000000000000000000 ``` -We can also add parameters for filtering or sorting to the request. Following example filters all Tasks that are READY and returns them sorted by the key of their Classification: +We can also add parameters for filtering or sorting to the request. +The following example filters all Tasks that are READY +and returns them sorted by the key of their Classification: ``` GET http://localhost:8080/kadai/api/v1/tasks?state=READY&sort-by=CLASSIFICATION_KEY ``` -The full documentation of the REST-API can be found [here](https://kadai-io.azurewebsites.net/kadai/docs/rest/rest-api.html). +The full documentation of the REST-API can be found [here](https://kadai-io.azurewebsites.net/kadai/swagger-ui/index.html). diff --git a/docs/user-guide/core-concepts/securityAndPermissions.md b/docs/user-guide/core-concepts/securityAndPermissions.md index 350039e..a8a3acd 100644 --- a/docs/user-guide/core-concepts/securityAndPermissions.md +++ b/docs/user-guide/core-concepts/securityAndPermissions.md @@ -16,7 +16,7 @@ step-by-step example with our [Getting Started](../getting-started/exampleSpring KADAI Java library needs its client to provide a mapping to the JAAS Subject used for users and groups. The client should create a JAAS context for the Java library. The ids of users and groups, -e.g. "user-1-1" or "admin", are then used for the internal logic in the Java library. Our REST +e.g. `user-1-1` or `admin`, are then used for the internal logic in the Java library. Our REST Service already provides LDAP support. ## Security Roles in KADAI @@ -27,10 +27,10 @@ Users can have one of the six different roles: The USER role grants access to KADAI. USER is everybody who gets assigned to and completes tasks. - **TASK_ADMIN** - The TASK_ADMIN role includes all permissions on tasks with the exception of deleting a task/tasks. + The TASK_ADMIN role includes all permissions on tasks except deleting a task/tasks. It can also READ all workbaskets in case to create/transfer tasks in/to them. - **BUSINESS_ADMINISTRATOR** - The BUSINESS_ADMINISTRATOR role allows to change the business configuration (workbaskets, + The BUSINESS_ADMINISTRATOR role allows changing the business configuration (workbaskets, classifications, ...) - **ADMINISTRATOR** The ADMINISTRATOR role includes all permissions on the system. @@ -49,19 +49,19 @@ KADAI Java library uses WorkbasketAccessItems for authorization. WorkbasketAcces in the WorkbasketAccessList database table. Each WorkbasketAccessItems contains values for each of the following permissions: *READ, OPEN, APPEND, TRANSFER, DISTRIBUTE and CUSTOM_1 through CUSTOM_12*. A WorkbasketAccessItem belongs to a specific Workbasket-User or Workbasket-Group pair. -The user or group are specified by their accessId (for example "user-1-1"). The different +The user or group are specified by their accessId (for example, "user-1-1"). The different permissions have the following meaning: -| Permission | Meaning | -|-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| READ | Read or query Workbasket metadata. If a user does **not** have the READ permission, he does not even know about the existence of the Workbasket. | -| READTASKS | Allows user to read or query metadata of Tasks without **explicitly** specifying Workbasket in the query. For this, the READ permission is also required. If a user does not have the READTASKS permission, he cannot specify this Workbasket when getting Tasks.| -| OPEN | The user is allowed to **explicitly** query the Tasks of specific Workbaskets. To do this, READ and READTASKS permissions are also required. If a user does not have the OPEN permission, he cannot query/filter Tasks by Workbaskets. | -| EDITTASKS | Allows the user to update, claim or complete tasks. For editing, READ and READTASKS permissions are also required. | -| APPEND | The user is allowed to append a Task to the Workbasket. This applies to creation of Tasks in this Workbasket as well as for transferring Tasks to this Workbasket. | -| TRANSFER | Allows the user to transfer Tasks from this Workbasket to another one. | -| DISTRIBUTE | The user is allowed to distribute Tasks from this Workbasket to the configured distribution targets. For distribution the APPEND and TRANSFER permissions are checked also. | -| CUSTOM_1 .. CUSTOM_12 | Permissions to be used in custom code to configure application specific scenarios which are not directly checked by KADAI. | +| Permission | Meaning | +|-----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| READ | Read or query Workbasket metadata. If a user does **not** have the READ permission, he does not even know about the existence of the Workbasket. | +| READTASKS | Allows user to read or query metadata of Tasks without **explicitly** specifying Workbasket in the query. For this, the READ permission is also required. If a user does not have the READTASKS permission, he cannot specify this Workbasket when getting Tasks. | +| OPEN | The user is allowed to **explicitly** query the Tasks of specific Workbaskets. To do this, READ and READTASKS permissions are also required. If a user does not have the OPEN permission, he cannot query/filter Tasks by Workbaskets. | +| EDITTASKS | Allows the user to update, claim or complete tasks. For editing, READ and READTASKS permissions are also required. | +| APPEND | The user is allowed to append a Task to the Workbasket. This applies to creation of Tasks in this Workbasket as well as for transferring Tasks to this Workbasket. | +| TRANSFER | Allows the user to transfer Tasks from this Workbasket to another one. | +| DISTRIBUTE | The user is allowed to distribute Tasks from this Workbasket to the configured distribution targets. For distribution the APPEND and TRANSFER permissions are checked also. | +| CUSTOM_1 .. CUSTOM_12 | Permissions to be used in custom code to configure application specific scenarios which are not directly checked by KADAI. | ### Example WorkbasketAccessList table @@ -75,7 +75,7 @@ Example WorkbasketAccessItems: ## Disable security using the *securityEnabled* parameter -The securityEnabled-flag can disable authentification for the complete KADAI functionality if set +The securityEnabled-flag can disable authentication for the complete KADAI functionality if set to false. The default value of the flag is true. You can change the value by specifying the *securityEnabled* parameter of the constructor of KadaiEngineConfiguration. @@ -84,7 +84,7 @@ KadaiEngineConfiguration(DataSource dataSource, boolean useManagedTransactions, boolean securityEnabled, String propertiesFileName, String propertiesSeparator) ``` -In the spring boot example, you can add following bean in order to disable security: +In the spring boot example, you can add the following bean to disable security: ``` @Bean @@ -93,8 +93,10 @@ In the spring boot example, you can add following bean in order to disable secur } ``` -The CONFIGURATION table has a ENFORCE_SECURITY field. If this field is already set, then -*securityEnabled* should be set to the same value. If the ENFORCE_SECURITY flag in the database has +The CONFIGURATION table has an ENFORCE_SECURITY field. +If this field is already set, then +*securityEnabled* should be set to the same value. +If the ENFORCE_SECURITY flag in the database has no value, then the first KadaiEngine connecting to the database sets its *securityEnabled* as the value of ENFORCE_SECURITY. diff --git a/docs/user-guide/core-concepts/taskLifecycle.md b/docs/user-guide/core-concepts/taskLifecycle.md index a0c746c..34c71ce 100644 --- a/docs/user-guide/core-concepts/taskLifecycle.md +++ b/docs/user-guide/core-concepts/taskLifecycle.md @@ -11,7 +11,11 @@ import timelineGeneral from '!!raw-loader!../static/core-concepts/TimelineGenera # Task Lifecycle -A Task goes through different states during its existence. The states and their transitions are described by the Task Lifecycle. Additionaly, a Task has timestamps for important state transitions and expected milestones in the processing of the Task. In this article, Task Lifecycle and the corresponding Task states are explained in detail. +A Task goes through different states during its existence. +The Task Lifecycle describes the states and their transitions. +Additionally, +a Task has timestamps for important state transitions and expected milestones in the processing of the Task. +In this article, Task Lifecycle and the corresponding Task states are explained in detail. The following diagram shows Task states and their transitions. You can read more about Task States below. @@ -29,21 +33,37 @@ The changes of state and timestamps during the lifetime of a Task can be shown i - **Reaction Time**: Describes the time taken for someone to claim the task after it has been planned. - **Processing Time**: Describes how long someone worked on the task from start to finish. -- **Lead Time**: Describes the time between supposed start date of task until completion. +- **Lead Time**: Describes the time between supposed start date of a task until completion. - **Service Level**: Describes maximum duration from supposed start until deadline. ### Task Timestamps Each Task has different timestamps. Most of them are shown in the [example](#example) below: -- **received**: Describes when the Task first came into the system. For example, it can be the timestamp of an e-mail contaiting the relevant document. If there is no such timestamp, then the received timestamp can be empty. +- **received**: Describes when the Task first came into the system. For example, it can be the timestamp of an e-mail containing the relevant document. If there is no such timestamp, then the received timestamp can be empty. - **created**: Describes when the Task was first inserted into the database. - **planned**: Describes when somebody should start working on the Task. -- **claimed**: Describes when someone started to work on this Task. +- **claimed**: Describes when someone started to work on this Task. - **due**: Describes the deadline for Task completion. -- **completed**: Describes when the Task was completed. +- **completed**: Describes when the Task was completed. - **modified**: Describes when the Task was modified last time. Modifying a Task includes creating, claiming, completing and updating it. -All timestamps except *received* can be set automatically. The timestamps *received*, *planned* and *due* can be set manually. However, the time between planned and due is usually configured to have a fix value by setting [servicelevel.validation.enforce](../configuration/classificationAndServiceLevel.md) to true. If [servicelevel.validation.enforce](../configuration/classificationAndServiceLevel.md) is true, the time between planned and due is the smallest service level corresponding to the Task. In order to find out the smallest service level of the Task, the service levels of Classification of the Task and the Classification of its Attachments are compared. Then, either due or planned are set accordingly. If both attributes, planned and due, were set manually without matching the service level, and [servicelevel.validation.enforce](../configuration/classificationAndServiceLevel.md) is true, an exception will be thrown. If [servicelevel.validation.enforce](../configuration/classificationAndServiceLevel.md) is false, the time between planned and due is not fixed. That means no exception will be thrown. +All timestamps except *received* can be set automatically. +The timestamps *received*, *planned* and *due* can be set manually. +However, +the time between planned and due is usually configured +to have a fix value +by setting [servicelevel.validation.enforce](../configuration/classificationAndServiceLevel.md) to true. +If [servicelevel.validation.enforce](../configuration/classificationAndServiceLevel.md) is true, +the time between planned and due is the smallest service level corresponding to the Task. +To find out the smallest service level of the Task, +the service levels of Classification of the Task and the Classification of its Attachments are compared. +Then, either due or planned are set accordingly. +If both attributes, planned and due, were set manually without matching the service level, +and [servicelevel.validation.enforce](../configuration/classificationAndServiceLevel.md) is true, +an exception will be thrown. +If [servicelevel.validation.enforce](../configuration/classificationAndServiceLevel.md) is false, +the time between planned and due is not fixed. +That means no exception will be thrown. ### Example diff --git a/docs/user-guide/features/howToUseServiceProviderInterfaces.md b/docs/user-guide/features/howToUseServiceProviderInterfaces.md index 912adbe..6f760bb 100644 --- a/docs/user-guide/features/howToUseServiceProviderInterfaces.md +++ b/docs/user-guide/features/howToUseServiceProviderInterfaces.md @@ -3,23 +3,34 @@ sidebar_position: 1 --- # How to use Service Provider Interfaces (SPIs) -KADAI allows to customize and modify it’s behaviour through the use of dedicated Service Provider Interfaces (SPI). Each SPI defines an interface that can be implemented by custom code. This is a common approach for Java developers to extend their applications. You can find out more about the background and the details in the Java documentation: https://docs.oracle.com/javase/tutorial/sound/SPI-intro.html +KADAI allows +customizing and modify its behavior through the use of dedicated Service Provider Interfaces +(SPI). +Each SPI defines an interface that can be implemented by custom code. +This is a common approach for Java developers to extend their applications. +You can find out more about the background and the details in the Java documentation: +https://docs.oracle.com/javase/tutorial/sound/SPI-intro.html -In order to use an SPI within KADAI, do the following: +To use an SPI within KADAI, do the following: 1. Create a class that implements the relevant interface. 2. Place that class into the classpath of your application. -3. Provide a control file with full name of the SPI (e. g. io.kadai.spi.task.api.CreateTaskPreprocessor) in the subdirectory META-INF/services of the classpath. This control file must contain the fully qualified classname (including the package) of the class that implements the relevant interface. This control file is used by the ServiceLoader to load the custom class at runtime. The control file may contain multiple classes that implement the interface. Each implementation should be declared in a new line. All implementations will be used consecutively in the declaration order of the control file. +3. Provide a control file with the full name of the SPI (e.g., io.kadai.spi.task.api.CreateTaskPreprocessor) in the subdirectory META-INF/services of the classpath. This control file must contain the fully qualified classname (including the package) of the class that implements the relevant interface. This control file is used by the ServiceLoader to load the custom class at runtime. The control file may contain multiple classes that implement the interface. Each implementation should be declared in a new line. All implementations will be used consecutively in the declaration order of the control file. The steps above can look the following way for implementing the SPI "TaskRoutingProvider": 1. Implement TaskRoutingProvider in a class with the name DmnTaskRouter. -2. Place this class within your application, for example into the package myapp. -3. Create src/main/resources/META-INF/services/io.kadai.spi.routing.api.TaskRoutingProvider with following content: +2. Place this class within your application, for example, into the package myapp. +3. Create src/main/resources/META-INF/services/io.kadai.spi.routing.api.TaskRoutingProvider with the following content: ``` myapp.DmnTaskRouter ``` -If you provide one or multiple implementations according to the description above, KADAI will invoke the implementations at a specific point. For example, the implementation of the CreateTaskPreprocessor will be invoked before a new Task is inserted into the database. The Javadoc of each SPI describes these invokation conditions. +If you provide one or multiple implementations according to the description above, +KADAI will invoke the implementations at a specific point. +For example, +the implementation of the CreateTaskPreprocessor will be invoked +before a new Task is inserted into the database. +The Javadoc of each SPI describes these invocation conditions. You can see the list of SPIs provided by KADAI [here](listOfProvidedSPIs.md). diff --git a/docs/user-guide/features/jobs.md b/docs/user-guide/features/jobs.md index 5283b21..ae479a8 100644 --- a/docs/user-guide/features/jobs.md +++ b/docs/user-guide/features/jobs.md @@ -4,22 +4,31 @@ sidebar_position: 4 # KADAI Jobs -During the usage of KADAI, some functionality has to be executed in the background implicitly. This is accomplished by Jobs that are run by the scheduler. Both, scheduler as well as customizable Jobs, run at a fixed rate that can be specified during KADAI set up. Each time the scheduler is run, it starts all jobs that are due. This way, jobs can be created and run automatically. Jobs can only be started by the scheduler. If the scheduler is run once daily, a job can't be executed more frequently. All job configuration options are explained [here](../configuration/kadaiJobs.md). - -You can implement your own Jobs or use Jobs provided by KADAI. The jobs provided by KADAI are listed below. +During the usage of KADAI, some functionality has to be executed in the background implicitly. +This is by Jobs that are run by the scheduler. +Both scheduler and customizable Jobs +run at a fixed rate that can be specified during KADAI set up. +Each time the scheduler is run, it starts all jobs that are due. +This way, jobs can be created and run automatically. +Jobs can only be started by the scheduler. +If the scheduler is run once daily, a job can't be executed more frequently. +All job configuration options are explained [here](../configuration/kadaiJobs.md). + +You can implement your own Jobs or use Jobs provided by KADAI. The jobs provided by KADAI are listed +below. ### TaskPriorityUpdateJob -Updates Task priority for each Task once in a fixed time interval. +This job updates Task priority for each Task once in a fixed time interval. ### UserInfoRefreshJob -Loads User Info into the User table from the .ldif file once in a fixed time interval. +This job loads User Info into the User table from the .ldif file once in a fixed time interval. ### TaskCleanupJob -Deletes Tasks comleted longer than a fixed time ago. This Job also runs at a fixed rate. +This job deletes Tasks completed longer than a fixed time ago. This Job also runs at a fixed rate. ### HistoryCleanupJob -Deletes HistoryEvents for deleted Tasks. This Job also runs at a fixed rate. +This job deletes HistoryEvents for deleted Tasks. This Job also runs at a fixed rate. diff --git a/docs/user-guide/features/kadaiHistorySPI.md b/docs/user-guide/features/kadaiHistorySPI.md index 5929dd4..838fcf9 100644 --- a/docs/user-guide/features/kadaiHistorySPI.md +++ b/docs/user-guide/features/kadaiHistorySPI.md @@ -4,9 +4,14 @@ sidebar_position: 3 # KadaiHistory SPI -In order to follow this article, please read [general SPI information](howToUseServiceProviderInterfaces.md) before proceeding. - -The KadaiHistory can be used for different purposes. In general, it tracks actions performed by KADAI, like creation of Workbaskets, completion of Tasks etc.. The HistoryService makes this information available for further usage. KADAI already provides an implementation for the KadaiHistory described [here](#kadaihistory-implementation-and-the-corresponding-rest-service). Below, you can see example business use cases for KadaiHistory. +To follow this article, please read [general SPI information](howToUseServiceProviderInterfaces.md) before proceeding. + +The KadaiHistory can be used for different purposes. +In general, it tracks actions performed by KADAI, +like creation of Workbaskets, completion of Tasks, etc. +The HistoryService makes this information available for further usage. +KADAI already provides an implementation for the KadaiHistory described [here](#kadaihistory-implementation-and-the-corresponding-rest-service). +Below, you can see example business use cases for KadaiHistory. ## Use Cases for KadaiHistory - History of one business process: (relevant for specialists working on a Task of that process) - Who worked on it before? @@ -14,13 +19,13 @@ The KadaiHistory can be used for different purposes. In general, it tracks actio - What happened in the process before it got assigned to the user? - Auditing: - Is everything completed? - - What happend to a specific document / process? - - Who aprroved what? + - What happened to a specific document / process? + - Who approved what? - Who changed something? - Reporting: (SLA/KPI) - How long did a process/Task take in average? - How long did it take until a new message from a customer is assigned to a specialist? - - How often was is required to change the Classification of the Task/document? + - How often was required to change the Classification of the Task/document? - Reporting: - How many Tasks of what Classification did we receive this day/week/month? - How many Tasks have been completed by team/location/etc.? @@ -28,8 +33,8 @@ The KadaiHistory can be used for different purposes. In general, it tracks actio ## KadaiHistory Implementation and the corresponding REST-Service -Additionaly to the SPI, KADAI already provides an implementation at io.kadai.simplehistory.impl.SimpleHistoryServiceImpl. -You can activate SimpleHistoryServiceImpl by adding following dependency to your pom: +Additionally to the SPI, KADAI already provides an implementation at io.kadai.simplehistory.impl.SimpleHistoryServiceImpl. +You can activate SimpleHistoryServiceImpl by adding the following dependency to your pom: ``` diff --git a/docs/user-guide/features/listOfProvidedSPIs.md b/docs/user-guide/features/listOfProvidedSPIs.md index 23b5b23..2bbd24a 100644 --- a/docs/user-guide/features/listOfProvidedSPIs.md +++ b/docs/user-guide/features/listOfProvidedSPIs.md @@ -4,7 +4,7 @@ sidebar_position: 2 # List of provided SPIs -Please read [general SPI information](howToUseServiceProviderInterfaces.md) in order to understand SPIs in KADAI in general. +Please read [general SPI information](howToUseServiceProviderInterfaces.md) to understand SPIs in KADAI in general. Currently, KADAI provides the following SPIs: @@ -13,8 +13,8 @@ Currently, KADAI provides the following SPIs: - **io.kadai.spi.routing.api.TaskRoutingProvider** : Add rules for automated Workbasket assignment for some of the new Tasks. - **io.kadai.spi.task.api.AfterRequestChangesProvider** : Add actions on Task that are executed after changes on reviewed Task have been requested (See more about Task Lifecycle [here](../core-concepts/taskLifecycle.md)). - **io.kadai.spi.task.api.AfterRequestReviewProvider** : Add actions on Task that are executed after a review on a claimed Task has been requested (See more about Task Lifecycle [here](../core-concepts/taskLifecycle.md)). -- **io.kadai.spi.task.api.BeforeRequestChangesProvider** : Add actions on Task that are executed before changes on a reviewd Task have been requested (See more about Task Lifecycle [here](../core-concepts/taskLifecycle.md)). +- **io.kadai.spi.task.api.BeforeRequestChangesProvider** : Add actions on Task that are executed before changes on a reviewed Task have been requested (See more about Task Lifecycle [here](../core-concepts/taskLifecycle.md)). - **io.kadai.spi.task.api.BeforeRequestReviewProvider** : Add actions on Task that are executed before a review on a claimed Task has been requested (See more about Task Lifecycle [here](../core-concepts/taskLifecycle.md)). -- **io.kadai.spi.task.api.CreateTaskPreprocessor** : Add actions on Task that are executed before a new is created. +- **io.kadai.spi.task.api.CreateTaskPreprocessor** : Add actions on Task that are executed before a new one is created. - **io.kadai.spi.task.api.ReviewRequiredProvider** : Add actions on Task that are executed after changes on reviewed Task have been requested (See more about Task Lifecycle [here](../core-concepts/taskLifecycle.md)). - **io.kadai.spi.user.api.RefreshUserPostprocessor** : Add actions on User that are executed each time after the User is refreshed. diff --git a/docs/user-guide/features/monitoring.md b/docs/user-guide/features/monitoring.md index 9f8de12..03ad99c 100644 --- a/docs/user-guide/features/monitoring.md +++ b/docs/user-guide/features/monitoring.md @@ -4,9 +4,16 @@ sidebar_position: 4 # Monitoring -Monitoring is a real time obervation of the current state of work. It allows to view and evaluate the status of the team, thus relevant for teamlead to monitor whether all tasks are completed on time. Monitoring also provides the possibility to see what work is due in the next few days so that it can be taken into account when staffing. +Monitoring is a real time observation of the current state of work. +It allows viewing and evaluating the status of the team, +thus relevant for team lead to monitor whether all tasks are completed on time. +Monitoring also provides the possibility +to see what work is due in the next few days so that it can be taken into account when staffing. -The data shown by the monitoring includes Tasks and their attributes, like Workbaskets, status, age etc. Tasks fullfilling certain criterias are counted in order to create a statistic representing all current Tasks and their attributes. An example of this can be seen below. +The data shown by the monitoring includes Tasks and their attributes, like Workbaskets, status, age, +etc. Tasks fulfilling certain criteria are counted + to create a statistic representing all current Tasks and their attributes. +An example of this can be seen below. ![Tasks by Workbasket and due date: Table](../static/features/monitoring-by-workbasket-and-due-date.png) @@ -14,9 +21,13 @@ This screenshot shows one of the representations that can be created by the Moni ![Tasks by Workbasket and due date: Diagram](../static/features/monitoring-by-workbasket-and-due-date-visual.png) -There are other options for filtering and aggregating Tasks in the KADAI Monitor. You can see them in detail by swithing tabs in the [monitoring UI](https://kadai.mybluemix.net/kadai/#/kadai/monitor/tasks-priority) as part of our demo application. The username and password for the demo application are "admin" and "admin". +There are other options for filtering and aggregating Tasks in the KADAI Monitor. +You can see them in detail +by switching tabs in the [monitoring UI](https://kadai-io.azurewebsites.net/kadai/#/kadai/monitor/tasks-priority) as part of our demo application. +The username and password for the demo application are `admin` and `admin`. -Some of the data is additionaly visualized. For example, you can see Tasks divided by their status in a pie chart in KADAI UI: +Some data is additionally visualized. +For example, you can see Tasks divided by their status in a pie chart in KADAI UI: ![Tasks by Status: Diagram](../static/features/monitoring-tasks-by-status.png) diff --git a/docs/user-guide/features/queriesFilteringAndSorting.md b/docs/user-guide/features/queriesFilteringAndSorting.md index a05aef2..f137115 100644 --- a/docs/user-guide/features/queriesFilteringAndSorting.md +++ b/docs/user-guide/features/queriesFilteringAndSorting.md @@ -4,10 +4,16 @@ sidebar_position: 7 # Queries: Filtering and Sorting -You can get a list of Tasks, Workbaskets, Classifications, Users and other resources using KADAI queries. They allow filtering and sorting according to different criterias, e. g. priority, owner, etc. Queries can be executed using the REST-API or the Java-API. +You can get a list of Tasks, Workbaskets, Classifications, +Users and other resources using KADAI queries. +They allow filtering and sorting according to different criteria, e.g., priority, +owner, etc. Queries can be executed using the REST-API or the Java-API. ## Query usage in the REST-API -KADAI provides a REST-API described [here](../core-concepts/restApi). You should use HTTP GET method in order to execute a query. Query parameters for filtering and sorting are specified in the HTTP request after "?". For example, the following request will return all Tasks that are owned by *user-1-1* or *user-1-2*: +KADAI provides a REST-API described [here](../core-concepts/restApi). +You should use HTTP GET method to execute a query. +Query parameters for filtering and sorting are specified in the HTTP request after "?". +For example, the following request will return all Tasks that are owned by *user-1-1* or *user-1-2*: ``` GET http://localhost:8080/kadai/api/v1/tasks?owner-in=user-1-1&owner-in=user-1-2 ``` @@ -17,7 +23,7 @@ Here is an example of the query from our [REST-API doc](../core-concepts/restApi ![Query](../static/features/postman-query.png) -More about queries using the REST-API can be found in the [REST-API Documentation](https://kadai-io.azurewebsites.net/kadai/docs/rest/rest-api.html). +More about queries using the REST-API can be found in the [REST-API Documentation](https://kadai-io.azurewebsites.net/kadai/swagger-ui/index.html). # Query in JAVA-API You can also execute queries using the [JAVA-API](../core-concepts/javaApiUsage.md) of KADAI. To do that, create a query using the service of the relevant entity. Then, add filtering and sorting parameters to your query and execute it. When querying for Tasks, you need to use ``TaskService.createTaskQuery()``. You can find the query filter and sorting parameters under ``io.kadai.TaskQuery.api``. diff --git a/docs/user-guide/features/users.md b/docs/user-guide/features/users.md index ccf5e7e..27f7a16 100644 --- a/docs/user-guide/features/users.md +++ b/docs/user-guide/features/users.md @@ -4,15 +4,23 @@ sidebar_position: 6 # Users -In KADAI, a User is an entity that represents a user. A user is used for authentication as well as for specifiyng the owner of a Task. The User entity has attributes such as name, phone number and e-mail. +In KADAI, a User is an entity that represents a user. A user is used for authentication as well as for specifying the owner of a Task. The User entity has attributes such as name, phone number and e-mail. -A user can belong to one or multiple groups and have permissions assigned. Groups and permissions are used to determine additinal access rights of the user. For example, if "user-1" belongs to the group "group-1", and "group-1" has access to the Workbasket "workbasket-of-group-1", then "user-1" has access to the "workbasket-of-group-1". Same applies to permissions. Users, Groups and permissons are identified via an **AccessId** in KADAI. The AccessId is used for determining access rights through WorkbasketAccessItems. You can read more about it [here](../core-concepts/overview.md#workbasketaccessitem). Additionaly, Users and Groups both have [Roles](../core-concepts/securityAndPermissions.md#security-roles-in-kadai) assigned. +A user can belong to one or multiple groups and have permissions assigned. +Groups and permissions are used to determine additional access rights of the user. +For example, if "user-1" belongs to the group "group-1", and "group-1" +has access to the Workbasket "workbasket-of-group-1", +then "user-1" has access to the "workbasket-of-group-1". +The same applies to permissions. +Users, Groups and permissions are identified via an **AccessId** in KADAI. +The AccessId is used for determining access rights through WorkbasketAccessItems. +You can read more about it [here](../core-concepts/overview.md#workbasketaccessitem). +Additionally, +Users and Groups both have [Roles](../core-concepts/securityAndPermissions.md#security-roles-in-kadai) assigned. ## Operations on Users You can create, get, update and delete a User via UserService in the Java-API. In the REST-API, you can fetch detailed information about Users via the associated API operations. -A detailed description of the REST-operations on AccessIds, Users and Groups can be found at the follwing links: - - [AccessIds](https://kadai.mybluemix.net/kadai/docs/rest/rest-api.html#_access_id_resource) - - [Users & Groups](https://kadai.mybluemix.net/kadai/docs/rest/rest-api.html#_user_resource) +A detailed description of the REST operations on AccessIds, Users and Groups can be found in the [REST API documentation](https://kadai-io.azurewebsites.net/kadai/swagger-ui/index.html) You can set up your Users using LDAP. In this case, you can also use the [UserInfoRefreshJob](jobs.md#userinforefreshjob) to keep the Users up to date with your .ldif file. diff --git a/docs/user-guide/getting-started/exampleSpringBoot.md b/docs/user-guide/getting-started/exampleSpringBoot.md index 6a450d6..0984f73 100644 --- a/docs/user-guide/getting-started/exampleSpringBoot.md +++ b/docs/user-guide/getting-started/exampleSpringBoot.md @@ -5,30 +5,29 @@ sidebar_position: 1 # Example Spring Boot In the first 4 steps, we will set up KADAI REST API without security. Then, we will show how to use -the resulting REST API with [postman](https://www.postman.com/). This guide then sets up security. -In the end of the guide, we will add the UI. +the resulting REST API with [Postman](https://www.postman.com/). This guide then sets up security. +At the end of the guide, we will add the UI. import styles from '../../../src/components/HomepageFeatures/styles.module.css'; import Link from '@docusaurus/Link'; ## What you'll need -In order to set up the example, please install: +To set up the example, please install: - an IDE of your choice (preferably IntelliJ) - Java 17 - maven -- optional: [postman](https://www.postman.com/) (makes REST API requests easier) +- optional: [Postman](https://www.postman.com/) (makes REST API requests easier) -Note: Please name your packages, folders and files exactly like in the example! +Note: Please name your packages, folders, and files exactly like in the example! ## Set up KADAI REST-API without security ### Step 1: Initialize an empty project Go to [Spring Initializer](https://start.spring.io/) and create an example Maven Project. Choose the -same options as in the Screenshot, except the spring version. Please check Java 17, then click on " -Generate". +same options as in the Screenshot, except the spring version. Please check Java 17, then click on "Generate". ![empty spring boot project](../static/getting-started/project-initializer.png) @@ -38,16 +37,18 @@ Unpack the project in the folder of your choice and open it in IntelliJ ### Step 2: Add dependencies -Please add following dependencies to the pom. All dependencies can be copied as one block at the end -of step 2. After adding the dependencies, please reload maven and recompile the project. +Please add the following dependencies to the pom. +All dependencies can be copied as one block at the end +of step 2. +After adding the dependencies, please reload maven and recompile the project. -** 1. spring core depenpendency: ** +** 1. spring core dependency: ** ``` org.springframework.plugin spring-plugin-core - 2.0.0.RELEASE + 3.0.0 ``` @@ -70,17 +71,17 @@ of step 2. After adding the dependencies, please reload maven and recompile the io.kadai kadai-common-data - 8.1.0 + 9.1.0 io.kadai kadai-common-logging - 8.1.0 + 9.1.0 io.kadai kadai-rest-spring - 8.1.0 + 9.1.0 ``` @@ -103,22 +104,22 @@ of step 2. After adding the dependencies, please reload maven and recompile the org.springframework.plugin spring-plugin-core - 2.0.0.RELEASE + 3.0.0 io.kadai kadai-common-logging - 8.1.0 + 9.1.0 io.kadai kadai-rest-spring - 8.1.0 + 9.1.0 io.kadai kadai-common-data - 8.1.0 + 9.1.0 com.h2database @@ -135,10 +136,12 @@ of step 2. After adding the dependencies, please reload maven and recompile the #### Step 3a: Fill out application.properties The example already has the configuration file ```application.properties``` in -the ``src/main/ressources`` folder. It's a standard configuration file used by spring. You can read +the ``src/main/resources`` folder. +It's a standard configuration file used by spring. +You can read more about spring configuration in the [spring documentation](https://docs.spring.io/spring-boot/docs/current/reference/html/application-properties.html). -You need to add following content into that file: +You need to add the following content into that file: ``` logging.level.io.kadai=INFO @@ -228,9 +231,11 @@ spring.ldap.embedded.validation.enabled=false #### Step 3b: Add kadai.properties -Create ```kadai.properties``` in the resources folder. This file contains kadai specific -configuration, like custom holidays etc.. Please -copy following content into ```kadai.properties```: +Create ```kadai.properties``` in the "resources" folder. +This file contains KADAI specific +configuration, like custom holidays, etc. +Please +copy the following content into ```kadai.properties```: ``` kadai.roles.user=cn=ksc-users,cn=groups,OU=Test,O=KADAI | teamlead-1 | teamlead-2 | user-1-1 | user-1-2 | user-2-1 | user-2-2 | user-b-1 | user-b-2 @@ -279,7 +284,7 @@ kadai.jobs.cleanup.history.simple.enable=false First, Add ```@ComponentScan({"io.kadai","com.example"})``` as annotation above the class definition of the ExampleApplication and a corresponding import to this class. This will allow the -apllication to find needed components. +application to find the necessary components. Then, create a java class with the name ```ExampleRestConfiguration``` in the com.example.demo package. This class defines the Beans and their dependencies. Your project structure should look @@ -362,7 +367,7 @@ public class ExampleRestConfiguration { ### Step 5: Try out the REST-API -Recompile the project and then start the DemoApplication in your IDE. You can now make following +Recompile the project and then start the DemoApplication in your IDE. You can now make the following request: ``` @@ -370,11 +375,11 @@ GET http://localhost:8080/kadai/api/v1/classifications ``` You should get a list of different Classifications in the body of the response. Here is a screenshot -of the request and the response in [postman](https://www.postman.com/): +of the request and the response in [Postman](https://www.postman.com/): ![example request](../static/getting-started/example-request-classifications.png) -You can also request Tasks using following command: +You can also request Tasks using the following command: ``` GET http://localhost:8080/kadai/api/v1/tasks @@ -393,7 +398,7 @@ ExampleWebSecurityConfig. The classes will be created in the next steps. ### Step 6: Add security dependencies and stop disabling security -Add following dependencies to your pom and reload maven: +Add the following dependencies to your pom and reload maven: ``` @@ -416,7 +421,7 @@ Add following dependencies to your pom and reload maven: Then, set the ``devMode`` property in ``application.properties`` to false. This enables authorization checks. -You also need to remove following lines from the ``ExampleRestConfiguration.java``: +You also need to remove the following lines from the ``ExampleRestConfiguration.java``: ``` @Bean @@ -436,7 +441,8 @@ Deleted because KadaiEngineConfiguration doesn't exist anymore ### Step 7: Add BootWebSecurityConfigurer.java -Create ```BootWebSecurityConfigurer.java``` in the security folder and copy following content into +Create ```BootWebSecurityConfigurer.java``` in the security folder +and copy the following content into it: ``` @@ -617,7 +623,7 @@ public class BootWebSecurityConfigurer { ``` -Create ```CsrfCookieFilter.java``` in the security folder and copy following content into it: +Create ```CsrfCookieFilter.java``` in the security folder and copy the following content into it: ``` package com.example.demo.security; @@ -648,7 +654,7 @@ final class CsrfCookieFilter extends OncePerRequestFilter { ``` -Lastly, create ```SpaCsrfTokenRequestHandler.java``` in the security folder and copy following content into it: +Lastly, create ```SpaCsrfTokenRequestHandler.java``` in the security folder and copy the following content into it: ``` package com.example.demo.security; @@ -761,16 +767,19 @@ First, restart the ExampleApplication. Try to make a request like in the previou GET http://localhost:8080/kadai/api/v1/tasks ``` -You should get the 401 Unauthorized response. Now, you can authorize yourself using basicAuth. -In [postman](https://www.postman.com/), go to the "Authorization" tab. There, select basicAuth and -type "admin" as user and "admin" as password. Then, you can make the following request: +You should get the "401 Unauthorized" response. +Now, you can authorize yourself using basicAuth. +In [Postman](https://www.postman.com/), go to the "Authorization" tab. +There, select basicAuth and +type "admin" as user and "admin" as password. +Then, you can make the following request: ``` GET http://localhost:8080/kadai/api/v1/tasks ``` It should return a list of Tasks in the response body. Here is a screenshot of the request and the -response in [postman](https://www.postman.com/): +response in [Postman](https://www.postman.com/): ![example request](../static/getting-started/request-security.png) @@ -778,13 +787,13 @@ response in [postman](https://www.postman.com/): ### Step 11: Add web dependencies -Add following dependencies to your pom and reload maven: +Add the following dependencies to your pom and reload maven: ``` io.kadai kadai-web - 8.1.0 + 9.1.0 org.springframework.boot @@ -796,7 +805,7 @@ Add following dependencies to your pom and reload maven: Add ```controllers``` package into the ```com.example.demo``` package (in src/main/java/com/example/demo). This package will contain the controllers for different paths. Our -application needs following three controllers: +application needs the following three controllers: - LoginController - ResourcesController @@ -860,8 +869,10 @@ the ```static``` folder for it. You can download the ```static``` folder here:
-Please unzip the ```static``` folder and copy it into ```resources```. Additionaly, there is -the ```com.example.demo.controllers``` folder for further customizations. Please downlad it here: +Please unzip the ```static``` folder and copy it into ```resources```. +Additionally, there is +the ```com.example.demo.controllers``` folder for further customizations. +Please download it here:
@@ -877,7 +888,8 @@ the ```com.example.demo.controllers``` folder for further customizations. Please

-Unzip the ```com``` folder and put it into ```resources```. Then, please copy following code +Unzip the ```com``` folder and put it into ```resources```. +Then, please copy the following code into ```ResourcesController.java```: ``` @@ -923,7 +935,8 @@ public class ResourcesController { #### Step 12c: Add ViewController.java -The ViewController manages the root view of kadai. Copy following code +The ViewController manages the root view of KADAI. +Copy following code into ```ViewController.java```: ``` @@ -1025,7 +1038,7 @@ type ```localhost:8080/kadai``` into your browser. You should see the login scre ![Log in](../static/getting-started/login.png) -Log in using "admin" as username and "admin" as password. Now, you should see following: +Log in using "admin" as username and "admin" as password. Now, you should see the following: ![Workbaskets](../static/getting-started/workbaskets.png) diff --git a/docs/user-guide/getting-started/supportedEnvironments.md b/docs/user-guide/getting-started/supportedEnvironments.md index cacd678..0bf63a5 100644 --- a/docs/user-guide/getting-started/supportedEnvironments.md +++ b/docs/user-guide/getting-started/supportedEnvironments.md @@ -5,7 +5,7 @@ sidebar_position: 2 # Supported Environments ### Supported JVM - - Java 11 + - Java 17 ### Supported Databases - or DB2 11.5 - or PostgresSQL 14.7 @@ -13,6 +13,6 @@ sidebar_position: 2 - Embedded Tomcat of Spring Boot - or Wildfly Application Server ### Web Browser (optional) - - Google Chrome (latest 2 version) - - or Mozilla Firefox (latest 2 version) - - or Microsoft Edge (latest 2 version) \ No newline at end of file + - Google Chrome (latest 2 versions) + - or Mozilla Firefox (latest 2 versions) + - or Microsoft Edge (latest 2 versions) \ No newline at end of file diff --git a/docs/user-guide/static/configuration/UISettings.png b/docs/user-guide/static/configuration/UISettings.png index ecb50b6..12a590c 100644 Binary files a/docs/user-guide/static/configuration/UISettings.png and b/docs/user-guide/static/configuration/UISettings.png differ diff --git a/docs/user-guide/static/features/monitoring-by-workbasket-and-due-date-visual.png b/docs/user-guide/static/features/monitoring-by-workbasket-and-due-date-visual.png index 4ddaaed..b48b2f8 100644 Binary files a/docs/user-guide/static/features/monitoring-by-workbasket-and-due-date-visual.png and b/docs/user-guide/static/features/monitoring-by-workbasket-and-due-date-visual.png differ diff --git a/docs/user-guide/static/getting-started/login.png b/docs/user-guide/static/getting-started/login.png index d67148e..5539220 100644 Binary files a/docs/user-guide/static/getting-started/login.png and b/docs/user-guide/static/getting-started/login.png differ diff --git a/docs/user-guide/static/getting-started/navigate.png b/docs/user-guide/static/getting-started/navigate.png index 36cfe33..ce5ce3f 100644 Binary files a/docs/user-guide/static/getting-started/navigate.png and b/docs/user-guide/static/getting-started/navigate.png differ diff --git a/docs/user-guide/static/getting-started/workbaskets.png b/docs/user-guide/static/getting-started/workbaskets.png index 161c4c5..729a5ea 100644 Binary files a/docs/user-guide/static/getting-started/workbaskets.png and b/docs/user-guide/static/getting-started/workbaskets.png differ diff --git a/docusaurus.config.js b/docusaurus.config.js index 20d0526..654db2e 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -85,6 +85,11 @@ const config = { label: 'REST API Doc', position: 'right', }, + { + href: 'https://kadai-io.azurewebsites.net/kadai/docs/java/kadai-core/index.html', + label: 'KADAI core Java Doc', + position: 'right', + }, { type: 'doc', docId: 'demo-app/demoApp', @@ -121,6 +126,10 @@ const config = { { label: 'REST API Documentation', href: 'https://kadai-io.azurewebsites.net/kadai/swagger-ui/index.html', + }, + { + label: 'KADAI core Java Documentation', + href: 'https://kadai-io.azurewebsites.net/kadai/docs/java/kadai-core/index.html', } ] },