This document provides a task-oriented introduction to using Annalist. It assumes Annalist has been installed or deployed, and provides step-by-step description of how various data management tasks can be performed using Annalist.
|This document is an early draft, and is much in need of improvement. Please submit feedback and comments either to the Annalist Github issues list, or via the Annalist discussion group.|
Table of Contents
- Running example
- Log in to Annalist
- User permissions
- Browsing an existing Annalist collection
- Creating a new collection
- Change collection metadata
- Create initial record type and views
- Create some initial data records
- Add simple fields to a data record
- Upload images to a collection
- Add repeating fields to a data record
- Create an additional data type (with view+list)
- Create links between records
- Display fields from a linked record
This tutorial uses a running example of a personal photograph library, starting with a simple catalogue of images and some associated metadata, and then adding additional structures to cross reference other entities involved in the picture-taking process. For this example, we use a prefix
pcat for URIs (actually ["Compact URIs"](http://www.w3.org/TR/curie/), or CURIEs) defined specifically for the photograph catalogue. This prefix will eventually be associated with a base URI to allow identification on the World Wide Web. (@@TODO: full linked data support.)
The completed example can be seen at the Annalist demo site, as collection [Annalist photo collection]. (@@TODO, once current in-development software is deployed.)
Log in to Annalist
The first time of logging in to an Annalist site from some computer will involve some or all of the following.
select a User ID
enter User ID into login form
select "Google" for the Login Service
At this point the browser is redirected to Google’s own login page to enter account credentials, and maybe also a 2-factor authentication code. Once the authentication credentials have been entered and verified, Google may then ask for your permission to disclose information to the Annalist application. The information to be disclosed is described; Annalist uses only the email address, which is used in conjucntion with the User ID entered to select a set of user permissions (see "User permissions" section).
If the User ID has already been used by a different user, a message is displayed (@@ message text)
After the first time, use the same details and click "Login". Typically, if this is a personal machine you have used before, the login will complete without any further interaction.
The login sequence associates an authenticated email address with the User ID given, which is used to determine appropriate access permissions (see "User permissions" below).
Once the login is complete, click on "Home" in the menu bar to return to the main Annalist site
Using public computers
If you login from a public computer, remember to log out from your identity provider when you have finished using Annalist and before leaving the computer.
Annalist has been designed to use third party authentication. This avoids having to deal with the tricky technical and operational difficulties of managing password files; leaked password files are a very common form of security failure, so by leaving this to the ID provider professionals, user security should be improved. This also allows users to log in using an existing account rather than having to allocate and remember a new password for Annalist.
Sometimes (for example when Annalist is required to be usable when not connected to the Internet), it may be preferred to use locally managed passwords. Annalist can use the local password management and login features of the Django web application platform on which it is built.
When installing Annalist, an administration account may be created using the
annalist-manager tool. When logged in to Annalist using this account, the Admin link in the footer of most Annalist pages will allow new user accounts to be created via the Django admin interface. More documentation about using this admin interface is in the The Django Admin Site, which is Chapter 6 of The Django Book.
To log in using a Dango account clock on the "Local user credentials"
login link, and enter a Django username and password into the new page that is displayed. Once logged in, return to the Annalist site "Home" page
Annalist keeps a set of user permissions associated with every combination of User ID and authenticated email address.
User permissions may be defined site-wide (i.e. they can apply for all collections across a site), or they may be defined separately for each collection. Thus, different permissions may be granted to different users in different collections. Permission to create new collections must be site-wide.
Within a collection, a user with
ADMIN permissions on that collection can view the user permissions for the collection in the List view
List users. To view the list of user permissions for a collection, browse to that collection which will display some list of records. In the
List view dropdown, select option
List users, and click
View see see user permissions defined for the collection only, or
View all to also list site-wide user permissions.
Special Annalist user identifiers
There are two "special" users that are used to select access permissions applied to users for whom no more specific permissions are available:
annal:User/_unknown_user_perms defines permissions that are applied for any user who is not logged in to Annalist. Typically, this might be used to grant public read-only access to a collection.
annal:User/_default_user_perms defines permissions that are applied for any user who is logged in to Annalist, but for whom no more specifiuc permissions are granted. Permissions thus granted are effectively available to anyone who comes to the web site, but any actions they perform are potentially auditable, being associated with an authenticated (by Google) email address.
Adding user access permissions to a collection
New permissions may be added from the "List user permissions" page (see above) by clicking
User Id field corresponds to the User Id entered in the login page.
URI field (usually a
mailto: URI) corresponds to the authenticated email address provided by the identity service (e.g. by Google). In principle, other forms of URI might be authenticated by an ID service, but these are not currently part of the OpenId Connect protocol used.
Permissions field is a list of tokens (names) corresponding to permissions granted to this user. For the permissions to apply, both the user ID used to log in and the authenticated email address must match the
User Id and
Adding site-wide user access permissions
Site-wide permissions are initially defined using the
annalist-manager command line administration tool. See Installing and setting up Annalist for more information about
annalist-manager, or run the command
Once basic administrative access has been established, additional site-wide permissions can be created by creating or editing user permissions in the
Annalist permission tokens
The standard Annalist permission tokens include:
ADMIN - required to create or view user permissions in a collection. The creator of a collection is automatically granted
ADMIN permissions over that collection, so they can assign permissions in that collection for other users. This permission at site level also allows creation and deletion of collections.
CONFIG - required to change the structure of a collection: to create and/or modify record types, views, lists, etc.
CREATE - required to create new data in a collection.
UPDATE - required to edit data records in a collection.
VIEW - required to view or read data records in a collection.
DELETE - required to remove data records in a collection.
CREATE_COLLECTION - this permission, or
ADMIN, is required at site level to create a new collection.
DELETE_COLLECTION - this permission, or
ADMIN, is required at site level to remove an existing collection.
(Future developments may allow for the introduction of additional tokens on a per-collection basis, but for now these are all of the available permissions.)
Browsing an existing Annalist collection
Creating a new collection
Creating a new collection requires site-level permission
To create a new collection, go to the Annalist site home page and enter a collection id and description for the new collection, and click the
New button. The collection id must consist of letters, digits and underscore ('_') characters only, and be no longer than 32 characters.
In the updated list of collections, click on the link corresponding to the new collection to view its initial content:
Change collection metadata
Modifying collection metadata requires
A collection name, label, description and other metadata may be edited by viewing the site home page, selecting the checkbox by the collection to be edited, then clicking on the "Edit selected" button:
@@TODO: update home page screenshot from demo site when deployed
By default, a collection inherits site-wide type, view and field definitions that are defined by the Annalisty software. It may also inherit definitions from another existing collection on the same site by selecting that collection in the
Parent field. This feature is intended to allow a collection to be based on an existing set of definitions rather than starting from scratch.
Create initial record type and views
It is possible to start creating new data records straight away in a newly created collection, using the in-built default type and views. But for practical use, it is probably better to start by creating a new record type and corresponding views to match the initial data to be collected.
Creating record types and views for a collection requires permission
CONFIG in that collection. The user who creates a collection is automatically granted full permissions for that collection. They may, in turn, create permissions for other users.
Switch to a listing of record types, by selecting
List types from the
List view selector, and then click on the
New button to create a new record type, and enter some details about this record type (e.g. as shown below). To define an initial tailorable view and list descriptions for the new record type, click on the
Define view+list button. The
Default view and
Default list fields are updated accordingly:
There is a possible bug in the software that needs investigating: if an error message is displayed saying the new type already exists, click
In this case, the automatically generated label, "List of Photograph", doesn’t really read smoothly. Details of the generated list and/or view descriptions can be edited by clicking on the nearby button, and making changes as desired. Click
Save when done to return to the type description page.
Save again to save any final changes to the type description and return to the "Type list" display.
Create some initial data records
Switch to a listing of "Photograph" records by selecting
Photographs from the
List view selector, and then click on the
View button; the initial list should be empty:
Click on the
New button to bring uo an initial forkm for enterimng details about a photograph. New record views contain a number of common fields:
Description. Only the
Id field and
Label fields are mandatory; the others are defined because they are commonly useful. The
Id field is used internally to identify the record, and is used in forming a URL that can be used to access the data. The
Label field provides a summary description of the record used in lists and drop-down selectors.
Enter some descriptive data into the fields and click
This process can be repeated for additional photographs.
Add simple fields to a data record
The default view fields presented when creating new records suggest a minimum amount of information to appear in a record. For many practical purposes, additional fields will be required. In the case of a photograph, one might wish to have separate fields to record when and where it was taken. New fields can be added to a view at any time by editing the view description.
There are several ways to edit a view description:
List viewsin the
List viewdropdown, click
View, then select the view to edit from the displayed list and click
Customizeon any list display, select the view to edit from from the column headed
Record views, and click on the
Display an instance of the view to be edited (e.g. a view of one of the Photographs in the list of photographs) by clicking on an
Idlink in the list, then click on the
View descriptionbutton and finally click on the
Editbutton of the pages displayed.
The following screenshots illustrate the last of these approaches.
To add a "Date" field: click
Add field. A new row is added to the list of fields, with unspecified values for
Position/size. Clicking on the
Field id value lists a few options, but none of these suggests a "Date" value. A new type of view field is required here, so click on the button:
This opens a new form to define details of a new field type. Fill in information for
Field value type,
Field render type,
Value mode and
Placeholder as shown. In ths case, the other fields should be left unspecified. (The meanings of all these fields are described in View fields in Annalist.)
When done, click
Save, which returns to the previous view editing form. Now, clicking on the
Field id value includes an option for the new field type just described. Choose this. The
Posityion/size columns can be left blank to use values from the field definiotion, or overriding values for the current view can be specified here. Select an appropriate value (
Repeat the above process, starting with
Add field, to define a new field for the location that a photograph was taken:
Returning to the view edit form, the new location field can be selected and its position/size specified. Next, select the two new fields and click the
Move ⬆ button so that they appear immediately after the
Close to return to the view of a Photograph, which should now look like this:
If the view is now edited, values for the date and location fields can be entered:
These new fields are clearly intended to hold specific types of value (date, location) and the examples suggest particular formats be used for them. But as far as Annalist is concerned, these are just simple text fields, and no attempt is made to check the format of any values entered. This is consistent with the Annalist pholosophy of making it easy to capture whatever data may be available with a minimum of hindrance to the user. The intent is that issues of consistency and data quality may be checked separately according to whatever criteria are deemed appropriate to the task at hand.
Upload images to a collection
A glaring omission from the record of a photograph created thus far is the photograph itself. Annalist supports a notion of "attachments", which are arbitrary files that are stored with an Annalist data record, and are made visible through appropriately defined fields, and which may also be accessed directly by Annalist-mediated URLs. Field definition options allow attachments to be uploaded via the browser from the user’s local file system, or imported from a web site. This example uses file uploads.
The steps for adding an image attachment to a record are:
Define a new field type for the upload imaged file
Add the new field to the Photograph view description
Edit Photograph records and upload images
There are several ways to accomplish these steps (see previous section). The following example goes via the "Customize" page, starting from the "List of photographs" page:
Click on the
Create a new field definition for images
Select "View of Photograph" in the "Record views" column, and click the
Edit button. On the resulting view description page, click
Add field, and then on the
+ button beside the newly added field:
Fill in details for the new field as shown:
The key fields to note here are:
Render field type: the value
Ref image fileindicates the field value is a reference to an image file.
Value mode: the value
File uploadindicates the referenced image will be an uploaded file.
With the field details entered, click 'Save' to return to the view editing form.
Add new image field to view description
Select Field Id
Image for the newly added field, select a value for size/position, click
Save to return to the
Customize page, and
Close to return to the list of photographs:
Upload image to Photograph record
To upload an image, click on the link for a photograph, then click
Edit; the photograph editing form, is displayed, now with an additional
Image field with a
Browse, select an image file to be uploaded, then
Open (or equivalent for the browser being used). On the photo editing page, click
Save. The Photograph record is now displayed with the uploaded image:
Clicking on the displayed image here will show the image alone in a new tab (or possibly a new window, depending on the browser used), occupying the full browser window.
Add repeating fields to a data record
Sometimes, it is desirable to have a field or group of fields in a record that can be repeated an arbitrary number of times. We have already seen this when editing a view description which may contain an arebitrary number of fields. Annalist implements such repeated fields as a special type of field that itself contains references to other fields via a "Field group" description.
Thus, to create a repeating field or group of fields within a view, the following must be defined:
One or more ordinary individual fields that are to be repeated.
A field group that references the field(s) that are to be repeated.
A repeating-value field that references the field group.
Annalist provides a short-cut for creating these various descriptions in the form of a "task button" that appears on the field description editing form.
For our example, we create a field that allows multiple keywords to be associated with a Photograph, starting with a view of a photograph record. Click on
View description, then on the next page displayed click
Add field, and then on the button by the newly added field.
Now fill in details for a single keyword field, as shown. When the details have been entered, click on
Define repeat field.
Now click on
Save, and select
Repeat field 'Keyword' for the new field id.
The repeat field structure just created is perfectly functional, but the automatically generated label field could be improved. Click on the button by the "Repeat field 'Keyword'" id. Change the
Placeholder fields as shown, then click on
On reeturning the the view editing form, noteice that the selection label for the newly added field is changed to "Keywords":
Close to return to the Photograph record view. To add some keywords, click
Add keyword, and fill in key word or phrase text. repeat for as many keywords as desired:
Save to view the resulting record:
Create an additional data type (with view+list)
The examples so far have been based on a single "Photograph" record type. Many interesting data collections consist of multiple cross-referenced record types. For example, we can create "Location notes" records to hold information about where photographs were taken.
Start by creating a new Type, with corresponding View and List definitions; e.g.
Photo_collectionin the top menu bar
List typesfrom the
List viewdrop-down, then click
Newto create a new Type
Enter details as shown
Save, then select the newly created type and click
Edit. (@@This step is a workaround for a bug in the Define view+_list handler, and should not be needed.)
Next, edit the Location notes view to include a map reference field:
List typespage, click on the link
Click on the link
View of Location notes
+button by the newly added field
Fill in details of the new field as shown.
Map referencefor the field id of the newly added field, and a value for Position/size.
Closeto return to thelist of views.
Now we can create an instance of the new type:
Photo_collectionin the top menu bar
List of Location notesfrom the
List viewdrop-down, then click
Newto create a new
A similar process is repeated, but this time also using the
Define repeat field button, to create a repeating field of links to further information about the location:
Now the new fields can be configured in the
A Location notes record can now be created with data for the additional fields:
Create links between records
The preceding section created a new record type for location notes. Here, we edit the Photograph view to allow each photograph to be linked to notes about the location where it was taken. This will be achieved by changing the type of
Location_taken field from a simple text field to a reference to a
To do this, open up the form for editing the view description
Photograph (using any of the navigation paths described previously). Then click on the writing hand button beside thefield id "Location taken":
Edit the "Location taken" field as shown beloiw, noting particularly values entered in these fields:
Field value type - same as the URI given in the
Location_notestype record (currently not used other than for documentary purposes)
Field render type -
Optional entity refpresents a dropdown of entities to which the field may link
Value mode -
Entity referenceindicates this field is a reference to some other Annalist entity in the current collection.
Refer to type -
Location notesindicates the type of entity to which this field may link.
Save the updated field and view descriptions, and redisplay one of the Photograph records: note that the
Location taken value is still displayed, but is rendered in a style used for non-existent entity references. Click on
Edit to edit the record data, and select the vcalue
Sileby Mill from the dropdown (corresponding to the previously created
Location notes record).
Save to return to the Phbotograph view, and note that the
Location taken field now displays as a link to the selected
Location notes record
Display fields from a linked record
Rather than just a link to a related record, it is sometimes useful to display one or more values directly from such a record. For the present example, the photograph "location taken" field is modified to display a link, description and map reference for the location in the photograph view.
This kind of display is created using a
Fields of referenced entity field type. This is a special kind of view field that behaves very differently in edit and view modes: in edit mode, it works just like an
Optional entity ref field, allowing the user to select an instance of some designated type. But in view mode, it displays one or more fields from the referenced entity.
First, navigate to a field description in the
Location_notes view; e.g. from any photograph view, click
View of location notes
Map reference and
An alternative to this slightly long winded navigation path would be to go to the collection front page (click
Photo_collection in the menu bar), select
List fields from the
List view selector, cick
View, click on
Location_mapref. Either way, the resulting page should look something like the last screenshot above.
In the form displayed, click
Define field reference: this will create a new field and field group
Location_mapref_ref referencing this field, and display an editing form for the new field definition.
Before making any changes to the field itself, click on the button by the
Field group field:
This will display a new form for editing details of the new field group. In this form:
Add additional fields
Labelto be displayed, using the
Add fieldbutton and the new field id selectors dislayed.
Move the two new fields in front of the map reference field by selecting their checkboxes and clicking
Make changes as desired to the field label and description (but leave other fielkds as they are).
Saveto save the changes and return to the new field definition that references this group.
Back in the field editing form, change the Id, label and description and property URI of the new field to better reflect its actual usage. Then click
At this point, navigate to the view description for Photograph (e.g. by displaying a Photograph record and clicking on
View description, or selecting and displaying
List views from the collection home page and then clicking on
Photograph). Then click on the
Edit button to display the view editing form. On this form, clicik
Add field, select the newly created
Location notes field type, and select
0/12 for the position/size value:
Now navigate to a view of a photograph record, click
Edit and inthe displayed form select a value for the new field
Location notes from the dropdown displayed.
Save to view the photoigraph records, and observe that the
Location notes field now displays three values from the selected record: