Process Properties are name/value pairs or variables that can be used to store arbitrary information to assist with the integration. The properties have "execution scope", meaning once set they remain available for the duration of the current Process execution. This also means the properties are available across other Processes initiated via the Process Call step, as is common in parent/child Process designs. For example, a Process Property set in a parent Process can be retrieved later in a child Process. The opposite is also true: a Process Property set or modified in a child Process can be retrieved later in the parent Process after the child execution completes.
You can also choose to persist a property value and "remember" its value for future Process executions. See Persisting Process Properties below.
Process Properties are a fairly simple but very powerful feature that can be used to facilitate a number of common integration scenarios, described in the Examples section below.
In this article:
Accessing Process Properties
Process Properties can be retrieved via:
Process Properties can be set via:
Considerations
- Be sure to type the property name carefully. You must use the same name when retrieving a value that was used when initially set. It is helpful to establish a naming convention to reduce typos, such as all caps with underscores/dashes for spaces for example.
- Property values are always stored as characters. This is important to note if you plan to store numeric- or date-type values as you may need to cast or reformat when retrieving or mapping them later.
- There is no limit to the number of Process Properties you can set.
Although not technically required or enforced it is a good practice to use globally unique Process Property names across all your Processes, especially if you plan to persist them. This typically simplifies maintenance and reduces the chance of referencing or overwriting the wrong property inadvertently.
Persisting Process Properties
By default Process Property values exist in memory during the Process execution but are no longer available after the execution completes, however it is possible to "remember" a property's value across subsequent executions. This is done by persisting the property value in a Set Properties step by selecting the "Persist this property" option. This stores the value in the Atom and is loaded into memory automatically the next time the given Process is executed.
Persisted properties are often used to maintain continuous "counters" or incremental values such as record dates that can be used in the selection criteria of future executions. See this article
for a detailed example of how to use persisted Process Properties to incrementally extract records based on a last modified date value.
When designing a Process, the point in the work flow at which you choose to persist a property is important and depends on the specific integration scenario. In some situations it is appropriate to persist the value immediately after performing one-time only and/or irreversible steps that should not be repeated even if the Process fails later in the work flow. In other situations it is desirable to persist the value at the very end of the Process to make sure the entire work flow completed successfully. This is common in incremental sync scenarios.
Don't forget to implement duplicate checking as part of your Process work flow to gracefully handle records being reprocessed due to errors.
A few important notes when working with persisted Process Properties:
- The value is persisted immediately upon the document reaching the Set Properties step. It does not wait until the Process completes or completes successfully.
- Persisted properties are loaded into memory automatically during Process execution initialization.
- Changes to the property's value in the Process after the Set Properties step will not update the persisted value.
- Persisted values are captured per Process. For example, you could set and persist a property with the same name in two different Processes without conflict. (However it is typically recommended to use a globally unique naming to facilitate troubleshooting and maintenance).
- Persisted values are captured per Atom/Cloud/Molecule. If the same Process is executed on different Atoms, each will have its own value for the same persisted property. This is especially important to note when using Environments.
- There is currently no way to view or modify the persisted Process Property value through the AtomSphere user interface.
When first developing with persisted Process Properties it helps to work on a local Atom so you can view the actual persisted values. You can find the persisted values in the appropriate ..\<Atom root>\execution\<Process ID>.properties file. The Process ID is the Component ID available in the Revision History link in the Process editor.
Special considerations when working with parent/child Processes: A property is persisted only for Process in which the Set Properties step (with the persist option checked) is used. During the next execution, by default that persisted property/value will be only available in that specific Process. If you wish to make it globally accessible across parent and child Processes again, you will need to explicitly set it again using a Set Properties step. Simply set the property value to itself, without persistence of course.
Extensions
Process Properties can be defined as Process Extensions. This allows you to essentially parametrize different points in the Process during configuration and defer specifying a value to deploy-time. This is most often used in the context of Environments or Widgets to configure environment-specific settings (e.g. "test" vs. "production" flags or other hard-coded values) or preferences.
Examples
The following examples describe several scenarios in which Process Properties are commonly used.
Single Global Value
The simplest use of a Process Property is to generate or capture a single global value so it can be referenced later in the Process. For example, when processing a number of documents you could capture the current timestamp once in a Process Property at the beginning of the Process and then reference it later when setting a file name or generating a "batch number". This enables each document to reference the same value. If the current timestamp was retrieved per document it is possible each document could get a slightly different value if second-, millisecond-, or even minute-precision is required.
Incremental Record Extraction
The most common scenario for using Process Properties is to capture and persist the most recent record date value from the actual records being processed to use as criteria for extracting records during the subsequent execution. Please read this step-by-step tutorial for a detailed explanation.
Summary Values or Flags
You can use Process Properties to capture the results of one part of the Process work flow and then reference them in another part to conditionally execute certain steps.
Suppose you need to import a batch of transactions from a order management system into an accounting system and you want to send a notification when the Process completes with the total amount of dollars imported. The order management system has a web service API that returns a separate XML document for each record so you can't use the basic Sum or Increment Map functions to capture the sum. (Also, the summary values from those standard functions only exist during the Map execution and would not be available later in the Process to use in the notification message.)
To accommodate this requirement, you can use a Process Property to maintain your own sum total. This is typically done with two Branches. When mapping to the accounting system request down path 1, use a User Defined Map Function with a single input for the current order's total amount. The steps inside the function would be: 1) Get Process Property, 2) Math add (taking in the function input and the property value), then 3) Set Process Property with the result of the add step. Then later down path 2 at the end of the Process, use a Notify or Message step to retrieve the property and construct an appropriate message around it.
To take this example one step further, suppose you wanted to send a different notification if there were any import errors. Assuming the accounting system returns a response with some status indicator, you could use a Decision step to check for failures and if found, set a Process Property value (e.g. "HAS_ERRORS" = "true"). Then later at the end of the Process, use another Decision step to check if that property is populated. If populated, you know there was at least one error and can construct an appropriate notification; if not, all the records imported successfully.
Environment Specific Configurations
When using Environments, sometimes there can be environment-specific values that will vary between "test" and "production for example. Instead of hard coding these values in the Process configuration, use Process Properties and define Process Property Extensions whose values will be set at deploy-time. Remember you can reference Process Property values in Map Functions to map an environment-specific default value or as a Parameter value in a Decision step (or a variety of other steps) to perform other steps conditionally, such as additional logging or debugging steps for example.
For Connection component configuration that will vary between Environments (e.g. user name, password, server, etc.) you will use Connection Setting Extensions.
Conditional Processing, One-Time-Only Steps
These scenarios often come into play when designing Processes to be delivered as a Widget. To provide end customers with flexible integration options, you can implement multiple execution paths and use Process Properties and Process Property Extensions to effect client-specific "preferences" that can dictate which steps are actually executed. Similarly, if certain one-time initialization steps or child Processes should only execute once, you can set and persist a Process Property "flag" upon their successful completion. Then for subsequent executions, use a Decision to check if the flag has been set and skip the initialization steps.
See this Widget Tutorial for a step-by-step example.
See also:
This page
Other pages
Account
