This is documentation for the CCMS (Collaborative Collections Management System).

1. Reference

1.1. Commands

1.1.1. alter project

Change the definition of a project

alter project project_name
    action

where action is one of:

    alter property property_name set value
    alter property property_name add subvalue
    alter property property_name drop { subvalue | all }
Description

The alter project command changes the definition of a project.

The alter property clause changes a property in the project’s metadata. The set action is used for single-value properties, while add and drop are for composite properties.

Parameters

project_name

The name of the project.

property_name

The name of the property in the project metadata.

value

The value of a single-value property.

subvalue

A subvalue in a composite property.
Properties
Property Type Value

title

single-value

text

action

single-value

action name (acquire, retire, digitize, move, other)

mou_link

single-value

text

funds

composite

fund name

origins

composite

location name (clockss, lehigh, nyu)

destinations

composite

location name

tracks

composite

track name (offsite, reserve, stacks)
Examples

Set the title of project myproj to My Project:

alter project myproj alter property title set 'My Project';

Add a fund palci_cultural to the project:

alter project myproj alter property funds add palci_cultural;

1.1.2. archive project

Archive a project

archive project project_name
Description

The archive project command marks a project as no longer active.

Parameters

project_name

The name of the project.
Examples

Archive a project myproj:

archive project myproj;

1.1.3. create filter

Define a new filter

create filter filter_name
    where search_condition
Description

The create filter command defines criteria for selecting objects. These criteria can then be used for querying sets via the filter() operator.

Parameters
where

The where clause specifies a search condition in the form of a Boolean expression. Only objects that satisfy this condition will be selected.

See also Reference > Queries.

Examples

To filter on records where decision = true:

create filter decided where decision = true;

select * from p.s where filter(decided);

1.1.4. create fund

Define a new fund

create fund fund_name
Description

The create fund command creates a new fund.

Parameters

fund_name

The name of the new fund.
Examples

Create a new fund cultural_lit:

create fund cultural_lit;

1.1.5. create project

Define a new project

create project project_name
Description

The create project command creates a new project.

Parameters

project_name

The name of the new project.
Examples

Create a new project myproj:

create project myproj;

1.1.6. create set

Define a new set

create set set_name
Description

The create set command creates a new, empty set.

Parameters

set_name

The name of the new set, prefixed with the project name and a dot (.). For example, a set s in project p would be written as p.s.
Examples

Create a set myset in project test:

create set test.myset;

1.1.7. create user

Define a new database user

create user user_name with option 'value' [, ... ]
Description

create user defines a new database user.

Parameters

user_name

The name of the new user.

with ( option 'value' [, …​ ] )

Configuration options for the new user.
Options

encrypted password

Sets the cryptographic hash of the user’s password.
Examples

Create a user anna:

create user anna with encrypted password 'GSDDdftAsLcbPQXynZYBnM4ZT8wPMmdY9Ws3SZWVs2I';

1.1.8. delete

Remove objects from membership in a set

delete from set_name
    [ where condition ]
Description

The delete command removes selected objects from membership in a set.

Parameters
from

The from clause specifies the set.

where

The where clause specifies a search condition in the form of a Boolean expression. Only objects that satisfy this condition will be deleted.

See also Reference > Queries.

Examples

To remove items in stock from the set test.myset:

delete from test.myset where availability = 'In stock';

To remove all items from the set test.myset:

delete from test.myset;

1.1.9. drop set

Remove a set

drop set set_name
Description

The drop set command removes a set from the system.

Parameters

set_name

The name of the set.
Examples

Remove a set test.myset:

drop set test.myset;

1.1.10. insert

Insert objects into a set

insert into target_set_name
    select *
           from source_set_name
           [ where search_condition ]
           [ limit count ]
Description

The insert command selects objects from a source set according to specified criteria, and inserts the selected objects into a target set.

Parameters
into

The into clause specifies the target set.

from

The from clause specifies the source set.

where

The where clause specifies a search condition in the form of a Boolean expression. Only objects that satisfy this condition will be selected.

See also Reference > Queries.

limit

The limit clause specifies a maximum number of objects that will be returned.

Examples

To select items in stock from the object set and insert them into a set test.myset:

insert into test.myset select * from test.object where availability = 'In stock';

1.1.11. select

Retrieve data

select { * | count(*) }
    from set_name
    [ where search_condition ]
    [ order by attribute [ asc | desc ] ]
    [ limit count ]
    [ offset start ]

select version()
Description

The select command retrieves data, typically a list of objects from a set according to specified criteria.

The CCMS server returns to the client no more than 10000 records per select command. If a result set is larger than this, the server returns an error. It is a good idea to use a limit clause if the query may return a large result set.
Parameters

The first argument specifies * meaning all available attributes or count(*) meaning a count of the number of rows returned.

from

The from clause specifies the desired set that will be the source of data.

where

