Package 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 Details

    • 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