Proc4-package: Four Process Assessment Database and Dispatcher

In ralmond/Proc4: Four Process Assessment Database and Dispatcher

Four Process Assessment Database and Dispatcher

Description

Utilities for working with messages in the four four process architecture as json objects.

Details

The DESCRIPTION file: This package was not yet installed at build time.
Index: This package was not yet installed at build time.

This package exists to supply core functionality to other processes implementing processes in the four process architecture (Almond, Steinberg and Mislevy, 2002). In particular, it contains low level code dealing with implementing message queues in a document database (mongo) and reading/writing messages from JSON.

There are five major features of this package documented below:

1. The P4Message object and the protocol for converting messages to JSON and saving them in the mongo database.

2. A withFlogging function which wraps the flog.logger protocol.

3. A number of Listener objects which implement an observer protocol for messages.

4. The config directory contains a number of javascript files for building database schemas and indexes.

5. The dongle directory contains a number of PHP scripts for exposing the database via a web server.

Earlier verisons included a number of tools which wrap funcions in the mongolite and jsonlite packages. In particular, this included the as.json, parse.json, and buildObject generic functions to manage the conversion from S4 object to JSON and back, the saveRec, getOneRec, and getManyRecs methods for saving and restoring objects from a database, and the buildJQuery for building Mongo queries from R-like syntax. These have been moved to the mongo package.

P4 Messages

The extended four process architecture defines a message object (P4Message) with the following fields:

_id:

Used for internal database ID.

app:

Object of class "character" which specifies the application in which the messages exit.

uid:

Object of class "character" which identifies the user (student).

context:

Object of class "character" which identifies the context, task, or item.

sender:

Object of class "character" which identifies the sender. This is usually one of "Presentation Process", "Evidence Identification Process", "Evidence Accumulation Process", or "Activity Selection Process".

mess:

Object of class "character" a general title for the message context.

timestamp:

Object of class "POSIXt" which gives the time at which the message was generated.

data:

Object of class "list" which contains the data to be transmitted with the message.

processed:

A logical value: true if the message has been processed, and false if the message is still in queue to be processed. This field is set with markAsProcessed.

pError:

If a error occurs while processing this event, information about the error can be stored here, either as an R object, or as an R object of class error (or any class). This field is accessed with processingError and set with markAsError.

Other classes can extend this message protocol by adding additional fields, but the header fields of the message object allow it to be routed.

In particular, the processed field allows a database collection of messages to be used as queue. Simply search for unprocessed message and begin processing them oldest first, using markAsProcessed to mark the complete process and markAsError to mark errors.

The mongo::as.json and mongo::parse.json functions build JSON representations of S classes. In general, this process needs explicit instructions on how to code/decode the fields of the object. Methods of the inner mongo::as.jlist and mongo::parse.jlist provide this functionality. Note that classes which extend P4Message class will need to use these methods. The cleanMessageJlist does the common processing for the P4Message parent class. Finally, buildMessage is a more specific version of the buildObject generic builder.

The functions saveRec, getOneRec and getManyRecs facilitate saving and loading message objects from the database. The function buildJQuery gives R-like syntactic sugar to building mongo (JSON) queries.

Logging

The logging system for the Proc4 processes is mostly just the flog.logger protocol. Aside from importing the futile.logger package, Proc4 adds the function withFlogging executes a series of statements in an environment in which the error messages will be logged, and at higher logging levels, stack traces for errors and warnings are given. The intention is that most message handling functions will be wrapped in withFlogging, so that information about the message causing the error/warning will be available for debugging.

The package also supplies a mongoAppender class, which provides a way of logging messages to a database.

Listeners

The Proc4 package implements an observer protocol called Listener. A listener is an abstract class which implements the receiveMessage function. The argument of this function is a P4Message object, which the listener then does something with. (In most of the implemented examples, this is to save it in a database.) Note that listeners should also define a isListener method to indicate that it is a listener.

Four listeners are currently implemented (see Listener or the individal listener classes):

CaptureListener

Creates an object of class CaptureListener which stores the messages in a list.

InjectionListener

Creates an object of class InjectionListener which inserts the message into the designated database.

UpdateListener

Creates an object of class UpdateListener which updates the designated field.

UpsertListener

Creates an object of class UpsertListener which insert or replaces the message in the designated collection.

TableListener

Creates an object of class TableListener which adds details from message to rows of a data frame.

