Document 'invoke', '/data/sessions' and everything that happens between workspace and /apps/...
By far the most annoying part is the time between having a working version on workspace and having the version installed in /apps/xyz and published. There are undocumented things going on behind the scenes that are impossible to figure out as an apps developer but are important. I’m especially talking about the different directories.
1dhetero is now the 3rd tool where I have gone through the publication process, after angel and qdot. Every tool has cost me 2-3 days of intense interaction with Steve Clark and a lot of nerves and frustation. Having 5 years of experience in Linux and C++, I do not consider myself completely unskilled in these things.
You absolutely need to provide documentation on: – what invoke is and how it works – what the role of /data/sessions is
Rappture is nice, but it’s not the end of the story when putting something up on nanohub and you should not make people believe it is.
Derrick Kearney at on
Thanks for your wish regarding documentation of the tool contribution process. We have put together a pretty comprehensive guide describing the people involved and each person’s responsibilities. The page is located here:
http://hubzero.org/documentation/1.0.0/managers/maintenance.tools
You may also be interested in a similar page we have regarding invoke scripts that use invoke_app.
http://hubzero.org/documentation/1.0.0/tooldevs/invoke
The invoke_app described in the above page is a newer version than the default /apps/rappture/invoke_app on nanohub.org. The newer version is located in /apps/invoke/current/invoke_app and can be used for testing.
We don’t have anything on the role of the session directory ($SESSIONDIR). I did just briefly explain it’s role to someone and it read something like this:
Files that are written to disk from the application are saved in a directory in the user’s home directory.
Each user has a data directory located in the home directory. Invocation of an application creates a new directory named data/sessions/SESSION, where SESSION is a unique number. This directory is referred to as the SESSIONDIR. The application runs in this directory and all files that are saved to disk are saved in this directory. Directory permissions restrict files from being saved to the tool’s installation directory under /apps. Because the SESSIONDIR changes with each invocation of the tool, it is usually not a good idea to save files to disk and expect the user to be able to navigate through their home directory to find the files. As an alternative, when using Rappture, you can provide the data in the files as a string output that the user can download, or if there are many files that the user would want to download, you could compress all output files into a tar or zip file and provide the compressed archive as a binary output by using the sting output container, and specifying “binary” as the size. see http://rappture.org/wiki/rp_xml_ele_string for more details.
I imagine we could add the above text onto the maintenance.tools page from the first link. Please let us know your feedback about both of the above documents. Let us know if there are things we left out or if anything is still unclear.
Reply Report abuse
Please login to comment.
Alisa Neeman at on
The session number is shown at the top of the session window, but it is very small.
It would be a simple thing to document that the users need to ‘note their session number to find their results later, give them the path, and documentation on how to use Webdav to download.
It should also be possible to put the session ID directly on the tool window’s web page and even some HTML saying, Output Files can be found at /home/hub/username/data/results/sessionID with the appropriate values for username and sessionID.
Just a little php code. Maybe I’ll add that as a wish.
Reply Report abuse
Please login to comment.