From NSDLWiki

Contents [hide] 1 NCS Use Cases for Collections API 1.1 Overview 1.2 To create/update a NSDL collection 1.3 To create/update an item-level record 1.4 Still to Document

NCS Use Cases for Collections API

Overview

In addition to creating collections- and item-level records, the NCS also generates NCS-specific data that it writes to the NDR (so that the NCS can restore itself from the NDR if needed) when it creates/updates collection- and item-level records.

In the proposed Collections API, these NCS-specific data are managed in the NDR as annotations and organized into collections. The NDR structures used to manage NSDL collections records, as well as the related ncs-specific data, is depicted in Graphical overview of NCS Collection Management using Collections API.

NCS maintains a collection of collectionInfo records (collectionInfoCollection) that hold ncs-specific info about the collections managed in the NCS.

For each collection managed by an NCS instance, there is itemInfoCollection, which stores information about the individual items in the collection.

To create/update a NSDL collection

1 – the collection itself is written using putCollection

Parameters to the putCollection call:

• collectionId – the id created/assigned in the NCS – if this ID already exists in the NDR and it is not owned by the NCS, an error will be thrown
• xmlFormat, name, description – pulled from the edited record
• collectionRecord – the ncs_collect record that is edited in the NCS
• agent – the NCS agent (as configured)
• metadataSource – the NCS metadataSource (configured)

2 – NCS-specific information about the collection is written via a putRecord to the collectionInfoCollection record for that collection.

Parameters to the putRecord call:

• collectionId – the id of the NCS’s collectionInfoCollection collection record.
• recordId – an id derived from the collection-record so that this record can be found and updated in the future
• xml – the NCS_specific information maintained by the NCS includes ncs_data and collection_configuration – These two XML structures would be combined into a single XML element, ncs_collection_internal, and written to the NDR so the NCS can restore itself from the NDR if necessary. ncs_collection_internal would contain the CollectionId, and it’s format registered with the NDR so that the association between it (as an annotation) and the collection record is maintained by the NDR. (In other words, when the collection Record is accessed via getRecord, the ncs_collection_internal record would be included in the response).
• restrictAccessTo – NCS and other trusted apps (TBD) that might need to access this info.

3 – If the items of the new collection are to be managed in the NCS, a collection of ncs-specific item-level information (itemInfoCollection) about the items in the collection is created (using putCollection).

The items in the itemInfoCollection are created/updated when the items in the collection are created or updated (see below).

To create/update an item-level record

1 – the item record itself is created/updated using putRecord

Parameters:

• collectionId – this item’s collection
• recordId – id assigned to record in the NCS (again, if this id exists at creation time in the NDR – and is owned by a different agent – an error will be thrown)
• xml – the record created/updated in the NCS

2 – the ncs-specific item-level info is written to the itemInfoCollection using putRecord Parameters:

• collectionId – the NCSs is item’s itemInfoCollection for this collection
• recordId – an id derived from the item-recordId so that this record can be found and updated in the future
• xml – the ncs-specific XML structure. As an annotation this XML must contain the item’s recordId, and it’s format must be registered with the NDR so that it will be attached to the item.
• restrictAccessTo – NCS and other trusted apps (TBD) that might need to access this info.

Still to Document

• syncing between NCS and NDR
• elevating existing NCS collections to NSDL collections
• de-accessioning collections
• ...