Core | Essentials | DAM (4.37)

# Conditional operations

Conditional Operations (CO) are operations that a user can perform on one or more data records. You can restrict a CO by using conditions, e.g. to make a certain operation available for the admin role only.

The following table lists the different types of conditional operations:

Name Description
NativeOperations Permissions of the CoreEngine such as Read, Delete, Edit, etc.
Templates Configured templates into which data records with their metadata are generated
ActionOperations Logic that is executed

# Conditions

Conditions determine whether a CO may be executed and displayed based on the data record and the user. The client can use this information to show or hide functions. For example, a user gets the "Edit picture" operation only if the selected image matches the supported mimetypes.

<conditions>
   <condition>
      <value1 type="field"><!-- default: value -->
         <value>status</value>
      </value1>
      <operator>=</operator><!-- default: '=' -->
      <value2>
         <value>1</value>
      </value2>
   </condition>
</conditions>

For extended requirements, conditions can also be defined by using the <sql> tag. The content of this tag is appended to the WHERE of the statement of the respective query.
The fields of the respective module can be accessed by name. The variables described below can be used within the <sql> tag. The Template Engine is used to insert the variables.

<conditions>
  <condition>
    <sql>
      '{$currentUser.role.roleName}' = '4ALLPORTAL Support'
      AND type = 'image'
    </sql>
  </condition>
</conditions>

# Value types

Values can be specified within the <value1> and <value2> tags. Example: <value1 type="field">.

You can use the following value types:

Name Description
value The value is taken directly from XML. You can define arrays by using multiple <value> tags.
field The field in the database. For example, if the <value> tag contains "status", a comparison is made with the "status" field in the current module.
permission The permission of the user for the current record (e.g. read all records, edit only own records ...)
variable The value is read from a dictionary stored in memory.
feature The value from the feature permissions of the current user.
preset The value from the presets of the current user.

# Comparison operators

You can use the following comparison operators:

long form short form
equal to =
not equal to ! =
like
not like
in
not in
less than <
greater than >
less than or equal to <=
greater than or equal to >=
is
is not

# Logical operators

You can use the following logical operators:

  • and
  • or
  • and not
  • or not

# Variables

We currently support the following variables:

  • {$currentUser.role.roleName}: the role name of the user
  • {$currentUser}: the current user as in "contact". All fields are available that are also available in the "contact" table (e.g. {$currentUser.firstname})
  • Specific operations can implement additional variables

Please also refer to the Template Engine documentation for more information.

# Dimensions

You can include special dimensions in a condition by using the <dimensions> element inside a <value> element:

<value1 field="price">
  <dimensions>
    <entry key="locale" class="array">
      <value class="null" /> <!-- All values that have no dimension assigned. -->
      <value>en_US</value>
    </entry>
    <entry key="channel" class="array">
      <value>print</value>
      <value>web</value>
    </entry>
  </dimensions>
</value1>

# NativeOperations

NativeOperations are determined by the permission management. They are displayed only for the records to which the user has a permission. Possible NativeOperations are:

  • Read (read)
  • Delete (del)
  • Edit (edit)
  • Assign (assign)
  • create_relation
  • delete_relation

Details about these permissions can be found here.

# Exceptions

  • create_relation applies only to requests for a relation from a subpanel view. It is delivered as soon as you have an "edit" permission on the related bean.
  • delete_relation applies only to requests for a relation from a subpanel view. It is delivered as soon as you have an "edit" permission on one of the two relation modules.
  • For requests to the main view, edit and assign are not delivered.
  • delete is not loaded for a detail view.

# ActionOperations

An ActionOperation or action is configured in the file system and is based on the OperationBase.
Actions are intended to trigger certain logics, i.e., code in the front end or back end.

  • With actions, it is possible to implement an operation e.g. that copies a record and adjusts certain fields.
  • It is also possible to display a form (Object Renderer) to the user to enter data for the operation.
  • Also, dialogs such as an upload can be realized by implementations in the front end. In addition to the parameters described in the OperationBase, the display can also be restricted by using conditions.

You can configure ActionOperations here: <module>/actions/<action-name>.xml

Example:

<action>
  <!-- refer to OperationBase -->

  <!-- Action specific -->
  <method></method><!-- MESSAGEBOX, INSTANT_CALL, FILE_ACCESS, FORM, FORM_SAVE -->

  <conditions></conditions><!-- refer to Conditions -->

  <classname></classname> <!-- Class for execution in the back end -->
  <classloader></classloader><!-- Classloader of the class -->

  <renderers>
    <renderer>
      <!-- refer to ObjectRenderer -->
    </renderer>
  </renderers>

</action>
Element Description
<method> MESSAGEBOX opens a popup with "Yes" and "No" buttons. "Yes" executes the back end implementation of <classname>.
INSTANT_CALL executes the back end implementation directly on clicking.
FILE_ACCESS opens the FileAccess popup (shows "Download" buttons).
FORM opens a form popup. The data from this form will be sent to the back end when confirmed.
FORM_SAVE opens a form popup. The data from this form are saved directly to the appropriate object(s).
<conditions> The action is only displayed if its conditions apply.
<classname> Class which must be loaded via a plugin in the back end. It must also implement the com.cm4ap.ce.vo.condoperation.action.IAction interface.
<classloader> Name of the Java classloader loaded into the class named in <classname>.
<renderers> Form displayed before the action is executed. Each renderer represents one page of the form. For more information, refer Object Renderer.

# Action Parameters

The following parameters can be added to an action to produce a progress information toast:

