Skip to end of metadata
Go to start of metadata

Helpful links


Scheduled task

Scheduled task is a user component that allows you to define a task that is performed periodically.

Creating a scheduled task is possible in the admin panel (Administration -> System configuration -> Scheduled tasks).


Defining a scheduled task

A scheduled task is created based on a definition created by the user. Such a definition must contain the following elements:

  1. Annotation @ScheduledTask (if the scheduled task is not defined in the plugin, it must come from the com.suncode package)
  2. A public method marked with the annotation @Define witch a single parameter ScheduledTaskDefinitionBuilder
  3. A public method named execute to be executed periodically. The execute method can return any type including void. The returned value will be displayed as the result of scheduled task processing. Setting the type void is equivalent to no result.

The definition may also contain the @ScheduledTaskScript annotation. This annotation transfers the path to the script (from classpath) containing the definition of the dynamic form.

An example definition is shown below:

@ScheduledTask
@ScheduledTaskScript( "js/example-form.js" )
public class ExampleScheduledTask {
	@Define
	public void definition( ScheduledTaskDefinitionBuilder builder ) {
		builder
			.id( "example-scheduled-task" )
			.name( "example.scheduled.task.name" )
 			.description( "example.scheduled.task.desc" )
			.cancelable()
			.parameter()
				.id( "scheduled-task-param" )
				.name( "example.scheduled.task.param.name" )
				.description( "example.scheduled.task.param.desc" )
				.type( Types.STRING )
				.create();
	}
	
	public void execute( @Param( value = "scheduled-task-param" ) String param )
	{
		// Body of scheduled task
		...
	}
}

Implementation of the execute method

A scheduled task must have a method named execute. The method can have the following parameter types:

  • a single scheduled task parameter - the parameter type must conform to the defined type and must be preceded by the @Param annotation. Supported parameter types:
    • STRING
    • BOOLEAN
    • INTEGER
    • FLOAT
    • DATE - mapping to org.joda.time.LocalDate (yyyy-MM-dd format)
    • DATETIME - mapping to org.joda.time.LocalDateTime (yyyy-MM-dd HH:mm:ss format)
    • FILE - mapping to com.suncode.pwfl.customfile.ComponentFile
    • STRING_ARRAY
    • BOOLEAN_ARRAY
    • INTEGER_ARRAY
    • FLOAT_ARRAY
    • DATE_ARRAY
    • DATETIME_ARRAY
    • FILE_ARRAY
  • Parameters - contains all the defined parameters of a scheduled task along with their values, this is an alternative to retrieving a parameter using the mentioned @Param annotation
  • Translator - translator for this component. More information here,
  • CancelationHandler - stores information about whether the user in the GUI clicked the Cancel execution button. The task cancellation mechanism itself must be implemented by the component developer. The Cancel Execution button will only show up if the cancelable method has been called in the builder,
  • Logger - a logger for logging custom messages in the component. Messages are saved to files (configured in Log4j) and will be displayed in the task execution history.
  • ProgressHolder - object, in which you can set the current progress of the scheduled task execution (a number between 0 and 1). This progress will be displayed in the GUI
  • ScheduledTaskInstanceInfo - an object that stores information about a given instance of a scheduled task

Registration of a scheduled task in the plugin

If the scheduled task is defined in the plugin then you need to additionally indicate that the plugin provides components. To do this, add an entry in the suncode-plugin.xml file:

<!-- Sharing components (among other scheduled tasks) -->
<workflow-components key="components" />

 

Method as a task scheduled in a plugin

A scheduled task in a plugin does not have to be a component. It can be created in the same way as scheduled tasks defined in client projects - a scheduled task as a public method call.

For example, after creating a class in a plug-in

package com.suncode.plugin;

public class SomePluginClass
{
    public void someMethod( String text, Integer number )
    {
        System.out.println( "Text: " + text + ", number: " + number );
    }
    public void someMethod2( String text, Double number )
    {
        System.out.println( "Text: " + text + ", number: " + number );
    }
}

After typing com.suncode.plugin.SomePluginClass in the Class Name field, the window for adding a new scheduled task will display someMethod1 and someMethod2 methods, which can be selected and added as a scheduled task.