The RefListener is an abstract class which provides methods for the other classes (in particular, promoting the class-based methods to true S4 methods. These include isListener(), listenerName, listeningFor, receiveMessage, and clearMessage. Note that the default methods for the latter two functions rely on internal $receiveMessage() and $reset() class-based methods, which must be implemented in the subclasses.

The ListenerSet class is a mixin to associate a collection of listeners with an object (the EIEngine and BNEngine classes use this). The generic function notifyListeners can be called. This logs information about the message (see logging system above), save a copy of the message in a “Messages” database, and calls the receiveMessage method on all of the listener objects in its collection.

Configuration Files

Using the mongo database, both security (user IDs and passwords) is optional. Running mongo without security turned on is probably okay as long as the installation is (a) behing a firewall, and (b) the firewall is configured to not allow connections on the mongo port except from localhost. However, other users may want to turn on security.

The recommended security setup is to create four users, “EIP”, “EAP”, “ASP”, and “C4” for the four processes and to assign a password to each. The URI's of the database connections then need to be modified to include the username and passwords. Each process would have an ini.R file which contains its password which is stored in an appropriate configuration directory. (On *nix systems, the recommend location is /usr/local/share/Proc4.)

The files Proc4.ini (PHP format) and Proc4.js (javascript format) can be used for saving the key usernames and passwords. These files are located in the directory file.path( library(help="Proc4")$path, "config"). To install these files it is necessary to copy the files to the configuration directory and edit them so that the password reflects local preferences.

The file setupDatabases.js in the config directory creates databases for each of the processes and stores the appropriate login credentials. (Note that this calls Proc4.js to get these credentials so that file must be established first.) This is a javascript file designed to be run directly in mongo, i.e., mongo setupDatabases.js. Note that it must be run by a user which has the appropriate priveleges to create databases and modify their security (a “root” user).

The file setupProc4.js in the config directory sets up schemas and indexes for collections in the Proc4 database which are used by the dongle process. Schemas are optional in mongo, but the indexes should speed up operations.

Dongle Files

The directory file.path(library(help="Proc4")$path, "config") contains files that facilitate direct communciation with the mongo database. In particular, there are a number of PHP scripts which if put in a directory available to the web server will allow remote processes to get information about users in the system. The scripts are:

PlayerStart.php

Called when player logs in on a given day. As data returns information needed to restore gaming session (currently bank balance and list of trophies earned). Note that player details are updated by the EI process.

PlayerStop.php

Called when player logs out. Currently not used. It is designed to help automatically shut down unneeded processed.

PlayerStats.php

Called when current player competency estimates are required, e.g., when displaying player scores. It returns a list of statistics and their values in the data field; the exact statistics returned depend on the configuration of the EA process. This database collection is updated by the EA process after each game level is processed.

PlayerLevels.php

Called when the game wants the next level. The message data should contain information about what topic the player is currently addressing and a list of played and unplayed levels, with the unplayed levels sorted so the next level according to protocol is first on the list. The complete list of levels should be returned so that if levels on the list have already been completed, a new level would be entered. Although the PHP script has been built, the AS process to feed it has not.

In addition, there is a file called LLtoP4 in that directory which is a bash script for translating between xAPI and Proc4 message formats. The function LLtoP4Loop repeatedly downloads xAPI statements from the learning locker database, translates them to P4 format, and uploads them to the EI process database.

The vingette file Dongle.pdf describes the dongle and database structure in more detail.

Acknowledgements

Work on the Proc4, EIEvent and EABN packages has been supported by the following grants:

• Bill and Melinda Gates Foundation grant “Games as Learning/Assessment: Stealth Assessment” (no. 0PP1035331, Val Shute, PI)

• National Science Foundation grant “DIP: Game-based Assessment and Support of STEM-related Competencies” (no. 1628937, Val Shute, PI)

• National Scient Foundation grant “Mathematical Learning via Architectual Design and Modeling Using E-Rebuild.” (no. 1720533, Fengfeng Ke, PI)

• Institute of Educational Statistics Grant: “Exploring adaptive cognitive and affective learning support for next-generation STEM learning games.” (no. R305A170376-20, Val Shute and Russell Almond, PIs')

The Proc4 package developement was led by Russell Almond (Co-PI).

Author(s)

Russell Almond

Maintainer: Russell Almond <[e-mail]>

References

Almond, R. G., Steinberg, L. S., and Mislevy, R.J. (2002). Enhancing the design and delivery of Assessment Systems: A Four-Process Architecture. Journal of Technology, Learning, and Assessment, 1, http://ejournals.bc.edu/ojs/index.php/jtla/article/view/1671.

The source code, and issues database can be found at https://github.com/ralmond/Proc4

See Also

flog.logger, EIEvent, EABN

ralmond/Proc4 documentation built on June 13, 2025, 7:13 a.m.