A Logic Example: Linking Documents To A Task

Most operations are performed by clients using some protocol over HTTP: XML-RPC, JSONRPC, REST, WebDAV, etc... It is also possible to utilize Python on any OpenGroupware Coils node to perform operations to use the Logic commands directly. The following example demonstrates how to create an object link from the specified task, OGo#318084549, to all the documents in folder OGo#231408659, setting the label of the link to the document's display name.

from coils.core import \
    AdministrativeContext, \
    initialize_COILS, \
    Document

TASK_OBJECTID = 318084549
FOLDER_OBJECTID = 231408659

if __name__ == '__main__':
    initialize_COILS()
    ctx = AdministrativeContext()
    task = ctx.r_c('task::get', id=TASK_OBJECTID)
    folder = ctx.r_c('folder::get', id=FOLDER_OBJECTID)
    for content in ctx.r_c('folder::ls', folder=folder):
        if isinstance(content, Document):
            ctx.link_manager.link(
                task, 
                content, 
                label=content.get_display_name(),
            )
    ctx.commit()

The call to initialize_COILS sets up the Coils runtime environment discovering the Logic bundles, etc... Then an AdministrativeContext is created - in OpenGroupware, both Legacy and Coils, nearly all operations are performed via a Context object. The Context provides the security context and identity used for all the Logic operations performed by calling run_command [for which r_c is a shortcut] as well as the database session and state [see the final call to the context's commit]. Context also provides a variety of manager object instances:

• link_manager for handling object links
• property_manager for handling object properties
• type_manager for entity introspection
• defaults_manager for user defaults
• lock_manager for taking and releasing entity locks

Many of the Logic commands utilized through run_command use these same manager instances from the context they are run in.

The AdministrativeContext assumed the security context of OGo#10000 - the OpenGroupware superuser. No security restrictions apply to AdministrativeContext. If operations should be performed as a user the AssumedContext can be used; the object id of the desired context is specified when the context is created.

ctx = AssumedContext(10100)  # Operate as user OGo#10100

Context objects of AnonymousContext having essentially no right beyond globally readable objects and NetworkContext having the rights of a network service are also available.

Using context objects and Logic commands scripting even complex operations can be accomplished relatively simply.

The one caveat with scripting on the OpenGroupware Coils node is to ensure you execute the script as the OpenGroupware user - typically ogo. If scripts are executed as another use it is possible to create files withing the OpenGroupware server root which will be inaccessible to server components.