Embedded Files
Before you can explore the contents of an online DataNav portal in Builder, you must define a locale for that portal and establish a connection to it. Furthermore, in order to modify the contents of the portal, you must login to it. These and other portal-related functions are the subject of this section.
To create a new portal locale, select Define portal from the File menu. A translucent gray input panel "rolls down" from the title bar of the currently selected locale. Enter the following information in the text fields within this panel, then press the Create button.
The address of the server hosting the portal, e.g., datanav.duhs.duke.edu.
The pathname to the DataNav Server application running on that machine. Your portal administrator will assign this path; for the Lisberger lab's data portal, we use dnportal. The pathname could have multiple levels, such as: path/to/portal.
The HTTPS and HTTP ports monitored by the web server and servlet container within which DataNav Server is running. Some communications between Builder and Server require the secure HTTPS protocol, since users must logon before they can administer the online portal or modify its contents. However, you can also choose to explore the portal's content anonymously, and all communications in that scenario use the HTTP protocol. Again, contact the portal administrator to find out what these port numbers should be. It may depend on whether you are accessing the portal from inside a firewall, or from the outside through a proxy. [The Lisberger lab's portal is accessed through a proxy; use HTTP=80, HTTPS=443.]
You only have to define a portal locale once. Builder stores the portal connection parameters among the application settings in your DataNav workspace. The next time you launch Builder, the portal locale will already be there, and Builder will attempt to connect to it during start-up. While you're likely to interact with only one portal at a time, Builder lets you define up to 3 different portal locales.
After you create the new portal locale, Builder "closes" the currently selected locale and "opens" the new one in a two-step animated transition. In the first phase, the selected locale's blue background "rolls up" so that only its title bar is still visible; in the second phase, the new locale's background "rolls down" into view at the bottom of the application window. The primary content editor panel and the navigation bar are hidden during the transition. After the new locale is "rolled down", they reappear under its title bar.
Since this is a portal locale, the portal command tool bar also appears: a row of five iconic tool buttons docked to the right edge of the locale background. These tool buttons expose portal-specific actions also available from the application's File menu:
Define a new portal locale.
Discard the selected portal.
Connect, login to, or logout of the selected portal.
Change your password or contact information; and, if you're an administrator, manage the portal's registered users.
View the recent portal activity log.
Typically, you will never need to connect to the portal explicitly. Builder automatically connects to each portal locale at start-up and when the locale is first created. However, if it is unable to connect because the portal was down, use the tri-state Connect / Login / Logout button to reconnect once the portal server is running again. Once a connection is established, the button icon becomes a white padlock on an orange background; click it again to login to the portal. A translucent "pop-up" panel rolls out of the top edge of the locale title bar. Enter your name and password in this panel and press the Login button. If login is successful, the status message in the title bar will show you as logged in. You can now change your password or optional contact information, manage the portal's registered users (if you have administrator privileges on the portal), and make changes to portal content. When you're done exploring the portal and/or making changes to its content, you can logout if you wish (Builder will automatically log you out when the application exits).
Once you define a portal locale, you cannot change its connection parameters (host name, path, HTTP/HTTPS ports). If your portal's connection parameters are changed for whatever reason, simply discard that portal locale and create a new one with the updated parameters.
A word on secure communications
All communications over HTTPS are encrypted by the sender and decrypted by the receiver in order to protect the data sent as well as the identity and authentication information of portal authors or administrators. HTTPS is a combination of the HyperText Transfer Protocol (HTTP) with the Transport Layer Security (TLS) cryptographic protocol that enables encrypted communications and secure identification of a network web server. In general, when a web browser opens an HTTPS connection with a web site, a fair amount of handshaking goes on to safely exchange the encryption keys needed to encode and decode future communications between the two. As a first step the web site must authenticate itself to the client by sending back a valid certificate recognized by a trusted certificate authority. If the browser finds that the site's certificate is not recognized, it will warn the user and let him decide whether or not to trust the web site.
The same process happens behind the scenes when DataNav Builder logs into a remote DataNav portal. If the web container running DataNav Server has not been configured with a signed TLS certificate recognized by a trusted certificate authority, then DataNav Builder will raise a dialog during login to ask the user to accept or deny the certificate that was sent (this may be a self-signed certificate, which is not as safe as using a certificate signed by a commercial authority like VeriSign). In this event, if you go ahead and accept the certificate, it will be stored in a private certificate store (mycacerts) located in your DataNav workspace directory. Future logins using the same certificate will succeed without having to manually accept the certificate again. [Note: Remember the password you use when you accept a certificate -- it becomes the password for the private certificate store and should be used when accepting other certificates in the future.]
The File|Activity log command (the gear-shaped icon button in the portal tool bar) raises a translucent gray "pop-up" panel containing a recent activity log. This log is primarily for developer use; it displays status messages about the various request-response exchanges between Builder and the remote portal. Users will typically ignore the log unless a serious problem occurs, in which case the log may contain information that should be forwarded to the portal administrator.
If you are currently logged into the portal, the File|Manage users... command is enabled. This command raises a translucent pop-up panel displaying the portal's registered users list. This list displays the login name, access level, and login status of every registered user on the portal. Users with administrator-level access are distinguished from normal users by a small yellow star in the icon next to the login name. The login status is shown in parentheses after the login name: either "online" or "offline". Keep in mind that this is merely a snapshot of the state of the users list at some given moment in time; press the refresh button to get an updated snapshot.
Use the controls in the section below the users list to change your password or update your contact information (name, job title/position, contact phone number and email address). Note that the contact information is optional and is initially blank for a new user. You can enter only that information which you wish to disclose to the general public, or none at all. The contact information fields are treated as simple strings and are not checked for correctness.
If you have administrative privileges on the portal, then you will also be able to add and remove registered users. To add a new user, enter the user's login name and password in the relevant controls to the right of the users list, check the Administrator? box if the user should be granted administrative-level access, then press the Add User button. If the operation is successful, the user list will be updated to reflect the new user. To remove an existing user, select the user's entry in the list and press the Remove User button (the red "X" icon). If that user is currently logged on, he will quickly find out that he no longer has access to the portal! Finally, you can toggle a user's access level (author or administrator) by pressing the button with the yellow star icon. (Note that you are NOT allowed to remove yourself from the portal, nor change your own access level.)
Once you are finished with the user information management pop-up, click the small "x" icon in the top-right corner to extinguish it.
Exploring and modifying portal content
You'll have noticed by now that -- with the exception of the portal command tool bar and its associated pop-up panels -- a portal locale is no different from the Local Archives locale. Once a connection with the portal server is established, Builder retrieves content from the portal's archive vault and displays it in the archive vault editor. As described in the tutorial, you can click on any figure archive thumbnail in that editor to explore it in greater detail in the figure archive editor. Alternatively, click on a hub thumbnail to load that hub into the data hub editor. From the hub editor you click on a particular navigation view to transition to the navigation view editor, which lets you peruse all hub data that can be presented through that view.
There are, however, some important differences between a portal locale and your local workspace locale. In the former case, since it's retrieving content from a remote portal, Builder could take significantly longer to update its display. For example, you may notice that the thumbnail images for archives in the archive vault editor are initially blank except for a "wait" icon. Once the necessary information is retrieved from the portal, the images are updated accordingly. Similarly, when you select a different view instance within the navigation view editor, you may have to wait a while for the new data to be displayed. The slower your network connection, the longer the wait. Builder aggressively caches portal content to minimize the waiting and keep the application as responsive as possible.
Furthermore, the contents of the portal's archive vault may actually change as you explore it. When you are logged into the portal, you can see every archive, whether it is marked as "public" or "private" (typically, a portal archive will be marked as "private" while it is under construction). However, once you log off, you are like any member of the general public that might explore the portal with the DataNav Viewer web application. Only those portal archives marked as "public" will be accessible to you. Upon logoff, Builder will discard any cached content from non-public archives. It is also possible that, while you are exploring a portal in Builder, the portal's content is modified in some manner by other users currently logged into the portal server. Eventually, Builder will detect the change and resynchronize its cached content appropriately.
Another big difference is that operations that modify content are much more restricted for a portal locale. The only operations that actually update a portal's "live" content are: mounting a figure or data archive, un-mounting an archive, toggling an archive's public/private flag, and checking in revisions for an archive that was previously checked out from the portal. These operations require that you be logged into the portal, and all take place in the context of the archive vault editor. Finer-grained modifications to a data or figure archive are only allowed when you have checked out the archive from the portal. In this scenario, you are not making changes to the "live" archive itself, but to an internal copy that is accessible only to you. All other users "see" only the state of the archive prior to checkout.
To upload an archive from your workspace and mount it on a portal, switch to the target portal locale and login. Then press the archive mount button (or select Edit|Mount... from the application menu). A simple input dialog lets you select the local workspace archive (by title) to be mounted. Once you make a selection, a modal progress dialog blocks the user interface while the selected archive is compressed and then uploaded to and mounted on the portal; the time it takes will depend on the size of the archive's backing store, the speed of the network connection, and the load on the portal server. Once the archive is successfully mounted on the portal, it is removed from your Local Archives. The archive now shows up in the portal's archive vault. You are automatically designated as the owner of that archive, which is initially marked as private. If you examine its thumb nail in the vault editor, you will see two badge icons centered along the bottom edge: a white star on a dark blue circle and a "locked" icon. The first icon indicates that you (the logged-in user) owns the archive; the second indicates that the archive is currently marked as private. If you would like to share your archive only with other registered portal users, then leave it as "private". Otherwise, to toggle a portal archive's public/private flag, highlight the archive's thumbnail within the vault editor, and click on the "lock" button in the right-hand toolbar; like the badge icon, the button's icon indicates whether the archive is private (locked) or public (unlocked). You can also use the checked menu item Edit|Public (Private) in the application's main menu.
Only the designated owner of an archive may remove it from the portal or toggle its public/private flag. Only the owner or a designated archive collaborator may check it out for revisions on a local machine. An archive collaborator is another portal user to whom the owner has granted permission to check out and revise the archive. [Multi-user collaboration was introduced in version 4.6.0 to facilitate cooperation on the construction and maintenance of large, complex data archives.]
Only the archive owner can add and remove users as collaborators on an archive, and only the owner may transfer ownership of an archive to another user. To do so, select the archive in the vault editor and press the "manage collaborators" button or choose Edit|Change owner/collaborators... from the application's main menu; this command will be enabled only when you're logged into the portal as the owner of the currently selected archive. A translucent pop-up panel appears that displays a re-ordered version of the portal's registered users list. You, as the owner of the archive, appear as the first entry in the list (note the round blue icon with a white star), followed immediately by entries for any users already designated as collaborators on the archive (distinguished by the blue user icon with a green checkmark). Any remaining entries in the list correspond to registered users that are NOT collaborators on the archive (gray user icon).
To add a collaborator, select the relevant user entry in the list and click the Add collaborator button; if you select a user that is already designated a collaborator, press the same button -- now labeled Remove collaborator -- to take that user off the archive's collaborator list. Finally, if you wish to transfer ownership to a different user, select that user's name in the list and press the Change owner button; you will remain as a collaborator on the archive, but you will no longer have ownership privileges (notice that the pop-up panel becomes read-only). When you are finished making changes, press the small "x" button in the top-right corner to extinguish the panel.
NOTES: (1) Whenever a portal administrator removes a registered user from the portal, any archive that was owned by the removed user is transferred to an archive collaborator; if there are no collaborators for a given archive, then the portal administrator becomes its owner. (2) If you remove an archive collaborator that has checked out the archive for revision, the portal server will automatically discard those revisions and check-in the archive upon revoking the user's collaborator privilege.
To update an archive that already exists on the portal, you must first checkout the archive for revisions. Press the archive checkout button in the vault editor's right-hand tool bar, or select Edit|Check out from the application menu. You must be logged into the portal as the archive's owner or a designated collaborator, and the archive cannot already be checked out by another user. The checkout scheme allows the owner or a collaborator to work on extensive changes to an archive while the current version of the archive remains "live" on the portal. As described above, the server makes an internal copy of the checked-out archive that is accessible only to you -- you hold the "checkout lock" on the archive. While logged into the portal, you "see" and make changes to this internal copy. Everyone else sees the "live" version of the archive, which is read-only and which cannot be checked out by any other user until you check it back into the portal. This feature prevents archive collaborators from "stepping on" each other's revisions.
A badge icon centered along the bottom edge of the archive's thumbnail indicates that the archive is currently checked out for revisions. A green checkmark on the badge indicates that you (the user currently logged into the portal through Builder) own the checkout lock on the archive and can make revisions to it. If the checkout badge has a red circle with a slash through it, then the archive is currently checked out by another user; only that user can edit the archive. If you hover the mouse over the thumbnail, a tool tip will appear that will indicate when the archive was checked out and who checked it out, along with some other information. Once you successfully checkout an archive, you can work on it for as long as you wish, possibly days or weeks, and over many login sessions. You will be able to add views to a data hub, add instance data, modify figure or view descriptions, and so on -- just as you would to any archive in your local workspace. Of course, you must be logged into the portal to see the checked-out copy of the archive and make changes to it.
Once you have completed all the changes, log into the portal and check-in the revised archive (Edit|Check in command). The portal server will replace the current "live" version with the internal copy containing all of the revisions you've made. [Note that you will also have the option to discard the revisions altogether; this is a safe way to "start over" if you're not happy with the changes you made to the archive.] After check-in, other portal users will be able to "see" the updated version, and the archive is once more available for checkout.
If at any point you decide to remove one of your archives from the portal altogether, use the Edit|Unmount command (the command is enabled only if you're the archive's designated owner). The selected archive is removed from the portal's archive vault, compressed, and downloaded to your local workspace vault (thus, you still have a copy of the archive in case you decide to re-mount it on the portal at a later date).
Page updated
Report abuse