puria / ksweb

Knowledge Shaper. The editor to share your knowledge.

ksweb

The KS (Knowledge Shaper) is a Document Automation digital product that enables the shaping and reuse of Knowledge Bases. Our effort is to allow and facilitate the creation of wizards that easily outputs documents just by answering to simple questions with an extra effort to a functiona design and UX.

You can try the demo online available on ks.studiolegale.it. Some example of Knowledge Bases are:

• Memorandum on GDPR compliance
• Lawyer quotation (in italian)

🚩 Table of Contents (click to expand)

• Getting started
• Manual Installation
• Usage
• Configuration
• I18n
• Notes
• Troubleshooting & debugging
• Acknowledgements
• Contributing
• License

🐳 Getting started

The easiest way to run ksweb is inside a docker container. just run

git clone --recursive https://github.com/puria/ksweb.git
cd ksweb
docker-compose up

For instructions about how to install docker-compose please refere to the official documentation

💾 Manual Installation (for advanced users)

Checkout the project

git clone --recursive https://github.com/puria/ksweb.git

Pre-requisites

Before install KSweb you need to have an instance of 🍃mongodb up and running, the python development headers and python3-virtualenv packages NB you need python3 >= 3.6 and pip >= 18.1

You also need to have to install pandoc for exporting the actual output to different formats.

Installer

run the installer:

🍎 macosx

brew install python3
cd ksweb
./install

🐧 debian derivatives

apt install python3-dev python3-virtualenv
cd ksweb
./install

Manual installation

Install ksweb using the setup.py script

    # Enter into the first project folder
    $ cd ksweb
    
    # Create a virtual environment for python2 (important)
    $ virtualenv -p python2 venv
    
    # Activate your virtual environment (very important)
    $ source venv/bin/activate
    
    # Enter the subproject folder
    $ cd ksweb
    
    # Install all the dependencies
    $ pip install -e .
    
    # Populate the mandatory data (TO RUN JUST AT THE FIRST USAGE OF A DATABASE)
    $ gearbox setup-app

Start the http server

 # Start a local webserver (NOT SUITABLE FOR PRODUCTION) 
 $ gearbox serve --reload

Then you are ready to go 🎉

---

🎮 Usage

To run the webapp activate your virtualenv and run the server:

cd ksweb
source venv/bin/activate
gearbox serve

and head your browser to http://localhost:8080

Default accounts (username - password):

Administrator: admin 🔑 adminks

Lawyer: lawyer 🔑 lawyerks

User: user 🔑 userks

---

🔧 Configuration

The conf files are development.ini and test.ini.

The most effective way is to edit the file and tweak stuff. Salient info are reported below.

🍃 MongoDB

The url of the database connection is ming.url find it in development.ini and change it per your needs.

---

🌐 I18n

The UI of the knowledge shaper is already translated in English and Italian. If you need othe languages, please indicate us someone who wants to help, and open and issue. The extensive documentation about how the translation works is available on this section of the Turbogears official site.

In briefe allows to:

• Create a new language (also called Catalog)
• Extract the strings from the software
• Update and Compile existing language/catalog

The catalogs are simple .po files that anyone can open with a translation software (eg. Poedit)

---

📝 Notes

---

🐛 Troubleshooting & debugging

To run the app in debug mode launch the server with the following flags

gearbox serve --debug --reload

---

😍 Acknowledgements

Copyright (C) 2018 by StudioLegale.it http://studiolegale.it

Designed, written by AXANT.it and currently maintained by Puria Nafisi Azizi.

---

👥 Contributing

1. FORK IT
2. Create your feature branch git checkout -b feature/branch
3. Commit your changes git commit -am 'Add some fooBar'
4. Push to the branch git push origin feature/branch
5. Create a new Pull Request
6. Thank you

---

💼 License

Knowledge Shaper, Collaborative knowledge tools editor
Copyright (c) 2017-TODAY StudioLegale.it <http://studiolegale.it>
                         AXANT.it <http://axant.it>

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.

ksweb's Issues

Order of checkbox answers in questionary

In case of checkbox Q/A, KS does not follow the order of the answer provided by the user.
For example, see this question

that in questionary is showed like this

Bug in odt file

At the end of the form procedure, the odt file downloaded is not formatted.

Editing A

In the Q/A Section you are allowed to create and delete answers for a given question, but not Edit them.

Insert the editing feature for existing Answers

Github integration

Look how much is possible to integrate VCS functionalities within the ksweb software

list of Q&A

When the user finalizes the form procedure, could be useful if he can see the list of Q&A he answered to.

Option menu in the filter page

In the /precondition index list, make working the New QA option.

When it's clicked should have a behaviour similar to New Output:
Open a new QA -> Prefill the Filter field <select> with the chosen filter

modify output

When I save an output modification, the software goes page "Q/A" list

it should go to "Output" list

Markdown export

Could be a good idea to save the compiled versions of the knowledge bases in Markdown in place of the html editor... and such a change could also imply a simpler editor, that allows .md editing directly

Export questionaires to .odt

Allow to save the questionaire results in a Libreoffice open format file.

Editing filter / Save labels

If you change a label, the workarea parameter is missing, and the save action crashes.

Questionary back button

For unknown reasons the back button, of the questionary-compile for the first usage, is not working anymore.

New Q/A and Output

Maybe could be a good idea, when a new Q/A is created (with the filters depending on the Q/A) a new Output should be created (with filter "Q/A -> Answered")

"New Simple Filter" button

In the "New Output" page there is a mistake in the "New Simple Filter" button.
See screenshot

Search page

For the Q/A, Filters, Outputs, Documents and all the pages that are paginated. The behaviour is that when you fill the input search it reloads page with the results.

