Tutorial: Setting Custom TSR/ACK Names and Folders

This tutorial shows you how to set the TSR/ACK names and folders.

Requires IWS version 1.0.1.254 or higher.

On this page

1 Simple CSV to EagleML Data Transformation
2 Alternative Settings
3 Examples of Use

The workflow below was created for this tutorial. It contains objects of several levels.

Simple CSV to EagleML Data Transformation

This is a simple CSV to EagleML data transformation process wrapped into a subprocess envelope to make the workflow tree a bit more complicated for the purposes of this section:

To manage the TSR/ACK names and locations click the Settings tab and click Workflow Settings.

A popup window should appear. Expand the tree to find the process you want to edit and customize the corresponding line of the process.

There are several columns:

1. Workflows & Tasks – illustrates the tree of all existing tasks/subprocesses/processes/workflows. It is built using "parent-child" links.

2. TSR Name Prefix – sets the TSR name prefix for all tasks/subprocesses/processes, for which the workflow in the line is parent.

Here you can customize your TSR reply messages names according to the following model:

CorrelationID_workflow_name_subprocess_name_object_name_20141222_130130.xml

Here is the breakdown of this model:

Black text = CorrelationID (will be set manually in the control message file later)
Red text = the global workflow name (prefix on all TSR message)
Blue text = the sub-process name
Green text = the component name
Light blue text = date and time stamp

For example, the settings:

tsr_ack_rename_demo to root_name
tsr_ack_name_loc_setting_demo_subprocess to sub_name
tsr_ack_translator to obj_nametimestamp
eagle_ml-2-0_default_in_xml_reference to default_name

will rename the TSR reply for the transformation process as follows (date-timestamp may differ):

CorrelationID_root_name_sub_name.xml
CorrelationID_root_name_sub_name_obj_name.xml
CorrelationID_root_name_sub_name_ default_name _20141222_130130.xml

The keyword "timestamp" will be replaced by current date and time (format: yyyymmdd_hhmmss). This keyword can only be used once per a TSR name. If it is set more than once, only the last one set will be processed and the rest will be removed.

renames TSRs for the transform process to:

CorrelationID_root_name_sub_name_ obj_name_20141222_13013.xml

3. ACK Name Prefix - sets ACK name prefix for all tasks/subpocesses/processes, for which this workflow is parent (the logic is absolutely the same as for the TSR Name Prefix).

4. Custom TSR Location – sets a custom TSR files location. E.g.: set "../../../cmw/reply/my_folder/" (relative path) value to put TSRs into the subfolder "my_folder" of the default "reply" folder.

5. Custom ACK Location – sets a custom ACK files location. E.g.: set "../../../cmw/ack/my_folder/" (relative path) value to put ACKs into the subfolder "my_folder" of the default "ack" folder.

