Dashboard administration tab¶

Creating a custom config with processingMCP.xml¶

When processing a SIP or transfer, you may want to automate some of the workflow choices. The processing configuration administration page of the dashboard provides you with an easy form to configure various decision points in the Archivematica workflow. Changes to this form are written to a file called processingMCP.xml. When you start a transfer in the Archivematica dashboard, it automatically uses the default processingMCP.xml.

For more advanced workflows, it might be desirable to create multiple processing configurations - for example, along with the default config, users might want to have a configuration specific to video files. You can add a new processing config through the user interface by clicking on the Add button.

Once you have created a custom processing configuration, you can download the XML file from /var/archivematica/sharedDirectory/share dMicroServiceTasksConfigs/processingMCPConfigs/. Then place this file in the root directory of the transfer. Archivematica will now use the included file to make processing decisions.

The processingMCP.xml follows a specific XML format:

<processingMCP>
 <preconfiguredChoices>
     <!-- Send to quarantine? -->
     <preconfiguredChoice>
         <appliesTo>755b4177-c587-41a7-8c52-015277568302</appliesTo>
         <goToChain>d4404ab1-dc7f-4e9e-b1f8-aa861e766b8e</goToChain>
     </preconfiguredChoice>
     <!-- Display metadata reminder -->
     <preconfiguredChoice>
         <appliesTo>eeb23509-57e2-4529-8857-9d62525db048</appliesTo>
         <goToChain>5727faac-88af-40e8-8c10-268644b0142d</goToChain>
     </preconfiguredChoice>
     <!-- Remove from quarantine -->
     <preconfiguredChoice>
         <appliesTo>19adb668-b19a-4fcb-8938-f49d7485eaf3</appliesTo>
         <goToChain>333643b7-122a-4019-8bef-996443f3ecc5</goToChain>
         <delay unitCtime="yes">2419200.0</delay>
     </preconfiguredChoice>
     <!-- Extract packages -->
     <preconfiguredChoice>
         <appliesTo>dec97e3c-5598-4b99-b26e-f87a435a6b7f</appliesTo>
         <goToChain>01d80b27-4ad1-4bd1-8f8d-f819f18bf685</goToChain>
     </preconfiguredChoice>
     <!-- Delete extracted packages -->
     <preconfiguredChoice>
         <appliesTo>f19926dd-8fb5-4c79-8ade-c83f61f55b40</appliesTo>
         <goToChain>85b1e45d-8f98-4cae-8336-72f40e12cbef</goToChain>
     </preconfiguredChoice>
     <!-- Select pre-normalize file format identification command -->
     <preconfiguredChoice>
         <appliesTo>7a024896-c4f7-4808-a240-44c87c762bc5</appliesTo>
         <goToChain>3c1faec7-7e1e-4cdd-b3bd-e2f05f4baa9b</goToChain>
     </preconfiguredChoice>
     <!-- Select compression algorithm -->
     <preconfiguredChoice>
         <appliesTo>01d64f58-8295-4b7b-9cab-8f1b153a504f</appliesTo>
         <goToChain>9475447c-9889-430c-9477-6287a9574c5b</goToChain>
     </preconfiguredChoice>
     <!-- Select compression level -->
     <preconfiguredChoice>
         <appliesTo>01c651cb-c174-4ba4-b985-1d87a44d6754</appliesTo>
         <goToChain>414da421-b83f-4648-895f-a34840e3c3f5</goToChain>
     </preconfiguredChoice>
   </preconfiguredChoices>
  </processingMCP>

Note that appliesTo is the UUID associated with the micro-service job presented in the dashboard and goToChain is the UUID of the desired selection.

Storage Service options¶

This is where you’ll find the complete URL for the Storage Service, along with a username and API key. See the Storage Service documentation for more information about this feature.

Checksum algorithm¶

You can select which checksum algorithm Archivematica will use during the Assign UUIDs and checksums micro-service in Transfer. Choose between MD5, SHA-1, SHA-256 and SHA-512.

Elasticsearch indexing¶

