P4Groovy advanced scripting


P4Groovy is a Groovy interface to P4Java that allows you to write Perforce commands in the pipeline DSL (Domain Specific Language).


The Pipeline Script Snippet Generator automatically creates a P4Groovy script from a form that is similar to the Freestyle project form. This is good way to learn how to write P4Groovy scripts, see Pipeline Syntax Snippet Generator.



To allow P4Groovy code to be executed clear the Use Groovy Sandbox checkbox on the Pipeline script page.

The setup P4Groovy create a 'p4' object.

For example:

// Define workspace
def ws = [$class: 'StreamWorkspaceImpl', 
charset: 'none', format: 'jenkins-${JOB_NAME}', 
pinHost: false, streamName: '//streams/projAce']

// Create object
def p4 = p4(credential: 'phooey', workspace: ws)

This code can be created for you using the p4: P4 Groovy pipeline syntax snippet generator. Click the Pipeline Syntax link under the Pipeline script to open the Snippet Generator. The Snippet Generator opens in a new tab.

Running a command

The run command takes a comma separated list of Perforce command and then arguments.

For example:

p4.run('changes', '-m5', '//depot/path/...')

The command will return an array of Maps (specifically Map<String, Object>[]).

For example:

def changes = p4.run('changes', '-m5', '//depot/path/...')

You can iterate through the response by iterating through each array item and extracting the keys.

For example:

for(def item : changes) {
        for (String key : item.keySet()) {
		value = item.get(key)
		println ("Key: " + key + " Value: " + value)

Working with forms

To retrieve the contents of a form as a map use fetch providing a spec type and spec id.

For example:

def client = p4.fetch('client', 'my_ws')

To save the contents of a form use save providing the spec type and spec as a Map.

For example:

p4.save('client', client)

For example to update a job description:

def job = p4.fetch('job', 'job000006')
def desc = job.get('Description')
desc = desc + env.BUILD_URL
job.put('Description', desc)
p4.save('job', job)

Adding additional flags to save, e.g. -f (do not add -i as this is already built into save):

p4.save('client', client, '-f')


P4Groovy provides two custom functions:

p4.getUserName()   // Get current User name
p4.getClientName() // Get current workspace/client name

Specify what is deleted from projects that include the P4Groovy cleanup step.


Used to cleanup the client workspace after the build. Optionally, setting the global option will delete the workspace files.


To delete the workspace files after the build, use the global setting in Perforce: OnDelete Workspace Options, see Perforce: OnDelete Workspace Options.

cleanup parameter:

  • true: Perforce cleans up the client workspace including the have list. Optionally, setting the global option will delete the workspace files, see below.
  • false: the client workspace is not deleted. Optionally, setting the global option will delete the workspace files, see below.

Perforce: OnDelete Workspace Options

Specify what is deleted from projects that include a P4Groovy cleanup step or a P4Groovy delete job.

From the Jenkins home page browse to Manage Jenkins > Configure System > Perforce: OnDelete Workspace Options:

You can select a number of options:

  • Delete Perforce client: only applicable when deleting a Jenkins job.
  • Delete Workspace files: if your Jenkins job contains a cleanup step or you are deleting a Jenkins job: Perforce deletes the workspace files including the have list.

Known Limitations

  • It is not possible to run an interactive resolve with P4Groovy. If a custom resolve is required use resolve -n to display the files that need to be resolved and iterate through the results making changes to the files and resolving as necessary.