# Handling process variables

When modeling a process, it may be necessary to check the value of a variable (RC variables are the most obvious example) or to access the values of a variable if it is not a simple string but a complex type with methods (e.g. the FileDetail variable type when activating an instance with the NewFile trigger).

Process variables are persistent entities that live within each process instance, identified by a name and a value.

Each time a process instance is started, the variables required to create the contract are activated and assigned their value. Any variables declared in each service task are activated during execution when that particular service task is encountered and executed without error.

The way to get the value of a simple variable is to enclose it in `${variableName}`. If it is a complex variable like the one described in **Process Variable Objects** below, it will contain multiple values that can be accessed with its getter method: e.g. `${file.getRegistryId()}`.

If the value of a variable is to be checked, in the case of an exclusive gateway, the condition must be between brackets: `${variableValue == 0}` or `[${file.getRegistryId() == 12}]`.

{% hint style="warning" %}
All variable names are in the same "bucket" as the entire flow instance.\
So, any service task writing a variable named "RC" will overwrite the previous one having the same name.\
To avoid undesired overwrites, use UNIQUE variable names in the same process model.
{% endhint %}

When **testing a process variable value in a conditional execution**, keep in mind all possible scenarios when implementing the condition. If you design a conditional flow with something like: `${variableValue.equals("go here")}`, you are actually assuming that the variable exists and that it is not null. Any condition should consider first of all that a variable exists, then that it is not null, and then if it has or is not a specific value.\
A statement like this:\
`${execution.getVariable("variableValue") != null && variableValue != null && variableValue.equals("go here")}` will verify that `variableValue` exists, that its value is not null, and that it has a value that matches the `"go here"` string.

## Process Variable Objects

These are variables of type "Object" that can be found in a process instance.\
The user modeling a process won't be able to access a variable value just by its name, that is what happens with non-object variables:

`${myCustomVariable}`

but since those are objects, there are methods providing access to the object's internal desired value:

i.e. `${myCustomVariable.getVariableValue()}`

### FileDetail

FileDetail is a Java Object returned from the New File Event and available as a predefined variable --> `file`.

| Parameter        | Type           | Function to retrieve the result | Description                                                                                                                                                                                 |
| ---------------- | -------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| registryId       | Long           | getRegistryId()                 | The Id Fileset inserted in the Databox (ex: ${file.getRegistryId()})                                                                                                                        |
| clusterName      | String         | getClusterName()                | The Cluster name where the file has been received (ex: ${file.getClusterName()})                                                                                                            |
| virtualPath      | String         | getVirtualPath()                | <p>The Databox (Virtual Path) where the file has been inserted. The format is vfsName:vfsPath (ex: ${file.getVirtualPath()})<br>Sample value:<br>epoLAB-vfs-unsigned:/eMail\_attachment</p> |
| name             | String         | getName()                       | The Original File Name (ex: ${file.getName()})                                                                                                                                              |
| virtualFolder    | String         | getVirtualFolder()              | <p>The Databox Folder where the file has been inserted. The format is vfsPath (ex: ${file.getVirtualPath()})<br>Sample value:<br>/eMail\_attachment</p>                                     |
| virtualFs        | String         | getVirtualFS()                  | <p>The Databox FileSystem name where the file has been inserted. The format is vfsName (ex: ${file.getVirtualFS()})<br>Sample value:<br>epoLAB-vfs-unsigned</p>                             |
| extension        | String         | getExtension()                  | File extension                                                                                                                                                                              |
| nameNoExtension  | String         | getNameNoExtension()            | File name without extension                                                                                                                                                                 |
| absoluteFileName | String         | getAbsoluteFileName()           | The absolute file name of the file (ex: ${file.getAbsoluteFileName()})                                                                                                                      |
| metadata         | String         | getMetadataValue(String key)    | Get a file metadata value by key                                                                                                                                                            |
| metadata         | List \<String> | getMetadatakeys()               | <p>Get file metadata values (list of values)<br><strong>NOTE</strong>: available only when the ${file} variable is created by an Incoming Update Metadata Event.</p>                        |

### ExternalFile

ExternalFile is a Java object returned by service tasks of the following types: Spls, DataboxSpls, RemoteSpls, and VirtualBox LS. Each service task returns a variable --> `fileList` that is a `List`. In the following examples, we assume that the current element of the list is referenced as --> `currentFile`.

| Parameter           | Type    | Function to retrieve the result | Description                                                                                                                                                       |
| ------------------- | ------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| fileId              | Long    | getFileId()                     | The Id Fileset inserted in the Databox (ex: ${currentFile.getFileId()}). This is available only from DataboxSpls that lists files in a Databox, otherwise is NULL |
| size                | Long    | getSize()                       | The size file attribute provided by the subsystem that created this entry                                                                                         |
| dateModified        | Date    | getDatemodified()               | The date of the last file modification                                                                                                                            |
| directory           | Boolean | getDirectory()                  | If true the file is a Directory (ex: ${currentFile.getDirectory()})                                                                                               |
| filePath            | String  | getFilePath()                   | The full path of the file (ex: ${currentFile .getFilePath()})                                                                                                     |
| fileName            | String  | getFileName()                   | File Name (ex: ${currentFile.getFileName()})                                                                                                                      |
| fileNameNoExtension | String  | getFileNameNoExtension()        | File Name only without extension (ex: ${currentFile.getFileNameNoExtension()})                                                                                    |
| size                | Long    | getSize()                       | The size of the file (ex: ${currentFile.getFileSize()})                                                                                                           |

### Properties

Properties is a Java Object returned from Command Server service tasks: Spprop. The return variable is --> property and is a Map\<String, String> read from a property file.

| Parameter | Type   | Function to retrieve the result | Description                                                                       |
| --------- | ------ | ------------------------------- | --------------------------------------------------------------------------------- |
| value     | String | getProperty(key)                | Get the value of the property with Key=key (ex: ${property.getProperty("MyKey")}) |

### GBIFlowInput

GBIFlowInput is a Java object that contains all parameters required to start a new GBI Process.

| Parameter     | Type                 | Function to retrieve the result | Description                                                                                              |
| ------------- | -------------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------- |
| flowId        | String               | getFlowId()                     | The GBI Flow Identifier                                                                                  |
| parameters    | Map\<String, String> | getParameters()                 | Map of all Input Parameters required by GBI Flow                                                         |
| correlationId | String               | getCorrelationId()              | System generated correlationId to be used as input in Camunda object that waits for GBI Flow termination |

### GBIFlowOutput

GBIFlowOutput is a Java object that contains all parameters returned from GBI Process.

| Parameter     | Function to retrieve the result | Type                 | Description                                                 |
| ------------- | ------------------------------- | -------------------- | ----------------------------------------------------------- |
| outcome       | getOutcome()                    | String               | The GBI Flow return code                                    |
| parameters    | getParameters()                 | Map\<String, String> | Map of all Output Parameters returned by GBI Flow           |
| correlationId | getCorrelationId()              | String               | System generated correlationId used for process correlation |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.primeur.com/data-mover-1.21/workflow-templates/variables/handling-process-variables.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.