To write the scripts, select "Configure Workspace" once you have created a part with the labtype as "Databricks". This action should launch VS Code editor in a new tab, You can use it to edit scripts in /voc/scripts directory. Once you have edited the scripts, select "Update" to deploy them for the labs.
Script overview
Scripts are executed in the order - workspace_init.sh => lab_setup.sh => user_setup.sh => lab_end.sh
Vocareum expects an exit status of 0 if the script succeeds, 1 otherwise. A JSON file voccustomdata.txt can be optionally created upon execution. If the script fails, Vocareum will look for value of parameter error_code and message and then store it for debugging purposes. Otherwise the contents of voccustomdata.txt are passed to the next script as environment variable VOC_CUSTOM_DATA.
workspace_init.sh
The script is called once after a workspace has been created.
Environment variables
VOC_DB_WORKSPACE_URL | URL of the workspace that is created prior to the call, Multiple users for the same class might be sent to the same workspace |
VOC_PARTID | This is a unique ID that is created for the part. It is also available from the Vocareum UI. |
VOC_LABID | This is a unique ID created for the lab instance. It can be used if the script needs a unique identified associated with the instance. |
VOC_RESOURCE_TAGS | A set of tags to apply to resources created |
Use voccustomdata.txt to pass ID of any resources created in this step to the next script.
lab_setup.sh
This script is called when a lab is pre-warmed via the fleet dashboard. If the pre-warm functionality is not required then this script does not need to be written.
Environment variables
VOC_DB_WORKSPACE_URL | URL of the workspace that is created prior to the call, Multiple users for the same class might be sent to the same workspace |
VOC_PARTID | This is a unique ID that is created for the part. It is also available from the Vocareum UI. |
VOC_LABID | This is a unique ID created for the lab instance. It can be used if the script needs a unique identified associated with the instance. |
VOC_CUSTOM_DATA | This is json data that is passed from the lab_setup.sh execution |
VOC_IPC_DATA_FILE | This is the json data file (filename: vocipcdata.txt) which the script can write into to pass on the relevant data in json e.g. notebook_url and Vocareum will redirect the learner to this URL
{"notebook_url" : "https://dbc-343433-sad7dsa.cloud.databricks.com/?o=5153453534522#notebook/31647543543544"}
Note: If you have a user_setup.sh script, you need to use that script to write into this file |
VOC_DB_USER_EMAIL | Email assigned to the user |
VOC_RESOURCE_TAGS | A set of tags to apply to resources created |
Use voccustomdata.txt to pass ID of any resources created in this step to the next script so that the pre-warmed resources can be mapped to a user in user_setup.sh.
user_setup.sh
This script is called to setup the lab for a user or resume the resources if it is called after a session was "stopped" rather than "terminated". If the pre-warm functionality is not required then the entire lab setup can be done in this script. Otherwise, it can be used just to associate a resource with a user, Information from pre-warm phase can be passed to this script via the environment variable VOC_CUSTOM_DATA.
Environment variables
VOC_DB_WORKSPACE_URL | URL of the workspace that is created prior to the call, Multiple users for the same class might be sent to the same workspace |
VOC_CUSTOM_DATA | This is json data that is passed from the lab_setup.sh execution |
VOC_IPC_DATA_FILE | This is the json data file (filename: vocipcdata.txt) which the script can write into to pass on the relevant data in json e.g. notebook_url and Vocareum will redirect the learner to this URL
{"notebook_url" : "https://dbc-343433-sad7dsa.cloud.databricks.com/?o=5153453534522#notebook/31647543543544"} |
VOC_DB_GROUP_NAME | Name of the Databricks group created by the platform in the workspace. User is a member of this group. By assigning the resource to this group, additional member like teachers and team members can be added to the group to provide access to the resources. |
VOC_DB_USER_EMAIL | Email assigned to the user |
VOC_RESOURCE_TAGS | A set of tags to apply to resources created |
lab_end.sh
This script is called to pause or terminate the resources. The following environment variables are passed to the script.
Environment variables
VOC_DB_WORKSPACE_URL | URL of the workspace that is created prior to the call, Multiple users for the same class might be sent to the same workspace |
VOC_CUSTOM_DATA | This is json data that is passed from the user_setup.sh script |
VOC_DB_GROUP_NAME | Name of the Databricks group (won't be available if end lab behavior is "terminate") |
VOC_END_LAB_BEHAVIOR | "stop" or "terminate" |
VOC_DB_USER_EMAIL | Email assigned to the user |
grade.sh
If this file is present then it will be executed when the user selects "submit" from their user interface.
VOC_DB_WORKSPACE_URL | URL of the workspace that is created prior to the call, Multiple users for the same class might be sent to the same workspace |
VOC_CUSTOM_DATA | This is json data that is passed from the user_setup.sh script |
VOC_DB_GROUP_NAME | Name of the Databricks group |
VOC_DB_USER_EMAIL | Email assigned to the user |
vocGradeFile | This is a randomly generated file name. Once the script is executed, Vocareum expects the score for user to be in this file in CSV format - <rubric2>,<score2> Please make sure that the rubrics are created during part creation. |
vocReportFile | This file is expected to contain and text that should be presented to the learner as "grading report" |