Events

Version 26.1.9516

Pre-Job Event
- Creating Environment Variables
- Using Environment Variables in the REPLICATE Query
Post-Job Event
- Triggering a Job Execution
- Extending the Example Scripts
More Information

Events

Often, users need to integrate external information into data flow tasks. CData Sync offers both pre-job and post-job events to enable such scenarios. These events enable you to inject query parameters or to trigger other external processes by using APIScript, an XML-based language that is included with the Sync application.

Complete code snippets for automating common actions, such as running a batch file, sending an email, or triggering a new job execution are included with Sync. On the Events tab for your job, click Insert Snippet and select the action you want to perform. The necessary code is inserted at the cursor.

Pre-Job Event

The pre-job event initiates before the job begins executing queries. The specifics about the job (including the name of the job, the source, the destination, and so on) are available as input parameters that you can use to make logical choices within the event script. You can also push attribute values in the output item that can be used later during the execution of the job.

<api:info title="Before Run" desc="This event is fired before running a job.">
  <input name="JobName"      required="true" desc="The name of the job being executed." />
  <input name="Source"       required="true" desc="The name of source connection." />
  <input name="Destination"  required="true" desc="The name of destination connection." />
  <input name="JobStatus"    required="true" desc="The previous job status." />
  <output name="env:*"                       desc="A variable to be used later in the Job" />
  <output name="CancelJob"                   desc="Set to true if you want cancel job execution." />
</api:info>

Creating Environment Variables

You can create environment variables in the pre-job event script and add them to the job execution. The following example creates a currentTimeStamp variable with the current timestamp and pushes the out item with that value to the job:

<api:set attr="out.env:currenttimestamp"  value="[null | now()]" />
<api:push item="out" />

Using Environment Variables in the REPLICATE Query

You can use environment variables that are pushed to the job in different ways within the REPLICATE query. To reference an environment variable, surround the env:attribute with curly braces ({}). The following example sets the value of currenttimestamp to the new column DateUpdated:

REPLICATE [Table] SELECT [ID], [Name], '{env:currenttimestamp}' AS [DateUpdated] FROM [Table]

Post-Job Event

The post-job event initiates after the job finishes executing queries. The input item includes the results of the job execution, which you can use to call other operations.

<api:info title="After Run" desc="This event is fired after running a job.">
  <input name="JobName"              required="true" desc="The name of the job that is executed." />
  <input name="Source"               required="true" desc="The name of source connection." />
  <input name="Destination"          required="true" desc="The name of destination connection." />
  <input name="JobStatus"            required="true" desc="The status of the completed run." />
  <input name="RunStartDate"         required="true" desc="The start date for job execution." />
  <input name="AffectedRows"         required="true" desc="The number of rows affected by the execution." />
  <input name="Details"              required="true" desc="The details of the job execution." />
  <input name="FailedQueries"        required="true" desc="The list of failed queries." />
  <input name="FailedQueriesCount"   required="true" desc="The count for failed queries." />
  <input name="SuccessQueries"       required="true" desc="The list of successful queries." />
  <input name="SuccessQueriesCount"  required="true" desc="The count for successful queries." />
  <input name="FailedTables"         required="true" desc="The list of failed tables." />
  <input name="RunTime"              required="true" desc="The previous job run time." />
  <input name="Query#"               required="true" desc="An array that contains each query that is executed." />
  <input name="QueryStatus#"         required="true" desc="An array that contains the status of each query that is executed." />
</api:info>

Triggering a Job Execution

You can configure a post-job event to trigger the execution of another job. For example, the following code snippet executes Job2 after the current job finishes running queries. You can also extend this example by using the api:if keyword to execute Job2 only if the current job succeeds.

<!-- Start Executing different Job -->
<api:set attr="job.JobName"        value="Job2"/>
<api:set attr="job.WorkspaceId"    value="default"/>
<api:set attr="job.ExecutionType"  value="Run"/>
<api:set attr="job.WaitForResults" value="true"/> <!--Setting value=true causes the processing to wait for the job to complete. -->
<api:call op="api.rsc/executeJob" httpmethod="post" authtoken="<YourAPIToken>" in="job"/>

Note: In this example, the job.WorkspaceId attribute identifies the workspace that contains the target job. When you want to trigger a job within the same workspace, set this attribute to default or specify the workspace’s name. When you want to trigger a job in another workspace, provide the name of that workspace. The Insert Snippet option in the Event editor includes the job.WorkspaceId attribute automatically with the value set to default.

This attribute is required in these cases:

The workspace for both jobs is the same workspace but is not the default workspace.
The initiating job and the target job belong to different workspaces.

If you omit this attribute in such cases, the API call can fail. When a failure occurs, Sync does not display an error message during the save operation or when the job runs. The job status appears as successful, even though the post-job event did not execute as expected. However, an error is recorded in the application logs. To verify whether a post-job event actually succeeded, review the logs after your job runs.

Extending the Example Scripts

The code snippets in this section are just a few examples of what is possible by using APIScript. The APIScript language is computationally complete, enabling it to manage complex business logic.

You can use other APIScript keywords to control execution flow and more. The script includes many enhancements and built-in operations that make processing and automation easy. For example, APIScript facilitates tasks such as sending an email, moving a file, and so on.

You can also pass additional input values that are specific to the operation.

Examples

The appSendEmail operation accepts several additional input items (such as body text, attachments, and SSL/TLS properties). You provide these items by using the api:set keyword.
You can call any of the built-in operations in an event and also make calls to the API by using the api:call keyword.

More Information

See Introduction to APIScript for more information about the APIScript syntax and capabilities.