Show Advanced KnowledgeHide Advanced Knowledge

User: Criteria-based »User Agreement« documents

1 Initial Problem

With the current implementation of the »Terms of Service«, a user has to accept terms as per a document on registration or after login. The type of document with the terms is determined by the user's language only. In certain scenarios, an institution needs different documents accepted by their users, determined by certain global ILIAS roles. A user assigned to a global role 'Vertriebsmitarbeiter' has to acccept another document than a user assigned to a global role 'Bezirksleiter'.

2 Conceptual Summary

To solve this, we suggest to make the 'User Agreement' documents (Terms of Services and User: Introducing »Data Privacy Statement« documents (global) role-dependent by introducing the concept of criteria based checks.

Beside some internal used ID, each criterion MUST define it's translated name for UI presentaton purposes. It MUST implement some kind of evaluation interface so that the 'User Agreement Service' can ask if a criterion is fulfilled based on the current context user. Furthermore it MUST provide form elements for the configuration of the value(s) being checked when evaluating the criterion based on the context user (e.g. a Drop-down list of installed languages or global roles, a tree selector etc. ...).
Finally, a criterion MUST provide some serializeable data structure (e.g. an array of primitives) created from the HTTP request (configuration form submission), and of course a value for UI presentation purposes of the current configuration.

Of course there will be some simple PHP interface or/and abstract class for such document criterions.

There will be two initial criteria developed which can be used to determine which document a user has to accept:

1. Language
2. Global Role
3. ... (other criteria could be implemented in future, e.g. 'Assigned to Organisational Unit', 'Member of Course' etc.)

Currently, the ISO language shorthandle, as the only criterion, is part of the documents file names, e.g.: ./Customizing/global/agreement/agreement_de.html

With the intrdocution of multiple criteria, we suggest to introduce an upload process for 'User Agreement' documents and abandon the old storage mechanism for client-related 'User Agreement' documents. Global agreement documents will be mirgrated to client-related documents (described below).
The client-related documents will also still be provided/uploaded as HTML documents. Documents will have a title. They can be deleted and a new HTML file may be provided. After uploaded once, the administrator is able to bind criteria to a specific document. This (editing/deletion) does not affect the history of tracked acceptances.
All uploaded documents will be presented in a table.

2.1 Evaluation - Which document to sign?

The administrator will be able to define the sorting of the document with its criteria. This sorting is relevant for the determination of the document to be accepted by a user on login. The first document matching all criteria (Logical-AND) for the context user is considered relevant and required to be signed.

• A document without any configured criterion will always be evaluated as true for all users during document determination and can be used as a fallback document.
• If the user's properties do not match all criteria of any document, the user will not be able to use the system (current behaviour, no change). An appropriate message will be displayed.

When presenting a terms of service document in the public area (e.g. on the self registration page), the agreement will be determined by the assigned roles of ANONYMOUS, and the chosen language of the user.

2.2 Migration

There will be a database update step migrating all existing client-based documents by creating new database records with a respective 'Language Criterion', parsed from the current filename of the document. The client-independent agreements (./Customizing/global/...) will be migrated to client-related documents.

Because each document requires a title, we will use an incremented 'Dokument <Number>' title for all documents of an installation with 'German' as the system language, and an incremented 'Document <Number>' title for all documents of installations with other system languages.
The sorting (described above) will be also be consecutively numbered during the database update (but can be changed afterwards in the ILIAS administration).

A 'Dear administrator ...' information will be added to the database update step. This will inform every administrator to check the user agreement configuration after upgrading to ILIAS 5.4.x.

2.3 Document Overview

The following changes will be applied to the list of documents:

• Information about 'Terms of Service' and reset button will be moved to a message box, while 'Add Document' button stays in a tool bar.
• Preview of documents will be done by clicking agreement title (opens agreement in light box) instead of using the "magnifier" icon.
• The column 'Terms of Service' (Missing/Existent) will be removed.
• The cell value of column 'Document' will be changed from a linked file system path to a linked document title.

2.4 Acceptance History

The history view/table of accepted documents will be changed.

The following filters will be removed:

• Language

The following columns will be removed:

• Language

The following columns will be added:

• Criteria (not sortable)
  • Cell Value: A unordered list of assigned criteria

The following columns will be changes:

• Document
  • Instead of the file system path the document's title will be presented

2.5 Conceptual Boundary

This feature request does not address real versioning of documents or resetting acceptance states for users per document. But this could be future enhancements.

If the feature request  User: Introducing »Data Privacy Statement« documents does not make it into Release 5.4, we will not change the UI translations.

3 User Interface Modifications

3.1 List of Affected Views

• Administration / Terms of Service

3.2 User Interface Details

3.2.1 Create a New Document

3.2.2 Overview Table

3.2.3 Document Criteria

3.3 New User Interface Concepts

None

4 Technical Information

The existing acceptance history records have to be migrated to be compatible with the assigned criterions. For old records the only criterion to be mapped is the language.

5 Contact

• Author of the Request: Jansen, Michael [mjansen]
• Maintainer: Jansen, Michael [mjansen]
• Implementation of the feature is done by: Jansen, Michael [mjansen]

6 Funding

• CaT Concepts and Training GmbH

7 Discussion

JourFixe, ILIAS [jourfixe], 16 JUL 2018 : We highly appreciate this suggestion and schedule the feature for 5.4 with the following changes:

• We abandon the client-independent (/global/) user agreements with 5.4 (please add a related FW page). All existing global agreements have to be migrated to client-related user agreements (/clients/).
• Modal should be used for adding and editing criteria (if possible)
• Preview of documents should be done by clicking agreement title (opens agreement in light box) instead of using the "magnifier" icon.
• Information about 'Terms of Service' and reset button should be moved to a message box, while 'Add Document' button stays in a tool bar.

Jansen, Michael [mjansen], 09 AUG 2018: 

JourFixe: Modal should be used for adding and editing criteria (if possible)

I tried this with rountrip modals, but this does not work, yet. It did neither work with the legacy property forms, nor with the new UI framework form component. The roundtrip modal itself MUST have at least two buttons at the bottom.

Round-Trip modals MUST contain at least two buttons at the bottom of the modals: a button to cancel (right) the workflow and a button to finish or reach the next step in the workflow (left).

Both form approaches have/render their own submit button(s) and do not support asynchronous form submission and validation, which MUST be submitted by the modal button in this UI scenario. This is not supported.

Round-Trip modals SHOULD NOT be used to add new items of any kind since adding item is a linear workflow redirecting to the newly added item setting- or content-tab.

--

All other changes will be implemented. The deletion of criteria (or more appropriate: detaching criteria) will be done with UI interruptive modal, the presentation of documents will be done with a UI lightbox.

8 Implementation

Client-independent user agreements are abandoned and migrated to client-related user agreements: Abandon Client-independent User Agreements

Test Cases

Test cases completed at 2018-08-20 by Jansen, Michael [mjansen]

• C24634 : Anzeige der Formulars
• C24635 : Aktivieren der Nutzungsvereinbarungen (keine Dokumente vorhanden)
• C24637 : Aktivieren der Nutzungsvereinbarungen (Dokumente vorhanden)
• C24636 : Deaktivieren der Nutzungsvereinbarungen
• C24663 : Hinweis über fehlende Nutzungsvereinbarungen
• C24638 : Tabelle der Dokumente
• C24664 : Nutzungsvereinbarungen global für alle Benutzer zurücksetzen
• C24639 : Dokument hinzufügen: Darstellung des Formulars
• C24640 : Dokument hinzufügen: Absenden des Formulars
• C24641 : Dokument bearbeiten: Darstellung des Formulars
• C24642 : Dokument bearbeiten: Absenden des Formulars
• C24643 : Löschen von Dokumenten (Bestätigungsdialog)
• C24645 : Löschen von Dokumenten
• C24644 : Sortieren von Dokumenten
• C24650 : Kriterium hinzufügen: Darstellung des Formulars
• C24651 : Kriterium hinzufügen: Absenden des Formulars
• C24650 : Kriterium hinzufügen: Darstellung des Formulars
• C24651 : Kriterium hinzufügen: Absenden des Formulars
• C24652 : Zuweisung des Kriteriums bearbeiten: Darstellung des Formulars
• C24653 : Zuweisung des Kriteriums bearbeiten: Absenden des Formulars
• C24654 : Zuweisung des Kriteriums löschen
• C24655 : Auflistung der Zustimmungshistorie
• C24659 : Anwenden eines Filters
• C24660 : Anzeige im Benutzerprofil
• C24665 : Ermittlung/Evaluierung von Nutzungsvereinbarung
• C24661 : Anzeige bei der Selbstregistrierung
• C24662 : Verlinkung und Anzeige auf der Anmelde-Seite
• C24666 : Vorlage nach erfolgreicher Anmeldung/Authentifizierung in der Benutzeroberfläche
• C24667 : Auswirkungen nicht akzeptierter Nutzungsvereinbarungen auf den ILIAS-Webservice
• C24668 : Auswirkungen nicht akzeptierter Nutzungsvereinbarungen auf den Mail-Service

Approval

Approved at 2018-10-22 by Klees, Richard [rklees].