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

1. User guide

1.1. Getting started

CCMS can be accessed in two ways: programmatically via a service API, or by using the ccc client. This section will introduce CCMS commands using the ccc client. A ccc session looks something like:

$ ccc
=> show sets
allobjects
myset
reserve
=> retrieve id from myset
053e4063-d70c-4a41-a968-e6900e6b47d5
ac256496-111a-4e13-9d3b-a55ac3d0f676

1.2. Retrieving objects

We can view objects in the "reserve" which is a predefined set that contains all available objects.

=> retrieve id from reserve limit 5
c644d186-399b-4f80-b92b-c6c38d69db07
ac256496-111a-4e13-9d3b-a55ac3d0f676
f43bfb56-fd34-4fd3-b944-dca46e22751f
053e4063-d70c-4a41-a968-e6900e6b47d5
dd7de2bf-b5e1-452a-97f6-bafa586e67c5

To look at a specific object in detail:

=> retrieve all from reserve where id = "053e4063-d70c-4a41-a968-e6900e6b47d5"

We can create a new set called "myset" and begin adding objects of interest to it:

=> create set myset
=> insert into myset from reserve where id = "053e4063-d70c-4a41-a968-e6900e6b47d5"
insert 1
=> insert into myset from reserve where id = "ac256496-111a-4e13-9d3b-a55ac3d0f676"
insert 1

To list the objects in myset:

=> retrieve id from myset
053e4063-d70c-4a41-a968-e6900e6b47d5
ac256496-111a-4e13-9d3b-a55ac3d0f676

We can create a set that contains all available objects, with the idea of subsequently removing unneeded objects. This may take a minute to run due to the large number of objects:

=> create set allobjects
=> insert into allobjects from reserve
insert 42698273
=> retrieve id from allobjects limit 5
c644d186-399b-4f80-b92b-c6c38d69db07
ac256496-111a-4e13-9d3b-a55ac3d0f676
f43bfb56-fd34-4fd3-b944-dca46e22751f
053e4063-d70c-4a41-a968-e6900e6b47d5
dd7de2bf-b5e1-452a-97f6-bafa586e67c5

To list all sets:

=> show sets
allobjects
myset
reserve

2. Reference

2.1. Concepts

CCMS provides a model to support user interface concepts:

User interface CCMS types CCMS commands Description

Object

object

 


An object is a bibliographic record.






List


set, list


create set
delete
insert
retrieve
show sets


A set is an unordered collection of objects.  A list is an ordered
collection of objects.  Sets are the primary data structure in
CCMS; however, query commands such as retrieve or
show sets return a list.






Profile


filter


define filter
show filters


A filter defines rules for selecting objects from sets.






Marker


tag


define tag
add tag
remove tag
show tags


A tag is a label that can be assigned to selected objects in sets.









Filters are applied using the filter keyword, e.g.:








define filter f where date >= "01-01-2025"

create set s

insert into s from reserve filter f








Tags use the tag keyword:








define tag t

add tag t on s where date >= "02-01-2025" and date < "03-01-2025"

retrieve isbn from s tag t








Multiple tags can be listed, separated by commas:








retrieve isbn from s tag t, u, not v, w










2.2. Protocol




Non-query commands such as create set return a diagnostic status:








{
  "command": "create set myset"
}










{
  "status": "create set"
}








The status may be an error:








{
  "status": "error",
  "message": "myset already exists"
}








Query commands such as retrieve also return tabular data sets, e.g.:








{
  "command": "retrieve id from myset"
}










{
  "status": "retrieve",
  "fields": [
    {
      "name": "id"
    }
  ],
  "data": [
    [
      "053e4063-d70c-4a41-a968-e6900e6b47d5"
    ],
    [
      "ac256496-111a-4e13-9d3b-a55ac3d0f676"
    ]
  ]
}










2.3. Commands




2.3.1. add tag




Add a tag to objects in a set








add tag tag_name
    on set_name
    [ where condition ]
    [ filter filter_name ]






Description




The add tag command adds a tag to objects in a set according to
specified criteria.  If no criteria are given, the tag is applied to
all objects in the set.




Parameters




The first argument specifies the name of the tag to add.




on




The on clause specifies the desired set to operate on.




where




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




filter




The filter clause applies a specified filter to the objects that
will be tagged.




Examples




To add a tag t to objects in a set s selected by a filter f:








add tag t on s filter f










2.3.2. 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.







Examples




Create a set s:








create set s










2.3.3. define filter




Define a filter








