DataFlow Instance Context (DFIC) 🚀
What is DFIC
The DataFlow Instance Context, or DFIC, is a descriptor associated with the dataflow instance that is created with the dataflow, and is enriched as the dataflow proceeds through its lifecycle along the contract actions of a COA chain.
This section describes the structure and contents of the DFIC, how to read its attributes and how to modify them.
DFIC structure
The DFIC contains two categories of information:
- System attributes: they are set by the system. They can be read and not changed during the life cycle of the dataflow.
- User attributes: they are a dataset that is created empty in the DFIC. They can be enriched by the user inserting data and reading them within the workflow templates used in the contract actions of a COA chain.
System attributes
When a new dataflow instance is created, the DFIC is initialized with only the Dataflow Instance Identifier (DFIID) and Log Correlation ID (LCID) attributes. As the dataflow proceeds through its lifecycle along the contract actions of a COA chain, other system attributes may be set automatically (e.g., file provenance information for pull and upload actions for SFTP, FTP, FTPS, HTTP and HTTPS).
System attribute | Description |
---|---|
DFIID | Dataflow Instance ID. Unique identifier to identify all Data One integration flows |
LCID | Log Correlation ID. Unique identifier for a Data One work session |
originalcluster | DATA ONE STENG cluster name |
original_peer | DATA ONE STENG peer |
original_role | Transfer mode, it can be either "CLIENT" or "SERVER" depending on the role of DATA ONE in the transfer |
original_server | The server name |
original_client-connection | When role is client, the client connection name |
original_protocol | Transfer protocol, both for server and role scenarios |
original_transferUser | Transfer user name, both for server and role scenarios |
original_connection-contract | When role is server, the name of the Connection Contract used to upload the file |
original_contract | The name of the Contract, when Data One role is client |
original_action | The name of the Contract Action, when Data One role is client |
original_actor | The name of the Actor |
original_actor-filename | File name on the Actor's system this is the name of the file in the source system; it might differ from the original_filename. For example, when pulling a file "foo" from an SFTP server of an Actor and writing it into Data One with a different name "bar" |
original_actor-path | Remote path on the Actor's system |
original_filename | Name of the file |
original_size | Size of the file in bytes |
original_corrid | Optional logical label associated to the file for correlation or identification |
original_virtualpath | Original Virtual Path where the file has been stored. This is the Virtual Path in Data One where the file first landed, representing the initial point of contact with Data One |
original_vfs | Original Virtual File System where the file has been stored. This is the Virtual File System in Data One where the file first landed, representing the initial point of contact with Data One |
System attributes are preserved with the republish action.
User attributes
DFIC user attributes are contained in the usrAttrs attribute, which internally has a name/value pairs structure.
By default there are no user attributes, and it is up to the user to set them, and subsequently read them, from within a workflow template underpinning a contract action in a COA chain, when required.
Since the DFIC lifecycle corresponds to the associated dataflow lifecycle, setting one or more user attributes in a contract and reading them in another contract executed later for the same dataflow, is an effective way of passing parameters between different contracts of the same COA chain.
For more information on how to read and write user attributes, please refer to the following chapter.
How to use DFIC
DFIC information can be read, and new attributes (user attributes) can be written in Mediation workflows.
User attributes are user-defined attributes that enrich the DFIC and are contained in a structure that enables users to write and read custom attributes.
Both user-defined and system attributes can be used within workflows to create logic for decision-making automations applicable to specific situations.
Get and Set actions are listed below.
Reading System Attributes
To read a system attribute, a specific function must be invoked:
System Attribute | Function |
---|---|
dfiid | DFIC.getDataFlowInstanceId(); |
lcid | DFIC.getLCID(); |
modelId | DFIC.getDataflowModelId(); |
modelName | DFIC.getDataflowModelName(); |
modelVersion | DFIC.getDataflowModelVersion(); |
originalTransferUser | DFIC.getOriginalTransferUser(); |
originalPeer | DFIC.getOriginalPeer(); |
originalProtocol | DFIC.getOriginalProtocol(); |
originalServer | DFIC.getOriginalServer(); |
originalFilename | DFIC.getOriginalFilename(); |
originalSize | DFIC.getOriginalSize(); |
originalActorFilename | DFIC.getOriginalActorFilename(); |
originalCluster | DFIC.getOriginalCluster(); |
originalCorrId | DFIC.getOriginalCorrId(); |
originalVirtualpath | DFIC.getOriginalVirtualpath(); |
originalVfs | DFIC.getOriginalVfs(); |
originalRole | DFIC.getOriginalRole(); |
originalActor | DFIC.getOriginalActor(); |
originalClientConnection | DFIC.getOriginalClientConnection(); |
originalActorPath | DFIC.getOriginalActorPath(); |
originalContract | DFIC.getOriginalContract(); |
originalContractAction | DFIC.getOriginalContractAction(); |
originalConnectionContract | DFIC.getOriginalConnectionContract(); |
Reading and Writing User Attributes
In order to create a new user attribute or update an existing user attribute you must set a workflow variable with the prefix "DFIC_userAttrs_"
using this workflow script task function:
execution.setVariable("DFIC_userAttrs_<user_attribute_name>", "<user_attribute_value>");
Please notice that user attributes can only have a String data type.
Conversely, when you need to read a previously set user attribute, you must use this script task function:
${DFIC.getUserAttr("<user_attribute_name")}
Example
Let's suppose that you need to logically tag a dataflow with its owner department, early in the COA chain, and use this logical tag later in the chain.
This is how you would initially establish a dataflow_owner_department
user attribute and set it to "ACCOUNTING"
execution.setVariable("DFIC_userAttrs_dataflow_owner_department", "ACCOUNTING");
and this is how you would retrieve its value when required:
${DFIC.getUserAttr("dataflow_owner_department")}
Updated 6 months ago