PILIN Web Tool User Manual
Version History
Version | Date | Status & changes | Expression identifiers |
V0.1 | 2007-06-26 | Initial release – |
|
V0.2 | 2007-10-25 | Initial Review changes done. |
|
|
|
|
|
To cite the latest version of this work use http://resolver.net.au/hdl/102.100.272/6DFDLCNQH
To cite this version of this work, use http://resolver.net.au/hdl/102.100.272/6DFDLCNQH
1 Purpose/Issue
This user manual is intended to give users a better understanding of the PILIN Web Tool.
2 Background
The PILIN Web Tool is a Web based management tool based on the Handle identifier system developed by C.N.R.I. It provides basic CRUD (create, read, update, delete) operations on Handle identifiers (Handles) for any local Handle server installation.
This user guide is intended for administrators and users of the Handle Identifier system.
3 Introduction
The Handle system comes out of the box with a Java-based client and an API for developers to use. This application is developed on a cleaned up version of the API developed by PILIN called J.A.HDL (Java API for Handle).
The PILIN Web Tool is used to perform simple and batch CRUD operations. These operations can be performed in two modes. The web tool can either take the input from the user interactively using the web forms, or else the input and the operation required can be specified in a XML file.
A Handle resolver is also included in the web tool allowing users to view the Handle Metadata.
4 User Interface Mode
The user interface mode allows for three operations to be performed.
Single Handle create operation.
Single Handle update operation.
Single Handle delete operation.
We will look into these options individually later.
4.1 Handle Server Authentication.
The first page that the user sees is the Handle server Authentication page. The page asks us to nominate and authenticate the user as an administrator for the Handle Server that we are going to log into.
The G.H.R. (Global Handle Registry) maintains the list of all the L.H.S. (Local Handle Servers) which are registered for use. The Handle system uses P.K.I. (Public Key Infrastructure) as its authentication model.
While setting up an L.H.S., a private key is generated that is used to authenticate the administrator for the L.H.S. After providing this key we are authenticated to perform the required operations on the L.H.S.
A pass phrase may have been used to encrypt the private key while the L.H.S. was set up. The same pass phrase, if any, is again required for authentication.
4.2 Handle Operations.
Now that we’re authenticated, we are able to create, add, or delete any Handle on our local server, because we’ve invoked administrator privileges for the entire server.
After the authentication is successful, the user sees the Handle operations page, which tells him which L.H.S. he will be operating on. The Handle server namespace can be changed to a different L.H.S. by pressing the “Change” button on the screen.
Choose one of the options from the radio boxes and chick “Next>>”
4.2.1 Single Handle Create Operation
This is used to create a single handle in our L.H.S.
4.2.1.1 Enter Suffix
At this stage the user needs to enter the Handle suffix. Identifiers under Handles have a prefix, the naming authority which corresponds to the name of the L.H.S; and a suffix, the identifier local to the naming authority.
Suffixes can come from many places. They can be sequence numbers, descriptive words, random numbers, UUIDs etc. users can type your own value here, or they can use a timestamp-based string PILIN have come up with. The PILIN timestamp is like a UUID, but much shorter, and encoded alphanumerically.
4.2.1.2 Specify Handle Value Types.
As far as the Handle system is concerned, every identifier is a record in a flat-file database, with certain attribute values. Handle system works through services looking up those values. So we are now being asked what handle value types the Handle record should contain.
The user can select from one of the predefined handle Value type as displayed in the webpage. The user can also specify the number of fields for that type that will be required.
The predefined types are:
HS_ADMIN: is a pre-defined data type used to describe Handle administrators or administrator groups.
URL: is the URL of the resource identified.
CREATION_DATE: is the date of creation of the handle.
DESC: is a prose description of what is being identified.
EMAIL is the contact address of the person responsible for maintaining the Handle.
HS_ALIAS: is used to add an alias to another Handle.
HS_SERV: contains site information for a service.
URN: type data is a handle value that stores a URN.
INET_HOST: is an IP address or host name.
HS_SECKEY: adds a secret key for P.K.I. as a handle value. Generally, you should check the 'public read permission'.
HS_VLIST: is used to define administrator groups with a list of other handle values.
For a detailed and complete list of all the handle value types please visit www.handle.net. Users will normally only use URL, CREATION_DATE, DESC, EMAIL and HS_ALIAS.
The user can also create new Handle value types. The Handle System provides a type registration service that allows organizations to register new data types for their applications. Data types can be registered as Handles under the naming authority "0.TYPE" by default. They can also register the Handle types as Handles in their own Handle server, and give the full Handle as the name of the custom type. For example, I can define 102.100.TYPE/ISBN to contain an ISBN number : this means that the Handle 102.100.TYPE/ISBN registers the new ISBN type.
User can click on the “Add” button to add custom types.
4.2.1.3 Add values to selected types
The next step is to enter the values, indexes and access privileges for the previously selected Handle types.
Each Handle value has a unique index, a number that distinguishes it from the other values in the Handle record. Handle indexes are already defined for the predefined types, and have to be assigned only for new user defined types.
Access privileges are defined in terms of read and write permissions, applicable to either public or to handle administrator(s). Each Handle value can have its permission field specified as any combination of the following:
PUBLIC_WRITE: allows anyone to modify or delete the handle value.
PUBLIC_READ: allows anyone to read the handle value.
ADMIN_WRITE: allows any Handle administrator to update or delete the handle value.
ADMIN_READ: allows the Handle value to be read by any Handle administrator with AUTHORITIVE_READ privileges.
At this stage the user can also nominate a different L.H.S. as an administrator for this new handle. This can be useful if some other organisation with a different namespace wants(needs?) to take control of your handles. By default this option is disabled.
The set of permissions for the HS_ADMIN record can be defined as follows:
Note that the permissions distinguish between the naming authority administrator (whoever manages the L.H.S.) and the Handle administrator (whoever is authorised to manage the particular Handle—this does not need to be limited to the naming authority administrator).
canAddHandle: This permission allows a naming authority administrator to create new Handles under a given naming authority.
canDeleteHandle: This permission allows a naming authority administrator to delete Handles under a given naming authority.
canAddNA: This permission allows the naming authority administrator to create new sub-naming authorities.
canDeleteNA: This permission allows the naming authority administrator to delete an existing sub-naming authority.
canModifyValue: This permission allows the Handle administrator to modify any handle values other than HS_ADMIN values.
canReadValue: This permission allows the Handle administrator to read any Handle value.
canAddValue: This permission allows the Handle administrator to add Handle values other than the HS_ADMIN values.
canRemoveValue: This permission allows the Handle administrator to remove Handle values.
canModifyAdmin: This permission allows the Handle administrator to modify HS_ADMIN values.
canRemoveAdmin: This permission allows the Handle administrator to remove HS_ADMIN values.
canAddAdmin: This permission allows the Handle administrator to add new HS_ADMIN values.
canLISTHandle: This permission allows the naming authority administrator to list Handles under a given naming authority.
4.2.1.4 Create Handle Confirmation.
Next the user sees a Create Handle Confirmation screen, which displays the handle record for the newly created Handle.
Clicking on the “Done” button finishes the operation.
4.2.2 Single Handle Update Operation
This is used to update an already existing Handle. The user can either update an existing value for a Handle type, and can also append or delete individual Handle type from the existing Handle record.
4.2.2.1 Enter Suffix
The user enters the Handle that needs to be updated and clicks the “Update Handle” button.
The record for the existing handle is displayed.. At this stage the user can decide if this is the correct Handle to modify.
The user presses the “Next” button to proceed with updating.
4.2.2.2 Update Values
On this page the user can update the values entered earlier in the Handle record. The user can also change the access privileges for a Handle type.
The “Delete” button next to individual handle field can be used to delete that field from the handle record.
The “Add” button can be used to append another new Handle type to this Handle.
HS_ADMIN record can also be updated for the Handle at this stage.
4.2.2.3 Update Confirmation.
A confirmation screen is shown next with the options of “Cancel”, “Update” and “Back” buttons.
4.2.2.4 Update Result.
An Update Handle result is shown to the user displaying the new updated Handle record.
4.2.3 Single Handle Delete Operation
Handle delete functionality is also provided. If your system supports truly persistent identifiers, you should never delete your Handles. Even if your resource is no longer available, you should continue to make your identifier available, if only so that consumers can realize that the resource is no longer available.
4.2.3.1 Enter Handle Suffix
A screen asks the user to enter the Handle suffix that needs to be deleted.
The user can add a Handle suffix and click the “Delete Handle” button to delete the Handle.
4.2.3.2 Delete Handle Confirmation
The user is shown the Handle record for the Handle about to be deleted.
4.2.3.3 Delete Handle Result
The user is informed that the Handle entered is deleted from the L.H.S.
5 XML Mode
This mode can be used for performing the Handle operations including batch operations by uploading a XML file. This XML file must contain the type of operation intended and the metadata needed for the same
The main use of the XML mode is for ease of specifying batch operations. Creation and updating of the multiple Handles via the user interface modes is repetitive and lengthy, Instead the user can specify all the Handles that need to be created (or operated upon) through the XML file, and the web tool can process it in a single request.
The PILIN XML schema and the sample files can be downloaded following the link on the above page.
5.1 Handle Server Authentication
This is the same as for the User Interface Mode.
5.2 XML Handle Operations.
Six Handle operations can be performed via the XML mode
Single Handle create
Single Handle update
Single Handle delete.
Batch Handle create.
Batch Handle update.
Batch Handle delete.
Select an operation to perform and upload the corresponding XML file.
A success message is displayed if all the batch operations succeed.
Click on the “Download Log File” button to view individual operations and failures, if any.
6 Handle Resolver
A Handle resolver is also provided in the Web tool for resolving individual Handles through the web. It allows the user to view the associated values for a handle if they have the permission to do so.
There are two modes for resolution:
Authentication Mode: Display any Handle value readable by the Handle administrator, including those which are not publicly viewable. You will be asked for the local namespace and the Handle server’s private key to authorise the administrator.
Non Authentication Mode: Display only those Handle values that have the public read permission enabled.
Select any radio button based on the above options.
6.1 Handle Resolver Page
Enter the Handle to resolve (<Handle Namespace>/<Handle Suffix>).
Select the Handle value types to be resolved and displayed.
Click “Resolve Handle” button.
6.2 Handle Resolver Result.
A web page is displayed with the resolved Handle values.
7 Glossary Of The Error Messages
Handle namespace required. | User needs to provide the Handle namespace for the L.H.S. |
Handle server private key required | User needs to provide the Handle server private key for authorisation. |
Handle namespace or certification invalid. | The Handle namespace and the private key do not match. |
Incorrect pass phrase | The pass phrase does not match. |
Handle operation required. | The user needs to select one of the radio buttons as an option for operation type. |
Handle suffix required | User needs to provide the Handle suffix. |
The selected handle type can't be null. | User needs to provide values for the Handle type. |
PILIN XML job request parsing error: Missing data for batch-delete-handle operation. Check your XML file. | The operation type selected and the operation type in the XML file do not match. |
XML file only | The input file is not a XML file. |
Handle index value is required. | User needs to provide Handle index for user defined types. |
INSUFFICIENT PERMISSIONS | The handle creation requires access privileges which have not been met. |