How do I use Jenkins Pipeline properties step?

Question

I am studying capabilities of Jenkins Pipeline:Multibranch. It is said that a recently introduced properties step might be useful there, but I can't catch how it works and what is its purpose.

Its hint message doesn't seem to be very clear:

Updates the properties of the job which runs this step. Mainly useful from multibranch workflows, so that Jenkinsfile itself can encode what would otherwise be static job configuration.

So I created a new Pipeline with this as a script (pasted directly into Jenkins not in SCM):

properties [[$class: 'ParametersDefinitionProperty',    parameterDefinitions: [[$class: 'StringParameterDefinition',        defaultValue: '', description: '', name: 'PARAM1']] ]] 

I ran it and nothing happened, job didn't received a new parameter and even if it did I don't get why I might need this. Could anyone please explain?

UPDATE1: I tried putting a dummy Pipeline with properties step into my git repo, then configured a multibranch job.

println 1 properties [[$class: 'ParametersDefinitionProperty', parameterDefinitions: [[$class: 'StringParameterDefinition', defaultValue: 'str1', description: '', name: 'PARAM1']]], [$class: 'RebuildSettings', autoRebuild: false, rebuildDisabled: false]] println 2 

It found my branch, created a job but the build failed with:

groovy.lang.MissingPropertyException: No such property: properties for class: groovy.lang.Binding at groovy.lang.Binding.getVariable(Binding.java:62) at org.jenkinsci.plugins.scriptsecurity.sandbox.groovy.SandboxInterceptor.onGetProperty(SandboxInterceptor.java:185) at org.kohsuke.groovy.sandbox.impl.Checker$4.call(Checker.java:241) at org.kohsuke.groovy.sandbox.impl.Checker.checkedGetProperty(Checker.java:238) at com.cloudbees.groovy.cps.sandbox.SandboxInvoker.getProperty(SandboxInvoker.java:23) at com.cloudbees.groovy.cps.impl.PropertyAccessBlock.rawGet(PropertyAccessBlock.java:17) at WorkflowScript.run(WorkflowScript:2) at ___cps.transform___(Native Method) at com.cloudbees.groovy.cps.impl.PropertyishBlock$ContinuationImpl.get(PropertyishBlock.java:62) at com.cloudbees.groovy.cps.LValueBlock$GetAdapter.receive(LValueBlock.java:30) at com.cloudbees.groovy.cps.impl.PropertyishBlock$ContinuationImpl.fixName(PropertyishBlock.java:54) at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:57) at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43) at java.lang.reflect.Method.invoke(Method.java:601) at com.cloudbees.groovy.cps.impl.ContinuationPtr$ContinuationImpl.receive(ContinuationPtr.java:72) at com.cloudbees.groovy.cps.impl.ConstantBlock.eval(ConstantBlock.java:21) at com.cloudbees.groovy.cps.Next.step(Next.java:58) at com.cloudbees.groovy.cps.Continuable.run0(Continuable.java:154) at org.jenkinsci.plugins.workflow.cps.SandboxContinuable.access$001(SandboxContinuable.java:19) at org.jenkinsci.plugins.workflow.cps.SandboxContinuable$1.call(SandboxContinuable.java:33) at org.jenkinsci.plugins.workflow.cps.SandboxContinuable$1.call(SandboxContinuable.java:30) at org.jenkinsci.plugins.scriptsecurity.sandbox.groovy.GroovySandbox.runInSandbox(GroovySandbox.java:106) at org.jenkinsci.plugins.workflow.cps.SandboxContinuable.run0(SandboxContinuable.java:30) at org.jenkinsci.plugins.workflow.cps.CpsThread.runNextChunk(CpsThread.java:164) at org.jenkinsci.plugins.workflow.cps.CpsThreadGroup.run(CpsThreadGroup.java:277) at org.jenkinsci.plugins.workflow.cps.CpsThreadGroup.access$000(CpsThreadGroup.java:77) at org.jenkinsci.plugins.workflow.cps.CpsThreadGroup$2.call(CpsThreadGroup.java:186) at org.jenkinsci.plugins.workflow.cps.CpsThreadGroup$2.call(CpsThreadGroup.java:184) at org.jenkinsci.plugins.workflow.cps.CpsVmExecutorService$2.call(CpsVmExecutorService.java:47) at java.util.concurrent.FutureTask$Sync.innerRun(FutureTask.java:334) at java.util.concurrent.FutureTask.run(FutureTask.java:166) at hudson.remoting.SingleLaneExecutorService$1.run(SingleLaneExecutorService.java:112) at jenkins.util.ContextResettingExecutorService$1.run(ContextResettingExecutorService.java:28) at java.util.concurrent.Executors$RunnableAdapter.call(Executors.java:471) at java.util.concurrent.FutureTask$Sync.innerRun(FutureTask.java:334) at java.util.concurrent.FutureTask.run(FutureTask.java:166) at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1110) at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:603) at java.lang.Thread.run(Thread.java:722) 

UPDATE2: when I put the same script (as in UPD1) back into Jenkins and runs it, it asked for new permission method groovy.lang.GroovyObject getProperty java.lang.String. I approved it, the build went green, however, still no changes to the job configuration appeared.

My env is: Jenkins 1.625.3, Pipeline+Multibranch 1.13

Answer 1

Using properties with explicit method syntax will work, i.e.:
properties( [ ... ] ) rather than properties [ ... ]

Alternatively, it will work without if you specify the parameter name, e.g.:

properties properties: [ ... ] 

For example defining three properties is as easy as :

properties([   parameters([     string(name: 'submodule', defaultValue: ''),     string(name: 'submodule_branch', defaultValue: ''),     string(name: 'commit_sha', defaultValue: ''),   ]) ])  /* Accessible then with : params.submodule, params.submodule_branch...  */ 

Answer 2

Multiple choice in Jenkins scripted pipeline

properties([   parameters([         choice(choices: 'sprint_6\nsprint_7\nsprint_8\nSprint_9', description: 'Select branch to Build', name: 'Branch'),         choice(choices: 'No\nYes', , name: 'choice2'),         choice(choices: 'No\nYes', name: 'choice3')   ]) ])