Configuring CollectionSpace

Contents

Configuration and customization

CollectionSpace allows you - and your consultants or integrators - to adapt the system for the specific needs of your museum (or collection or heritage institution) through:

• Configuration, changing the behavior and the look and feel of the system by:
  
  
  • Editing values directly on web-based Administration pages, wherever such pages are available.
    
    Currently, there are Administration pages through which you can edit user accounts, roles and permissions, and lists of controlled terms. More Administration pages may be coming in the future; there are also alternate ways provided to perform similar administrative tasks.
    
    
  • Editing text files that control its behavior and appearance, such as various XML- and JSON-based configuration files, HTML template files, CSS stylesheet files, and 'bundle' files containing text fragments that are displayed on various CollectionSpace pages.
    
    You'll generally adapt CollectionSpace for your museum by editing text files in just a couple of folders, within the source code trees for CollectionSpace's three layers: the Services layer, the Application layer, and the User Interface (UI) layer. And nearly all of this work involves either or both of:
    
    
    • Modifying relatively straightforward XML-based configuration files in the Application layer
    • Editing HTML templates and "message bundle" files (that define text labels) in the UI layer.
      
      
• Customization, extending the system's functionality by adding or editing Java and JavaScript source code.

This document, together with its related documents, describes how to configure CollectionSpace.

If you or your consultants or integrators are interested in customizing CollectionSpace, which requires Java and/or JavaScript programming skills:

• Check out the CollectionSpace source code
• Find the appropriate developer-oriented documentation that addresses your customization needs:
  • In the Developing for CollectionSpace section of this documentation wiki
  • On the /wiki/spaces/collectionspace/overview.
• Freely ask questions on the project's /wiki/spaces/collectionspace/pages/666276158

Screencasts showing configuration

In addition to the instructions below, we've been planning to create a set of Screencasts that walk you through various configuration steps. Watch this space for future additions here!

Creating a configuration space ("tenant") for your museum or collection

To configure CollectionSpace, it's important to understand the concept of tenancy. You can think of a tenant as simply the concept of a space or partition on a CollectionSpace system for your museum or collection, within which you'll be making most or all of your configuration changes.

CollectionSpace has built-in multi-tenant hosting capabilities, making it possible for you or a hosting provider to use just 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 their 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. Your museum's own tenant will reside alongside the several sample tenants that come with every "out of the box" CollectionSpace system. (In a future version of CollectionSpace, you will be able to easily activate or deactivate tenants, including the sample tenants.)

In the current version, there are three sample tenants. One of these is generic, and two others, based on that generic tenant, demonstrate how CollectionSpace can be configured to meet the needs of a museum or other collections-holding institution in a specific community of practice or domain.  These sample tenants can often be valuable references, while you are configuring your own museum's tenant.

Creating your tenant

The following is an overview of the one-time set of steps required to create own new tenant, the space or partition within which you will configure CollectionSpace for your museum.

• Using git client software or otherwise as described, check out the source code for all three of CollectionSpace's layers into folders on your own system. You'll generally check out source code releases that have been marked, or "tagged," with the version of CollectionSpace that your museum is currently using.
• Within each layer's source code tree, "clone" (copy) the folders or sets of files pertaining to the sample core tenant, to create a new folder or set of files for your own museum.
• Edit those files as needed. The editing required is fairly minimal, mostly just editing filenames and file contents to replace the name of the core tenant with the short name of your museum.
• Copy ("deploy" or "push") copies of the files you've changed in the source code tree, to the appropriate places within the CollectionSpace server folder. This typically means that, from within each relevant layer's source code tree, you'll run a build command at your operating system's command line, such as mvn install or ant deploy, that will copy these files to the right places in the server folder.
• Within CollectionSpace's Services layer source code tree, run one or more build commands that set up default user accounts for your new tenancy, including an admin user that has the rights to create additional users and a reader account with read-only access.

Configuring your tenant

After you create your new tenant - a one-time task - you'll then make configuration changes in this way:

• In each layer's source code tree, within the folder location(s) relevant to your tenant, edit XML- and/or JSON-based configuration files, HTML template files, and CSS stylesheet files, as needed. (See the individual documents linked under Configuring CollectionSpace, in the sidebar at left, or as Child Pages below, for specifics about which configuration files you'll need to modify in order to make the changes to behavior and appearance that you desire.)
• Copy ("deploy" or "push") copies of the files you've changed to the appropriate places within the CollectionSpace server folder. This typically means that, from within each relevant layer's source code tree, you'll run a 'build' command at your operating system's command line, such as mvn install or ant deploy, that will copy these files to the right places in the server folder.
• Clear your browser's caches and login to your CollectionSpace system once again to see the effects of your changes. (In a few cases, you may also need to stop and restart your system to make certain changes take effect.)

More documentation on configuring CollectionSpace

The following documents provide somewhat more in-depth overviews of how to configure CollectionSpace:

Configuring the Amazon S3 plugin

Configuring CollectionSpace's Application Layer - An Overview

Configuring CollectionSpace's User Interface (UI) Layer - An Overview

For details of how to make very specific configuration changes, please see the relevant individual documents linked under Configuring CollectionSpace, in the sidebar at left, or as Child Pages below.

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.