Tasks

Products: FastReport Cloud, FastReport Corporate Server, FastReport Publisher

A task is a unit of work in the Service solution. All transformations, whether creating a report from a template, exporting to various formats, or sending a file by email, are tasks.

The following types of tasks exist:

  • transformers;
  • transports.

Task properties

All tasks have the following properties:

  1. Name - the name of the task (for example, "Sending pay stubs to employees");
  2. Locale - the localization to be used when generating the report;
  3. SubscriptionId - the identifier of the workspace in which the task is executed (if not specified, the default workspace for the user running the task will be used);

The remaining properties are unique for each type of task.

Transformers

Transformers are designed to transform source objects into final objects through a transformation function.

There are the following transformers:

  • PrepareTemplateTask - template -> report;
  • ExportTemplateTask - template -> file in the required format (pdf, html);
  • ExportReportTask - report -> file in the required format (pdf, html);
  • adding data structure to the data source (FetchTask) - a data source without a structure -> a data source with a data structure that can be used later in the Designer.

Properties of transformers

In addition to the basic properties of tasks described above, all transformers contain the following properties:

  1. InputFile - information about the template from which the report should be generated, containing the following fields:

    • EntityId - template identifier;

    • Type - file type (in this case, the type should be Template);

    • Content - template content in the form of a byte array (can be passed instead of the identifier);

    • FileName - template name (optional to pass).

  2. OutputFile - information about the report generated by the task (except for fields similar to fields InputFile it also contains a field FolderId the folder where the report should be saved. If not specified, the report will not be saved);

  3. Transports - a list of transport tasks to be called after the report is prepared.

Thus, the result of each transformation task can be sent using transport tasks (by email, webhook).

Please note that the Content field is only available when the task is launched from the body of the request.

If the OutputFile is not specified, it will be saved to a temporary folder (the ID of which matches the ID of the launched task), if an empty OutputFile is specified, it will be saved to the root folder, otherwise, it will be saved to the specified folder.

Prepare Template Task

PrepareTemplateTask transforms a template (.frx file) into a report (.fpx file).

In addition to the general properties of tasks and transformation tasks, it contains the following properties:

  1. PagesCount - the number of pages to be prepared (if not specified, a report with all pages will be generated);

  2. ReportParameters - a dictionary of parameters passed during the report generation;

  3. Exports - a list of exports (ExportReportTask), called after the report is prepared.

As can be seen from the listed properties, the result of the prepare template task, in addition to being sent via transports, can also be further exported (and then saved or sent to the recipient).

Export report task

ExportReportTask converts a report file (.fpx) into a file in the specified format (pdf, html, jpeg, etc.).

In addition to the general properties of tasks and transformers, it contains the following properties:

  1. ExportParameters - export parameters, unique for each export (specified in the FastReport .NET documentation);
  2. Format - export format (pdf, html, svg, and others);
  3. PagesCount - the number of exported pages starting from the first one;

Export template task

ExportTemplateTask converts a template (.frx) into a file in the specified format (pdf, html, jpeg, etc.).

Before the export is performed, the template is converted into a report, inserting the necessary data. Thus, the export template task, in addition to the general properties of tasks, transformers, and the properties of the export template task, contains the ReportParameters, where the parameters for preparing the report are specified.

The task of adding data structure to the data source

This task (FetchTask) adds a structure (tables, their column names, and data types) to the data source, which can then be used further in the Designer or in the user panel.

Transports

Transports are designed to deliver objects generated by transformers to the final recipient, whether a group of users, a data repository, or another program.

The following transport tasks exist:

  • email task (EmailTask);
  • webhook (WebhookTask);
  • ftp (FTPUploadTask)

All transports have the following properties:

  1. Files - list of files to be sent (templates, reports, or exports). The properties of each item match the InputFile properties of transformers);
  2. Type - type of transport task (Email, Webhook, FTPUpload).

Email task

EmailTask allow the results of converter tasks to be delivered to email addresses. It is possible to send templates, reports, and exports to a single recipient or a group.

In addition to the main properties for all transports, it contains the following properties:

  1. Body - email body text;
  2. IsBodyHtml - format the email text as HTML markup;
  3. Subject - email subject;
  4. To - list of email addresses to send to;
  5. From - sender's email address;
  6. Username - email user's username;
  7. Password - email user's password;
  8. Server - email SMTP server address;
  9. Port - server port;
  10. EnableSsl - whether SSL encryption is enabled;

Properties 5-10 are not mandatory to use. By default, the parameters of the "Fast Reports" email server are taken.

FTP upload task

FTPUploadTask allows the results of transformers to be delivered to an FTP server. Templates, reports and exports can be sent.

In addition to the main properties for all transports, it contains the following properties:

  1. FtpHost - FTP server address;
  2. FtpPort - FTP server port;
  3. FtpUsername - FTP server username;
  4. FtpPassword - password;
  5. DestinationFolder - path to the folder on the FTP server where the files will be uploaded;
  6. Archive - archive the file. Accepts values true or false;
  7. ArchiveName - archive name;
  8. UseSFTP - use SFTP (Secure FTP) for the connection. Accepts values true or false;

Webhook

WebhookTask or user callback task allows you to deliver the results of transformers to a third-party server by making an HTTP POST request to the specified address.

