com.almworks.jira.structure.api.effector

Interface Effector

@PublicSpi
public interface Effector

An effector is a component that generates effect descriptions based on a forest, a set of attribute values, and a set of user-provided, implementation-specific parameters.

The effector itself doesn't change anything, but only produces effect descirptions for effect providers.

Method Summary

Modifier and Type	Method and Description
void	addDefaultFormParameters(Map<String,Object> form) Fills the parameter map for the edit form Velocity template with default values for a new effector instance of this type.
default void	addParametersForSummary(Map<String,Object> parameters, Map<String,Object> summaryParameters) Given the effector-specific parameters, fills the parameter map for the summary Velocity template.
void	addParametersToForm(Map<String,Object> parameters, Map<String,Object> form) Given the effector-specific parameters, fills the parameter map for the edit form Velocity template.
default void	addPlaceholdersForSummaryTemplate(Map<String,String> templatePlaceholders) This method fills parameters for summary Velocity template.
Map<String,Object>	buildParametersFromForm(Map<String,Object> form, ErrorCollection errors) Validates the parameters from the edit HTML form and constructs a serializable parameter map for getEffectorFunction(Map, EffectorContext).
EffectorFunctionResponse	getEffectorFunction(Map<String,Object> parameters, EffectorContext context) Returns an EffectorFunction, given the parameters.
default boolean	isAvailable() Checks if this effector is currently available in the Automation menu on UI.

Method Detail

getEffectorFunction

@NotNull
EffectorFunctionResponse getEffectorFunction(@NotNull
                                                      Map<String,Object> parameters,
                                                      @NotNull
                                                      EffectorContext context)

Returns an EffectorFunction, given the parameters. The returned function will be called by Structure to produce effect descriptions.

For attributes, the effector must not use the attribute service directly, but require the attributes by calling EffectorContext.requireAttribute(AttributeSpec).

If it's impossible to create an effector function, e.g. because of incorrect parameter values, the effector must return an error response explaining the problem.

Parameters:

parameters - effector-specific parameters

context - the context object

Returns:

a response containing either an effector function or a collection of errors

isAvailable

default boolean isAvailable()

Checks if this effector is currently available in the Automation menu on UI.

For example, an effector can be unavailable when a certain plug-in is missing, or a certain application feature is disabled.

Note that Structure doesn't prevent existing effector instances from being used if the effector is unavailable. Structure only hides the effector from the Automation menu so users can't create new instances from UI. Also unavailable effectors can still be launched as one-off processes (see EffectorProcessManager.startProcess(String, Map, ForestSpec, boolean)

To prohibit the effector execution return error response from getEffectorFunction(Map, EffectorContext).

Returns:

true if the effector must be available in the Automation menu. Returns true by default.

addDefaultFormParameters

void addDefaultFormParameters(@NotNull
                              Map<String,Object> form)
                       throws EffectorUnavailableException

Fills the parameter map for the edit form Velocity template with default values for a new effector instance of this type.

Parameters:

form - form template parameters (output)

Throws:

EffectorUnavailableException - if the operation cannot be performed

addParametersToForm

void addParametersToForm(@NotNull
                         Map<String,Object> parameters,
                         @NotNull
                         Map<String,Object> form)
                  throws EffectorUnavailableException

Given the effector-specific parameters, fills the parameter map for the edit form Velocity template.

Parameters:

parameters - effector parameters (input)

form - edit form template parameters (output)

Throws:

EffectorUnavailableException - if the operation cannot be performed

buildParametersFromForm

@NotNull
Map<String,Object> buildParametersFromForm(@NotNull
                                                    Map<String,Object> form,
                                                    @NotNull
                                                    ErrorCollection errors)
                                             throws EffectorUnavailableException

Validates the parameters from the edit HTML form and constructs a serializable parameter map for getEffectorFunction(Map, EffectorContext).

Any errors for invalid input parameters must be reported to the provided ErrorCollection; if it contains any error messages after this method is called, they are reported to the user and the resulting map is ignored.

The resulting parameter map could be stored in the database or transferred over the wire, so it must be serializable to JSON. We advise that you put in only simple objects (strings, numbers, booleans), serializable maps, or lists thereof.

Parameters:

form - the parameters from the edit HTML form (input)

errors - the collector for error messages (output)

Returns:

serializable parameter map for getEffectorFunction(Map, EffectorContext)

Throws:

EffectorUnavailableException - if the operation cannot be performed

addParametersForSummary

default void addParametersForSummary(@NotNull
                                     Map<String,Object> parameters,
                                     @NotNull
                                     Map<String,Object> summaryParameters)

Given the effector-specific parameters, fills the parameter map for the summary Velocity template.

You have to override this method if your effector supports name generation, i.e. has a Velocity template with name = "summary" and a client-side descriptor.

Parameters:

parameters - effector parameters (input)

summaryParameters - summary template parameters (output)

addPlaceholdersForSummaryTemplate

default void addPlaceholdersForSummaryTemplate(@NotNull
                                               Map<String,String> templatePlaceholders)

This method fills parameters for summary Velocity template. Similarly to addParametersForSummary(Map, Map). Method should place a placeholder (for example {myEffectorParam}) for each parameter that will be replaced with real value from effector edit form (see addParametersToForm(Map, Map)) by corresponding client-side descriptor.

Each placeholder declared in this method will be automatically highlighted by Structure CSS on client side.

You have to override this method if your effector supports name generation, i.e. has a Velocity template with name = "summary" and a client-side descriptor.

Parameters:

templatePlaceholders - summary template parameter templates