Workbench Jobs

Advanced

Workbench Jobs allows you to run R scripts in new sessions independent of your current RStudio Pro session. These jobs are helpful for executing long-running scripts such as training models or running multiple jobs simultaneously. Users can also run Background Jobs on RStudio Pro. However, Background Jobs runs in the same RStudio Pro session, whereas Workbench Jobs runs independently of RStudio Pro sessions. See a comparison of Background Jobs vs. Workbench Jobs below.

Note

The ability to run Workbench Jobs requires your server administrator to configure Job Launcher. Contact your server administrator to change these defaults and refer them to the Job Launcher section of the Administration Guide.

To start a Workbench Job, in an RStudio Pro session, select Source as Workbench Job…:

Depending on how your administrator has set up Posit Workbench, different options will be available when launching a job. Resource sizing and Docker image selection options will be available if Posit Workbench utilizes an external cluster such as Slurm or Kubernetes.

Monitoring Workbench jobs

Once a Workbench Job is created, jobs can be monitored from the Workbench Jobs tab of any RStudio Pro session, which shows all of your jobs (not just those launched from the current session). You can safely quit your R session without affecting any currently running Workbench Jobs.

You can also monitor the status of running and completed Workbench Jobs on the Posit Workbench home page:

Audited Workbench jobs

Audited Workbench jobs capture information on a Workbench job’s output, including digital signatures, environment information, and custom information configured by users. Create audited Workbench jobs by selecting the Include auditing details with this job check box when dispatching a Workbench job.

Audit details

After an audited Workbench job finishes running, view the details in the Audit Details section of the job details page:

Custom user information

To add custom information to the audit details, add the files you wish to include to the audit details directory. For example, this script captures a file called hello-world.txt:

path = Sys.getenv("AUDIT_DETAILS_PATH")
file_path = paste(path, "hello-world.txt", sep="/")
fileConn = file(file_path, "w")
writeLines(c("Hello World!"), fileConn)
close(fileConn)

After the job finishes running, the files you have included appear as part of the audit details in the User Defined Data tab.

Managed credentials

Preview

Preview feature

This feature is in preview. Preview features are unsupported and may face breaking changes in a future release. Any issues found in the feature will be addressed during the regular release schedule; they will not result in immediate patches or hotfixes.

We encourage customers to try these features and we welcome any feedback via Posit Support, but we recommend that the feature not be used in production until it is in general availability (i.e., officially released as a full feature). To provide feedback, please email your Posit Customer Success representative or sales@posit.co and specify that you are trialing this feature.

If your administrator has enabled managed credentials in jobs, a Managed Credentials section is available in the job launch dialog. Select the Share Workbench-managed credentials with this job checkbox to make your active AWS, Databricks, and Snowflake credentials available to the job. These credentials are available the same way they are in your RStudio Pro session.

This checkbox is disabled if you do not have an active AWS, Databricks, or Snowflake credential. Azure delegated credentials and Custom OAuth integrations are not covered by this checkbox. See Using Azure credentials and Using credentials in Workbench Jobs for how to retrieve those instead.

Contact your server administrator to enable this feature. See Managed Credentials in Workbench Jobs in the Administration Guide.

Workbench Jobs vs Background Jobs

Local Background Jobs are supported by all versions of the RStudio IDE, server, and desktop. Workbench Jobs are a feature of RStudio Pro and VS Code sessions on Posit Workbench, which execute remotely from the current session, and can use the resources of a remote resource manager like Kubernetes or Slurm. The table below provides a comparison.

	Background Job	Workbench Job
Availability	Open source RStudio Desktop, RStudio Server, RStudio Desktop Pro, and Posit Workbench’s RStudio Pro.	Posit Workbench’s RStudio Pro and VS Code.
Where process runs	As a child process in the same session as the current session.	As a new process either on the local server or off-host.
Visibility	Only see the job status in the Background Job pane from the session that initiated the job.	View the job status from the Workbench Workspaces page or from the Workbench Jobs pane from any RStudio Pro session or the Workbench extension in any VS Code session.
Lifetime	If you close the working session, the job terminates. In the RStudio Desktop, you will be warned if you attempt to close the window while the background job is still running. In open source RStudio Server or Workbench, the session will not be suspended if a background job is running.	Because it is a separate process from the session that launched it, you can close the working session and still have your Workbench Job run.
Environment	You can elect to run the Background Job with a copy of the current session’s global environment and/or copy the results back to the session’s global environment. Because the job is running as a child process of the current session, any environment variables set process-level or shell-level are passed to the background job from the main session.	The job runs in a clean environment.