LLMCMSS.04 - CMS service component functional specification

This part of LLMCMSS specifies the functionality and behaviour of the LLM CMS service software.

LLMCMSS.04.00 Document Control

LLMCMSS.04.02 Overview

1. The CMS service is the core of the central management of the LLM system. It has no user interface, but provides a web service API for all of its functionality. The LLM CMS LUI and other higher-level functionality use this API to provide a user frontend to the management functions and to perfrom management and adminitrative actions.
2. The CMS component provides also a Web-based RUI (Remote User Interface) including, aside from the functions provided locally by the CMS LUI, all enhanced administrations activity necessary for LLM CMS configuration management.
3. This part of LLMCMSS specifies API functions to be accessible via web-service.
4. All API methods shall be usable also as locally invoked functions. However, documentation shall state where side-effects are to be expected because of the then following multi-instantiation or security issues of underlying objects. As an example, sessions may be created locally and per web-service. Sessions are held persistent in the LLM-DB. A local applicaiton may not have access to the LLM-DB, only CMS service shall have it. Therefore, session management MUST be called remotely.
   On the other hand, there may be idempotent helper objects whose manageing methods may be invoked also locally.
5. IMPORTANT: (new in issue 06) There are a number of functions specified in this part. Not all othem may be required by the higher-level applications. Their existence has been expected at some time in the specification process. However, the implementation may take other paths as foreseen by the specification and may render some functions no longer necessary. In order to avoid redundance, higher level applications should be designed together with the top-level-design of the CMS service in order to identify obsolete functions.
   Functions that are already known to be possibly not required, at least not in Version 1 of the LLM system, are marked up with OPTION_CHECK. This means that before implementing this function, the higher level applications should be examined for the requirement.
   NOTE however, that a few functions in this part are marked as MANDATORY and are expected to be required anyway, either by near future enhancements or by plug-ins in either LRF , LLF, PTC or CTC integrations. Therefore, these shall be implemented anyway.
6. The CMS service component exposes 2 interfaces: a web-service API and a web user interface. The former is specificd in LLMCMSS.04.02, the latter, also titled "CMS RUI", is specified in LLMCMSS.04.05.

LLMCMSS.04.02 CMS API functions

1. Not all API functions need to be available as CMS RUI functions, CMS RUI functions are explicitely named in LLMCMSS.04.05
2. Every API function shall be protected by access security and shall be logged including security credential information and terminal name(if applicable)
   
   1. User credentials shall be kept in the session and associated with a terminal.
   2. credentials shall be valid only with the terminal kept in the session. Therefore, each API call needs to have a terminal ID with it. API calls not from real terminals must provide valid virtual terminal IDs.
   3. Sessions may be transferred from one terminal to another by a specific "change terminal" API call. This API call shall not be available to all users, only to special ones.
3. There shall be a generic strcuture editor API to perform low-level viewing and changing of LLM-DB PROPERTIES structure (for generic editing, the API specified in LLMCMSS.04.02.14 shall be employed):
   1. Session shall keep "edit point" in the PROPERTIES structure
   2. navigation commands/methods to go up/down/previous(n)/next(n)/list(n) in the PROPERTIES tree
   3. commands/methods to add/change/delete current item
   4. commands/methods to export/import from download/upload XML file
4. User logon
5. Session management
   1. Create Session, associate with terminal (local/remote) and user account
   2. Lock/Unlock Session
   3. Dump / Restore Session
   4. Terminate / Shutdown Session
   5. Manage Session variables/properties (create/query/delete/associate)
   6. change terminal
6. user account management
   1. A user account may have arbitrary properties in hierarchical manner associated with it.
      1. Managing secret values shall avoid sending cleartext values across any network (even LAN)
      2. Especially, managing picture code loigin tokens shall be in conformance with LLMCMSS.06.02.01
   2. Create Account
      1. There shall be a template for each user account created
      2. The template shall have default property values copied into the newly created account
      3. If there is no template name given, a default template, the name of which is configured in the property
         "/sysconfig/sysdefaults/default_user_template_name", shall be used. The hardcoded default for this shall be that no template shall be used.
      4. If there is no template applicable, the empty template will be used, this means, no properties will be assigned to the user account.
   3. Lock/Unlock Account
   4. Export / Import Account
