Document how to use any properties (name:value) defined for a resource

[jeffreyofisher]

Describe your use-case which is not covered by existing documentation.

Except for this bit in the JCasC section:
- name: "Resource-with-properties"
properties:
- name: "Property-A"
value: "Value"

I'm not seeing any documentation on how to use any properties (meaning the "Property-A":"Value" above) associated with a lockable resource. I've been able to define them and see them on the lockable-resources page, but can I do anything else with them?

Can I use them in a lock() statement to affect what resource gets locked?

Once I've used a lock() statement to acquire a resource, can I programmatically access any defined Property:Values for that resource?

Is it possible to programmatically access the definitions for resources defined in Lockable Resources without doing a lock()?

Thanks

Reference any relevant documentation, other materials or issues/pull requests that can be used for inspiration.

https://plugins.jenkins.io/lockable-resources/

Are you interested in contributing to the documentation?

No response

[jeffreyofisher]

Later, I saw this at the documentation link given previously
echo env.LOCKED_RESOURCE0 echo env.LOCKED_RESOURCE0_PROP_ABC

and while the first line works for me, the second line does not, giving a null for the value (My resource property uses different names than the example)

[mPokornyETM]

Closing with documentation — see next comment for full details.

[mPokornyETM]

How resource properties work

Resource properties (name:value pairs) are exposed as environment variables when you use the lock() step with the variable parameter. Without variable, no environment variables are injected.

Environment variable naming pattern

Variable	Value
{variable}	Comma-separated list of all locked resource names
{variable}0	Name of the first locked resource
{variable}0_{PROPERTY_NAME}	Value of that resource's property
{variable}1	Name of the second locked resource
{variable}1_{PROPERTY_NAME}	Value of the second resource's property

Example: Access properties in a pipeline

Assume a resource my-server has properties HOST=192.168.1.10 and PORT=8080:

pipeline {
    agent any
    stages {
        stage('Deploy') {
            options {
                lock(resource: 'my-server', variable: 'LOCKED')
            }
            steps {
                echo "Resource name: ${env.LOCKED0}"
                echo "Host: ${env.LOCKED0_HOST}"
                echo "Port: ${env.LOCKED0_PORT}"
            }
        }
    }
}

Example: Lock by label and read properties

pipeline {
    agent any
    stages {
        stage('Test') {
            options {
                lock(label: 'gpu', quantity: 1, variable: 'GPU_RES')
            }
            steps {
                echo "Got resource: ${env.GPU_RES0}"
                echo "GPU model: ${env.GPU_RES0_MODEL}"
            }
        }
    }
}

Common pitfalls

1. Missing variable parameter — if you don't specify variable, NO env vars are created. This is the most common reason env.LOCKED_RESOURCE0_PROP_ABC returns null.
2. Property name must match exactly — the env var name is {variable}{index}_{propertyName}. If your property is named host (lowercase), the env var is LOCKED0_host, not LOCKED0_HOST.
3. Accessing outside lock block — properties are only available inside the lock() { ... } closure.

Can I use properties in a lock() statement to filter resources?

Not directly via built-in parameters. However, you can use a Groovy resource match script to filter by properties:

lock(extra: [
    [$class: 'LockableResourcesStruct',
     resourceMatchScript: [
         $class: 'SecureGroovyScript',
         script: 'resourceInstance.properties.any { it.name == "ENV" && it.value == "staging" }',
         sandbox: true
     ],
     resourceNumber: '1'
    ]
]) {
    echo "Got a staging resource"
}

Accessing resource info without locking

You can read resource definitions via the REST API:

GET $JENKINS_URL/lockable-resources/api/json?pretty=true

Closing as this is a documentation issue and the feature works as described above. The reporter's issue with env.LOCKED_RESOURCE0_PROP_ABC returning null was most likely caused by not specifying the variable parameter in the lock() step.