Triggering a Flow with a Control File

A flow can run automatically when a control file is detected in a monitored directory. This feature is useful in situations where the flow needs another process to complete before running. For example, you may have a flow that needs an input file generated by another business process. You can set up the other process to place a control file into a folder, and configure Spectrum Technology Platform to run a flow when that control file appears.

Note: Be sure that the control file is placed in the monitored folder only after all files required by the flow are in place and ready for processing.

If you have not already done so, expose the flow.

You can expose a flow by opening it in Spectrum Enterprise Designer and selecting File > Expose/Unexpose and Save.
Open Spectrum Management Console.
Go to Flows > Schedules.
Click the Add button .
In the Name field, enter the name you want to give to this schedule. This is the name that will be displayed in the schedules listing.
In the Flow field, enter the job or process flow that you want to run. Only jobs and process flows that are saved and exposed are available here.
After you specify a flow, additional fields appear below the Flow field, one field for each of the flow's source stages (such as Read from File) and sink stages (such as Write to File).
These fields show the files that will be used when the flow runs by this schedule. By default, the flow will use the files specified in the flow's sources and sinks. You can specify different files to use when this schedule runs by replacing the file path with the path to another file. For example, if your flow has a Read from File stage that reads data from C:\FlowInput\Customers.csv but you want to use data from C:\FlowInput\UpdatedCustomers.csv when this schedule runs, you would specify C:\FlowInput\UpdatedCustomers.csv in the Read from File field.

Note: In order change the files used in the source and sink stages you must have Read permission for the Resources - File Servers secured entity type.

Note that when a flow is triggered by a schedule the files used by a flow must reside on the Spectrum Technology Platform server or on a file server defined as an external resource in Spectrum Management Console. This applies both to jobs as well as job activities within a process flow. If a source or sink stage references a file on a client computer to modify the dataflow or override the dataflow file location.

Option 1: Move the file to the Spectrum Technology Platform server or file server then modify the dataflow:
1. Open the dataflow in Spectrum Enterprise Designer.
2. Double-click the source or sink stage.
3. In the File name field, click the browse button.
4. Click Remote Machine then select the file you want.
  Note: If you are running Spectrum Enterprise Designer on the same machine as the Spectrum Technology Platform server, it will appear that clicking Remote Machine is no different than clicking My Computer. However, you must select the file using Remote Machine in order for the system to recognize the file as being on the Spectrum Technology Platform server.
Option 2: Override the dataflow file location when this schedule runs.
You can override the file references contained in the flow when this schedule runs. To do this, replace the default file shown in each source and sink field with a path to a file on the Spectrum Technology Platform server or a file server resource defined in Spectrum Management Console.
In the Trigger field, choose Control File.
In the Control file field, specify the full path and name of the control file that will trigger the flow. You can specify an exact file name or you can use the asterisk (*) as a wild card. For example, *.trg would trigger the flow when any file with a .trg extension appears in the folder.
The presence of a control file indicates that all files required for the flow are in place and ready to be used in the flow.
The control file can be a blank file. For jobs, the control file can specify overrides to file paths configured in the Write to File or Read from File stages. To use a control file to override the file paths, specify the Read from File or Write from File stage names along with the input or output file as the last arguments like this:
```
stagename=filename
```
For example:
```
Read\ from\ File=file:C:/myfile_input.txt 
Write\ to\ File=file:C:/myfile_output.txt
```
The stage name specified in the control file must match the stage label shown under the stage's icon in the flow. For example, if the input stage is labeled "Read From File" you would specify:
```
Read\ From\ File=file:C:/inputfile.txt
```
If the input stage is labeled "Illinois Customers" you would specify:
```
Illinois\ Customers=file:C:/inputfile.txt
```
When overriding a Read from File or Write to File location be sure to follow these guidelines:
- Start the path with the "file:" protocol. For example, on Windows specify "file:C:/myfile.txt" and on Linux specify "file:/testfiles/myfile.txt".
- The contents of the file must use an ASCII format ISO-8559-1 (Latin-1) compatible character encoding.
- You must use forward slashes in file paths, not backslashes.
- Spaces in stage names need to be escaped with a backslash.
- Stage names are case sensitive.
Note: If there are multiple schedules that use a control file trigger, it is important that they each monitor different control files. Otherwise, the same control file may trigger multiple jobs or process flows causing unexpected behavior. For organizational purposes we recommend putting all required files and the control file in a dedicated directory.
In the Poll interval field, specify how frequently to check for the presence of the control file. For example, if you specify 10, the monitor will look every 10 seconds to see if the control file is in the monitored folder.

The default is 60 seconds.
In the Working folder field, specify a folder where the control file will reside temporarily while the flow runs. Spectrum Technology Platform copies the file from the monitored folder to the working folder before running the flow. This clears out the monitored folder, which prevents the flow from being kicked off again by the same control file.
In the Working folder options field, specify what to do with the files in the working folder when the flow finishes running.

Keep

Leaves the files in their current location with their current name. If you select this option, the files in the working folder will be overwritten each time this schedule runs.

Move to

Moves the files from the working folder to a folder you specify. This allows you to preserve the files that were in the working folder by moving them to another location so that they are not overwritten the next time the file monitor runs. You can also use this option to move the files to another monitored folder to trigger a downstream process, like another flow or some other process.

Rename with time stamp

Adds a time stamp to the file name in the working folder. This allows you to preserve a copy of the files in the working folder since the renamed file will have a unique name and so will not be overwritten the next time the monitor runs a flow.

Delete

Deletes the files from the working folder after the flow finishes running.
If the flow is configured to send email notifications you can specify additional recipients for the notifications that will be sent when this schedule runs. The recipients you specify here will receive notifications in addition to those recipients specified in the flow's notification settings. To configure a flow to send notifications, open the flow in Spectrum Enterprise Designer and go to Edit > Notifications.
Click Save.

Example: Monitored Folder and Working Folder

Let's say you have a car repair shop. Each day you want to mail the previous day's customers a coupon for a discount on future service. To accomplish this, you have a flow that takes the list of customers for the day, ensures the names have the correct casing, and validates the address. The list of customers for the day is generated by another system every evening. This other system generates a file containing the customer list, and you want to use this file as the input to the flow.

The system that generates the customer list puts it in a folder named DailyCustomerReport. It also places a blank trigger file in the folder when it is done. So you configure Spectrum Technology Platform to monitor this folder, specifying the trigger file as:

C:\DailyCustomerReport\*.trg

This tells Spectrum Technology Platform to run the flow whenever any file with a .trg extension appears in this folder. You could also specify a specific file name, but in this example we are using a wild card.

When a .trg file is detected in the DailyCustomerReport folder, Spectrum Technology Platform needs to move it to another folder before running the flow. The file must be moved because otherwise it would be detected again at the next polling interval, and this would result in the flow running again. So the file is moved to a "working folder" where it resides during the execution of the flow. You choose as the working folder C:\SpectrumWorkingFolder.

After the flow is finished processing the customer list, you want the trigger file to be moved to another location where it will trigger another process for billing. So, you select the Move to option and choose a folder named C:\DailyBilling.

So in this example, the trigger file starts off in C:\DailyCustomerReport and is then moved to the working folder C:\SpectrumWorkingFolder. After the flow is done, the trigger file is moved to C:\DailyBilling to initiate the billing process.