The where clause specifies a search condition in the form of a Boolean expression. Only objects that satisfy this condition will be retrieved.

See also Reference > Queries.

order by

The order by clause specifies a sort order for objects to be returned. The objects are sorted by the specified attribute, with asc for ascending order (the default) or desc for descending order.

limit

The limit clause specifies the maximum number of objects that will be returned.

offset

The offset clause specifies a number of objects that will be skipped and not returned as part of the result. This can be useful for retrieving objects one page of data at a time. Note that the order by clause is required when offset is used.

Examples

To retrieve items in stock from the set test.myset:

select * from test.myset where availability = 'In stock' order by title;

1.1.12. show

List the values of a system variable

show filters

show funds

show projects [ archived ]

show project project_name

show sets [ in project project_name ]

show users
Description

show lists the current values of system configurations or other variables.

Examples
show sets;

1.1.13. update

Update object attributes

update project_name.object
    set attribute = { value | null }
    where id = object_id
Description

The update command changes the value of the specified attribute for an object having a specified ID.

Parameters

The first argument specifies the object set to be updated.

set

The set clause specifies the attribute to set and its new value.

where

The where clause specifies the object ID.

Examples

To set the fund in an object having ID = 12:

update myproj.object set fund = cultural where id = 12;

1.2. Queries

1.2.1. Value expressions

The where clause in a query is followed by a search condition. This condition is a Boolean expression consisting of operators and operands.

1.2.1.1. Operators

The supported operators, in order of precedence, are:

Operator Associativity Description

filter()

filtering operator

= <> < > <= >= like ilike

comparison operators

not

right

logical negation

and

left

logical conjunction

or

left

logical disjunction

Parentheses may be used to override these precedence rules.

1.2.1.2. Operands

Supported operand types are:

Operand type Example Description

name

author

attribute name

string literal

'Thomas à Kempis'

string constant

number

33

numeric constant
1.2.1.3. Attributes

Supported attributes are divided into two groups. The first group are provided by CCMS or the original data source and cannot be modified:

Attribute Type Description

id

bigint

CCMS identifier

author

text

100 $a

title

text

245 $a and 245 $b

full_vendor_name

text

999 13 $a

availability

text

999 13 $z

The second group are shared within a project and may be modified using the update command:

Attribute Type Description

decision

boolean

true if the decision to take the project action has been made

fund

fund name

selected from the project property funds

1.3. Lexical structure

1.3.1. Constants

String constants are enclosed in single quotes, for example, 'It is a beautiful day'.

A single quote within a string constant is written as two single quotes, for example, 'It''s a beautiful day'.

2. Server administration

2.1. System requirements

2.1.1. Hardware requirements

This section will contain system hardware requirements.

2.1.2. Software requirements

  • Operating system: Linux

  • Database system: PostgreSQL 19 or later

  • To build from source:

2.2. Building the software

It is suggested that a ccms user be created and the server run by that user, for example, in /home/ccms.

To build CCMS, first set the GOPATH environment variable to specify a path that can serve as the build workspace for Go, e.g.:

export GOPATH=$HOME/go

Then to build the server:

./build

The build script creates a bin/ subdirectory and builds the ccd server and ccc client executables there:

./bin/ccd help

./bin/ccc help

In general running ccd takes the form:

ccd <command> <arguments>

Some typical commands are:

  • init initializes a new CCMS instance

  • start starts the server

  • stop shuts down the server

  • version prints the CCMS version

For more infomation about a specific command:

ccd help <command>

2.3. Server configuration

The ccd server makes use of local storage in a data directory which is created using ccd with the init command. In this example we will create the data directory as data/:

ccd init -D data

This will also create a file ccd.conf in the data directory with the following structure:

[db.main]
host = host name of the PostgreSQL server
port = port number of the PostgreSQL server
user = database user that is the owner of the database
password = password of user
dbname = database name
sslmode = should be set to "require" or stronger option

This file should be edited to add database connection parameters, for example:

[db.main]
host = ccms.indexdata.com
port = 5432
user = ccms
password = w6bqYkFWm4rpGR5mCtFw
dbname = ccms
sslmode = require

The ccd server will assume that the user and database defined here already exist; so they should be created before continuing. The user should be the owner of the database.

2.4. Upgrading from a previous version

Upgrading from a previous version of CCMS is not currently supported.

2.5. Running the server

To start the server:

nohup ccd start -D data -l ccd.log &

To stop the server:

ccd stop -D data

The server can be set up to run with systemd via a file such as /etc/systemd/system/ccms.service, for example:

[Unit]
Description=CCMS
After=network.target remote-fs.target

[Service]
Type=simple
User=ccms
ExecStart=/bin/bash -ce "exec /home/ccms/bin/ccd start -D /home/ccms/data -l /home/ccms/ccd.log"
Restart=on-abort

[Install]
WantedBy=multi-user.target

Then:

systemctl enable ccms

systemctl start ccms