Automatic tasks

Automatic tasks are user components that are separate tasks in the process path.

Created automatic tasks are available in the process editor and can be easily used in a business process enabling the execution of business logic. Their behavior can be additionally configured using parameters.

Defining the automatic task

Applications are created based on their definition, created by the user. Such a definition must contain the following elements:

1. Annotation @Application (if the application is not defined in the plugin, it must come from the com.suncode package)
2. A public method annotated @Define with a single parameter ApplicationDefinitionBuilder
3. A public method named execute, which is responsible for executing the necessary logic.

The application can also provide a script that builds the appearance of parameters when it is defined in the PWE. To do this, add another annotation for the class @ComponentsFormScript with the path to the script passed in (from classpath).

An example definition is shown below. The application calculates the gross value based on the net value and VAT value and will set it to the variable specified in the parameter.

@Application
@ComponentsFormScript( "path/example-form.js" )
public class ApplicationExample
{
    @Define
    public void definition( ApplicationDefinitionBuilder builder )
    {
        builder
            .id( "example-application" )
            .name( "application.example" )
            .description( "application.example.desc" )
            .category( Categories.TEST )
            .parameter()
                .id( "netValue" )
                .name( "application.parameter.net.name" )
                .description( "application.parameter.net.desc" )
                .type( Types.FLOAT)
                .create()
            .parameter()
                .id( "vat" )
                .name( "application.parameter.vat.name" )
                .description( "application.parameter.vat.desc" )
                .type( Types.FLOAT)
                .create()
            .parameter()
                .id( "grossValue" )
                .name( "application.parameter.gross.name" )
                .description( "application.parameter.gross.desc" )
                .type( Types.VARIABLE)
                .create();
    }
 
    public void execute( @Param Double netValue, @Param Double vat, @Param Variable grossValue )
    {
        if ( netValue == null )
        {
            return;
        }
        grossValue.setValue( netValue * vat );
    }
}

Implementation of an automatic task

The automatic task must have a method named execute. The method can have the following types of parameters:

• single automatic task parameter - the type of the parameter must be consistent with the defined type and must be preceded by the annotation @Param,
  parameter mapping two array parameters (key, value) - the type of the parameter must be of type java.util.Map<K,V>, where K is the defined type of the component parameter being the key, and V is the defined type of the component parameter being the value for the key. The parameter must be annotated PairedParamwith defined properties (key - id of the parameter being the key, value - id of the parameter being the value).

• a single parameter, type DataSourceInstance marked with an annotation @Param - if you have such a type, the DataSourceInstance object will be injected based on the value of this parameter, which must be the id of the data source.
• Parameters - contains all the defined parameters of the automatic task with their values, this is an alternative to retrieving the parameter using the above mentioned annotation @Param
• ApplicationContext - context of the automatic task, you can read the process and task identifier from it,
• ActivityContextMap - an object storing the variables of the form along with their current values and the process and task identifier; all variables can be set values.
• ContextVariables - context variables available in this automated task. More info here.
• Translator - ttranslator for this component, so that the messages returned by the automatic task can be translated. More info here.
• UserInfo - object containing information about the user accepting the task.
  
  
  

public void execute( @Param Double netValue, @Param Double vat, @Param Variable grossValue )
{
    try
	{
		grossValue.setValue( netValue * vat );
	}
	catch( Exception exception )
	{
		throw new AcceptanceException( "Nie udało się obliczyć wartości.", exception );
	}
}

Registration of an automatic task in the plugin

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

<!-- Sharing automatic tasks--> 
<workflow-components key="components" />

Application and class that sets variables (setter) in a single component

Applications and setters are practically no different from each other in terms of component construction, so it is possible to create a single definition that can act as both an application or a setter in the system. The definition of such a component must be of the form:

@Application
@VariableSetter
public class MixedComponent
{
    @Define
    public void definition( CommonDefinitionBuilder builder )
    {
        // @formatter:off
        builder
            .id( "variable-and-application-component-id" )
            .name( "variable-and-application-component-name" )
            .category( Categories.CUSTOM )
            .parameter()
                .id( "variable-and-application-param-id" )
                .name( "variable-and-application-param-name" )
                .type( Types.VARIABLE)
                .create();
        // @formatter:on
    }

    public void execute( @Param( "variable-and-application-param-id" ) Variable param )
    {
        handle( param );
    }

    public void set( @Param( "variable-and-application-param-id" ) Variable param )
    {
        handle( param );
    }

    public void handle( Variable param )
    {
        param.setValue( "some value" );
    }
}

The execute method will be called if it is an application; set if it is a setter. If both methods are to do exactly the same thing, you can use the above concept. The arguments that can be passed to each calling method are still in accordance with the documentation of the application and the setter.

So note that in the application you can download ApplicationContext in a setter  AcceptanceContext. They differ only in that it AcceptanceContext contains the name of the action that accepted the task. Both classes inherit from WorkflowContext, so in both set and execute methods you can retrieve this type of parameter.