Document Properties are additional information or "meta data" about an individual document as it executes through a Process. The values contained in properties are separate from the document's actual data contents. These properties remain with a given document as it progresses through the various Process steps, even as the document data itself is manipulated through Map steps or outbound Connector calls.
There are two types of Document Properties: "Standard" Document Properties and User Defined Document Properties. Standard Document Properties contain runtime specific information such as Connector or Trading Partner details. User Defined Document Properties are arbitrary values that you can use to temporarily store related values.
In this article:
Accessing Document Properties
Document Properties can be retrieved via:
Document Properties can be set via:
"Standard" Document Properties
Standard Document Properties contain runtime-related information related to a document. Some properties are set and maintained automatically by the runtime engine and cannot be modified, such as inbound Connector information like original source file name or Connector Application Response Code. Other properties can be set by the Process developer to specify things such as outbound Connector information like destination file name or remote directory.
The different Standard Document Properties are organized into several categories:
Review the different types of Standard Document Properties then read about a few common specific examples below.
Application Connectors
Some Application Connectors have properties that can be retrieved and set during processing. These includes things like Disk File name, FTP Remote Directory, Mail Subject, etc. These properties are displayed in the Process Reporting view at the document-level.
Note: Not all Connectors have properties that can be retrieved or set.
When setting an Application Connector property, you are setting it for the outbound Connector to which the document will eventually be sent. A very common scenario is specifying the file name before writing to a disk or FTP directory. This is accomplished with a Set Properties step to set the appropriate Application Connector property. To illustrate the concept: If you are sending to a Disk Connector, you would set the Disk File Name; if you are sending to an FTP Connector, you would set the FTP File Name; if you are sending the same document to both Connectors, you would set both properties. See Set Properties for more information.
When retrieving an Application Connector property, the value is always that from the original inbound Connector used in the Start step. For example, suppose a Process retrieved a file from an FTP server. If you used a Set Properties step to set the FTP File Name to some value, and then referenced the FTP File Name property in a subsequent step, the value returned would be that from the original FTP Connection in the Start step, not the value you specified in the Set Properties step.
Trading Partner Connectors
Trading Partner Connector properties represent various values related to a document framework such as X12 EDI including sender/receiver ID, ISA control number, etc. These properties are set automatically by the Trading Partner components configured in the Start step.
The Trading Partner Connector properties are primarily used for retrieving only. For example, if you have a Process that receives documents from multiple Trading Partners, you could inspect the "Sender ID" property to route or map individual documents accordingly.
Although you can technically set outbound Trading Partner Connector property values, you should use a Trading Partner step instead to take advantage of the reusable configuration and acknowledgment handling.
Meta Information
Several kinds of Process steps set Document Properties with the results of their execution. These properties are found under the "Base" category and are read only. They will only be populated after the document has successfully passed through the given step.
| Property |
Description |
| Application Status Code |
Set by an outbound Connector step. Contains the status code returned from the underlying application. Eliminates the need to reference a "response" Profile to retrieve the status code for determining success/failure and logging. This is most relevant when the Send Operation is configured to "Return Application Error Responses". Often this value will simply be blank if the call was successful. |
| Application Status Message |
Set by an outbound Connector step. Contains the status message returned from the underlying application. Eliminates the need to reference a "response" Profile to retrieve the status message for logging. This is most relevant when the Send Operation is configured to "Return Application Error Responses". |
| Cleanse Result Message |
Validation message set by the Cleanse step. Useful in constructing alerts or messages for end users. |
User Defined Document Properties
User Defined Document Properties are properties that the Process developer can define and use to temporarily store additional pieces of information about a given document. They are essential arbitrary name/value pairs that follow the document through its execution, through Map transformations and outbound Connector calls. These properties are highly flexible and can be used to improve performance, robustness, and sophistication of your Processes.
There are several general use cases where User Defined Document Properties are commonly used. See the Examples section below for more details.
- Maintain source record context - This is the most common use case, enabling better logging/error reporting and facilitating "write backs" to the source application for synchronization scenarios.
- Augment current document data - A variation of the previous scenario, you can capture values that are not defined in the current document data or Profile. These values can be used for routing, decisions, logging, etc. The use of Document Properties to capture additional temporary values not contained in the source data is a simpler approach than having to map the document to an intermediate proprietary Profile format.
- Abstract data from Profiles - Pass documents with different data formats (i.e. different Profiles) through the same series of steps or sub-Process. By setting and referencing a property, you can avoid replicating the same Process step configuration for each Profile format encountered.
Read about some common specific examples below.
Considerations
- Once set, the properties remain with the document as it moves through subsequent steps in the Process. However the properties will not be available on "sibling" paths. For example, if a Document Property is set before a Branch step that has two paths, the prop will be available down both path 1 and 2. However if the property is set somewhere along path 1, it will not be available when the document eventually goes down path 2.
- Document Properties will remain with the document through Process Call steps with "Passthrough" sub-Processes as well as Return Documents steps.
- A Document Property value cannot be modified iteratively within a given Map step execution. When retrieving a Document Property in a Map, the value will always be that of the document that entered the Map step. For example, you could not use a Document Property to maintain a document-level "counter" to summarize or aggregate multiple detail level elements within the document. The result would simply be that of the last value and would not reflect any intermediate changes. To accomplish this sort of functionality, use the Sum or Line Item Increment Functions or Process Properties instead.
Additional considerations for User Defined Document Properties
- 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 User Defined Document Properties you can set.
Examples
"Standard" Document Property Examples
The following examples describe several scenarios in which Standard Document Properties are commonly used.
Setting an Outbound File Name
To set an outbound File Name:
- Use a Set Properties step
- Add a "Property to Set" on the left and select Document Property >> Application Connectors >> Connector Type (e.g. Disk or FTP, whatever you are writing to) >> File Name.
- Add one or more Parameters to create a simple (Static value) or complex (mix of Static and dynamic Parameters).
- Connect the Set Properties step to the Connector step.
Maintaining the inbound file name
To maintain the file name from the inbound Connector, follow the steps above and for the single Parameter, simply choose the appropriate Document Property/Application Connector File Name for the Connector used in the Start step.
Using the Application Status Code and Message
A number of application Connectors set the special Application Status Code and Application Status Message properties for "Send" Operations as a convenience to the Process developer that chooses to handle Connector responses manually. This save you from having to reference and understand the response Profile (some Connectors do not even generate a response Profile component).
These properties are typically used like this:
- Configure the "Send" Operation to "Return Application Error Responses".
- After the Connector step, add a Decision step to determine whether the response was successful (assume "true" path) or not.
- Configure the Decision step to compare the Application Status Code Document Property to some value. This is often simply blank if successful, but does vary by Connector.
- Down the "false" path (represents errored documents in this example), add a Notify or Exception step.
- Configure a formatted message, referencing the Application Status Message and Code as replacement parameters.
Not all types of Connectors set these properties.
User Defined Document Property Examples
The following examples describe several scenarios in which User Defined Document Properties are commonly used.
Checking for Record Existence
A common integration scenario is the need to check if a given record exists in the destination application to determine whether to perform a Create or Update call. Furthermore, many applications require you to pass their internal system ID when performing updates. The best way to approach this is to:
- Use a Set Properties step to perform a Connector call that attempts to retrieve the internal ID for the given record and store the result as a User Defined Document Property.
- Then use a Decision step to check if that property is populated (e.g. Document Property "not equal to" Static value of <blank>) and direct to the Create or Update Map and Connector steps appropriately.
- In the Update Map, use a Map Function to retrieve the internal ID value and map it accordingly.
This approach avoids the need to perform a second Connector call in the Update Map to retrieve the internal ID again.
Upserts greatly simplify things. If the destination application supports an "upsert" call, you can avoid the whole lookup and decision step and simply map to the single upsert request with some external identifier.
Maintaining Source Record Context
By capturing the record-identifying values of source record such as internal ID and/or name, you can easily reference these values later after an outbound Connector call, for example. In most cases, the response returned from the destination will not contain much or any of the data values you sent in the request. Having values like the original record's ID and name available after the Connector call are necessary to do things like:
- Generate a meaningful, contextualized error message or notification (e.g. "Error syncing record 'Order 123'").
- Perform an update to the original system to change a status flag or to write the new ID from the destination application to assist with subsequent syncs.
Abstracting Profiles
Suppose you want to have a common series of steps that handles a special logging or error reporting routine that need to performed in multiple Processes. It would probably make sense to encapsulate those steps in a common child Process that could be called from each parent Process. However the problem is that the data from each Process will probably be in a different format and would need to be accessed via a different Profile. This would mean the "common" steps would actually need to be replicated for each Profile. However by configuring the common steps to reference one or more User Defined Document Properties instead of Profile elements, they could safely be used across the various parent Processes. Each parent Process would need to set those properties before passing the documents to the child Process.
Setting Flags for Validation, Routing
To perform very complex validation or routing logic, it can often make sense to configure them in a User Defined Map Function instead of a tangled web of Decision, Route, Connector, and other steps. The steps in the function can perform Connector lookups and scripting to determine the fate of a given document. The end result of the logic can set some value (e.g. "VALID"/"INVALID" or "CREATE"/"UPDATE"/"SKIP"/"WARN") as a User Defined Document Property that can be evaluated after the Map step by a Decision or Route step to process the document accordingly.
See also:
This page
Other pages
Account