7. Preferences management
   1. Screen readability
   2. Audio levels
   3. Language Settings
   4. skinnig
   5. avatar hooks and avatar state
      1. preparation for integration of Audio TTS notification reading
      2. preparation for integration of alternative forms entry methods:
         1. provide user credentials / authorisation information via:
            1. smartcard
            2. sound recognition
         2. provide dialogue box (yes/no/...) responses via:
            1. sound recognition
8. Equipment Management
   1. PTC Equipement and Settings
   2. CTC Equipment and Settings
   3. export / import settings
9. Statistics data management
   1. query logging/statistics data
   2. filter
   3. export / import
   4. delete
   5. space management
10. schedule/appointment processing
    1. create scheduled activities/appointments with repeat/interval/calendar characteristics
    2. Execute the scheduled activity or generate notifications when schedules are due
    3. optional / for later versions: pre-announcements and repeat announcements if not confirmed
11. workflow processing
    1. CMS component shall be able to manage workflows conformant to WMFC standards, preferrably XPDL
       There are a number of open source XPDL processors available, shall be checked.
       Events and Agents and Activities shall be mapped to the respective LLM object types
12. notification management
    1. CMS shall keep information about the state of users and sessions
    2. any application shall be able to issue a notification request for a user or a specific session of a user via CMS SOAP API
       A notification shall be a displayable entity and shall have properties structuring the data and giving hints about presentation of the data
    3. CMS shall display the notification in the appropriate window and requested way plus bringing the window to the front if requested
    4. CMS shall keep track of confirmation of a notification (press a button when notification is read) if requested and perform follow-up activity in case of no confirmation from the user
    5. Notification shall be able also to take alternative forms additionally to local terminal display: send email, forward events to other applications and/or workflows
13. general functions for schedule/workflow/notification management
    
    1. General event API
       There shall be set of methods to inject events into the CMS subsystem.
       Events shall have arbitrary properties that can be used as mapping/routing criteria or to carry information up to displayable text or processing instructions
    2. Event mapping
       Events shall be able to be mapped to activities inside the CMS component configurably depending on property values
    3. Timing facility
       There shall be a function to execute activities based on absolute or relative time/date values or intervals. This facility shall be able to interact with the calendar/schedule management to perform activities and generate notifications based on schedule/calendar entries.
14. MANDATORY (needed by LLMCMSS.06.05.02) There shall be an umbrella API for the use of applications and the configuration editor use case in LLMCMSS.06.05.02. The same mechanisms for structure navigation and manipulation as in LLMCMSS.04.02.03.
    1. Session shall keep "edit point" in the PROPERTIES structure
    2. navigation commands/methods to go up/down/previous(n)/next(n)/list(n) in the PROPERTIES tree
    3. commands/methods to add/change/delete current item
    4. commands/methods to export/import from download/upload XML file; handling parameters as in LLMCMSS.06.05.02 and in conformance with screen definitions in LLMCMSS.06.06.06
    5. The virtual unified "tree" shall look like this (sub-structures  of the elements at root level except for "PROPERTIES" shall be as specified in the LLM-WS definition):
       1. root "/"
          1. "MEMBERS"
          2. "USERS"
          3. "SENIORS"
          4. "USER_SENIOR_RELATIONS"
          5. "CTC"
             1. "COMPONENTS" - CTC components
             2. "ACTIVITIES" - CTC activity
             3. "SENIOR_ACTIVITIES" - CTC senior's activity
          6. "PTC"
             1. "COMPONENTS"
             2. "ACTIVITIES"
             3. "SENIOR_ACTIVITIES"
          7. "ILC"
             1. "COMPONENTS"
             2. "ACTIVITIES"
             3. "SENIOR_ACTIVTIES"
          8. "PROPERTIES"
             1. "CLASSES" - tree templates for standard objects, with classes and types for object attributes
             2. "TYPES" - type definitions of tree leaves, including subtyping and ranges
             3. "SESSIONS" - session persistent structure
    6. The mapping (as described above) of disparate structures into the virtual tree shall not be hard-coded. There shall be a struture in the PROPERTIES subtree defining the tree. The employed pattern shall be that of a Unix file system tree with mounted file systems. Each subtree (="mounted filesystem") may have its own implementing dynamically loaded class library.
    7. OPTION_CHECK (implement only if the need by applications arises) The above mapping structure shall also allow for "links" as already specified in LLMCMSS.09.03.01.06, but this time explicitely allowing to access one and the same structure by different names (=points in the information tree)

