Adam Arrowsmith

5 Awesome Ways to Use Properties

Blog Post created by Adam Arrowsmith Employee on Aug 1, 2016

You might be familiar with using properties in your processes but these five tips can help you get the most out of them. Defining standards around their usage can help your integration team develop more consistent processes that are easier to build, maintain, and troubleshoot.



Properties: A Refresher

Properties can be Document-level or Process-level. Document-level properties are associated with an individual document and follow it through the remainder of the process path. Process-level properties are essentially global variables that live at the process execution.


They are essentially metadata about a given document or process execution. Some are read-only, some are write-only, others are read/write. Some are set automatically by inbound connector or shared web server, environment extensions, process shape execution. Some are set manually by you as part of process flow. They generally live for the life of a process execution but can some can be persisted across executions.


Here are the types of properties at a glance:


  • Document Properties
    • Connector and Trading Partner Information
      • Inbound (read-only), outbound (write-only)
    • Meta Information
      • Set by certain shapes
      • Read-only


  • Dynamic Document Properties
    • Arbitrary name/value pairs
    • Read/write
  • Process Property component
    • Pre-configured component
    • Defined data types
    • Read/write


  • Dynamic Process Property
    • Arbitrary name/value pairs
    • Name can be dynamically-specified
    • Read/write



To help illustrate the tips below, we'll use the following process that incrementally queries NetSuite for new or modified customers and syncs them to Salesforce:



Any failures sending to Salesforce are handled in a common subprocess:



#1 Capture records IDs in consistent document properties

After pulling documents into your process, capture key values like record IDs, names, etc. in dynamic document properties to be able to reference consistently later in your process. These key values may be useful downstream in error notifications, lookups, write-backs, etc. Because the document data may change during mapping or message shapes, the original key values may not be present in the current data so you can't access them via a profile element. Document properties retain these values regardless of what happens to the document data contents.


In this example, the internal ID and name from each NetSuite customer are captured in two document properties, DDP_RECORD_ID and DDP_RECORD_NAME:



While this is a classic use case for dynamic document properties, the key takeaways are:

  1. Determine the values that make sense for your process
  2. Set them consistently across processes
  3. Devise and follow a property naming convention


A few thoughts on naming conventions:

  • Consider generic names to get the most reuse. Notice we used "record ID" not "customer ID" to be applicable regardless of the record type.
  • Consider using all upper case with underscores instead of spaces. This can help avoid typos. Alternatives include CamelCase or using-hyphens. Whatever the exact syntax, the point is to adopt a convention and use it
  • Prefixing the type of dynamic property can be helpful when communicating and documenting. For example, "DDP" for Dynamic Document Property. and "DPP" for Dynamic Process Property.


Additional Considerations

  • If you anticipate needing to reference many fields and/or repeating values from original document, store the entire document in a Document Cache instead and set a single document property with the key/ID value to retrieve from the cache later.
  • When using the branch shape, remember that a document property value set on one branch is NOT available on subsequent branches.


#2 Persist properties across executions

You can persist process property values in one process execution to reference in a subsequent execution. This is a common technique in incremental sync patterns in which you only want to extract records that have been created or modified since the last time the process ran.


The general approach is:

  1. Query record with a filter of last modified date greater than the value the persisted last record date property
  2. Capture the most recent last modified date from the records retrieved
  3. Execute the rest of the process
  4. At the end of the process, persist the most recent last modified date to use in the query filter during the next process execution


This example uses the business rules shape technique to manipulate properties without mapping the data:



Here's the map function used in the business rules shape that does the property comparison to determine the most recent last modified date encountered and store it in the working property:



Here's the script for those curious:


if (propval != "" && propval > thisval) {
result = propval;
} else {
  result = thisval;



And then at the end of the process, the process-specific persisted property is set from the working/runtime property:



#3 Set global process state to reference later

This is a pretty classic use of process properties but a good one to keep in your design toolbox.


In our example, we're handling errors/application failures gracefully (we don't want to fail the entire process) in the first branch but we need to know if there were any problems to determine whether or not the last record date property should be persisted later at the very end of the process. In this case, we set a Process Property "HAS_ERROR" to "TRUE" in the unsuccessful path on branch 1. Then in branch 2, simply use a decision shape to inspect that value and conditionally persist the property.



Set properties shape configuration:



Decision shape configuration:



#4 Use as "parameters" for common subprocesses

Creating common subprocesses for things like error handling, notifications are a great way to make configuration more reusable. However because those subprocesses will be used by any number of processes that will be handling a variety records and therefore profiles, they cannot reference anything process- or profile-specific. To solve this, use dynamic document or process properties to pass runtime parameters generically to the subprocesses.


Our example process uses a common error handling subprocess that needs to dynamically receive the current error message and error "level". To pass this information generically, we set two dynamic document properties "DDP_LOG_EVENT_MESSAGE" and "DDP_LOG_EVENT_LEVEL" in the main process.



Then in the subprocess, the notify shape only references the error message from the dynamic document property (along with the record ID and name we set earlier) to construct the notification event:



#5 Use Process Property components for process-specific settings or global constants


Process-specific Settings

Expanding upon #2 and #4 above, using Process Property components are a convenient way to group the various settings, default values, and/or persisted properties for the given process. Process Property components are also more convenient when using environment extensions.


In our example we use a Process Property component named "NS Customer Sync Config" that contains the persisted Last Record Date as well as several parameters and even an extensible value to be used with the common error subprocess:



In the error subprocess, we've designed the option for some processes to choose to additionally output errors to a custom log file. This is based off the "Write Errors to Log File" value in that process-specific property. However because we can't reference anything process-specific in the common subprocess, we simply "move" those values to generic dynamic process properties in the beginning of the main process:



The subprocess then inspects this Dynamic Process Property value using a decision shape:



Furthermore, certain properties in the process-specific Process Property component can be extensible. For example, the error subprocess writes the custom log to a disk directory. Suppose we want to be able to change that directory location depending on the environment (production vs. test). We can define that property as extensible in the main process:



Global Constants

Another clever use of Process Property components is to define static, constant values to reference consistently throughout your processes. This avoids typos and having to remember the exact syntax of the value.


For example, when we set the HAS_ERROR property in #3 above, the value used came from a Process Property component named "CONST Global Values":



This Process Property contains a number of static values:



However note there is a deployment dependency: if you add or change a property in the component, any process referencing that Process Property component will show as having undeployed changes and will need to be deployed to take effect. For this reason you may want to consider scoping the constants to a subset of processes, perhaps by project or endpoint.


A Few More Helpful Properties Tips

  • For dynamic properties, establish a naming convention and FOLLOW IT!
  • Remember process properties have “execution scope”. They can be read/modified across parent and child processes within the same execution.
  • Be aware that persisting properties happens immediately, not upon successful process completion.
  • Avoid storing the entire document (i.e. Current Data) in properties, especially process properties, to avoid out-of-memory exceptions.
  • Document properties will stay with documents through all shapes with a few exceptions:
    • Combine Documents – Only properties from the first document will survive.
    • Get/Query Connector Shapes – Because they create new documents, properties from the old documents do not survive.
  • Document properties set on one branch path are NOT available on subsequent branch paths (because different "version" of the document).
  • Document properties stay with documents added to a Document Cache.


Understanding how to use properties effectively can take your integration processes to the next level by facilitating re-usability


In what other awesome ways do you use properties?