WebhookTask in addition to the basic properties common to all transports, contains a property called Endpoints, which is a list of objects containing the following fields:

  1. Url - the address of the server and application that receives the POST request from the Service solution.
  2. BearerToken - the token, if authentication is required.

The data transmitted to the third-party server has the type multipart/form-data, i.e., it is a list of files (templates, reports, or exports). The name of the list passed in the request is files. The receiving party must implement a method that processes the POST request to the specified address, using the received list.

For example, for an ASP.NET WebApi, the function to which the webhook is assigned can look like this:

[HttpPost]
public ActionResult<List<long>> Receiver(IFormFileCollection files)
{
    List<long> fileLengths = new List<long>();
    foreach (var img in files)
    {
        using (MemoryStream ms = new MemoryStream())
        {
            img.OpenReadStream().CopyTo(ms);
            fileLengths.Add(ms.ToArray().Length);
        }
    }
    return Ok(fileLengths);
}

S3 upload task

S3UploadTask allows you to deliver the results of transformers to an S3 storage. It is possible to send templates, reports, and exports.

In addition to the common properties for all transports, it includes the following specific properties:

  1. AccessKey – public access key for the S3 storage;
  2. SecretKey – secret access key for the S3 storage;
  3. BucketName – name of the bucket in the S3 storage;
  4. Url – S3 service endpoint URL;
  5. Region – AWS region where the bucket is located (e.g., us-east-1);
  6. DestinationFolder – path to the folder in the S3 storage where files will be uploaded;
  7. UseAws – whether to use the official AWS S3. Accepts the values ​​true or false. If false, it assumes an S3-compatible service (MinIO, Wasabi, etc.);
  8. EnableSsl – whether to use HTTPS when connecting to S3. Accepts the values ​​true or false;

Properties 4–8 are optional.

Tree Tasks

Tasks can have a hierarchical structure and contain subtasks. For example, a template prepare task may contain the following subtasks:

  1. A list of transport tasks (email, webhook) that send the completed report.
  2. A list of export tasks (ExportReportTask) - export to PDF, HTML.

Export tasks, in turn, can have a list of transports.

Thus, the sequence of the template prepare task may look like this:

The task of converting from a template to a report, after its execution, will call the task of exporting to PDF and the task of exporting to SVG. And they, in turn, will call email or webhook tasks.

Saving and reusing

Tasks can be saved in cloud storage and run on demand or on a schedule. Examples of working with tasks are available in the Guides section.

Scenarios for interacting with tasks

There are 2 modes of operation provided:

  1. Running a task from the request body;
  2. Running a previously saved task.

In the first case, all parameters are defined at the time the task execution request is sent, while in the second case, the task is saved in the cloud storage and called by a unique identifier.

Task scheduler

Task scheduling is done by setting CRON expressions. This way, you can achieve maximum flexibility in setting up the schedule.

You can also specify the time when the scheduler will start working and the conditions under which it will finish its work (upon reaching the set date and time or the number of task runs).

The following fields are provided for setting scheduling parameters in tasks:

  1. CronExpression - CRON expression, which sets the dates and time for the task to run;
  2. StartsOn - the start date and time of the schedule;
  3. Ends - the conditions for terminating the scheduled work. The object contains the following child fields:
    • After - the number of times the task should run before the scheduled execution is completed;
    • On - the date and time when the schedule should be terminated.

If you set empty values for the After and On fields in the Ends field, the task will run on schedule until the scheduled execution is turned off.

To disable scheduled execution, you need to set an empty string in the CronExpression field.

Furthermore, for the user's convenience, the graphical interface can provide a more intuitively understandable configuration of task scheduling:

  • hourly (run every few hours);
  • daily (every few days or only from Monday to Friday);
  • weekly (every week on a specified day);
  • monthly (every month on a specified day);
  • annually (every year on a specified month and day).

And, of course, you can manually set the CRON expression for specific scenarios of running tasks on a schedule.

Task Lifecycle in the Scheduler

A task is added to the scheduler when it is created or updated, if a CRON expression is specified. At this point, it is assigned a first execution time according to the specified settings. The scheduler runs tasks no more than once per minute. When the estimated run time arrives, the task is executed, after which it is assigned a subsequent execution time.

The start (StartsOn) and end (Ends->On) times define the time boundaries within which the task can execute. These boundaries are included in the execution interval, meaning the task will run at both the StartsOn and Ends->On times if they match the CRON expression.

It is recommended to set the start and end times with a small margin (at least ±1 minute), if allowed by the task logic. This is due to the nature of floating-point calculations: due to possible rounding errors, the estimated time may differ slightly from the expected time, which could theoretically lead to a missed run precisely at the interval boundary.

After the Ends->On time has passed or after the limit specified by the Ends->After parameter has been reached (when its value reaches zero), the task is automatically removed from the scheduler and will not be executed again until its parameters are changed again through the user interface or API.

While processing tasks, the scheduler pauses the calculation of the next run. Therefore, if the number of tasks is large and their processing time (before entering the queue) exceeds one minute, the next scheduled run will be skipped.

If a run is missed (for example, due to high load, server unavailability, or a reboot), the task will still be executed as soon as possible, but not at the strictly scheduled time. However, if two or more consecutive executions are missed, the task will only be executed once to prevent a backlog. After that, it will resume execution according to the original schedule.