The jobs site is where you can run your code on the server against real data, view your analysis outputs on the server and view outputs that have been reviewed, approved and released from the server by our team of output checkers.
Jobs site structure🔗
The jobs site is centred around Projects. When an application to run a study in OpenSAFELY is approved by the data controller, a Project is automatically created. You can see a list of approved projects, and the organisation they belong to here. We will add any GitHub usernames listed in your approval to our
opensafely GitHub organisation. We also will transfer your existing OpenSAFELY study repository (if you have one) into the same organisation. This allows OpenSAFELY to enforce certain security standards, such as multi-factor authentication.
Within each Project, there are one or more Workspaces, which are linked to a GitHub repository in the OpenSAFELY organisation. Any actions you develop as part of your project pipeline within the attached repository are linked to the workspace, allowing these to be run against real data.
A Job is an instance of an Action running on real data. Jobs are run by selecting one or more actions to be run as part of a single Job Request. You can see all the Job Requests that have been run from a Workspace by clicking on "View logs" from a Workspace page. You can see a log of all Job Requests being run here.
graph TD A[Project] --> B[Workspace] A --> C[Workspace] B --> D[Job Request] B --> E[Job Request] C --> F[Job Request] subgraph Actions[Actions - taken from your project.yaml] Action_1[Action] Action_2[Action] Action_3[Action] end Action_1 --> F Action_2 --> F F --> G[Job] F --> H[Job]
Once outputs have been produced by running jobs from within a Workspace, there are several stages they must go through before being made publicly available:
- Outputs on the Level 4 server. These are outputs marked as
project.yamlfile and are only viewable when logged into the Level 4 server. These outputs have to be reviewed by our output checking team before they can leave the server.
- Released outputs. These are analysis outputs that have been reviewed for any disclosivity issues and released from the Level 4 server by the output checking team to the relevant Workspace on the Jobs site. These are only viewable if you have the correct permissions for the Project the Workspace belongs to.
- Draft public outputs. Released outputs can only be shared with close collaborators of your projects (examples of who this could include can be found here). To be shared more widely, they have to first be approved by NHS England. Once approved, and if you have the correct jobs site permissions, you can create draft public outputs for approval.
- Published outputs. Once approved, draft public outputs are made publicly available to view by anyone through the Workspace they belong to.
When users are approved to use the OpenSAFELY platform, each user is assigned roles that define what they are permitted to do on the jobs site within their project. By default, most researchers using the platform will have the
ProjectDeveloper role for a specific Project, which permits them to:
- Create workspaces in that Project
- Run jobs in Project workspaces
- Cancel jobs for this Project
- View job outputs for any Workspace in this Project
- Create draft public outputs for approval
Users with the
ProjectCollaborator role can:
- View released outputs
- View draft public outputs
There are some additional roles linked to the release of outputs from the server, reserved for output checkers:
- Release outputs from Level 4 environments
- Delete outputs in a release
- Publish draft public outputs
Viewing and requesting changes to your permissions🔗
You can view the permissions you have for your project by navigating to the Project page (see arrow below), where can see the permissions for all researchers involved in your project.
If you are not able to do any of the tasks and you think you should, please contact your co-pilot to confirm you have the correct permissions.
Creating a Workspace🔗
- Log in using your GitHub credentials
- Create a Workspace:
- Click the
Create a new workspacebutton (circled in red below).
- Pick a Project from the list.
- Click the
Create a new workspacelink.
- Choose a name, for example the name of the repo.
- Select the repo and branch whose action you want to run (in most cases, the branch will be either
- Click the
Running your code on the server🔗
- Click the
Run Jobsbutton (see red arrow below) from your workspace.
- Select actions to run:
- Select the actions you want to run by clicking the
- If any of these actions have dependent actions (e.g. running a cohort extractor action before an analysis script is run) then they will also be run, unless their outputs already exist.
- If any dependencies have already been set to run, your current job will be queued until dependencies have completed.
- Dependencies can be viewed by clicking the
- You can force dependencies to be run by clicking
Force run dependencies, even if those actions have already been run.
- You can choose to send notifications for the selected actions to your email address.
- When you're ready, click
- Select the actions you want to run by clicking the
The workspace is available at
You can view the progress of these actions by click the
Logs button from the workspace, or going to
https://jobs.opensafely.org/<WORKSPACE_NAME>/logs. If you selected to receive notifications, you will also receive an email to notify you when each job completes.
When you submit a job-request you are competing with other users for resources on the server. As such, jobs can sometimes take a while to start even if their dependencies have successfully completed. You can see all the jobs currently running here and the current status of all OpenSAFELY backends here.
Click here for information on the exact steps that occur when each job is run on the server
- A new, empty temporary directory for the job is created.
- Copy in all files on the selected branch.
- The job is run.
- All the files matching the specified output patterns are copied into the local repo.
- The log files for the job are saved into the
- The temporary directory is deleted.
Each job will either succeed or fail. In either case, the output and log files are only visible in the secure environment to avoid disclosure of potentially sensitive information.
Viewing analysis outputs on the server🔗
You can view
moderately_sensitive outputs from any of your submitted jobs via the Jobs website if you have access to and are logged into the backend the job was run on.
Once you are logged into the server:
- Navigate to https://jobs.opensafely.org/ using google chrome (make sure to use https://)
- Log in using your GitHub username
- Navigate to your Workspace
- Under Releases, navigate to Level 4 Outputs
- Choose the correct backend
- Pick the file you would like to view from the list of files
Viewing released outputs🔗
You can view the various output types from the
Releases section (see red arrow below) of your workspace.
Any files that you would like to be released from the server, have to first be checked by our team of output checkers. You can find instructions for requesting a release here.
Once reviewed, approved and released, your requested files will be available to view from your Workspace in the Released Outputs section of Releases. To view released outputs, you need to have the ProjectDeveloper or ProjectCollaborator role. If you would like to add a project collaborator to your Workspace, please read this section of the researcher policy and/or contact your co-pilot (if you have one).
You must seek NHS England approval for any publication or wider sharing of results, papers, presentations (e.g. submitting to a journal or a pre-print server, or uploading to any public facing website).
For instructions on how to request approval, please see this section of the researcher policy document. Following approval from NHSE, you should also create draft public outputs for review. To do this, navigate to the release containing the outputs you would like to be published and click the
As part of publishing your outputs, you should also make the repository where your analysis code is written public. You can find instructions on how to do that here.
Once approved, your released outputs will be “published” and viewable from the published outputs in the
Published outputs section of your
Releases. This is accessible by everyone, even those without a login.
Updating project status🔗
When you start a new project on OpenSAFELY it will have the Ongoing status, but as your work progresses you'll want to update this status.
If you are a member of a project you will see an
Edit button near the top of your project page:
Select your project status using the options in the dropdown box.
Further details should be provided in the
Status description field. Guidance for each status type is provided below.
Postponed: provide the reasons why the project has been postponed. You must also contact our IG team to let them know.
Retired: provide the reasons why the project has been retired and provide a brief report summarising any results. You must also contact our IG team to let them know.
Ongoing - paper/report linked: provide URLs to published papers or reports (this includes preprints). If further papers/reports are expected, please give details.
Completed - paper/reports linked: provide URLs to published papers or reports (this includes preprints). If further papers/reports are expected, please give details.
Completed - awaiting paper/reports: provide some indication of when papers and/or reports are expected to be published.