Configuring CollectionSpace

CollectionSpace allows you – and your consultants or integrators – to adapt the system for the specific needs of your museum (or collection or heritage institution). This overview describes high-level concepts related to configuring Collectionspace.

Contents

Understanding tenancy

To configure CollectionSpace, you'll first create a tenant. You can think of a tenant as a space or partition on a CollectionSpace system for your museum or collection, within which you'll be making most of your configuration changes.

CollectionSpace has built-in multi-tenant hosting capabilities, making it possible for you or a hosting provider to use a single server to support multiple museums. Each museum's configuration and data is contained within its own tenancy. A museum's CollectionSpace users will log into a tenant-specific URL on the server to work with that museum's own records. Even if your CollectionSpace system will be used only for one museum – your own – you will create a new tenant, and then make your configuration changes within that tenant.

Types of configuration

CollectionSpace is made up of two applications: a front-end (user interface, or UI) running in a web browser, and a back-end (services layer) running on the server. Each of these applications is configured separately for your tenant.

Front-end (UI) configuration

Front-end configuration allows you to change the way CollectionSpace looks to users in their web browsers. Many common customizations to CollectionSpace can be achieved with only front-end configuration, including:

• Changing the logo displayed in the login page and header
• Changing login screen text, field labels, and other text
• Removing and reordering fields
• Adding, removing, and relabeling options in controlled lists
• Changing how a field is displayed in the UI for editing, for example: from single line free-text to multi-line free-text; from free-text to option list dropdown; from multi-valued (repeating) entry to single-value
• Adding, removing, and relabeling form templates
• Removing and renaming record types
• Removing, reordering, and resizing columns in search results and sidebar listings
• Adding, removing, and reordering fields in advanced search forms

Configuring the front-end requires basic understanding of HTML, CSS, JSON, and JavaScript.

Some front-end configuration changes should be done in tandem with back-end configuration changes to make them fully functional. For example:

• Adding a new field. The front-end may be configured to show a new field on a record, but that field must also be added to the back-end configuration so that the server will know how to save the field.
• Adding a new record type. The front-end may be configured to display a new record type, but back-end configuration is required to make loading, saving, and searching records of the type functional on the server.
• Changing a field to be edited with an authority-controlled autocomplete input, or a term list-controlled dropdown input. These types of inputs allow users to set the value of the field to a reference to another record (an authority item, or an item in a term list, which is itself a record). Back-end configuration is required so that the server will know to treat these values as references to records instead of plain strings.

Back-end (services) configuration

Back-end configuration allows you to change the way the CollectionSpace server stores and retrieves data. This includes:

• Adding new fields
• Adding new record types
• Changing the fields returned in search results
• Changing a field to contain a reference to a record

Configuring the back-end requires familiarity with XML.

Often, making a back-end configuration change implies that a corresponding front-end change should be made as well. For example:

• When a new field is added in the back-end, it’s likely that it should also be added to a form template in the front-end, so that users may view and edit the value of the field in the UI.
• When a new record type is added to the back-end, it should usually be configured into the front-end as well, so that users can use the UI to search, view, edit, and relate records of the type.
• When a field is added to search results returned by the back-end, the front-end would need to have a column added to its search results configuration in order for the field to be displayed to users of the UI.
• When a field is indicated to contain a reference to a record in the back-end, the front-end should be configured to display the field as an authority-controlled autocomplete input, or a term list-controlled dropdown input, so that users can easily select a record.

There are exceptions to the rule; for example, a field or record type might be added with the intent to be used only by other, specialized CollectionSpace clients, not by the standard UI. In that case, it would only be necessary to configure the back-end. Consider how your back-end configuration change will be used to determine if a front-end change is needed to support the desired use.

Understanding schemas and extensions

In CollectionSpace, a schema defines a set of fields that are included in a record. For each field, this includes information like the name of the field, its data type (string, date, float, or integer), and whether the field holds a single value, or is multi-valued (repeating). Complex types – fields that contain other fields – are also supported. A record type may include multiple schemas. Each record type that is defined in CollectionSpace will have a common schema, containing fields that are commonly used by most collecting institutions.

Additional schemas may be added to record types on a per-tenant basis. These additional schemas are called extension schemas. An extension schema may contain fields that are useful for many collecting institutions within a domain or community of practice (a domain extension), or it may contain fields that are specific to one museum or collection (a local extension). CollectionSpace profiles come pre-configured with domain extensions for various record types, adding fields that are useful to the type of collection represented by the profile.

When you configure the back-end of CollectionSpace, most of what you're doing is creating local extension schemas, defining the fields in those local extensions, and adding those local extensions to record types in your tenant. You might also add one or more domain extensions to various record types.

It is important to note that the common schemas and domain extensions that come with CollectionSpace may not be changed. These schemas are "owned" by the community; having shared schemas allows reports, import/export tools, and external programs that use CollectionSpace data to be shared as well. When a change to a field in a common or domain schema is desired – for example, changing the data type from an integer to a string, making the field multi-valued, or adding a child field to a complex field – this can effectively be accomplished by defining a new field in a local schema extension, and replacing the common field with the new local field in the font-end. Similarly, fields may not be removed from common or domain schemas, but they can be removed from the front-end configuration, so that users won't be able to see or edit the field in the UI.

More documentation on configuring CollectionSpace

The following documents provide in-depth instructions for configuring CollectionSpace:

• Creating your new tenant

Getting help

For help with configuring CollectionSpace, you're encouraged to freely ask questions on the project's /wiki/spaces/collectionspace/pages/666276158. Many of CollectionSpace's other implementers and project team members actively participate in discussions on that list.