LLMCMSS.04.03 CMS function interfaces

The CMS function block has 4 interfaces:

1. Web-Service interface provided to be used by CMS LUI or other CMS function consumers
2. Web-Service client to LLM-DB
3. local Filesystem for local configuration, basic logging/auditing and data caching
4. web-application environment for basic bootstrap configuration

LLMCMSS.04.03.01 CMS function provided web service interface

The CMS function block shall expose a web service interface providing all the functions listed in LLMCMSS.04.01.

LLMCMSS.04.03.02 LLM-DB functions needed by CMS

All data structures and functions required by the whole CMS subsystem are kept together in LLMCMSS.09

LLMCMSS.04.04 CMS implementation issues

1. CMS shall be implemented as a web-application providing SOAP web services running in a JEE container
2. CMS shall be implemented stateless, only using internal structures for buffering, persistent storage shall be kept in LLMDB, most probably in the sessions context.
3. Instantiation and life cycle management
4. domain scope
   1. one instance of CMS shall be associated with one administrative domain, i.e. one instance of LLMDB. However, multiple database connections shall be possible to address redundancy issues

LLMCMSS.04.05 CMS RUI functionality

The functions mentioned in this section shal be offered by the CMS on the web-based RUI interface:

LLMCMSS.04.05.01 user administration

As of LLMCMSS Issue 0.8 and newer, there is no administration task to be handled using the LUI. All administration is to be handled via RUI. Therefore, the requirements in this section are moved from LLMCMSS.02 to here.

1. CMS RUI shall allow to create a user account, provided creating user has appropriate rights
   1. new user account shall be pre-filled from a template, template shall be selectable at creation time
2. CMS RUI shall allow user account deletion, provided user has appropriate rights.
   
   1. Real Deletion shall be effected only in certain cases. In order to avoid data referencing "into the void", user accounts shall be marked "deleted", but not deleted really if avoidable.
3. user accounts shall have arbitrary number of attributes, CMS RUI shall take account for this fact:
   1. UserCategory: Senior, User
   2. UserRole: Relative, Therapist, Administrator, Unknown
   3. All attributes assigned by LLMDB web service interface
   4. Additional Attributes as seen fit to fulfil additional features:
      1. Multi-Tenancy
      2. Sub-Grouping
      3. Privacy Attributes
      4. Judisdiction imposed properties
      5. Managing picture code loigin tokens shall be in conformance with LLMCMSS.06.02.01
4. unique user ID shall be constant across database versions and shall allow
   1. moving a user across database instances
   2. exporting / importing single or multiple users
   3. merging and splitting of LLMDB instances during re-organization
   4. manipulation of users on database level without breaking validity on web service level
5. The user administration shall be only a configuration of the general object editor (GOE) specified in LLMCMSS.04.05.03. General functionality shall be re-used as much as possible. If there seems to be special functionality required by the user administration, it shall be investigated if it can be generalized and to be put in the general object editor. One special functionality for user administration is the management of the picture code. It shall be managed inside the GOE with a specific Add-On to handle picture codes like specified in LLMCMSS.06.02.01.

LLMCMSS.04.05.02 schedule administration

1. CMS RUI shall allow creation, modification and deletion of scheduled events for any user
2. schedules shall be administered according to functionality specified in LLMCMSS.04.02.10
3. The schedule editor shall be only a configuration of the general object editor specified in LLMCMSS.04.05.03. General functionality shall be re-used as much as possible. If there seems to be special functionality required by the schedule editor, it shall be investigated if it can be generalized and to be put in the general object editor.

LLMCMSS.04.05.03 GOE - general object editor

1. Every Administration or data management web user interface shall be derived from a general object editor. The common functionality of each admin function shall be kept in a common framework in order to implement it only once and then re-use it. Moreover, this also allows for future enhancements without having to develop an extra administration or editing software component for future additional configuration or other structured data.
2. The general object editor, also abbreviated GOE, shall allow creation, modification, inspection, deletion, export and import of any structured data in the LLM database.
3. The GOE shall rely on the API specified in LLMCMSS.04.02.14 for uniform tree-based access to the LLM-DB
4. Metadata shall be used to define:
   1. what properties (memeber variables) an object of a specific class shall have
   2. the attributes of the properties of an objects
   3. user entry, validation and editing methods for specific property data types
   4. at what point in the LLM-DB-tree which types/classes of objects are allowed
