Editing Using Issues for Quality Control (section)

==Behind the scenes==

Issues can be defined in two ways: issues that relate to the properties of an individual item are defined in a configuration file using an XML syntax; issues that require a larger scope (such as comparing the item to other items in the repository) are implemented as EPrints plugins.

The "Issues" tab on the details page has 2 sections (see "Issues Tab in Detail" above):

* Current Issues
* Issues Recorded

Any XML-defined issues are displayed in the "Current Issues" section immediately. A command line script called "[[API:bin/issues_audit|bin/issues_audit]]" must be run to process the plugin-based issues - any identified are recorded and will then appear in the "Issues Recorded" section, '''Note there is a special plugin which checks for each of the XML-defined issues - see Plugin Reference below - hence XML defined issues can appear in both the "Current Issues" and "Recorded Issues" sections'''. '''Note that this script must be run regularly in order for the "Issues Search" to function correctly'''. Therefore, the "Current Issues" section reflects the "live" issues for the item whereas the "Issues Recorded" section lists the issues that were reported the last time the issues_audit script was run.

===issues.xml===

Issues that relate to the properties of an individual item are defined in the configuration file ''archives/ARCHIVEID/cfg/issues.xml''.

The issues.xml file uses the [[EPrints_Control_Format|EPrints Control Syntax]] and [[EPScript|EPrints Script]] to define a series of tests that can be carried out on an item's metadata to work out which issues an item has. Each issue is then defined using an "<issue>..</issue>" construct.

'''Example 1''' Test the metadata fields '''date''' and '''ispublished''' - if the date is at least 2 years in the past and ispublished has the value "submitted" or "inpress", report the "old_but_not_published" issue for the item (this example is taken from the default issues.xml in EPrints 3.1.3).

   <epc:if test="date.is_set() and date lt today().datemath( -2,'year' ) and ( ispublished = 'submitted' or ispublished = 'inpress' )">
      <issue type="old_but_not_published">Date is <strong><epc:print expr="date" /></strong> but item is still marked as <strong><epc:print expr="ispublished" /></strong>.</issue>
   </epc:if>

'''Example 2''' An <issue> without a conditional test will always be reported.

 <issue type="always_reported">This issue is always reported.</issue>

[[Image:Always_reported.png]]

'''Example 3''' Report articles that do not have an ISSN.

   <epc:if test="type='article' and ispublished='pub' and !issn.is_set()">
     <issue type="published_but_no_issn">Item is published but has no ISSN. </issue>
   </epc:if>

===Issues plugins===

The default EPrints Issues plugins can be found in ''perl_lib/EPrints/Plugin/Issues/''. Local repository plugins should be stored in ''archives/ARCHIVEID/cfg/plugins/EPrints/Plugin/Issues/''.

Each plugin receives a list of EPrints to test. Plugins can implement some or all of the following methods:

* '''process_item_in_list''' - record issues/details for whole list
* '''item_issues''' - return a list of issues for the given item
* '''process_at_end''' - add any additional issues after the list has been processed

If a plugin implements '''process_item_in_list'' this will be called for each item in the list, otherwise, '''item_issues''' will be called for each item in the list. '''process_at_end''' will be called after the whole list has been processed.

'''Example 1''' Use '''process_item_in_list''' to keep a record of all the titles encountered; check for duplicate titles in '''process_at_end''' and create issue for each matching item (code excerpts from the EPrints 3.1.3 default ExactTitleDups.pm plugin):

 sub process_item_in_list
 {
        ...
        my $title = $item->get_value( "title" );
        push @{$info->{titlemap}->{$title}}, $item->get_id;
 }
 
 sub process_at_end
 {
        ...
        foreach my $code ( keys %{$info->{titlemap}} )
        {
                my @set = @{$info->{titlemap}->{$code}};
                next unless scalar @set > 1;
                foreach my $id ( @set )
                {
                                ...
                                push @{$info->{issues}->{$id2}}, {
                                        type => "duplicate_title",
                                        id => "duplicate_title_$id",
                                        description => $desc,
                                };
                                ...
                }
        }
  }

'''Example 2''' Implement the item_issues method to check for PDF documents where the depositor has accidentally uploaded more than 1 file.

 sub item_issues
 {
        my( $plugin, $dataobj ) = @_;
  
        my @issues;
        foreach my $doc ( $dataobj->get_all_documents )
        {
                my $format = $doc->get_value( "format" );
                my %files = $doc->files;
                if( $format eq "application/pdf" && scalar keys %files > 1 )
                {
                        push @issues, {
                                id => "extra_files_" . $dataobj->get_id,
                                type => "extra_files",
                                description => "Extra files uploaded to PDF document",
                        };
                }
        }
        return @issues;
 }

[[Image:Issues_extra.png]]

===Plugin Reference===

This table lists the default EPrints Issue plugins:

{| border="1" cellspacing="0" cellpadding="10"
!Name
!EPrints Version
!Description
|-
|ExactTitleDups.pm
|3.1.3
|Finds items with identical titles, records issue on each matching item
|-
|SimilarTitles.pm
|3.1.3
|Find items with similar titles, records issue on each matching item
|-
|XMLConfig.pm
|3.1.3
|Apply rules in issues.xml to each item, record each issue
|}

'''All default plugins are located in perl_lib/EPrints/Plugin/Issues/