The following settings will create a new folder in "../../../cmw/" called "demo" (if it didn't exist before) containing two separate subfolders for TSR and ACK messages:

6. TSR Name Case - sets TSR Name case for the TSR Name Pattern property. This property can be used to support previous versions of TSR Name generating.

7. TSR Name Pattern - sets TSR Name Pattern. There is difference between TSR Prefix and TSR Pattern: if the pattern set, the prefix set will be ignored; TSR Pattern set is only a part of the TSR name.

8. Emails for Notifications - sets the emails, to which Notifications should be sent. Use comma to set more than one email, for example: myemail@rr.ru, myemail2@tt.ru, myemail3@dd.com, etc.

If the TSR/ACK name is too long, it will be cut and the result TSR/ACK name turns into: "corrID_cut_[task_name]timestamp.xml".

To reset the TSR/ACK names and locations to defaults click the Reset & Save button.

After your preferences are set click the Save & Close button and close the Workflow settings popup window.

Save all files:

and Publish your solution:

To execute the newly created process you need to make up a control message and send it into the default eagle_ml-2-0_default_cm_control_message stream or use the Run option of IWS. The control message to launch the example workflow is given below.

Remember to change the workflow name to your own and to set a unique name for the correlationId (both highlighted).

<EagleML
    xmlns="http://www.eagleinvsys.com/2011/EagleML-2-0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:type="RunTaskRequest"
    eaglemlVersion="2-0"
    xsi:schemaLocation="http://www.eagleinvsys.com/2011/EagleML-2-0 eagleml-main-2-0.xsd"
    eaglemlType="RunTaskRequest">
    <header>
        <messageId>TST_TSR_ACK_RENAME</messageId>
        <sentBy>http://www.eagleinvsys.com</sentBy>
        <sendTo>http://www.eagleinvsys.com/eagle_ml-2-0_default_cm_control_message</sendTo>
        <creationTimestamp/>
    </header>
    <taskIdentifier>
        <correlationId>TST_TSR_ACK_RENAME</correlationId>
        <businessTaskId>TST_TSR_ACK_RENAME</businessTaskId>
    </taskIdentifier>
    <workflowState>
        <processCorrelationId correlationIdScheme="correlationIdScheme">TST_TSR_ACK_RENAME</processCorrelationId>
        <originatingCorrelationId correlationIdScheme="correlationIdScheme">TST_TSR_ACK_RENAME</originatingCorrelationId>
    </workflowState>
    <taskTypeEnum>LOAD</taskTypeEnum>
    <taskParameters>
        <taskParameter>
            <name>StreamName</name>
            <dataType>S</dataType>
            <value>eagle_ml-2-0_default_cm_execwkfl</value>
        </taskParameter>
        <taskParameter>
            <name>ActionType</name>
            <dataType>S</dataType>
            <value>EXECUTE</value>
        </taskParameter>
        <taskParameter>
            <name>WorkflowName</name>
            <dataType>S</dataType>
            <value>tsr_ack_rename_demo</value>
        </taskParameter>
    </taskParameters>
</EagleML>

The next step is sending your data file with the file mask matching the data file mask set in your IWS workflow into the default eagle_ml-2-0_default_cm_ndfa stream to let your workflow process it. (For example: demo_data.txt matches demo_data* file mask given on page).

When the process finishes you will find your TSR and ACK files as expected:

Alternative Settings

How to set TSR / ACK custom names via editing the "W_REPLYCM_MODE" parameter

W_REPLYCM_MODE is a special parameter in the include file /eagle_ml-2-0_custom_cm/w_config_custom.inc. It can be set to one of the following values:

N/OFF – eagle_ml-2-0_default_cm_task_reporter stream will use old logic to generate TSR and ACK names (if W_REPLYCM_MODE is not set, then OFF option will be applied).
Y/ON – eagle_ml-2-0_default_cm_task_reporter stream will use new logic to generate TSR and ACK names.
ONonlyForIWS – eagle_ml-2-0_default_cm_task_reporter stream will use the new logic to generate TSR and ACK names only for IWS created workflows.
NOTE: If the TSR /ACK name is too long, it will be cut and the result TSR/ACK name will be: "corrID_cut_[task_name]timestamp.xml".
ONuseExactFileName – excludes the correlationID prefix when you use ACKStrictPattern and TSRStrictPattern parameters to modify the file name.

How to set TSR / ACK custom folders via editing the "W_REPLY_CUSTOM_LOCATIONS_MODE" parameter

W_REPLY_CUSTOM_LOCATIONS_MODE is a special parameter in the include file: /eagle_ml-2-0_custom_cm/w_config_custom.inc. It can be set to one of the following values:

N/OFF – eagle_ml-2-0_default_cm_task_reporter stream will use default folders to save TSR and ACK messages (../cmw/reply and ../cmw/ack).
Y/ON – eagle_ml-2-0_default_cm_task_reporter stream will create a special folder for each workflow (and use its name as a folder name) (Example: ../cmw/reply/testsolution).
ONonlyForIWS – eagle_ml-2-0_default_cm_task_reporter stream will use the new logic to create folders only for IWS created workflows.

Using this option can make your navigation in reply and ack folders much more comfortable.

Examples of Use

Using W_REPLYCM_MODE

The goal of the tests was to check eagle_ml-2-0_default_cm_task_reporter stream usability with different values of the W_REPLYCM_MODE and W_REPLY_CUSTOM_LOCATIONS_MODE parameters assigned. The 3 options for the parameter were described in the previous paragraph and can be set in w_config_custom.inc.

Workflow used: tsr_ack_name_loc_setting_demo.
Its solution was created via IWS. The following messages names were set:

W_REPLYCM_MODE – N/OFF

Testing W_REPLYCM_MODE "N" or OFF" in w_config_custom.inc:

Related content of the default /../../cmw/reply folder:

Related content of the default /../../cmw/ack folder:

W_REPLYCM_MODE – Y/ON

Testing W_REPLYCM_MODE "Y" or "ON" in w_config_custom.inc:

Related content of the default /../../cmw/reply folder:

Related content of the default /../../cmw/ack folder:

Messages are located in default folders and their names have been generated according to the required model:

CorrelationID_WorkflowName_ParentName_TaskName_yyyymmdd_hhmmss.xml

W_REPLYCM_MODE – ONonlyForIWS

This parameter should be used if customized settings are to be applied only to solutions created via IWS. There is no difference between ON and ONonlyForIWS flagged for solutions created via IWS.

Using W_REPLY_CUSTOM_LOCATIONS_MODE

W_REPLY_CUSTOM_LOCATIONS_MODE is a variable located in w_config_custom.inc. It can be set to:

Y/ON – TSR messages will be saved in ../cmw/reply/workflowname and ACK messages in ../cmw/ack/workflowname. Using this feature will make your navigating in reply - ack folders easier.
N/OFF – TSR and ACK use default folders as their location.
ONonlyForIWS – Only IWS created solutions will use custom folders as their location.

As a result of the test with this parameter set to "Y" or "ON" subfolders, named tsr_ack_name_loc_setting_demo (matches the workflow name) in ../cmw/reply/ and ../cmw/ack/ have been created. The TSR and ACK files have been saved inside.

Note

CustomReplyLocation and CustomAckLocation parameters override this parameter.

Reference tables

	In the config file:	As a setting in IWS
	/eagle_ml-2-0_custom_cm/w_config_custom.inc
Parameter name	W_REPLYCM_MODE
Possible values	N/OFF - TSR and ASK messages are named by default. Y/ON - TSR and ASK messages are named as defined in the IWS solution. ONonlyForIWS - If the solution was created via IWS, TSR and ASK messages are named as defined in the solution. If not - default names are assigned. ONuseExactFileName - excludes correlationID prefix from the file name when you use ACKStrictPattern and TSRStrictPattern parameters to modify it.	To reset the settings to default, click the Reset&Save button in the bottom of the settings window.
		To define specific names, fill the corresponding boxes.

Example of use	<COL TAG="W_REPLYCM_MODE" EXPRESSION="Y"/>
Default value	N	all fields clear or default file names set

	In the config file:	As a setting in IWS
	/eagle_ml-2-0_custom_cm/w_config_custom.inc
Parameter name	W_REPLY_CUSTOM_LOCATIONS_MODE
Possible values	N/OFF - TSR and ACK files are saved in the default ../cmw/reply and ../cmw/ack folders	To reset settings to default manually clear the boxes.
	Y/ON - TSR and ACK files are saved in the ../cmw/reply/%workflowname% and ../cmw/ack/%workflowname% subfolders of the corresponding default folders	Using this feature in IWS allows you to set any folder name to save the TSR/ACK messages, you may prefer to make it differing from the workflow name. You can also specify a non-default folder.
	ONonlyForIWS - If the solution was created via IWS, the TSR/ASK messages are saved in the ../cmw/reply/%workflowname% and ../cmw/ack/%workflowname% subfolders in the corresponding default folders. If not - default folders are used (no subfolders are created).
Example of use	<COL TAG="W_REPLY_CUSTOM_LOCATIONS_MODE" EXPRESSION="Y"/>
Default value	N	All fields clear or ../../../cmw/reply/ and ../../../cmw/ack/ set, respectively.