As of Archivematica 1.7, Elasticsearch is optional. Installing Archivematica without Elasticsearch means reduced consumption of compute resources and lower operational complexity. Disabling Elasticsearch means that the Backlog, Appraisal, and Archival Storage tabs do not appear and their functionality is not available.

This section in the General configuration shows if Elasticsearch is enabled or disabled.

AtoM DIP upload¶

Archivematica can upload DIPs directly to an AtoM website so that the contents can be accessed online. The AtoM DIP upload configuration page is where you specify the AtoM installation where you’d like to upload DIPs (and, if you are using Rsync to transfer the DIP files, the Rsync transfer details).

If AtoM is installed on a remote server, Archivematica uses SSH and rsync to copy the DIP to a temporary directory on the AtoM server. If Archivematica and AtoM share a common filesystem (e.g. a shared network directory) this step is unnecessary.

Archivematica sends a REST request to AtoM to tell AtoM which archival description is the target of the DIP. The DIP target description is identified by the description’s “slug”. The actual upload of the DIP contents to AtoM is done via a background job, and may take some time to process if a large DIP is uploaded.

An AtoM background worker uploads the DIP metadata (METS file) and digital objects from the temporary directory to AtoM, links them to the target description, then deletes the temporary files.

The AtoM DIP upload configuration page is where you specify the details of the AtoM installation you’d like the DIPs uploaded to (and, if using Rsync to transfer the DIP files, Rsync transfer details).

Fields:

• Upload URL: the URL of the destination AtoM website.
• Login email: the email address used to log in to AtoM.
• Login password: the password used to log in to AtoM.
• AtoM version: the version of the destination AtoM website.
• Rsync target: if you’d like to send the DIP with Rsync before it is deposited in AtoM, enter the destination value for rsync, e.g. foobar.com:/dips. This field is optional.
• Rsync command: if you’ve entered an Rsync target, specify the remote shell manually, e.g. ssh -p 22222 -l user. This field is optional.
• Debug mode: if you would like to have additional details in failure reports, also enable debug mode by choosing “Yes”.

You will also need to make some changes in the AtoM user interface:

• The SWORD plugin (Admin –> Plugins –> qtSwordPlugin) must be enabled in order for AtoM to receive uploaded DIPs.
• Enabling Job scheduling (Admin –> Settings –> Job scheduling) in version 2.1 or lower is also recommended.

AtoM DIP upload can use Rsync as a transfer mechanism. Rsync is an open source utility for efficiently transferring files. The rsync-target parameter is used to specify an Rsync-style target host/directory pairing, foobar.com:~/dips/ for example. The rsync-command parameter is used to specify rsync connection options, ssh -p 22222 -l user for example. If you are using the rsync option, please see AtoM server configuration below.

To set any parameters for AtoM DIP upload change the values, preserving the existing format they’re specified in, in the Command arguments field then click “Save”.

$ sudo -u archivematica ssh-keygen

$ sudo apt-get install rssh
$ sudo useradd -d /home/archivematica -m -s /usr/bin/rssh archivematica
$ sudo passwd -l archivematica
$ sudo vim /etc/rssh.conf // Make sure that allowrsync is uncommented!

$ sudo mkdir /home/archivematica/.ssh
$ chmod 700 /home/archivematica/.ssh/
$ sudo vim /home/archivematica/.ssh/authorized_keys // Paste here the contents of id_dsa.pub
$ chown -R archivematica:archivematica /home/archivematica

--url="http://atom-hostname/index.php" \
--email="demo@example.com" \
--password="demo" \
--uuid="%SIPUUID%" \
--rsync-target="archivematica@atom-hostname:/tmp" \
--debug

ArchivesSpace DIP upload¶

Before ingesting digital objects destined for ArchivesSpace, ensure that the ArchivesSpace DIP upload settings in the Administration tab of the dashboard have been set.

These settings should be created and saved before digital objects destined for upload to ArchivesSpace are processed. Note that these can be set once and used for processing any number of transfers (i.e. they do not need to be re-set for each transfer).

