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:

1. System attributes: they are set by the system. They can be read and not changed during the life cycle of the dataflow.

2. 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 Mover integration flows
LCID	Log Correlation ID. Unique identifier for a Data Mover work session
originalcluster	Data Mover STENG cluster name
original_peer	Data Mover STENG peer
original_role	Transfer mode, it can be either "CLIENT" or "SERVER" depending on the role of Data Mover 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 Mover role is client
original_action	The name of the Contract Action, when Data Mover 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 Mover 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 Mover where the file first landed, representing the initial point of contact with Data Mover
original_vfs	Original Virtual File System where the file has been stored. This is the Virtual File System in Data Mover where the file first landed, representing the initial point of contact with Data Mover

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")}