(Quick Reference)

8 Administration interface - Reference Documentation

Authors: Lucien van Wouw

Version: 1.4

8 Administration interface

The administration interface is where a CP administrator can:
  • create ftp accounts.
  • set a profile. That is, defaults for the processing instruction such as access, mimetype, the prefered services to use
  • define access policies
  • oversee the production of instructions, starting procedures and monitor the status
  • download technical metadata of stored material

Access to the administration interface is possible via a privileged account only. Such accounts cannot be set via the administration interface directly. Contact the administrator directly to set such accounts.

8.1 Staging area Ftp accounts

Upload and file arrangements are done with an ftp client. You can manage the required ftp accounts at the "Staging Area" section.

Create a user

Fill in or edit the following fields:
  • Login name: A user name containing letters and numbers
  • Password: If the password is left blank, a random password will be created
  • E-mail: The end-user's mail address.
  • Enabled: If on, the account can be used to login.

Press save to store. An account confirmation message is sent to the e-mail. It contains all user and ftp details to login.

Editing and removing

Any account can be modified and deleted. If you delete an ftp account; the user's uploaded files and home directory still remain on the staging area. You need to move or delete these yourself with your ftp administration account.

8.2 Dissemination Accounts

The "Dissemination Accounts" section will allow you to manage user accounts. Such accounts can operate or download repository resources. You can specify what access policies are available to the user and what resources are available to the user and under that conditions.

Create a user

You need to fill in or edit the following fields:
  • Login name: A user name containing letters and numbers
  • Password: If the password is left blank, a random password will be created
  • E-mail: The end-user's mail address.
  • Enabled: If on, the account can be used to login.
  • Access Scope: see below for more details

Webservice key

Each account type has a webservice key. The key is intended to access an object repository resource that is normally closed for anonymous users. The key needs to be attached to the resolve URL that points to a resource. Or be in the header file of a client that is responsible for downloading the files.

To modify the webservice key select "Change key"

Each time you change the access scope settings, this key will change too. You must update your software client or inform the end user of the new key

Access Scope

This setting determines what a user can access.

Set access by Policy
Your repository resources are governed by access policies. If the user is allowed to download files with one or more of these policies, then select them here.

'all'
This account can access all resources, no matter their access policy.

'administration'
This account type has the same scope as the 'all' setting. In addition it allows a client to operate the repository API. All actions regarding account and permission creation can be operated via API calls using the webservice key.

Manage access to resources
Leave the access scope option blank and save the account. You can then show the account and select the 'manage access to resources' option. In this section you can specify the resources by it's PID or OBJID value. Select 'New Userresource' to add a new resource.
  • ResourcePid : The PID value of the individual resource. Or objid of the resources
  • Download limit (default is no limit) : The number of times a user is allowed to download this resources. Set to zero for no limit.
  • Apply downloadlimit for levels : The levels this download limit applies to.
  • Expiration date (default is no date) : The end date the resource is available

Once one or more resources are declared this way, the user can visit their "User's download page". It will show all available ( and possibly expired ) resources and the way those resources are disseminated. The location of this page is:

http://[object repository domain]/resource?access_token=[webservice key]

Editing and removing

Any account can be modified and deleted. The webservice key will change when the Access Scope setting changed.

8.3 Dissemination Accounts API

You can create new user accounts and defined the access to resources with API calls. To make those calls your client needs an administration account and it's webservice key that goes with it. The API will allow you to:
  • create a user account
  • re-set a user account, refreshing the webservice key or password
  • add or update access to resources; setting optional download limits and expiration dates

You cannot:

  • delete a user account
  • create 'administration' and 'all' accounts
  • set policy access
  • delete resources access
  • create or update an account with a username created by a different object repository owner

Content type

The API content type can be JSON and XML. It's entry point is:

http://[object repository domain]/[your naming authority]/user

Creating an account parameters

  • user.username: the login name
  • user.password: the unencrypted password. If empty this will automatically create a password
  • user.mail: an e-mail address
  • user.resources: the list of repository resources that can be accessed with this account
  • user.resources.userResource: a resource element with:
    • pid: the PID of OBJID
    • downloadLimit (default 0)
    • expirationDate (default none): format YYYY-mm-DD
    • buckets ( default 'master' ): a repeatable list of levels the downloadLimit and expirationDate apply to

Updating an account parameters

An existing account will be updated when you use the same user.username value
  • user.replaceKey ( default false ): will change the webservice key

Examples

To create or update a user account; and set the access for two resources, one with a download limit, another with an expiration date, sent:

Request:

