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 attributeDescription
DFIIDDataflow Instance ID. Unique identifier to identify all Data One integration flows
LCIDLog Correlation ID. Unique identifier for a Data One work session
originalclusterDATA ONE STENG cluster name
original_peerDATA ONE STENG peer
original_roleTransfer mode, it can be either "CLIENT" or "SERVER" depending on the role of DATA ONE in the transfer
original_serverThe server name
original_client-connectionWhen role is client, the client connection name
original_protocolTransfer protocol, both for server and role scenarios
original_transferUserTransfer user name, both for server and role scenarios
original_connection-contractWhen role is server, the name of the Connection Contract used to upload the file
original_contractThe name of the Contract, when Data One role is client
original_actionThe name of the Contract Action, when Data One role is client
original_actorThe name of the Actor
original_actor-filenameFile 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-pathRemote path on the Actor's system
original_filenameName of the file
original_sizeSize of the file in bytes
original_corridOptional logical label associated to the file for correlation or identification
original_virtualpathOriginal 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_vfsOriginal 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 AttributeFunction
dfiidDFIC.getDataFlowInstanceId();
lcidDFIC.getLCID();
modelIdDFIC.getDataflowModelId();
modelNameDFIC.getDataflowModelName();
modelVersionDFIC.getDataflowModelVersion();
originalTransferUserDFIC.getOriginalTransferUser();
originalPeerDFIC.getOriginalPeer();
originalProtocolDFIC.getOriginalProtocol();
originalServerDFIC.getOriginalServer();
originalFilenameDFIC.getOriginalFilename();
originalSizeDFIC.getOriginalSize();
originalActorFilenameDFIC.getOriginalActorFilename();
originalClusterDFIC.getOriginalCluster();
originalCorrIdDFIC.getOriginalCorrId();
originalVirtualpathDFIC.getOriginalVirtualpath();
originalVfsDFIC.getOriginalVfs();
originalRoleDFIC.getOriginalRole();
originalActorDFIC.getOriginalActor();
originalClientConnectionDFIC.getOriginalClientConnection();
originalActorPathDFIC.getOriginalActorPath();
originalContractDFIC.getOriginalContract();
originalContractActionDFIC.getOriginalContractAction();
originalConnectionContractDFIC.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")}