- Overview of PURLs
- Using the PURL Server
- Administering Users
- Administering PURLs
- Administering Groups
- Administering PURL Domains
- Batch Interfaces
1. Overview of PURLs
PURLs are Persistent Uniform Resource Locators (URLs). A URL is simply an address on the World Wide Web. A Persistent URL is an address on the World Wide Web that points to other Web resources. If a Web resource changes location (and hence URL), the PURL pointing to it can be updated. A user of a PURL always uses the same Web address, even though the resource may have moved.
PURLs are themselves valid URLs. Figure 1 shows the parts of a PURL. The scheme part tells your Web browser which protocol to use when resolving the address. The host part tells which machine to connect to. In the example below, the host is "purl.org"; in the case of our PURL server it is purl.fcla.edu. The next part, the PURL domain, is analogous to a path in a URL. The domain is a hierarchical information space that separates PURLs and allows for PURLs to have different maintainers. Each domain may be administered by one or more designated maintainers. We have top-level domains for each school (UF, USF, FAMU, etc.) and one for FCLA and PURLs created by PALMM programs (FCLA). Each top-level domain can be further subdivided as needed. Finally, the PURL name is the name of the PURL itself. The domain and name together are unique, and constitute the PURL's "id".
Figure 1. Parts of a PURL
PURL servers may be accessed either by this Web user interface or a batch interface. PURLs and their associated domains, users, groups of users and documentation may be reached by either method. Figure 2 shows the tabbed navigation options in the Web user interface.
Figure 2. Tabbed Navigation in the Web User Interface
2. Using the PURL Server
You can perform some actions (searching for PURLs and users, validating PURLs and resolving PURLS) without being logged in. To do anything else, such as creating or updating a PURL, requires logging into an previously created account. If you don't have an account, you can request one by filling out the Registration form. See 3.1 Register as a New User below.
When you perform an action, such as do a search, your results will display BELOW the form. You may have to scroll down to see complete results.
3. Administering Users
Four actions may be taken on the PURL User Administration screen: Register a new user, Search for a user, and Delete a user. To modify an existing user, first find the user record using Search, and then click the "Modify record" icon to get an edit screen.
3.1 Register as a New User
Users have to be registered with the PURL server before they can create, modify or delete PURLs, participate in groups or administer domains. Anyone can submit a new User Registration Form (you do not have to be logged in to do this) but registration is not complete until approved by a PURL administrator. The PURL Administrator will contact you when your registration is approved.
Full name: enter your full first and last name, e.g. Joe Plumber
Affiliation: use your institution code, e.g. UF, UCF, FGCU, etc.
Email address: this is where your confirmation email will be sent
Userid: this is what you will use to log on in the future
Password: whatever you want
Password hint: we STRONGLY recommend you use this field
Justification: you can use this to send a comment to the PURL administrator; normally just leave blank
3.2 Search for User Information
User records are searched using the User Search Form, shown in Figure 3(a). Records may be searched by user name, affiliation, email address or user ID. All of these fields are case-insensitive, and search terms in all of them can be truncated with a wildcard (*).
Figure 3(a) shows a sample search for registered users affiliated with Zepheira and Figure 3(b) shows a typical response. The icon labeled A in Figure 3(b) will cause search results to be shown in a new window. To subsequently edit the user record, click the Modify record icon (labeled B in this example).
Deleted users remain in the system as "tombstoned" user records. They are not searched by default, but can be included in a search by selecting the checkbox labeled "Search tombstoned users" in the User Search Form as shown in Figure 3(a). More information about tombstoning may be found in 4.3 Delete a User, below.
Figures 3(a) and 3(b). Searching User Records
3.3 Delete a User
You can delete your own user record by entering your own userid on the "Delete a user" form. Only a PURL system administrator can delete a userid belonging to someone else.
Please note that users are never actually deleted, they are "tombstoned". This ensures that any PURLs administered by a deleted/tombstoned user do not become inaccessible. Tombstoned user records may be searched by selecting the checkbox labeled "Search tombstoned users" in the User Search Form as shown in Figure 3(a).
Figure 4(a) shows an example deletion request and Figure 4(b) shows a typical response upon success.
Figures 4(a) and 4(b). Deleting a User
4. Administering PURLs
A "maintainer" of a PURL is someone who can modify that PURL. The user who creates a PURL is automatically added as a maintainer, but other maintainers can be added as well, individually or in groups.
Four actions may be taken on a PURL from the PURL Administration page: Create a new PURL, Search for a PURL, Validate a PURL, and Delete a PURL. To modify a PURL, first find the PURL by searching for it, then click on the "Modify record" icon. (See ????)
4.1 Create a New PURL
Remember that PURL ids consist of a domain and a PURL name, as shown below.
Repeat of Figure 1. Parts of a PURL
Figure 5(a) shows the creation of an example PURL. "Path" is the PURL id, starting with the domain. "Target URL" is the URL to which the PURL will redirect. "Maintainers ids" is one or more users and/or groups authorized to update the PURL record. You don't have to add your own id because the PURL creator will automatically be added as a maintainer. Figure 5(b) shows a typical response upon success.
Figures 5(a) and 5(b). Creating a PURL
4.2 Search for a PURL
PURL records can be searched using the PURL Search Form, shown in Figure 6(a). Records can be searched by PURL path (which must always start with a slash), target URL, or maintainer IDs. (Two types of maintainer fields are used: "Maintainer IDs" expands groups into lists of users and "Explicit Maintainers" does not.) Each kind of search is treated as a "begins with" search and must match exactly, so for example if the purl id is "/usf/diglib/winston_123" it will not be found by searching "winston_123". A wildcard can be used for right truncation, e.g. "/usf/diglib/w*"
Note that the PURL server will say that a Search is successful even if no matches are found.
Tombstoned (deleted) PURL records may be searched by selecting the checkbox labeled "Search tombstoned PURLs" in the PURL Search Form as shown in Figure 6(a). PURL records become tombstoned if they are deleted via the PURL Deletion Form. More information about tombstoning may be found under 1.6 Delete a PURL.
Figures 6(a) and 6(b). Searching for PURLs
Figure 6(a) shows a sample search for PURLs maintained by the user "david" and Figure 6(b) shows a typical response. The PURL id is listed, followed by the type of PURL, target URL, maintainers and status. The Type will be 302 for a normal PURL or 410 for a tombstoned PURL. Both individual and group maintainers are listed; group maintainers are shown in italics. Search results can be shown on a separate page by selecting the icon labeled A in Figure 6(b). To modify the PURL information, click the icon labeled B in Figure 6(b). To see the history of changes for that PURL, click the "Show history" icon .
4.3 Validate a PURL
PURL validation returns much the same information as a Search for a PURL, but it also checks that the target URL exists. Note that a successful validation only means the URL resolves to a web object, it does not mean the URL points to the correct object. A tombstoned purl will also return a "validate successful" message.
4.4 Delete a PURL
PURLs can only be deleted using the PURL Deletion Form. You have to enter the entire PURL id, begining with the path. Please note that deleting PURL records actually results in them being "tombstoned" so that they do not become inaccessible. Instead, deleted PURLs will continue to exist on a PURL server but will be modified to return an HTTP 410 status code (Gone). Tombstoned PURLs can be searched by selecting the checkbox labeled "Search tombstoned PURLs" in the PURL Search Form as shown in Figure 6(a). They can also be validated, and will return a validation Success if the Tombstoned PURL is found.
Figure 7(a) shows an example deletion request and Figure 7(b) shows a typical response upon success.
Figures 7(a) and 7(b). Deleting a PURL
5. Administering Groups
It can be convenient to create groups of users to facilitate administration. For example, if you create a large number of PURLs and each PURL may be changed by the same list of people, it will be easier to create a single group to represent those people than to individually list all those people as maintainers.
Four actions can be taken on a group from the Group Administration screen: Create a new group, Search for an existing group or Delete a group. To modify the Group, first find the Group by Search, then clicking the Modify Group icon.
5.1 Create a New Group
Groups can be created via the Group Creation Form. Figure 7(a) shows the creation of a sample group. The "group name" is an optional descriptive name for the group, which can be useful when searching for the group. A "maintainer" is a user or group authorized to administer a group and a "member" is a user or group that is a member of this group. The user who creates the group is automatically entered as a maintainer and member of the group. Figure 7(b) shows a typical response upon success.
Figures 7(a) and 7(b). Creating a Group
5.2 Search for Group Information
Group records may be searched using the Group Search Form, an example of which is shown in Figure 8(a). Records may be searched by group name, group ID, maintainer ID or member ID. Figure 8(a) shows a sample search for Groups that have "brian" as a maintainer and Figure 8(b) shows a typical response. Click the icon labeled A in Figure 8(b) to show results on a separate page; click the Modify icon B to get a modification form.
Like users, inactive groups are not deleted but "tombstoned." Records for tombstoned groups can be included in a search by selecting the checkbox labeled "Search tombstoned groups" in the Group Search Form as shown in Figure 8(a).
Figures 8(a) and 8(b). Searching for Group Information
5.3 Delete a Group
Groups can be deleted using the Group Deletion Form. Please note that deleting group records actually results in them being "tombstoned" so that any PURLs they administer do not become inaccessible. Figure 9(a) shows an example deletion request and Figure 9(b) shows a typical response upon success.
Figures 9(a) and 9(b). Deleting a Group
6. Administering PURL Domains
A domain is the path portion of the PURL URL form, as shown in Figure 1 above. All PURLs must be created within a domain; that helps to ensure order and security on a PURL server.
Three actions can be taken from the Administer PURL Domains screen: Create a domain, Search domains, and Delete a domain. Note that the creation of top-level domains requires permission from the PURL server administrator. Top-level domains are the first domain after the hostname. E.g., in the PURL http://purl.fcla.edu/fcla/fulltext there is one domain, the top-level domain "/fcla". In the PURL http://purl.fcla.edu/fcla/admin/fulltext the domain is "/fcla/admin" which contains the top level domain, "/fcla".
6.1 Create a New Domain
Top level domains have already been established for all schools using the PURL server. They are: /famu, /fau, /fcla, /fgcu, /fiu, /fsu, /ucf, /uf, /usf, /uwf. All PURLS should be created within one of these domains. To create a second-level domain (for example, "/fau/serials") you can use the Domain Creation Form shown in Figure 10(a). This will send a request to the PURL server administrator who will create the domain for you and notify you when done.
On the domain creation form a "maintainer" is a user or group authorized to administer a domain and a "writer" is a user or group authorized to create PURLs within a domain. The operator requesting the domain will automatically be added to both groups.
Figures 10(a) and 10(b). Creating a Domain
6.2 Search for Domain Information
Domain records can be searched using the Domain Search Form, an example of which is shown in Figure 11(a). Records may be searched by domain name, domain ID, maintainer ID or writer ID. When entering the domain ID, it must begin with a slash and end with no slash. E.g. searching "/fcla" will find that domain, but searching "fcla" or "fcla/" or "/fcla/" will fail.
Tombstoned domain records may be searched by selecting the checkbox labeled "Search tombstoned domains" in the Domain Search Form as shown in Figure 24(a). Domain records become tombstoned if they are deleted via the Domain Deletion Form. More information about tombstoning may be found under 6.4 Delete a Domain.
To modify a domain, click the "modify record" icon on your search results. Domain IDs can not be modified, but the name, maintainers, and writers can be modified.
Figures 11(a) and 11(b). Searching for Domain Information
6.3 Delete a Domain
Domains can be deleted by providing their domain IDs to the Domain Deletion Form. Only a maintainer of a domain can delete it. Please note that deleting domain records actually results in them being "tombstoned" so that any PURLs they contain do not become inaccessible.
Figure 12(a) shows an example deletion request and Figure 12(b) shows a typical response upon success.
Figures 12(a) and 12(b). Deleting a Domain
7. Batch Interfaces to the PURL Server
Besides the Web Interface, there are two batch interfaces to the PURL server, batch update and Web client. Batches of PURLs may be created or modified (but not searched or deleted) by using an XML document conforming to a RELAX-NG schema. A RESTful web client can perform all operations via a server API. To use either of these methods, contact FCLA.