POST /12345/user HTTP/1.1
Accept: */*
Connection: Keep-Alive
Content-Type: text/xml; charset=utf-8
Authorization: Bearer [webservice key]

<user>
  <username>a username</username>
  <password>a password</password>
  <mail>an e-mail address</mail>
  <resources>
    <userResource>
        <downloadLimit>100</downloadLimit>
        <pid>12345/a-pid</pid>
        <buckets>master</buckets>
        <buckets>level1</buckets>
    </userResource>
    <userResource>
        <expirationDate>2020-01-01</expirationDate>
        <pid>12345/another-pid</pid>
     </resources>
</user>

Which is - had you sent it as text/json - equivalent to:

{
    user:{
        username: 'a username',
        password: 'a password',
        mail: 'an e-mail address',
        resources:[
            {
                pid:'12345/a-pid',
                buckets:'master',
                buckets:'level1',
                downloadLimit:100
                },
                {
                pid:'12345/another-pid',
                expirationDate:'2020-01-01'}
        ]
        }
}

Response:

<user>
  <message>ok</message>
  <url>http://[repository-url]/resource/list?access_token=[webservice key]</url>
  <username>a username</username>
  <password>a password</password>
</user>

Which JSON equivalent is

{
    "user":{
        "message":"ok",
        "url":"http://[repository-url]/resource/list?access_token=[webservice key]",
        "username":"a username",
        "password":"a password"
        }
}

8.4 Profile

The profile is where you set the default values that are taken over by any processing instruction. That is: Settings in the profile substitute any absent values in the XML processing instruction. It makes sense therefore, to place all your broad access policies and most frequently used file content values.

The available options are described at the settings section.

8.5 Access policies

A policy determines what an anonymous user can and cannot do. Lets say that is a person with a webbrowser who is not logged on to the object repository. Access to each master file and its related derivatives are thus governed by a policy.

There are three main policies available:

policyaccess
closedno files can be downloaded or viewed
restrictedlevel 1 derivatives are restricted ; level 2 and 3 are viewable to the world
openAll derivatives are viewable to the world

The meaning of restricted means the anonymous user can only see the file with a webservice key. Even though at this moment this is not the case, this setting can be used to offer for example a "give me persmission to see this file" option. This will never be the case when the file is closed.

Custom policies

You cannot modify these default policies, but to add your own custom policy is easily done by selecting "New Policy". For each master and derivative you can determine it's access level.

8.6 Managing and monitoring instructions

Each main folder in the staging area you see is represented here.

The moment when a XML instruction is offered; or when it is autocreated, the number of declared files will show up. In addition each file will have a validation status. The files can be viewed by selecting the link of the main folder.

Commands

Autocreate This will autocreate an instruction. Press it and depending on the number of files, the instruction will be put into the database.

that the use of this service will not apply a checksum comparison between the content at the producer's side (outside the staging area that is ). And the material stored onto the staging area. The content producer should decide if the transport is reliable enough to ensure the data's integrity.

Recreate This option is available at the "Stored objects panel". It will reconstruct an earlier used instruction. This command will not work, if there are still files staged with an existing instruction.

Download One you created or uploaded an instruction, it can be downloaded as an XML instruction document.

Unfortunately, the download onto to the staging area of an instruction is not possible because of server permissions. Choose the "download instructions via the browser" option in stead.

Upload You can upload a XML instruction here so it will be placed on the staging area. FTP is also a way of uploading an instruction.

Validate Will perform a check on the instruction vis-a-vis the files in the staging area.

Process files Kick starts the instruction

If you monitor the progress of for example an upload, creation or validation of an instruction it will eventually finish. However no ingest instruction option seems to appear. To make it appear, press the browser's refresh button.

Monitoring

Each phase or step in the creation and running of an instruction can be monitored. The same for each individual files. During an ingest, you can see the accumulative result of all files by selecting the link of the main folder.

Instruction status

This is the particular status of an instruction.

Monitoring with the API

You can use the API to retrieve the current status as well. Use:

NA/instruction/status?pid=The PID of a file contained in the instruction

Example request:

GET /12345/instruction/status?pid=12345/abcdefg HTTP/1.1
Accept: */*
Connection: Keep-Alive
Content-Type: text/xml; charset=utf-8
Authorization: Bearer [webservice key]
:

Example response:

<instruction xmlns="http://objectrepository.org/instruction/1.0/" access="open" action="upsert" autoGeneratePIDs="none" contentType="application/octet-stream" embargoAccess="closed" fileSet="/mnt/sa/12345/67890/folder" na="12345" pdfLevel="level2" replaceExistingDerivatives="true" resolverBaseUrl="http://hdl.handle.net/" task="org.objectrepository.instruction.Task : null" id="56d964380cf264fa84b921ae" plan="StagingfileIngestMaster">
    <workflow>
        <identifier>39f9f6f0-cd30-446f-986d-85f187d89608</identifier>
        <name>InstructionIngest</name>
        <statusCode>900</statusCode>
    </workflow>
