University of Colorado
How do I start using the ES-DOC Questionniare?
The first step in using the ES-DOC Questionnaire is to sign up for a Questionnaire account. Clicking the "sign up" button at the top of the page will open the registration form (Figure 1).
Once an account has been created the account-holder will be able to update their details (Figure 2).
It is particularly important to select an institute the user is affiliated with. Currently, users without an insittute will be unable to publish any CIM Documents.
Once a user's email address has been verified, they can join a Questionnaire project. The main Questionnaire Project page provides a button to do this.
Clicking that button will send a request to the Questionnaire Project Administrator who can approve or deny it. Until membership is granted, a user will be able to view CIM Documents in the Questionnaire but not create, edit, or publish them.
How do I create a CIM Document?
Once an appropriate customization exists, creating and editing CIM documents can begin. From the main ES-DOC Questionnaire Project Page (Figure 4) either use the drop-down menu to select a document type and click “create” or else choose an existing document from the provided list and click “edit”. In both cases, this will open the editing form in a new browser tab.
Once an appropriate customization exists, creating and editing CIM documents can begin. From the main ES-DOC Questionnaire Project Page (Figure 4) either use the drop-down menu to select a document type and click “create” or else choose an existing document from the provided list and click “edit”. In both cases, this will open the editing form in a new browser tab (Figure 5).
Properties for a document appear from top to bottom and can be grouped in tabs by category. There are three different types of properties: atomic, enumeration, and relationship.
Atomic properties take simple values such as strings, dates, or integers.
Enumeration property values are selected from a predefined list (Figure 6). In some cases you may choose “other” from the enumerated list and provide a custom value.
Relationship properties point to other CIM entities which themselves contain properties. Relationships can be rendered in one of two ways: either as references or in-line as subforms. Relationship to other CIM Document must be rendered as a reference. The reference widget (Figure 7) allows users to select from published CIM Documents. Other types of relationships must be rendered as a subform (Figure 9). This is simply a nested set of property fields corresponding to the related document type. A subform could itself have a subform.
Clicking on the reference widget will bring up a dialog box listing published documents from which to select the reference (Figure 8).
What about hierarchical documents?
Some documents, such as those describing CMIP6 Realms (sea ice, biogeochemistry, etc.), contain relationships that should be treated as hierarchies of inline documents. For example, a sea ice realm contains several sub-processes including dynamics, thermodynamics, and radiative processes. These processes are rendered as part of a hierarchical component tree on the left-hand of the editing form (Figure 5).
Selecting any node of that tree renders the corresponding property collection on the right-hand side of the editing form. Additionally, toggling the checkbox next to each node will activate or deactivate the corresponding property collection. In the case of a deactivated property, none of that content will be included during publication. In this way a user can describe a model that does not, for instance, contain a thermodynamics sub-process.
What if I don’t know the value of a CIM Document property?
Some properties (those that are not required by a project) can be marked as ignored. A property that is explicitly ignored can remain blank while not affecting the “completeness” of that document. Ignoring a property can also help to clarify if a value is blank because it has not yet been filled in or if there simply is no suitable value. Choosing to ignore a property will force it to become read-only and requires users to explain why it is being ignored (Figure 10).
How do I publish a CIM Document?
All required properties of a document must have a value - or be explicitly ignored - before a user can publish that document. An icon next to the document’s name on the ES-DOC Questionnaire Project Page (Figure 4) indicates whether or not a document is complete (as does the presence or absence of a “publish” button).
Upon publication the document contents are serialized to XML and published to a local ATOM feed. This feed is checked regularly by other ES-DOC tools and newly published documents will eventually appear in the ES-DOC Archive where they can be viewed or compared with other documents of the same type.