Needed Documentation

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

Troubleshooting "Error - Invalid email/password combination" error messages with a newly-created tenant (see this November 2016 Talk list discussion thread)

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)
- BAMPFA-43
- BAMPFA-246
  (A representative example, demonstrating how to provide additional disambiguation values for Person authority terms. Relevant changes in GitHub, nearly all pertinent to this issue but including a couple of other mods to these two files: Demands.js and core-messages.properties-overlay)

Vocabulary Terms

Creating the initial set of terms for a dynamic vocabulary
Assigning a dynamic vocabulary to a field
- See CSPACE-6821 (for both this and the previous item)

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).
- Notes: see BAMPFA-23.
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
- Notes: see BAMPFA-199.
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.)

Writing SQL queries of CollectionSpace's databases to create reports (CSPACE-6879). (And see also this June 2016 Talk list discussion thread.)
- Note that in a future release of CollectionSpace, a prospective Jasper Reports CMIS connector could simplify the task of writing queries for reporting, and make these queries more independent of underlying database structure. Here's a flavor of CMIS's SQL-like query language.
Writing reports that can elegantly handle instances where no data is returned. (For a useful technique here, see Lam Voong's comment on CSPACE-6948.)
Writing reports that return dynamic and static media (see this August 2016 and September 2016 Talk list discussion thread, which also encompasses CollectionSpace's data model).
Understanding CollectionSpace's data model (see this August 2016 and September 2016 Talk list discussion thread, which also encompasses reports that include media).

Bulk Operations

Deleting all records of a particular record type (via SQL) (see this June 2016 Talk list discussion thread)
Clearing out / deleting an entire database (when doing evaluation, or working with tests of data imports, for example). (See this May 2016 Talk list discussion.)

(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:

Deleting all records of a particular record type (via SQL) (see this June 2016 Talk list discussion thread)

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
- Notes: see Thursday Developer Meeting notes - ADR#ADR-DebuggingintheUIlayer
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

CollectionSpace 5.0 Documentation