Homec4science
Diffusion invenio-infoscience (master) Browse

R3600/modules/bibcatalog/doc/admin/bibcatalog-admin-guide.webdoc
cfbbb0a27d1amaster

Last Change
Raw File

bibcatalog-admin-guide.webdoc
View Options

## -*- mode: html; coding: utf-8; -*-
## This file is part of Invenio.
## Copyright (C) 2013 CERN.
##
## Invenio is free software; you can redistribute it and/or
## modify it under the terms of the GNU General Public License as
## published by the Free Software Foundation; either version 2 of the
## License, or (at your option) any later version.
##
## Invenio is distributed in the hope that it will be useful, but
## WITHOUT ANY WARRANTY; without even the implied warranty of
## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
## General Public License for more details.
##
## You should have received a copy of the GNU General Public License
## along with Invenio; if not, write to the Free Software Foundation, Inc.,
## 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
<!-- WebDoc-Page-Title: BibCatalog Admin Guide -->
<!-- WebDoc-Page-Navtrail: <a class="navtrail" href="<CFG_SITE_URL>/help/admin<lang:link/>">_(Admin Area)_</a> -->
<lang>
<en>
<h2><a name="overview">1. Overview</a></h2>
<h3><a name="whatis">1.1 What is BibCatalog</a></h3>
<p>
The BibCatalog Admin module allows the administrator to setup automatic ticket
generation for incoming or existing records.</p>
<p><em>In the future, this might be expanded to also be able to manage the configured ticketing system via the command line.
Like resolving a range of tickets etc.</em></p>
<h3><a name="features">1.2 Features</a></h3>
<p>
The following functionality is currently available:
<ul>
<li>BibCatalog BibTask to create tickets both newly updated records or a selection of records using search queries, record ID's etc.</li>
<li>Easy-to-define ticket templates to customize each specific ticket contents, queue and requirements</li>
</ul>
</p>
<h2><a name="config">2. Configuration</a></h2>
<h3><a name="tickets">2.1 Define ticket templates</a></h3>
Before you can create any tickets, you need to have defined a ticket template. A ticket template is a single python file/module that implements two
functions:
<ul>
<li>check_record(ticket, record): this function accepts a ticket object (BibCatalogTicket) and a record object (BibRecord) and returns True if the record should have a ticket created for it. False if not.
<br />
<blockquote>
<pre>
def check_record(ticket, record):
"""
Checks to see if we should create a ticket.
@param ticket: a ticket object as created by BibCatalogTicket() containing
the subject, body and queue to create a ticket in.
@type ticket: record object of BibCatalogTicket.
@param record: a recstruct object as created by bibrecord.create_record()
@type record: record object of BibRecord.
@return: returns True if record is a 'ARTICLE' record.
@rtype: bool
"""
return record_in_collection(record, "ARTICLE")
</pre>
</blockquote>
</li>
<li>generate_ticket(ticket, record): generates the content and subject of the ticket itself. Returns the enriched BibCatalogTicket object.
<br />
<blockquote>
<pre>
def generate_ticket(ticket, record):
"""
Generates a ticket to be created, filling subject, body and queue values
of the passed BibCatalogTicket object. The enriched object is returned.
@param ticket: a ticket object as created by BibCatalogTicket() containing
the subject, body and queue to create a ticket in.
@type ticket: record object of BibCatalogTicket.
@param record: a recstruct object as created by bibrecord.create_record()
@type record: record object of BibRecord.
@return: the modified ticket object to create.
@rtype: BibCatalogTicket
"""
title_code = load_tag_code_from_name("title")
title = record_get_field_value(record, **split_tag_code(title_code))
abstract_code = load_tag_code_from_name("abstract")
abstract = record_get_field_value(record, **split_tag_code(abstract_code))
ticket.queue = "NEW-ARTICLES"
ticket.body = "%s\n\n%s" % (title, abstract)
ticket.subject = "New record: %s" % (title,)
return ticket
</pre>
</blockquote>
</li>
</ul>
<p>
The name of this file, or <em>ticket template</em>, is what you would later use to refer to it.
</p>
<p>
For example: a ticket template named <em>article_record.py</em> will be referred to on the command line like this:
</p>
<blockquote>
<pre>
$ bibcatalog --tickets="article_record"
</pre>
</blockquote>
<blockquote>
<strong>Note:</strong> You can select more than one ticket template to run by seperating their names with comma (,)
</blockquote>
<h2><a name="usage">3. Usage</a></h2>
<h3><a name="basic">3.1 Basic Usage</a></h3>
<h4>List available ticket templates</h4>
<p>To list all the available tickets, you can run the following:</p>
<blockquote>
<pre>
$ bibcatalog --list-tickets
</pre>
</blockquote>
<p>The special argument <em>--all-tickets</em> can be used to select all tickets available</p>
<p>
<strong>When launching the BibCatalog daemon, selecting a specific ticket using <em>--ticket=TICKET,TICKET</em> or <em>--all-tickets</em> is mandatory.</strong>
</p>
<p>
<strong>Note:</strong> If some templates cannot be loaded due to syntax errors etc. BibCatalog will report the broken plug-ins to the terminal output.
<∕p>
<h4>Select ticket templates</h4>
<p>
A ticket template like the above named <em>article_record.py</em> will be referred to on the command line like this:
</p>
<blockquote>
<pre>
$ bibcatalog --tickets="article_record"
</pre>
</blockquote>
<blockquote>
<strong>Note:</strong> You can select more than one ticket template to run by seperating their names with comma (,)
</blockquote>
<h4>Find records</h4>
<p>BibCatalog needs a set of records to create tickets for. You can give the BibCatalog task these records in many ways:</p>
<p>By search query:</p>
<blockquote>
<pre>
$ bibcatalog -q "collection:Thesis and not subject:automation" --all-tickets
</pre>
</blockquote>
<p>or, by <em>-i</em> parameter:</p>
<blockquote>
<pre>
$ bibcatalog -i 12,13,15 --tickets="article_ticket,thesis_ticket"
</pre>
</blockquote>
</p>
</en>
c4science · Help