Parameter Description
showLongLoading Parameter showLongLoading can be added and set to true or false(default).
If set to true, a toast informs about an action taking longer than the defined timeout, counting until the first synchronous response.
timeout Parameter timeout defines the time before the toast appears in milliseconds (default: 3000).

# OperationBase

The following configuration options apply to all COs that can be configured. These can be actions, templates, or other COs.

Example:

<any-co><!-- <action> or <template> -->
  <label></label> <!-- translated -->
  <info></info> <!-- translated -->
  <icon></icon> <!-- icon (StyleManager) -->
  <group></group> <!-- Group key -->
  <order></order> <!-- Integer: define GUI order by weight -->
  <views>
   <!-- Define the visibility for each view. -->
   <view visible="true|false">subpanel</view>
  </views>
  <min_beans>0</min_beans> <!-- Minimum beans to show up (-1 is infinite) -->
  <max_beans>1</max_beans> <!-- Maximum beans to show up (-1 is infinite) -->
  <enabled>true|false</enabled> <!-- If disabled, the CO is ignored -->
</any-co>
Element Description
<label> Text that is written on the button. Label keys (e.g. L-FILE-ADD_TO_BASKET) are translated automatically.
<info> Text that appears as a tooltip when you mouse over. Label keys (e.g. L-FILE-ADD_TO_BASKET-INFO) are translated automatically.
<icon> Icon from the icon servlet, which is displayed in front of the label text.
group Key name of the group. If two COs have the same group, they are displayed grouped in the GUI.
group_label Deprecated: group will be used to generate group label. For example L-FILE-CO-G-COLLECTIONS. Old behavior: Text that is written on the group. Label keys (e.g. L-FILE-ADMIN_ACTIONS) are translated automatically.
group_info Deprecated: group will be used to generate group info. For example L-FILE-CO-G-COLLECTIONS-INFO. Old behavior: Text that appears as a tooltip when you mouse over. Label keys (e.g. L-FILE-ADMIN_ACTIONS-INFO) are translated automatically.
<order> Integer weighting for the order in the GUI. Negative values are also allowed. The NativeOperations use the range -11 to -6. The default value is 0.
<views> Controls the visibility of the CO per view. A view that is not specified is not delivered to the GUI. If the view is configured as visible="false", the CO is delivered as not visible. GUI plugins can then react to this without the CO being displayed. Default: If no view is specified, the CO is displayed in all views.
<min_beans> If fewer data records are selected in the GUI than configured here, then the CO will not be delivered. The default value is 1.
<max_beans> If more data records are selected in the GUI than configured here, then the CO will not be delivered. -1 means there is no restriction. The default value is -1.
<enabled> If enabled is set to "false", the CO will not be delivered in any case, as if it did not exist. The default value is "true".


Conditional operations in the GUI: Actions in the toolbox with configured icons and tooltips

# Conditional Operation Chaining

Conditional operation chaining allows you to execute multiple conditional operations in succession.
When a CO is executed, error code 428 can be returned instead of error code 0 (= OK). 428 is the sign for the front end that another CO must be executed. The operation is returned in the result-object.

Chaining can be used when there are CO preconditions that were not met when the operation was executed. E.g. for a CO that requires a confirmation prompt (e.g. for an operation that deletes records).

# Exemplary procedure

The operation in the back end should expect the confirmed parameter to determine whether the user has confirmed the execution of the operation. If the operation is executed without this parameter, the back end assumes that the user has not confirmed the operation.

In this case, the back end returns error code 428. In addition, the operation itself is returned in the result-object. Only this time the method parameter of the conditional operation is set to a new value confirmation.

In order for the front end to display a confirmation popup, a CondOperationPlugin must be implemented. It ensures that:

  • the confirmation popup is displayed before the execution of all operations that are called with method=confirmation
  • that the confirmed parameter is included during execution

By doing this, the back end knows on the second attempt that the user has confirmed the execution of the operation.

# CondOperationPlugin

The CondOperationPlugin is a plugin that is used to execute extended code when loading or executing COs. On the one hand, it can be used to supplement, replace or even cancel the handling of operations. On the other hand, the operations loaded by the back end can be supplemented with further operations or reduced by certain operations.

The entire processing of COs in the GUI works via this logic. If there is no corresponding plugin for an operation, no code will be executed on click.
This does not mean that for each additional operation something new has to be developed or a new plugin has to be created. But new operation types will probably not find any standard processing.

For some default operation types there are default plugins included in the CoreEngine GUI.

# Examples for conditions

# Compare field with value

<conditions>
   <condition>
      <value1 type="field"><value>status</value></value1>
      <operator>!=</operator>
      <value2><value>1</value></value2>
   </condition>
</conditions>

# Compare value with value

<conditions> <!-- Always false -->
   <condition>
      <value1><value>1</value></value1>
      <value2><value>0</value></value2>
   </condition>
</conditions>

# Compare preset with value

<conditions>
   <condition>
      <value1 type="preset"><value>contact.can_mail</value></value1>
      <value2><value>true</value></value2>
   </condition>
</conditions>

# Compare field with preset

<conditions>
   <condition>
      <value1 type="field"><value>required_power</value></value1>
      <operator>less than</operator>
      <value2 type="feature"><value>contact.assign_power</value></value2>
   </condition>
</conditions>

# Compare NativeOperation with value

<conditions>
   <condition>
      <value1 type="permission"><value>create</value></value1>
      <value2><value>true</value></value2>
   </condition>
</conditions>

← Configuration Changes →

Request missing documentation