However, such tasks have limitations:


  • annotation AdvancedTask cannot be used to give a name, description, etc. for a scheduled task
  • you cannot abort that kind of task
  • you cannot set progression for this kind of task
  • you cannot log

Due to the above limitations, this functionality should only be used for testing custom classes in plugins. It is preferred that ultimately the tasks scheduled in plugins are components.

Note

If a scheduled task is written as an extension of the AbstractAdvancedTask class and has the cancelable = true annotation enabled, then to stop the execution of such a task you need to add a condition in the method code:

if (Thread.currentThread().isInterrupted())
{
    taskLog.info( "Anulowano....");
    log.info( "Anulowano....");
    break;
}

Dynamic form

The dynamic form allows you to define a scheduled task parameter form.

Dynamic form registration

File forwarded in @ScheduledTaskScript annotation
PW.ScheduledTasks.register('example-scheduled-task', {
    buildParams: function (form) {
        form.addCombobox({
            id: 'example-scheduled-task',
            values: [
                ['wartosc1', 'Wartosc 1'],
                ['wartosc2', 'Wartosc 2'],
                ['wartosc3', 'Wartosc 3']
            ]
        });
    }
}

If, when adding an element to the form, you define the id of the element and this value refers to the id of the parameter defined in the component, then all properties for the field will be read from the parameter definition (name, description, requirement, type).

If, on the other hand, you want to add a field that is not related to any parameter, then you should define the name, description, type and requirement.

Available functions of the dynamic form

FunctionParametersDescription
addField(definition, [position])

definition - identifier of the added parameter

or object containing the definition of the field

position - the position at which the parameter is to be added.

When position is not specified, the paramter will be added at the end of the form.

listeners - an object that defines the function of events on the variable

  • change - a function called when the value of a field changes.

    The function can use the following parameters:
    • field- the Combobox field for which the change occurred
    • newValue - the new value of the field


Adding parameter.

Example:

...
form.addField('param-1');
...

If we add a field unrelated to the component parameter, we can specify what type the field should be.

The following types are available: string, integer, float, date, datetime, boolean, string[], integer[], float[], date[], datetime[], boolean[].

...
form.addField({
	id: 'custom',
	fieldType: 'date',
	...
});
...
 addTextArea(definition, [position])definition - identifier of the added parameter

or object containing the definition of the field

position - the position at which the parameter is to be added.

When position is not specified, the paramter will be added at the end of the form.

listeners - an object that defines the function of events on the variable

  • change - a function called when the value of a field changes.

    The function can use the following parameters:
    • field - the field for which the change occurred
    • newValue - the new value of the field

Adding a parameter as a field of type `TextArea`.

Parameter must be of type String.

 

Example

...
form.addTextArea('param-1');
...

or

...
form.addTextArea({
	id: 'param-1',
	...
});
...
addCombobox(definition, [position])definition - object containing the definition of a field

The definition should contain the following fields:

  • id - identifier of the parameter (optional)
  • valueField -  name of the field, setting the the value of the field
  • displayField - the name of the field whose value will be displayed in the field
  • minChars - the minimum number of entered characters, after which Combobox starts filtering.
    Default: 0.
  • values - ((info) for local type) an array of records of field display values; a record can be:
    • an object with valueField and displayField fields defined in the configuration
    • a 2-element array with value and display text
  • remote - ((info) for remote type) object containing the definition of remote data retrieval. The object contains the following fields:
    • url - URL address
    • remoteSort - determines whether the data should be sorted on the server side (value true) or on the browser side (value false).
      The default is false.
    • pageSize - amount of displayed results per page.
      Default is 25.
  • sort - object defining the method of sorting.
    It contains the following fields:
    • field - the field by which we want to sort
    • direction - the direction by which we want to sort.
      ASC for ascending direction,
      DESC for descending direction.
  • listeners - an object that defines the function of events on the variable
    • change - a function called when the value of a field changes.
      The function can use the following parameters:
      • field - the field for which the change occurred
      • newValue - the new value of the field

position - The position on which the parameter is to be added.

When position is not specified, the parameter will be added to the end of the form

 

Adding a parameter as a field of type `Combobox`.

Example of adding a field of type `Combobox` local (local):

...
form.addCombobox({
	id: 'param-1',
	values : [
        ['activity', 'Zadanie'],
		['stage', 'Etap'],
	    ['process', 'Proces']
    ],
	sort: {
		field: 'display',
		direction: 'DESC'
	},
	listeners: {
        change: function (field, newValue){
		    ...
	    }
    }
});
...

Example of adding a field of type 'Combobox' remote (remote):

...
form.addCombobox({
	id: 'param-1',
	valueField: 'id',
	displayField: 'display',
	remote: {
		url: Suncode.getAbsolutePath('plugin/com.suncode.example-plugin/example-combo/get'),
		remoteSort: false,
		pageSize: 20
	},
	sort: {
		field: 'display',
		direction: 'DESC'
	},
	listeners: {
        change: function (field, newValue){
		    ...
	    }
    }
});
...
addCheckbox(definition, [position])definition - identifier of the added parameter

or object containing the definition of the field

position - the position at which the parameter is to be added.

When position is not specified, the paramter will be added at the end of the form.

listeners - an object that defines the function of events on the variable

change - a function called when the value of a field changes.

The function can use the following parameters:
  • field - the field for which the change occurred
  • newValue - the new value of the field

Example:

...
form.addCheckbox('param-1');
...

If we pin this to a component parameter, the type of this parameter must be boolean.

addRow( [definition] )

definition - definition of a row.

It contains the following fields:

  • id - row identifier (optional).
  • fieldsSpace -space in pixels between elements of the row. The default is 5
  • fieldLabel - the name (label) of the row. By default, the row name is created based on the names of the elements contained in the row.

Adds and returns an "empty" row. The returned row allows you to add fields to it. The fields will be added side by side.

Example:

var row = form.addRow();
row.addField('param-1');
row.addField('param-2');
row.addCombobox(...);
addButton(definition, [position] )

definition - button definition.
It contains the following fields:

  • id - button identifier
  • text - the displayed text of the button
  • handler - function that is called when the button is clicked

position - the position at which the parameter is to be added.

When position is not specified, the paramter will be added at the end of the form.

Adding a button on the form.

Example:

form.addButton({
	id: 'btn-1',
	text: 'Przycisk',
	handler: function(){
	...
	}
})
addPassword(definition, [position])definition - the identifier of the added parameter or the object containing the field definition

position - the position at which the parameter is to be added

If position is not specified, the parameter will be added at the end of the form.

listeners - an object that defines event functions on the variable

  • change - a function called when the value of the value of the field.

    Funkcja może korzystać z następujących parametrów:
    • The function can use the following parameters:
      • field - the field for which the change occurred
      • newValue - the new value of the field

Adding a parameter as a field of type 'Password'.

Parameter must be of typeString.

Example

...
form.addPassword('param-1');
...

or

...
form.addPassword({
	id: 'param-1',
	...
});
...
hide(elementId)elementId - element identifier

Hides the field with the specified id.

Example

...
form.hide('param-1');
...
show(elementId)elementId - element identifier

Hides the field with the specified id.

Example

...
form.show('param-1');
...
disable(elementId)elementId - element identifier

Hides the field with the specified id.

Example

...
form.disable('param-1');
...
enable(elementId)elementId - element identifier

Hides the field with the specified id.

Example

...
form.enable('param-1');
...
getValue(elementId)elementId - element identifier

Hides the field with the specified id.

Example

...
form.getValue('param-1');
...
setValue(elementId, value)

elementId - element identifier

value - value to be set

Sets the forwarded value to the parameter with the specified id.

For array types, the value is an array of values.

Example

...
form.setValue('param-1', 'value');
...
mask(onlyForm)

onlyForm - true - to apply the mask only to the parameter form, false - to apply the mask to the contents of the entire window.

Applies a mask to a parameter form or window content.

Example

...
form.mask(false);
...
unmask(onlyForm)

onlyForm - true - to apply the mask only to the parameter form, false - to apply the mask to the contents of the entire window.

Applies a mask to a parameter form or window content.

Example

...
form.unmask(false);
...



  • No labels

1 Comment

  1. Piotr Teresiak

    Proszę uzupełnić dokumentacje o ScheduledTaskContext.