define filter new_filter_name
    [ where condition ]
    [ template existing_filter_name ]






Description




The define filter command defines criteria for selecting objects
from sets.




Parameters




The first argument specifies the name of the new filter.




where




The where clause specifies a condition in the form of a Boolean
expression.  Only objects that satisfy this condition will pass
through the filter.




template




The template clause specifies an existing filter.  The new filter
will duplicate the existing filter.




Examples




To define a filter f and apply it to a set s:








define filter f where date >= "01-01-2025"

retrieve all from s filter f










2.3.4. define tag




Define a tag








define tag tag_name






Description




The define tag command defines a new tag.




Parameters











tag_name


The name of the new tag.







Examples




Define a tag t:








define tag t










2.3.5. delete




Delete objects from a set








delete from set_name
    [ where condition ]
    [ filter filter_name ]
    [ tag [not] tag_name [, ...] ]






Description




The delete command deletes objects from a set according to specified
criteria.  If no criteria are given, all objects in the set are
deleted.




Parameters




The first argument specifies the name of the set.




where




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




filter




The filter clause applies a specified filter to the objects
selected.  Objects that pass through the filter will be deleted.




tag




The tag clause selects objects having the specified tags.  Those
objects will be deleted.




Examples




To delete a specific object:








delete from s where id = "053e4063-d70c-4a41-a968-e6900e6b47d5"










2.3.6. help




Show supported commands








help






Description




The help command shows a list of supported commands.




Examples






help










2.3.7. insert




Insert objects into a set








insert into target_set_name
    from source_set_name
    [ where condition ]
    [ filter filter_name ]
    [ tag [not] tag_name [, ...] ]






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 condition in the form of a Boolean
expression.  Only objects that satisfy this condition will be
selected.




filter




The filter clause applies a specified filter to the objects
selected.




tag




The tag clause selects objects having the specified tags.




Examples




To select an object by id from a set s and insert it into a set
t:








insert into t from s where id = "053e4063-d70c-4a41-a968-e6900e6b47d5"










2.3.8. remove tag




Remove a tag from objects in a set








remove tag tag_name
    on set_name
    [ where condition ]
    [ filter filter_name ]






Description




The remove tag command removes a tag from objects in a set according
to specified criteria.  If no criteria are given, the tag is removed
from all objects in the set.




Parameters




The first argument specifies the name of the tag to remove.




on




The on clause specifies the desired set to operate on.




where




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




filter




The filter clause applies a specified filter to the objects that
will be untagged.




Examples




To remove a tag t from a specific object in a set s:








remove tag t on s where id = "053e4063-d70c-4a41-a968-e6900e6b47d5"










2.3.9. retrieve




Retrieve objects from a set








retrieve { all | attribute [, ...] }
    from set_name
    [ where condition ]
    [ filter filter_name ]
    [ tag [not] tag_name [, ...] ]
    [ sort attribute [, ...] ]
    [ offset start ]
    [ limit count ]






Description




The retrieve command retrieves a list of objects from a set
according to specified criteria.




Parameters




The first argument specifies a comma-separated list of attributes for
which to retrieve data, or the keyword all meaning all available
attributes.




from




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




where




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




filter




The filter clause applies a specified filter to the objects
retrieved.




tag




The tag clause selects objects having the specified tags.




sort




The sort clause specifies a comma-separated list of attributes to
sort the objects on.  The default order is undefined if sort is not
specified.




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 a time.  Note: sort is
required whenever offset is used.




limit




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




Examples




To retrieve the id and title attributes of five objects from the
reserve set:








retrieve id, title from reserve limit 5








To look at a specific object in detail:








retrieve all from reserve where id = "053e4063-d70c-4a41-a968-e6900e6b47d5"










2.3.10. show filters




List existing filters








show filters






Description




The show filters command lists existing filters.




Examples






show filters










2.3.11. show sets




List existing sets








show sets






Description




The show sets command lists existing sets.




Examples






show sets










2.3.12. show tags




List existing tags








show tags






Description




The show tags command lists existing tags.




Examples






show tags
















3. Server administration






3.1. System requirements




3.1.1. Hardware requirements




This section will contain system hardware requirements.








3.1.2. Software requirements




    

  • 

    Operating system: Linux
    

    • 

  • 

    Database system: PostgreSQL 18 or later
    

    • 

  • 

    To build from source:
    

    


    

    • 











3.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>










3.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:








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








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








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








The ccd server will assume that the database, superuser, and
systemuser defined here already exist; so they should be created
before continuing.








3.4. Upgrading from a previous version




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








3.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