5. Metadata shall also be stored on the LLM-DB tree
6. protection mechanisms shall be obeyed to determine if the user using the GOE is allowed to perform the desired object editing operation. If the standard LLM-DB security control mechanism is not sufficient to determine the specific access control. the metadata shall augment the security definitions to a greated level of detail. One such enhancement may be that a specific role of user may only add a property at a certain location of the LLM-DB-tree or that another role of a user only may set a specific property to a certain value range.

LLMCMSS.04.05.04 - Generic property editor

1. The CMS RUI shall provide a generic access to the LLM-DB as viewed by the LLM-DB tree API specified in LLMCMSS.04.02.14.
2. This function shall be abbreviated as GPE - the Generic Property Editor
3. GPE shall be a low-level access to each single property as stored in the LLM-DB. No interpretation shall be done, all properties shall be displayed and editable in their primitive data types with the full value range allowed for these:
   1. NUMBER - decimal text representation of the number
   2. STRING - display the string with escapes for non-prinbtable characters
   3. PROPERTIES - display a hyperlink leading to another list displaying the contents of the respective tree branch level
4. GPE shall display one level of the tree at one time.
5. Each property shall be displayed as 3 text fields:
   1. The name
   2. The Type: NUMBER, STRING and PROPERTIES
   3. The value
6. All fields shall be editable text fields
7. Each property row shall have a "submit changes" button and a "delete" button, performing the respective action directly, if allowed by security settungs in the database.
8. If the number of entries shown at one time exceeds a configurable limit, the listing shall be split up in pages. The RUI shall provide controls to navigate between the pages
9. each page shall have an empty row if input fields to add a new property. It shall have an "add" button to commit the new row to the LLM-DB
10. GPE shall have a "select file" form to specify a file name to import from or to export to
11. GPE shall have an "import" button. Pressing this button shall effect in importing property values from the specified file in XML form
12. GPE shall have an "export" button. Pressing this button shall effect in exporting the current property tree into the specified file in XML form
13. The "import" and "export" functionality shall support:
    1. moving a subtree inside the whole tree
    2. backing up of a subtree or a complete LLM-DB
    3. restoring a subtree or a complete LLM-DB
14. After submitting changes (delete, submit changes, import, export, add) the current page shall be re-displayed with possible effect caused by re-arranging the subtree. If applicable, the first page shall be displayed in spite of the current page (after deletion or importing)
15. GPE RUI screens shall be taken from LLMCMSS.06.06.06

LLMCMSS.04.05.05 - Training Result Viewer

1. CMS RUI shall provide a web-based viewer for training results intended for the audience class the current RUI user belongs to
2. The training results shall be assumed to have been prepared by the LRF in the same manner as the feedback for the senior.
3. Training results for audience classes like therapist or relative may contain more details than the results for the senior.
4. Training results displayed shall be able to have additional auxiliary data related to the training results. Which data to select shall be configurable but need to be retrievable based on a training result record like:
   1. senior name
   2. training session time
   3. additional senior properties
   4. training session details retrievable from the raw training result records
5. The RUI training result viewer shall allow selection of training results by criteria like:
   1. senior name or ID
   2. training type
   3. time range
   4. target audience class
6. Allowed values for selection criteria, target audience class and presented auxiliary data shall be restrictable by the security credentials of the RUI user:
   1. A relative for one senior may be allowed only to view results for this senior and only for the relative target audience class.
   2. A therapist may be allowed only to view results for the seniors assigned to her/him in the "attending doctor" relation
   3. A training programme developer may be able to view all training result for a specific programme but not the names or other personal data of the respective seniors
7. RUI Training result view screen shall have 2 panes:
   1. entry form for selection criteria
   2. display form for report HTML output and auxiliary data
8. If the selection criteria result in more than one report record to be displayed, the display pane shall have navigation control to browse amongst the result.
9. In order to use screen real estate as efficient as possible, the display pane shall be a scrolling area potentially capable of displaying more than one report in a scrollable area
10. The user shall be able to choose amongst a number of configurable display pane templates to select the displayed data items and to be able to flexibly choose amongst list/page/... views
11. display and selection pane contents shall be printable of exportable in CSV/PDF, detailed output depending on the applicable representation types. generated exports shall be able to be sent via Email