Perforce

Updated October 2026

Describes how Dousen links Perforce changelists to Jira tasks, sets up your workspace, and shows file locks in your DCC. Also covers shelving and the server connection.

DousenDesktop runs p4 on your workstation, under your own Perforce user and workspace, to open and submit each task’s changelist and to restore shelved changes. Desktop asks DousenCore to authorize each operation and reports the result afterward, so Core can keep the changelist keyed to the Jira issue. Desktop and every DCC addon also run local p4 commands for lock status, checkout, sync, and revert.

Work on and submit one task

You need the Perforce command-line client, a signed-in Perforce user, a workspace that maps your source and project files, and a selected Jira task.

  1. In DousenDesktop, select the project and the Jira issue, and check the Perforce connection in the status bar.
  2. If the task has no changelist yet, click Open changelist in the task’s detail pane. Desktop creates a numbered changelist in your workspace with p4 change -i and reports the number to Core. If the task already has an open changelist, Desktop reuses it instead of creating a duplicate.
  3. Sync the submitted source files you need before you edit. To edit an existing file, click Check Out in the DCC panel. A new file is added to Perforce (p4 add) when you create it with Dousen’s new-asset setup, or you can add it in P4V after you save it under a mapped path.
  4. Check the lock status in the DCC panel. If another user has the file locked, coordinate with them instead of publishing over their work.
  5. Save, validate, and publish. Exports from any DCC addon go to the task’s changelist through the live task context. Check the result in Unreal, and make sure the changelist holds the exported files, sidecars, and changed Unreal packages that your project needs.
  6. Click Submit changes. In the Submit Changelist dialog, enter a message of at least 5 characters and click Submit changes. Desktop sets the description, runs p4 submit -c <CL#>, and reports the result to Core.
  7. Check the submitted changelist in Perforce and any Jira transition.
Submit dialog showing a task, changelist 28471, and the submit message field.
The submit dialog. Screenshots on this page use a sample project.

The submit fails if the task’s changelist has no opened files, because Desktop never moves files out of the default changelist. Move the files you want into the task’s numbered changelist in P4V first. A confirmed publish doesn’t mean the changelist was submitted.

Automatic workspace from the depot path

Your admin sets a depot_path for each project, for example //depot/MyGame/.... In the setup wizard’s Workspace step, click Check. Dousen runs p4 client -o, p4 where, and p4 info for that path.

Before it creates the workspace, Dousen runs p4 streams to check whether the depot path is a stream root. If it is, Dousen writes a stream workspace, with a Stream: field in the client spec. Otherwise it writes a classic client spec with a View: mapping. The confirmation names the type: Stream workspace "<name>" created or Classic workspace "<name>" created. If the stream check fails, Dousen shows an error and doesn’t create a workspace. The workspace for a separate source repository uses the same check.

Onboarding doesn’t sync the workspace. The confirmation says "… created. Sync it from P4V or UnrealGameSync before continuing." Run your first sync before you open any DCC.

Streams

Dousen detects streams from the clientStream field of p4 info, so there’s nothing to configure. After you sign in, the DousenDesktop status bar shows one of these:

The Dousen panel in each DCC runs the same check and shows a short version next to your file lock status: Stream: <name> for a stream workspace, or Classic depot otherwise.

File locks inside your DCC

The Dousen panel in Blender, Maya, 3ds Max, Houdini, Substance Painter, and Substance Designer shows live Perforce status from p4 fstat, through P4Python if it’s installed or the p4 command line otherwise. You can check out (p4 edit), revert (p4 revert), sync (p4 sync), and add (p4 add) files under your own Perforce user. Checkout and add use the active Jira task’s changelist, or Perforce’s default changelist if no task is active.

The status refreshes about every 30 seconds. Each file shows one of these lines:

StatusMeaning
Locked by <user> (CL n) Someone else has the file checked out exclusively.
Opened by <user(s)> One or more people have it open without an exclusive lock.
Locked by you You hold the Perforce lock, from an exclusive checkout or p4 lock.
Not at latest (have r<n>, head r<m>) Your local copy is behind the depot.
Available Nobody else has the file open or locked, and your copy is current.
P4 error: <detail> or Not in Perforce Perforce can’t answer, because the server is unreachable or the file isn’t in the depot.
DCC Perforce panel with source-file status, a changelist, and the Check Out, Sync and Reload, Revert, and Refresh buttons.
The Perforce section of the DCC panel.

