Data Envelope and Metadata

This page describes an Orbeon Forms project, not a feature which is currently part of Orbeon Forms.

Contents

  1. 1 Rationale
  2. 2 Envelope format
  3. 3 Permissions in form definitions
    1. 3.1 Form Builder
    2. 3.2 Form Runner
    3. 3.3 Persistence layer
    4. 3.4 Backward compatibility

Rationale

Form Runner currently receives and sends form data only, as an XML document. Metadata such as form name, app name, document UUID, are provided via request parameters. For more advanced applications, including workflow-based applications, this is not enough as the amount of metadata increases. This is the motivation for adding an extensible metadata document, which can either be used independently or combined with data by adding an envelope.

Envelope format

An XML document tentatively looking like this:

<fr:envelope>
    <fr:head>
        Form head elements; see table below
    </fr:head>
    <fr:body xmlns="">
        <form>
            Form data
        </form>
    </fr:body>
</fr:envelope>

Description of the elements:

fr:envelope     Root element of the envelope
  fr:head   Head section
    fr:uuid Form Runner-assigned UUID
    fr:app-name Form Runner application name
    fr:form-name Form Runner form name
    fr:workflow-id Optional workflow id passed from an external source. This information is not used by Orbeon Forms, but can be stored in this element when an external workflow system "opens" a form in Orbeon Forms. This way, when control is given back to the external workflow system, it knows, based on this id, what workflow the data is for.
    fr:workflow-state Optional workflow state passed from an external source. The state can be a token, like pending or approved.
  fr:create-rolesOptional space separated list of roles.
  fr:create-usernamesOptional space separated list of usernames
    fr:access-roles Space separated list of roles
  fr:access-usernamesSpace separated list of usernames.
  fr:task-rolesOptional space separated list of roles.
  fr:task-usernamesOptional space separated list of usernames.
  fr:body   Payload containing a single root element which is the form data

  • Users can create an instance of a form if their role is listed in fr:create-role or username is listed in fr:create-username in the corresponding form definition. These two elements are only present in the fr:head section for form definitions (not form data). This drives the forms listed in the Start a new form section of the Start page.
  • Users can access a form if their role is listed in fr:access-roles or username is listed in fr:access-usernames. For form definition, this means the user can edit the form in Form Builder; the form is listed in the Archive section of the Start page. For form data, if users also have a task for the form, it is listed in the Your tasks section, otherwise in the Archive section of the Start page.
  • Users have a task for a form if role is listed in fr:task-roles or username is listed in fr:task-usernames. In general, users having a task for a form should also have access to the form, so when their task is completed the form shows in their Archive.

TBD: How the title (description), task, and state are encoded in the head, taking into account that all 3 must be i18n aware.

Permissions in form definitions

  1. Permissions — The fr:head section of form definition can contain a fr:permissions element. When it does, this imposes limits who can perform what operation on the data of the relevant form type. For instance with the following we say that guest users can post a sales inquiries, but only sales people can read them:

    <fr:permissions>
        <fr:permission operations="create">
            <fr:user-role any-of="guest"/>
        </fr:permission>
        <fr:permission operations="create read update delete">
            <fr:user-role any-of="sales"/>
        </fr:permission>
    </fr:permissions>

  2. User role condition — The fr:permission gives permission to perform the operation(s) in the operations attribute when all the conditions expressed by children elements are met. In the above example, each permission has only one condition: fr:user-role with an attribute any-of which means "the current user must have at least one of the roles listed in the space-separated value of the attribute any-of.

  3. Future conditions for Form Builder — In a first phase, we only intend to support the fr:user-role constraint. In the future, we could imagine additional constraints such as <fr:control name="app" value="hr"/> which would grant the permission only of the value of the control name app is hr. Adding this capability would be a more generic way to implement what is done right now in form-builder-permissions.xml. This would also allow administrator to setup similar permissions for other forms; for instance to say that only sales people with the sales-americas can access sales inquires if the value of the region field is americas:

    <fr:permission operations="create read update delete">
        <fr:user-role any="sales-americas"/>
        <fr:control name="region" value="americas"/>
    </fr:permission>

  4. Blue-sky thinking — Users could define their own operations by using a prefix, for instance: my:approve-expense. We could have a <fr:control any-of="..."/> whose attribute could be an AVT. Also, let's assume we have an XPath function my:get-direct-reports() returning a space separated list of the username of the employees reporting to the current user. Then the following would assign the permission my:approve-expense to users who are the manager of the employee who filled that expense report. Then the form could test on the precence of that permission to enable or disable certain fields, like an approved checkbox.

    <fr:permission operations="update my:approve-expense">
        <fr:role any="manager"/>
        <fr:control name="username" any-of="{my:get-direct-reports()}"/>
    </fr:permission>


Implementation steps

Form Builder

Form Builder is modified to support the envelope and generate it upon form creation. If the envelope is present, then the user interface binds to the nested form data.

Form Runner

Form Runner is modified to support the envelope. If the envelope is present, then the user interface binds to the nested form data.

Persistence layer

The persistence layer is made envelope-aware to allow storing/retrieving/searching the envelope.

Backward compatibility

Possibly, for compatibility, an envelope-free mode might be still supported (TBD), and/or be configurable.

Comments