Needed Documentation

Owned by Aron Roberts (Unlicensed)
Jul 12, 2017
6 min read

This page provides an informal place to identify documentation that's "missing": documents that are needed, but aren't yet present on the CollectionSpace Documentation Wiki.

Please always edit the latest copy of this page, on the UNRELEASED wiki; that way, changes you make here will be carried forward to future versions of the CollectionSpace documentation wiki. Please feel free to edit this page to add, annotate, or delete items here as you see fit!

The listings below are organized under each major section on the wiki:

Installing CollectionSpace

The following documents would be useful additions to the installation documentation. (Some of these might also be referenced from, or even moved to, the Hosting CollectionSpace section.)

  • Configuring the port number on which CollectionSpace listens for connections.
  • Tuning PostgreSQL for faster listing / browsing / searching (as a deeper dive than the succinct/rote 'tuning' section in the current PostgreSQL installation doc) (see this November 2015 Talk list discussion thread)
  • Not a document, but a clarification improvement to one or more existing pages, per an implementer comment: "take from all my experiences that future adopters will need to dig VERY hard to find a copy of Ubuntu Server 14.04 otherwise, as per my experience, frustration will follow. I suggest that docs highlight the necessity of true 14.04 and don't just mention it."
  • The example VM image ("box") mentioned in instructions in Using VirtualBox and Vagrant to Host CollectionSpace needs to be changed from Fedora 18 to a more recent/relevant Linux release, such as Ubuntu 14.04.

Configuring CollectionSpace

The following documents would be useful additions to the configuration documentation. Given the large number of documents here, these are further categorized by area of functionality.)

Tenants

Authority Terms

  • Creating a new authority
  • Creating a new vocabulary within an authority
  • Attaching a new vocabulary to a field
  • Associating authorities and their vocabularies with an autocomplete field
  • Adding a new vocabulary to an existing authority

  • Editing the values that appear in the disambiguation pop-up dialog (visible when hovering over terms in an autocomplete field's dropdown menus)

Vocabulary Terms

  • Creating the initial set of terms for a dynamic vocabulary
  • Assigning a dynamic vocabulary to a field

Procedures

  • Hiding a procedure
  • Renaming a procedure
  • Adding a new procedure (the existing documentation for doing this is too far out of date to be of much use)

Record Editing and Viewing

This covers all record-scale functionality except schemas and layout (see that category below).

  • Excluding fields from being copied during Create new from existing
  • Changing the summary fields displayed in large text above a record

  • Specifying required fields (may be a special case of data validation?)

    • Notes: In the Services layer, via ValidatorHandler classes. In the UI layer, via configuration and selectors; e.g. as discussed in a comment on CSPACE-6461.
  • Setting the default value for a field (drop-down list).
  • Setting the default value for a field (text field).
  • Validating data in real time (e.g. during data entry, or after a user clicks or tabs out of a field). Examples: ensuring that a field contains a (non-blank or non-whitespace) value, or that a field contains a value matching a pattern.
  • Sorting media snapshots in the right sidebar (e.g. sorted by the values of field(s) in related media records).
  • Enabling record versioning (along with a discussion of the implications of doing so).
  • Adding Google Analytics code or similar visitor tracking code.
    • Notes: add it in the UI layer to the footer template, html/components/footer.html
  • Automatically populating a field with a computed value from one or more other fields (on the same record)
  • Automatically populating a field with a computed value from one or more other fields (from a different type of record or records)
  • Adding or changing columns in the right sidebar (e.g. in Terms Used, Used By, Cataloging, Procedures)
  • Adding or changing the label text in column headers in the right sidebar
  • Changing the order of sections in the right sidebar
  • Changing the number of records shown by default, in lists in the right sidebar (see this November 2015 Talk list discussion thread)
  • Changing the display order of the secondary tabs (see this July 2017 Talk list discussion thread)
  • Adding or changing columns in secondary tabs

Record Schemas and Layout

  • Changing a field's data type (see CSPACE-6736)
    • Note: there are a number of plausible permutations from 'old data type' to 'new data type,' and some of these changes may involve a different set of steps than others.
  • Changing the display size of a text field
  • Changing the tab order of fields
  • Adding a group of fields
  • Adding a repeatable group of fields
  • Adding a list of repeatable groups of fields (a repeatable group of fields that can itself be repeated, as a group)
  • Adding a new field to an existing group of fields
  • Adding a new field to an existing group of repeatable fields
  • Adding a new field to an existing list of groups of repeatable fields
  • Removing or adding a data template for a record (which appears on the Create New page, and provides a different editing view for a record) (see this November 2015 Talk list discussion thread)
  • Removing an entire record type (see this November 2015 Talk list discussion thread)

Search and List

  • Changing which fields appear in search and list results (for one example, see UCJEPS-106).
  • Adding columns to search and list results
  • Changing the headers for columns in search and list results
  • Changing the number of records shown by default in search and list results (see this November 2015 Talk list discussion thread)
  • Enabling accent-insensitive full text search
  • Adding or removing a field from an Advanced Search page (see this November 2015 Talk list discussion thread)
  • Changing the behavior of the default (quick) search option
  • Make current location searchable; see
    Error rendering macro 'jira' : Unable to locate Jira server for this macro. It may be due to Application Link configuration.

Reporting

Note: when updating Reporting-related documentation, please also check the UCB-developed Managing iReport for possible material. (For instance, the "IREPORT ONGOING MAINTENANCE" section offers a detailed checklist on updating and deploying reports, which is well-tested.)

Bulk Operations

 

(As well, the descriptions of the various configuration options in unified collectionspace config badly need updating.)

Maintaining CollectionSpace

The following documents would be useful additions to the maintenance documentation.

  • Daily Monitoring and Other Periodic Review (this document is present on the wiki but is partly a stub).

  • Automated, remote monitoring of a CollectionSpace system to detect problems and outages

As well, there are administrative tasks that may need to be performed using the Services REST API or SQL commands. It's not clearly evident which of the current sections these fall into, but for now, these are being gathered here:

Upgrading CollectionSpace

The following documents would be useful additions to the upgrading documentation.

  • Upgrade instructions from v4.2 to v4.3. These are very much needed.
  • Upgrade instructions to v4.4 (after that release comes out).

Migrating to CollectionSpace

The following documents would be useful additions to the migration documentation.

  • Importing records that are related to one another

  • Importing vocabulary terms

  • Importing authorities and authority terms

  • Importing media records and "binary blobs" (media files)

See also Maintaining CollectionSpace, above, for needed documentation around some administrative tasks that might be particularly useful during the migration process.

Developing for CollectionSpace

The following documents would be useful additions to the developers' documentation.

  • Extending CollectionSpace via extension points, in its Services layer:
    Extending CollectionSpace via extension points, in its UI layer

    • Batch jobs
    • Event listeners / handlers
    • Validation handlers
    • Custom SQL scripts
      • Note that Nuxeo now offers "startup hooks" for running SQL scripts during startup, supplementing (and perhaps even supplanting) the mechanism for running such scripts offered within CSpace's Services layer.
    • Post-init handlers (which run during the server startup sequence)

  • Viewing UI->App layer payloads: where to set a breakpointViewing App->Services layer payloads - where to enable logging to view these

  • Changing what's logged in the Services layer

  • Changing what's logged in the Application layer

  • Demonstrating how to change log levels, configuration in Services layer, so as to log full payloads sent between App and Services layers

  • Troubleshooting issues in the UI layer using a browser-based debugger

See also

More documentation suggestions can be found near the end of /wiki/spaces/collectionspace/pages/666274105