Libraries [VC 21.3 GEN]

Whereas collections are more of a generic container for entities, the strength of libraries lies in the ability to have the library content dynamically updated based on a query.

Use libraries to for example:

• Manage the current search performed by a user.

• To represent saved searches created by your users.

• To implement dynamic storage rules or access control restrictions based on the metadata of items.

Creating libraries

When searching for items you can create a library containing the items matching the query by specifying result=library. If used together with autoRefresh=true you can create a “saved search”. When accessing the library later, its content will return

PUT /item?updateMode=REPLACE&autoRefresh=TRUE&result=library HTTP/1.1
Accept: application/xml
Content-type: application/xml

<ItemSearchDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <field>
    <name>project_priority</name>
    <value>urgent</value>
  </field>
</ItemSearchDocument>

<ItemListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <library>VX*19</library>
  <item>VX-13</item>
  <item>VX-14</item>
  <item>VX-71</item>
</ItemListDocument>

Check the library settings to find out how a library was created, or why a library contains a specific set of items, for example when using self-refreshing libraries.

GET /library/VX*67/settings

<LibrarySettingsDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <id>VX*67</id>
   <username>admin</username>
   <updateMode>REPLACE</updateMode>
   <autoRefresh>true</autoRefresh>
   <query>
      <field>
      <name>originalWidth</name>
      <range>
         <value>640</value>
         <value>720</value>
      </range>
      </field>
   </query>
</LibrarySettingsDocument>

Libraries without a query

Libraries can also be created using POST /library. You will need to specify the items that the library should contain, but this can also be changed afterwards.

POST /library HTTP/1.1
Content-Type: application/xml

<ItemListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <item id="VX-250"/>
   <item id="VX-1000"/>
</ItemListDocument>

<URIListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <uri>VX*48</uri>
</URIListDocument>

Check the library settings and you will see that it does not specify a query, in comparison to libraries created when searching.

Automatic deletion

Libraries will be automatically deleted after having not being accessed for a period of 24 hours. There are some exception to this rule. If any of the following conditions apply, the library will not be automatically deleted:

• The library is part of a collection

• The library has a storage rule set

• The library has a site rule set

• The library has autoRefresh=true

• The library has an updateFrequencey set.

Self-refreshing libraries

Libraries can be set to keep their contents up to date with the queries in two ways (see the table below). The two different methods can either be used together or separately. Neither of these modes will have an affect on transient libraries, as they will always be kept up to date.

Having autoRefresh set means that metadata changes will have an almost immediate effect on libraries. But it has the drawback that libraries using variables, such as a timestamp search containing ranges with the “NOW” variable, will not be updated unless a user changes its metadata. To remedy this libraries can be updated periodically. From a performance point of view though, it is more efficient to check if an item belongs to a library then to refresh an entire library – so period updates should be done with care.

Queries involving variables

Using variables in queries, e.g. the use of the word “NOW” when searching timestamped metadata, is not reliable for libraries unless they are either set as TRANSIENT or they are set to be updated periodically.

Update modes

MERGE

In this mode any items that matches query will be added to the library without removing any existing items.

REPLACE

Unlike MERGE, this mode will also remove items that no longer matches the query.

TRANSIENT

This mode has the same semantics as REPLACE, with some important differences. It only contains items on a logical basis, so instead of simply retrieving its items it needs to perform a search every time its contents is being requested. This leads to a faster creation time than REPLACE, but slower lookup and cannot be used to restrict item access.

Example

Creating a library that contains items created within the last 5 days.

PUT /item?autoRefresh=false&updateFrequency=60&updateMode=REPLACE&result=library
Content-Type: application/xml

<ItemSearchDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <field>
      <name>created</name>
      <range>
         <value>NOW-5DAYS</value>
         <value>NOW</value>
      </range>
   </field>
</ItemSearchDocument>

Restrictions

At most 999 self-refreshing libraries can exist in the system simultaneously.

If using the default Solr configuration, it is a good idea to set the useLucene property to speed up matching of self-refreshing libraries.

Restricting access to items

Setting access controls on a library will cascade down on the items. This means that libraries can be used to batch update access controls on a set of items. Note that this does not work on libraries with updateMode TRANSIENT.

Storage rules on libraries

You can set storage rules on libraries. All items belonging to the library will then be affected by the rule. Note that this does not work on libraries with updateMode TRANSIENT. Having a storage rule on a library will also prevent it from being automatically deleted.