New Workspace with name already used

I can't create a new Workpace with name "prova" with my account.

I get the following debug feedback:

Object { workspace_name: "prova" } prova start:139:17
Object { readyState: 4, getResponseHeader: .ajax/E.getResponseHeader(), getAllResponseHeaders: .ajax/E.getAllResponseHeaders(), setRequestHeader: .ajax/E.setRequestHeader(), overrideMimeType: .ajax/E.overrideMimeType(), statusCode: .ajax/E.statusCode(), abort: .ajax/E.abort(), state: .Deferred/i.state(), always: .Deferred/i.always(), catch: .Deferred/i.catch(), altri 10… } error start:150:21

Workspace "prova" didn't exist in my user area.

I see it exists a Workspace named "prova" for user "demo".

My guessing is that I can't create a Workspace "prova" with my user because it already exists with user "demo".

Label not updated after edit

When you modify the label of an output (or other entity) in /document/edit or /output/edit the label within the editor is not updated.

Label's popup

Advanced filters and output and document... based on the original design, implement the popup showing info about the entities.

For the answer green boxes, show the question... and if the answers are short a simple way to see the answers

Adding the JSON prettify on Exporting Knowledge Bases

as per subject

Error with Output ending with "space"

If you edit an Output ending with an empty space, when you open it again the space is canceled

Questionary compile

After the first usage, any percentage, when a questionary is reopened, you can move back between questions, but not follow the NEXT button

Multiline questions and answers in questionary compile

When you input on textareas for multiline questions and/or answers in the questionary compilation, unfortunately, shows everything on a single line.
See for example this question

that in the questionary is showed in one line

New lines of answers are not showed nor in questionary nor in print.

Notify new entities created

Add a badge with the number of new entities automatically created by the KS Bot (therefore not already visualized).
The number decreases when the entity is visualized.
Add an icon to the entities created by KS Bot.
The icon is deleted when the author visualize the entity.

Complex Filter

When you make a new complex filter KS requires you to enter the label even if there is text in the label

Demo form

Create a demo like form, for the GDPR document, that allows non registered users to compile the form without register.
The link should be in the index page site, and the result is destroyed each time after the user leaves the page.

Label of complex filter: change does not work

When you change the label of a complex filter nothing happens

Document metadata -> Accordion

By default the metadata of a Document should be hidden. (Author, License etc.)
A button with "Metadata: show more details" should be added.

Fix "method_complexity" issue in ksweb/ksweb/controllers/resolve.py

Function _clone_and_modify_ has a Cognitive Complexity of 45 (exceeds 5 allowed). Consider refactoring.

https://codeclimate.com/github/puria/ksweb/ksweb/ksweb/controllers/resolve.py#issue_5a7a4e146592c500010000ae

Rename Questionary

Maybe adopt "form" instead of "questionary"?

New Form button

Button "New Form" In page /document/edit? does not work

Advanced filter editing error

When using the following KB: marco55555/Memorandum-GDPR@bd4b3d5

When editing the advanced filter "Elenco Attività Valutare No" the software raises an exception

Remove filters

When editing an output, that already has a filter, it is not possible to remove it.
Could be a nice idea to add a button to remove a filter.

Error with Output starting with line break

If you save and reopen the Output, KS shows an additional line break

add focus

Add focus when opening modals

questionary broken

Using the "new questionary" function here

does not work.

I created a document with just one output with no filters (but with embedded outputs with filters, including advanced filters

If I create the questionary here

the questionary does not allow filling (goes to the end)

Output/Output+ Editor newline

Whenever you open an Output that was saved with the Output+ button, the content loses formatting (like the newlines).

Workarea landing

The workarea home should be redirect to the document page of the workarea, with a banner that incites to reuse the GDPR memorandum and/or import something

Export file: make easy analyzing diff

Analyzing differences among versions of the json file exported from KS could be easier if two issues are solved:

• Outputs are saved in one single (sometimes very long) lines,
• when you import a file in a workspace and export it again all the identifiers of the nodes are changed.
  I wonder how this issues could be addressed.

Welcome page

Here
http://localhost:8080/welcome?

wise tool -> knowledge base

knoledge base -> knowledge base

make import a link to
http://localhost:8080/document?workspace=5adaf3b0f26dcd185ba5b5d0#

*nix installer

Create an easy-peasy *nix installer for people not confident with python environments.

Test ticket from Code Climate

Add a filter icon within the label output

Within the output/document editor if an output is added from the sidebar, mark "output with filter" with an icon like the one in the sidebar.

Create new Workspace with Safari

MacOS 10.12.6 (16G1212) and Safari 11.0.3 (12604.5.6.1.1) do not allow to create new Workspace

Checkbox

Checkboxes in the QA should allow just one answer to be valid, and created.

Sidebar search

Make a ajax filter that filters out by the given keyword, output, filters

Release tracking with ansible deploy

http://docs.ansible.com/ansible/latest/modules/github_release_module.html

"New Output" behaviour

By creating a new output in the Output page it should check for:

• at least one char in the Label field
• at least one char in the editor or one entity (QA)
  if the conditions are not met the software should alert the user with a message Please add a value

If the filter was not selected before saving the user should be warned with the following message: "You didn't choose any filter. Are you shure you want to create an Output without a filter?"

Filter shortcut

In the Q/A editor and in the output editor, link the chosen filter with some link or something that allows to see the filter content

Loader

Add loader on long term operations

Reset password should be fixed

By now it's broken and throws a 500.

Remove the download

Until we don't decide a right politics and or a good external tool to convert the final document into a good and well formatted .odt, we should disable the download button for now, in the questionary/compile page!