Fields:

• ArchivesSpace host: the URL of the host database. Do not include https:// or www., e.g. aspace.test.org.
• ArchivesSpace backend port: the port of the database, e.g. 8089.
• ArchivesSpace administrative user: the username of a user with administrative permissions in ArchivesSpace.
• ArchivesSpace administrative user password: the password for user set above. If you make changes to this configuration, you will need to re-enter the password.
• Restrictions Apply: Selecting Yes will apply a blanket access restriction to all content uploaded from Archivematica to ArchivesSpace. Selecting No will send all content to ArchivesSpace without restrictions. Should you wish to enable the PREMIS-based restrictions functionality, choose Base on PREMIS.
• XLink Show: indicate how the link to the digital object, as it appears in ArchivesSpace, should operate.
  • Embed: the digital object screen is embedded in the current window.
  • New: the digital object screen opens in a new window.
  • None: no specific behaviour is passed to the link.
  • Other: no specific behaviour is passed to the link.
  • Replace: the digital object screen opens in the current window.
• XLink Actuate: indicates when a digital object should display in ArchivesSpace (e.g. whether the link occurs automatically or must be requested by the user). Used in conjunction with XLink Show attribute.
  • None: no specific behaviour is passed to the link.
  • onLoad: link is activated when the document loads (used when Show = Embed).
  • Other: no specific behaviour is passed to the link.
  • onRequest: link is activated when the user selects the link.
• Object Type: entering a value from ArchivesSpace’s controlled list of object types will apply this value to all objects. This field is optional.
• Use statement: entering a value from ArchivesSpace’s controlled list of use statements will apply this value to all objects. This field is optional.
• URL prefix: the URL of DIP object server as you wish it to appear in ArchivesSpace record. Example: http://example.com
• Conditions governing access: entering a value in this field will populate the Conditions governing access note in ArchivesSpace for all objects.
• Conditions governing use: entering a value in this field will populate the Conditions governing use note in ArchivesSpace for all objects.
• ArchivesSpace repository number: the identifier for the ArchivesSpace repository where you are uploading DIPs. Note that the default identifier for a single-repository ArchivesSpace instance is 2.

Archivists’ Toolkit¶

Before ingesting digital objects destined for Archivists’ Toolkit, ensure that the Achivists’ Toolkit DIP upload settings in the Administration tab of the dashboard have been set.

These settings should be created and saved before digital objects destined for upload to Archivists Toolkit are processed. Note that these can be set once and used for processing any number of transfers (i.e. they do not need to be re-set for each transfer). The screenshots below show the template in the dashboard.

Fields:

• Database host: the URL of the host database. Do not include https:// or www., e.g. atoolkit.test.org.
• Database port: the port of the database, e.g. 8089.
• Database name: the name of the database.
• Database user: a username with administrative access to the database.
• Database password: the password for the above user.
• Archivists’ Toolkit username: a username for Archivists’ Toolkit.
• Restrictions apply: if you wish to enable the PREMIS-based restrictions functionality, choose base on PREMIS. To add PREMIS rights, please see Add PREMIS rights and restrictions.
• EAD DAO actuate: indicates when a digital object should display in Archivists’ Toolkit (e.g. whether the link occurs automatically or must be requested by the user). Used in conjunction with EAD DAO Show attribute.
  • None: no specific behaviour is passed to the link.
  • onLoad: link is activated when the document loads (used when Show = Embed).
  • Other: no specific behaviour is passed to the link.
  • onRequest: link is activated when the user selects the link.
• EAD DAO show: indicate how the link to the digital object, as it appears in Archivists’ Toolkit, should operate.
  • Embed: the digital object screen is embedded in the current window.
  • New: the digital object screen opens in a new window.
  • None: no specific behaviour is passed to the link.
  • Other: no specific behaviour is passed to the link.
  • Replace: the digital object screen opens in the current window.
