Contribute to the DSpace Development Fund
The newly established DSpace Development Fund supports the development of new features prioritized by DSpace Governance. For a list of planned features see the fund wiki page.
SWORD (Simple Web-service Offering Repository Deposit) is a protocol that allows the remote deposit of items into repositories. DSpace implements the SWORD protocol via the 'sword' web application. The specification and further information can be found at http://swordapp.org/.
SWORD is based on the Atom Publish Protocol and allows service documents to be requested which describe the structure of the repository, and packages to be deposited.
Enabling SWORD v2 Server
To enable DSpace's SWORD v2 server, set the following in your local.cfg:
swordv2-server.enabled = true # Optionally, if you wish to change its path swordv2-server.path = swordv2
Once enabled, the SWORDv2 module will be available at ${dspace.server.url}/${swordv2-server.path}. For example, if "dspace.server.url=http://localhost:8080/server", then (by default) it will be available at http://localhost:8080/server/swordv2/
Configuring SWORD v2 Server
These are the SWORD (v2) configurations. They may be edited directly or overridden in your local.cfg config (see Configuration Reference).
Configuration File: |
|
---|---|
Property: |
|
Example Value: |
|
Informational Note: | Whether SWORDv2 module is enabled or disabled (disabled by default). |
Property: |
|
Example Value: |
|
Informational Note: | When enabled, this is the subpath where the SWORDv2 module is deployed. This path is relative to |
Property: |
|
Example Value: |
|
Informational Note: | The base url of the SWORD 2.0 system. This defaults to |
Property: |
|
Example Value: |
|
Informational Note: | The base URL of the SWORD collection. This is the URL from which DSpace will construct the deposit location URLs for collections. This defaults to |
Property: |
|
Example Value: |
|
Informational Note: | The service document URL of the SWORD collection. The base URL of the SWORD service document. This is the URL from which DSpace will construct the service document location urls for the site, and for individual collections. This defaults to |
Property: |
|
Example Value: | swordv2-server.accept-packaging.collection.METSDSpaceSIP = http://purl.org/net/sword/package/METSDSpaceSIP swordv2-server.accept-packaging.collection.SimpleZip = http://purl.org/net/sword/package/SimpleZip swordv2-server.accept-packaging.collection.Binary = http://purl.org/net/sword/package/Binary |
Informational Note: | The accept packaging properties, along with their associated quality values where appropriate. Package format information
|
Property: |
|
Example Value: | swordv2-server.accept-packaging.item.METSDSpaceSIP = http://purl.org/net/sword/package/METSDSpaceSIP swordv2-server.accept-packaging.item.SimpleZip = http://purl.org/net/sword/package/SimpleZip swordv2-server.accept-packaging.item.Binary = http://purl.org/net/sword/package/Binary |
Informational Note: | The accept packaging properties for items. It is possible to configure this for specific collections by adding the handle of the collection to the setting, for example Package format information
|
Property: |
|
Example Value: | swordv2-server.accepts = application/zip, image/jpeg |
Informational Note: | A comma-separated list of MIME types that SWORD will accept. To accept all mimetypes, the value can be set to "*/*" |
Property: |
|
Example Value: | swordv2-server.expose-communities = false |
Informational Note: | Whether or not the server should expose a list of all the communities to a service document request. As deposits can only be made into a collection, it is recommended to leave this set to false. |
Property: |
|
Example Value: | swordv2-server.max-upload-size = 0 |
Informational Note: | The maximum upload size of a package through the SWORD interface (measured in bytes). This will be the combined size of all the files, metadata, and manifest file in a package - this is different to the maximum size of a single bitstream. |
Property: |
|
Example Value: | swordv2-server.keep-original-package = true |
Informational Note: | Should DSpace store a copy of the orignal SWORD deposit package? |
Property: |
|
Example Value: | swordv2-server.bundle.name = SWORD |
Informational Note: | The bundle name that SWORD should store incoming packages within if |
Property: | swordv2-server.bundle.deleted |
Example Value: | swordv2-server.bundle.deleted = DELETED |
Informational Note: | The bundle name that SWORD should use to store deleted bitstreams if |
Property: |
|
Example Value: | swordv2-server.keep-package-on-fail = false |
Informational Note: | In the event of package ingest failure, provide an option to store the package on the file system. The default is false. The location can be set using the |
Property: |
|
Example Value: | swordv2-server.failed-package-dir = /dspace/upload |
Informational Note: | If |
Property: |
|
Example Value: | swordv2-server.on-behalf-of.enable = true |
Informational Note: | Should DSpace accept mediated deposits? See the SWORD specification for a detailed explanation of deposit On-Behalf-Of another user. |
Property: | swordv2-server.on-behalf-of.update.mediators |
Example Value: | swordv2-server.on-behalf-of.update.mediators = admin@mydspace.edu, mediator@mydspace.edu |
Informational Note: | Which user accounts are allowed to do updates on items which already exist in DSpace, on-behalf-of other users? |
Property: | swordv2-server.verbose-description.receipt.enable |
Example Value: | swordv2-server.verbose-description.receipt.enable = false |
Informational Note: | Should the deposit receipt include a verbose description of the deposit? For use by developers - recommend to set to "false" for production systems |
Property: | swordv2-server.verbose-description.error.enable |
Example Value: | swordv2-server.verbose-description.error.enable = true |
Informational Note: | should the error document include a verbose description of the error? For use by developers, although you may also wish to leave this set to "true" for production systems |
Property: | swordv2-server.error.alternate.url |
Example Value: | swordv2-server.error.alternate.url = http://mydspace.edu/xmlui/contact |
Informational Note: | The error document can contain an alternate url, which the client can use to follow up any issues. For example, this could point to the Contact-Us page on the XMLUI |
Property: | swordv2-server.error.alternate.content-type |
Example Value: | swordv2-server.error.alternate.content-type = text/html |
Informational Note: | The |
Property: |
|
Example Value: | swordv2-server.generator.url = http://www.dspace.org/ns/sword/2.0/ |
Informational Note: | The URL which identifies DSpace as the software that is providing the SWORD interface. |
Property: |
|
Example Value: | swordv2-server.generator.version = 2.0 |
Informational Note: | The version of the SWORD interface. |
Property: |
|
Example Value: | swordv2-server.auth-type = Basic |
Informational Note: | Which form of authentication to use. Normally this is set to |
Property: |
|
Example Value: | swordv2-server.upload.tempd = /dspace/upload |
Informational Note: | The location where uploaded files and packages are stored while being processed. |
Property: |
|
Example Value: | swordv2-server.updated.field = dc.date.updated |
Informational Note: | The metadata field in which to store the updated date for items deposited via SWORD. |
Property: |
|
Example Value: | swordv2-server.slug.field = dc.identifier.slug |
Informational Note: | The metadata field in which to store the value of the slug header if it is supplied. |
Property: |
|
Example Value: | swordv2-server.author.field = dc.contributor.author |
Informational Note: | The metadata field in which to store the value of the atom entry author if it supplied. |
Property: |
|
Example Value: | swordv2-server.title.field = dc.title |
Informational Note: | The metadata field in which to store the value of the atom entry title if it supplied. |
Property: |
|
Example Value: | swordv2-server.disseminate-packaging.METSDSpaceSIP = http://purl.org/net/sword/package/METSDSpaceSIP swordv2-server.disseminate-packaging.SimpleZip = http://purl.org/net/sword/package/SimpleZip |
Informational Note: | Supported packaging formats for the dissemination of packages. |
Property: | swordv2-server.statement.bundles |
Example Value: | swordv2-server.statement.bundles = ORIGINAL, SWORD, LICENSE |
Informational Note: | Which bundles should the Statement include in its list of aggregated resources? The Statement will automatically mark any bitstreams which are in the bundle identified by the |
Property: |
|
Example Value: | plugin.single.org.dspace.sword2.WorkflowManager = org.dspace.sword2.WorkflowManagerDefault |
Informational Note: | Which workflow manager to use. |
Property: | swordv2-server.workflowmanagerdefault.always-update-metadata |
Example Value | swordv2-server.workflowmanagerdefault.always-update-metadata = true |
Informational Note | Should the WorkflowManagerDefault plugin allow updates to the item's metadata to take place on items which are in states other than the workspace (e.g. in the workflow, archive, or withdrawn) ? |
Property: | swordv2-server.workflowmanagerdefault.file-replace.enable |
Example Value | swordv2-server.workflowmanagerdefault.file-replace.enable = false |
Informational Note | Should the server allow PUT to individual files? |
Property: |
|
Example Value: | swordv2-server.mets-ingester.package-ingester = METS |
Informational Note: | Which package ingester to use for METS packages. |
Property: |
|
Example Value: | swordv2-server.restore-mode.enable = false |
Informational Note: | Should the SWORD server enable restore-mode when ingesting new packages. If this is enabled the item will be treated as a previously deleted item from the repository. If the item has previously been assigned a handle then that same handle will be restored to activity. |
Property: |
|
Example Value: | swordv2-server.simpledc.abstract = dc.description.abstractsimpledc.date = dc.datesimpledc.rights = dc.rights |
Informational Note: | Configuration of metadata field mapping used by the SimpleDCEntryIngester, SimpleDCEntryDisseminator and FeedContentDisseminator |
Property: |
|
Example Value | swordv2-server.atom.author = dc.contributor.author |
Informational Note: | Configuration of metadata field mapping used by the SimpleDCEntryIngester, SimpleDCEntryDisseminator and FeedContentDisseminator |
Property: | swordv2-server.metadata.replaceable |
Example Value | swordv2-server.metadata.replaceable = dc.description.abstract, dc.rights, dc.title.alternative, dc.identifier.citation |
Informational Note | Used by SimpleDCEntryIngester: Which metadata fields can be replaced during a PUT to the Item of an Atom Entry document? Fields listed here are the ones which will be removed when a new PUT comes through (irrespective of whether there is a new incoming value to replace them) |
Property: |
|
Example Value: | swordv2-server.multipart.entry-first = false |
Informational Note: | The order of precedence for importing multipart content. If this is set to |
Property: |
|
Example Value: | swordv2-server.workflow.notify = true |
Informational Note: | If the workflow gets started (the collection being deposited into has a workflow configured), should a notification get sent? |
Property: |
|
Example Value: | swordv2-server.versions.keep = true |
Informational Note: | When content is replaced, should the old version be kept? This creates a copy of the ORIGINAL bundle with the name V_YYYY-MM-DD.X where YYYY-MM-DD is the date the copy was created, and X is an integer from 0 upwards. |
Property: |
|
Example Value: | swordv2-server.state.workspace.uri = http://localhost:8080/xmlui/state/inprogress swordv2-server.state.workspace.description = The item is in the user workspace swordv2-server.state.workflow.uri = http://localhost:8080/xmlui/state/inreview swordv2-server.state.workflow.description = The item is undergoing review prior to acceptance in the archive |
Informational Note: | Pairs of states (URI and description) than items can be in. Typical states are |
Property: | swordv2-server.workspace.url-template |
Example Value | swordv2-server.workspace.url-template = http://mydspace.edu/xmlui/submit?workspaceID=#wsid# |
Informational Note | URL template for links to items in the workspace (items in the archive will use the handle). The |
Other configuration options exist that define the mapping between mime types, ingesters, and disseminators. A typical configuration looks like this:
plugin.named.org.dspace.sword2.SwordContentIngester = \ org.dspace.sword2.SimpleZipContentIngester = http://purl.org/net/sword/package/SimpleZip, \ org.dspace.sword2.SwordMETSIngester = http://purl.org/net/sword/package/METSDSpaceSIP, \ org.dspace.sword2.BinaryContentIngester = http://purl.org/net/sword/package/Binary plugin.single.org.dspace.sword2.SwordEntryIngester = \ org.dspace.sword2.SimpleDCEntryIngester plugin.single.org.dspace.sword2.SwordEntryDisseminator = \ org.dspace.sword2.SimpleDCEntryDisseminator # note that we replace ";" with "_" as ";" is not permitted in the PluginManager names plugin.named.org.dspace.sword2.SwordContentDisseminator = \ org.dspace.sword2.SimpleZipContentDisseminator = http://purl.org/net/sword/package/SimpleZip, \ org.dspace.sword2.FeedContentDisseminator = application/atom+xml, \ org.dspace.sword2.FeedContentDisseminator = application/atom+xml_type_feed # note that we replace ";" with "_" as ";" is not permitted in the PluginManager names plugin.named.org.dspace.sword2.SwordStatementDisseminator = \ org.dspace.sword2.AtomStatementDisseminator = atom, \ org.dspace.sword2.OreStatementDisseminator = rdf, \ org.dspace.sword2.AtomStatementDisseminator = application/atom+xml_type_feed, \ org.dspace.sword2.OreStatementDisseminator = application/rdf+xml
Deposit to SWORDv2 Server
If you'd like to deposit content to your repository via the installed SWORD Server, you'll need to select a SWORD Client to do so.
- Some SWORDv2 Clients are available at http://swordapp.org/sword-v2/
It's possible to simply deposit a valid SWORDv2 Zip package via common Linux commandline tools (e.g. curl). For example:
# Deposit a SWORD Zip package named "sword-package.zip" into a DSpace Collection (Handle 123456789/2) as user "test@dspace.org" # (Please note that you WILL need to obviously modify the Collection location, user/password and name of the SWORD package) curl -i --data-binary "@sword-package.zip" -H "Content-Disposition:attachment; filename=sword-package.zip" -H "Content-Type:application/zip" -H "Packaging:http://purl.org/net/sword/package/METSDSpaceSIP" -u test@dspace.org:[password] -X POST http://[dspace.url]/swordv2/collection/123456789/2 # Template 'curl' command: #curl -i --data-binary "@[zip-package-name]" -H "Content-Disposition:attachment; filename=[zip-package-name]" -H "Content-Type:application/zip" -H "Packaging:http://purl.org/net/sword/package/METSDSpaceSIP" -u [user]:[password] -X POST http://[dspace.url]/swordv2/collection/[collection-handle]
Other example SWORDv2 commands
# Example of retrieving Item information via "edit-media" path in ATOM format (can be run on any item within DSpace, but requires authentication) # NOTE: Accept header is required, and must be a format supported by a SwordContentDisseminator plugin (see configuration above) curl -i -H "Accept:application/atom+xml" -u test@dspace.org:[password] -X GET http://[dspace.url]/swordv2/edit-media/[internal-item-identifier]
Troubleshooting
Missing expression of encoding in XML header
If your SWORD Deposit requests are unsuccessful, please check that the XML in your initial metadata deposit correctly specifies the encoding.
If you use:
<?xml version="1.0"?>
DSpace will default to UTF-32.
So to successfully deposit an XML in UTF-8, make sure you use:
<?xml version="1.0" encoding="utf-8" ?>