A publish also stops before it exports if another user has locked a file that the export would write.

Shelving and unshelving

In the My tasks detail pane, Desktop lists the shelved changelists that Dousen opened for the selected task in your workspace, which it recognizes by the Dousen markers in their description. It then enables Restore shelved changes, which runs p4 unshelve -s <CL#> -c <CL#> for a pending changelist. Desktop doesn’t pass -f, so it never overwrites a writable local file.

Restoring shelved changes from DousenDesktop is a preview feature. Plain p4 shelve and p4 unshelve work as usual. Don’t build a team workflow around this feature until it’s generally available.

Jira transition on submit

If your project admin has set up a project-level Jira connection and jira.on_submit_transition, submitting a Dousen changelist moves the linked Jira issue forward, for example to review. The setting takes a transition name, which can differ from the status name. For setup, see Jira tasks.

Server connection (admin)

DousenDesktop runs the Perforce commands under each artist’s own Perforce user, so DousenCore doesn’t need network access to your Perforce server or credentials for it. Core still has its own Perforce connection, set with the environment variables below, for the older server-run routes in the endpoint reference. Those routes serve Desktop builds that predate local changelists, and Desktop setups where none of the Perforce server, user, and workspace is configured.

VariablePurpose
DOUSEN_P4PORTPerforce server address.
DOUSEN_P4USERService user the server acts as.
DOUSEN_P4CLIENTService workspace for the server’s changelist operations.
DOUSEN_P4PASSWD Optional. If unset, Core relies on its environment and the P4 ticket file.

Separate source-art repositories

A project can keep source art in a second Perforce workspace, which can be on a different server, with sparse on-demand sync. Source files and Unreal files then get separate changelists, and the Jira transition waits until every non-empty changelist for the task is submitted. A submit across two servers isn’t atomic, so check both changelists afterward. See Source repositories for the admin binding, onboarding, the FBX location, and recovery after a partial submit.

Changelist descriptions

Dousen keeps the Jira key in each changelist description, and DousenCore stores each changelist under that jira_key.

Opened byDescription while openAfter submit
DousenDesktop The Jira key, then two marker lines: [Dousen:<changelist UUID>], which holds Core’s id for the changelist and not the Perforce number, and [DousenProject:<project id> Task:<JIRA-KEY>] Your message, followed by the same two marker lines
DousenCore (server-run routes, single service workspace) [dousen <JIRA-KEY>] <display name> [dousen <JIRA-KEY>], followed by your message

Dousen uses the markers to find a changelist again, so an Open or Submit that didn’t finish, for example after a lost reply, doesn’t create a duplicate. For changelists that Desktop opened, the markers stay after submit, so the Jira key stays in the depot’s submitted history. A changelist opened through the server-run route keeps its [dousen <JIRA-KEY>] marker in front of your message.

Endpoint reference

These endpoints need a signed-in JWT. Desktop or a DCC panel normally calls them, so the table is mainly for scripting and troubleshooting. Desktop’s local operations use POST /api/vcs/desktop/prepare and POST /api/vcs/desktop/complete. Core records the workspace and result that Desktop reports and doesn’t check them against the Perforce server.

EndpointRequest bodyResponse body
POST /api/vcs/open {"jira_key":"DOU-31","project_id":"<uuid, optional>"} {"changelist_id":"<uuid>","vcs_changelist_id":"<p4 CL#>"}
GET /api/vcs/pending?jira_key=DOU-31 — {"changelist_id":str|null,"vcs_changelist_id":str|null}
POST /api/vcs/submit {"changelist_id":"<uuid>","message":"...","project_id":"<uuid, optional>"} {"submitted_vcs_changelist_id":"<p4 CL#>","files_submitted":<int>}
GET /api/vcs/info — {"is_stream":bool,"stream_name":str|null,"stream_root":str|null,"server_version":str|null,"client_name":str}
GET /api/vcs/shelved?jira_key=DOU-42 — {"shelved":[{"changelist_id","description","user"}]}
POST /api/vcs/unshelve {"changelist_id":"<p4 CL#>"} {"changelist_id":"<p4 CL#>"}