• Object type: entering a value from Archivists’ Toolkit’s controlled list of use statements will apply this value to all objects. This field is optional.
• Use statement: entering a value from Archivists’ Toolkit’s controlled list of use statements will apply this value to all objects. This field is optional.
• URL prefix: the URL of DIP object server as you wish it to appear in Archivists’ Toolkit record. Example: http://example.com
• Conditions governing access: entering a value in this field will populate the Conditions governing access note in Archivists’ Toolkit for all objects. This field is optional.
• Conditions governing use: entering a value in this field will populate the Conditions governing use note in Archivists’ Toolkit for all objects. This field is optional.

API keys¶

Use of the REST API requires the use of API keys. An API key is associated with a specific user. To generate an API key for a user:

• Browse to /administration/accounts/list/
• Click the “Edit” button for the user you’d like to generate an API key for
• Click the “Regenerate API key” checkbox
• Click “Save”

After generating an API key, you can click the “Edit” button for the user and you should see the API key.

IP whitelist¶

The API key is always required but in some cases the administrator may want to add an additional security measurement. IP whitelisting allows you to create a list of trusted IP addresses from which you can access to the API.

The IP whitelist can be edited in the administration interface at /administration/api/. If the whitelist is empty all requests will be allowed.

Approving a transfer¶

The REST API can be used to approve a transfer. The transfer must first be copied into the appropriate watch directory. To determine the location of the appropriate watch directory, first figure out where the shared directory is from the watchDirectoryPath value of /etc/archivematica/MCPServer/serverConfig.conf. Within that directory is a subdirectory activeTransfers. In this subdirectory are watch directories for the various transfer types.

When using the REST API to approve a transfer, if a transfer type isn’t specified, the transfer will be deemed a standard transfer.

HTTP Method: POST

URL: /api/transfer/approve

Parameters:

directory: directory name of the transfer

type (optional): transfer type [standard|dspace|unzipped bag|zipped bag]

api_key: an API key

username: the username associated with the API key

Example curl command:

curl --data "username=rick&api_key=f12d6b323872b3cef0b71be64eddd52f87b851a6&type=standard&directory=MyTransfer" http://127.0.0.1/api/transfer/approve

Example result:

{"message": "Approval successful."}

Listing unapproved transfers¶

The REST API can be used to get a list of unapproved transfers. Each transfer’s directory name and type is returned.

Method: GET

URL: /api/transfer/unapproved

Parameters:

api_key: an API key

username: the username associated with the API key

Example curl command:

curl "http://127.0.0.1/api/transfer/unapproved?username=rick&api_key=f12d6b323872b3cef0b71be64eddd52f87b851a6"

Example result:

{
    "message": "Fetched unapproved transfers successfully.",
    "results": [{
            "directory": "MyTransfer",
           "type": "standard"
        }
    ]
}

CLI creation of administrative users¶

If you need an additional administrator user one can be created via the command-line, issue the following commands:

sudo -u archivematica bash -c " \
    set -a -e -x
    source /etc/default/archivematica-dashboard || \
        source /etc/sysconfig/archivematica-dashboard \
            || (echo 'Environment file not found'; exit 1)
    cd /usr/share/archivematica/dashboard
    /usr/share/archivematica/virtualenvs/archivematica-dashboard/bin/python manage.py createsuperuser
";

CLI password resetting¶

If you’ve forgotten the password for your administrator user, or any other user, you can change it via the command-line:

sudo -u archivematica bash -c " \
    set -a -e -x
    source /etc/default/archivematica-dashboard || \
        source /etc/sysconfig/archivematica-dashboard \
            || (echo 'Environment file not found'; exit 1)
    cd /usr/share/archivematica/dashboard
    /usr/share/archivematica/virtualenvs/archivematica-dashboard/bin/python manage.py changepassword <username>
";

Security¶

Archivematica uses PBKDF2 as the default algorithm to store passwords. This should be sufficient for most users: it’s quite secure, requiring massive amounts of computing time to break. However, other algorithms could be used as the following document explains: How Django stores passwords .

Our plan is to extend this functionality in the future adding groups and granular permissions support.