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 - <rubric1>, <score1> <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"