</instruction>

The instruction action and status is mentioned in the @instruction/workflow element. The codes indicate the following:

For a validation where the name is InstructionValidate

100=Validation
100.status=Validation instruction command
100.info=A command to validate the instruction was given
200=Validate files
200.status=Validate instruction command received
200.info=You gave the command for validating the instruction
300=Validation requested
300.status=Validation requested
300.info=A request to validate your instruction and files is being prepared
400=Working
400.status=Validating instruction
400.info=The instruction is being validated is placed in a queue
500=Done
500.status=Done validating
500.info=The instruction is validated
600=Verification
600.status=Verification
600.info=Verifying if the validation was succesfull
700=Validation failed
700.status=Unable to validate
700.info=The validation process was interupted
701=Validation error
701.status=File already exists
701.info=File already exists! Either delete it first or use the Update functionality!
702=Validation error
702.status=File does not exist
702.info=File does not exist; please upload a file
703=Validation error
703.status=File size is zero in length
703.info=File size is zero; please re-upload the file
704=Validation error
704.status=File cannot not be read
704.info=File may be corrupted. Please re-upload the file or change its settings
705=Validation error
705.status=Missing contenttype.
705.info=There are files in the instruction that do not have a contentType. Set these contentTypes… or set a global contentType that can be applied to all files.
706=Validation error
706.status=Declared file not found
706.info=The file mentioned in the location element in the instruction is not in the staging area
707=Validation error
707.status=File missing
707.info=The system can not find the file the section refers to
708=Validation error
708.status=Unable to set PID
708.info=No <pid> value provided and no NA attribute present for the system to create random value
709=Validation error
709.status=Unable to set PID
709.info=No <pid> value provided and lidPrefix attribute present for the system to create random value
710=Validation error
710.status=Unable to set PID
710.info=No <pid>, no lidPrefix attribute & <lid> not in proper format () for
711=Validation error
711.status=Checksum mismatch
711.info=The CP-provided <md5> checksum does not match the one generated by the system for file.
712=Validation error
712.status=md5 missing
712.info=There is no md5 checksum.
713=Validation error
713.status=Missing access qualifier
713.info=There are files in the instruction that do not have an access qualifier. Set these… or set a global access status that can be applied to all files.
714=Validation error
714.status=No action qualifier.
714.info=There are files in the instruction that do not have an action qualifier. Set these… or set a global action status that can be applied to all files.
715=Validation error
715.status=Identifier missing
715.info=The file has no persistent identifier or local substitute
716=Validation error
716.status=Persistent identifier missing
716.info=The file has no pid
723.status=MD5 checksum
723.info=Two or more md5 checksums are identical, but only one unique file can be ingested
800=Validation
800.status=Validation complete
800.info=The instruction has been validated

For an ingest where the name is InstructionIngest:

100=Ingest
100.status=Ingest file command
100.info=A command to ingest the files was given
200=Process files
200.status=Process files command received
200.info=You gave the command for ingesting files
300=Ingest requested
300.status=Ingest requested
300.info=A request to ingest your files is being prepared
400=Queued
400.status=Ingest pending
400.info=The command is placed in a queue
500=Working
500.status=Ingesting files
500.info=The files are placed on the ingest queue
600=Verification
600.status=Verifying the batch ingest
600.info=Checking if all files are marked for ingest
700 = Failure
700.status = There were problems processing the instruction.
700.info=Examine the files and correct where necessary
800 = Files are being ingested
800.status = Files are being ingested
800.info=The files are being ingested
900.status=Tasks complete
900.info=All tasks have been completed.

Files status accumulative

All progress for the files

Per file view

Success and retries

When all services of a file have completed, the file reference will be removed from the staging area. In the end all the declared files will be gone.

Of course, things can go wrong. In that case the error is mentioned and nothing will happen until the issue is resolved. If you feel this is because of a bug or system application failure, please contact the service desk that operates the object repository.

You can rerun instructions with different options. For example, because you want to change a label, access status, produce derivatives, etc.

8.7 Stored files

The files section will show all persisted files. Using the dropdown list, you can filter by instruction label. Each file can be edited to change the policy and labeling.

In addition, download all technical metadata as XML per file of for all the files. The XML does not follow a schema and is subject to change.

Recreate instruction If you select a label from from the dropdown list; then you can use that selection to recreate an instruction.

Find by pid Use the PID of a file to display it in the list. Or use the objid of the compound object to find all grouped files.