README.md 7.11 KB
Newer Older
Mark Jordan's avatar
Mark Jordan committed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
# Islandora BagIt Light

## Introduction

[BagIt](https://wiki.ucop.edu/display/Curation/BagIt) is a specification for packaging content and metadata about that content into a format that can be shared between applications. This module provides a framework for generating Bags for Islandora objects. It is a fork of the [Islandora BagIt](https://github.com/Islandora/islandora_bagit) module. The main differences between it and this module are:

* this module does not provide a usere-facing option to generate Bags, it only provides a Drush command.
* this module does not probide implementations of Islandora hooks to detect when an object or datastream has been ingested or modified.
* this module replaces Islandora BagIt's plugins with submodules.

Islandora sites should not enable both this module and Islandora BagIt. Only one should be enabled since they share permissions and hook definitions.

## Requirements

Islandora BagIt Light requires the following modules/libraries:

* [Islandora](https://github.com/islandora/islandora)
* [Libraries](https://drupal.org/project/libraries)
* [Scholars' Lab BagItPHP library](https://github.com/scholarslab/BagItPHP)
* [Archive_Tar](http://pear.php.net/package/Archive_Tar)

## Installation

To install the Islandora BagIt Light module:

1. Install [Archive_Tar](http://pear.php.net/package/Archive_Tar). This package is required by PEAR so if you have PEAR installed on your system, you won't need to install Archive_Tar separately.
2. Install the [Libraries API](https://drupal.org/project/libraries) contrib module.
3. Unzip this module into your site's modules directory as you would any other contrib module.
4. Install the BagItPHP library by entering your site's sites/all/libraries directory and issuing the following command:

   ```git clone git://github.com/scholarslab/BagItPHP.git```

5. Enable the Libraries and Islandora BagIt Light modules like you would any other contrib modules.

## Configuration

All configuration for this module is performed either via Drush options.

### Extending and customizing the BagIt module

Islandora BagIt Light ...

### Modifying a Bag from your own modules

This module provides a drupal_alter() hook, which allows other modules to use hook_islandora_bagit_alter($bag, $islandora_object). Your module can modify the current Bag using any of the methods provided by the BagItPHP library. Each implementation of this hook must take $bag and $islandora_object as parameters; $islandora_object is provided so you can access properties of the object in your module easily. A typical implementation looks like this:

```
/**
 * Implementation of hook drupal_alter().
 *
 * @param object $bag
 *   A BagIt object instantiated in the BagIt module.
 *
 * @param object $islandora_object
 *  The current $islandora_object.
 */
function mymodule_islandora_bagit_alter($bag, $islandora_object) {
  // Add some custom metadata to bag-info.txt.
  $bag->bagInfoData('Some-Arbitrary-Field', 'Foo bar baz');
  // Add a file that is not managed by a plugin. Note: extra files
  // should be added by plugins if possible, since files that are
  // added in drupal_alter() hooks are not counted in Payload-Oxum
  // values generated by the Islandora BagIt module.
  $bag->addFile('/path/to/file.txt', 'myfile.txt');
  // Update the Bag (this is required).
  $bag->update();
}
```

Note that implementations of hook_islandora_bagit_alter() must call $bag->update() themselves, typically at the very end of the function.

### Post-Bag-creation hook

Islandora BagIt provides an additional hook, islandora_bagit_post_create, that allows other modules to get notifications that a Bag has just been created. A basic implementation is:

```
/**
 * Implements hook_islandora_bagit_post_create().
 *
 * @param string $pid
 *   The PID of the Islandora object that the Bag was just created for.
 *
 * @param string $bag_path
 *  The path to the Bag, relative to the Drupal installation directory.
 */
function mymodule_islandora_bagit_post_create($pid, $bag_path) {
  // Do something interesting.
}
```

This hook can be used to send notification emails after a Bag has been created, to add the Bag to a queue for further processing, or to copy the Bag to a different server.

### Drush integration

Bags can be created for individual Islandora objects or for all objects in a given collection using Drush:

```drush --user=UID create-islandora-bag [object|collection] PID```

where UID is the user ID or user name of the fedoraAdmin user (or equivalent), 'object' or 'collection' indicates whether you want to create a Bag for a single object or a Bag for every member of a collection, and PID is the PID of the Islandora object or collection.

### Permissions and security

This module is intended for users who have a fairly high level of permissions on a Drupal site. Because the goal is to package up all or some of the datastreams in an Islandora object, users who can create and download Bags should have access to those datastreams. However, the module does check the current users' access to a datastream before adding it to the Bag.

## Known Issues

Fedora 3.8.0 fails to generate FOXML files requested using the 'archive' context ([JIRA ticket](https://jira.duraspace.org/browse/FCREPO-1384)). Earlier versions may succeed on exporting 'archive' FOXML files if the resulting FOXML is smaller than approximately 200 MB, but fail on larger files. The Islandora BagIt module triggers this set of errors if 'archive' FOXML files are generated from within one of its plugins ([JIRA ticket](https://jira.duraspace.org/browse/ISLANDORA-1193)). Until this issue is resolved in Fedora, users of the Islandora BagIt module should not use plugins that generate 'archive' FOXML, including plugin_object_foxml.inc distributed with versions of Islandora BagIt prior to 7.x-1.5. The other FOXML export contexts, 'public' and 'migrate' ([documentation](https://wiki.duraspace.org/display/FEDORA37/REST+API#RESTAPI-export)), can be used safely.

Some bags do not finish properly even with PHP CLI's php.ini set to ```max_input_time = -1``` ([JIRA ticket](https://jira.duraspace.org/browse/ISLANDORA-1403)). For better performance the CLI's php.ini should have the lines ```max_execution_time = 0``` and ```man_input_time = -1```, and well as including ```Timeout 86400``` in Apache2's apache2.conf.

## Documentation

Further documentation for this module is available at ...

## Troubleshooting/Issues

Having problems or solved a problem? Check out the Islandora google groups for a solution.

* [Islandora Group](https://groups.google.com/forum/?hl=en&fromgroups#!forum/islandora)
* [Islandora Dev Group](https://groups.google.com/forum/?hl=en&fromgroups#!forum/islandora-dev)

## Maintainers/Sponsors

Current maintainers:

* [Mark Jordan](https://github.com/mjordan)

## Development

If you would like to contribute to this module, please check out [CONTRIBUTING.md](CONTRIBUTING.md). In addition, we have helpful [Documentation for Developers](https://github.com/Islandora/islandora/wiki#wiki-documentation-for-developers) info, as well as our [Developers](http://islandora.ca/developers) section on the [Islandora.ca](http://islandora.ca) site.

## License

[GPLv3](http://www.gnu.org/licenses/gpl-3.0.txt)