Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision 		Previous revision
devel:documentation:bulk_actions:dev:bulk_actions [2020/02/06 11:21]
husniko [Bulk actions] 		devel:documentation:bulk_actions:dev:bulk_actions [2020/10/15 05:38] (current)
husniko [How can I add support for bulk action?]
Line 6: Line 6:
 ===== How it works? ===== ===== How it works? =====
  
-Action types: +Ways of item selection:
-  * **With items are selected** - To backend is from frontend send whole filter definition or set of ids. When user check checkbox for select all entities is setup constat. The constant define that is selected all entities (constant can be found in basic table - Basic.Table.SELECT_ALL). When is this constant active user also can remove some entities from this select. The removed entities is saved to new set - removed entities and to backend is send in another property (removeIdentifiers). +
-  * **Without items are selected** - action can be executed without items are selected on frontend - can be used on the whole agenda for import / export feature or simply for all data in agenda.+
  
-Action type is defined by the action properties ''showWithoutSelection'' and ''showWithSelection'' and can be combined => one action could be executed with or without items are selected.+  * **Individual item selection** - When user checks individual items in a table such items are chosen to be processed by bulk action. IDs of these items are sent to BE together with type of the selected bulk action.
  
-After specified controller receive new bulk action (rest post method). Controller transform given map<String, Object> to filter and execute new bulk action as new long running task. In abstract parent of all bulk action ''AbstractBulkAction'' provides basic validate method for form attributes and behavior with sending message.+  * **All items selection** - In case of using the checkbox which marks all items as selected, selection is controlled by filter. Individual items may be unchecked by which they are added to the list of items excluded from processing. Such filter setting is sent to BE together with the list of excluded items.
  
-Abstract parent for identity bulk actions has behavior with process filter or set of ids. If is used filter class perform method findIds by service with given filter. From this step is set of ids does't change. All identity bulk action has implemntation of method ''processIdentity''. The method process one identity and return operation result. If this method throws exception is catch by parent method and it will be created new failed log item.+* **Applying action without item specification** - The last supported option is to apply bulk action to the whole agenda without any item specification. All items are included. This option is by default disabled and needs to by enabled in BE bulk action implementation by overloading method ''showWithoutSelection'' returning ''true'' value. 
  
-After every success or failed process for identity will be created log item with result model. This log items are saved into processed items. This is same table as for schedulable task, but without removing or check existing items. It is used only for log results from process items. There isn't any another logic.+Every agenda is allowed to have more implemented bulk actions for different purposes. It is possible to combine all selection strategies. First two selection strategies are controlled by another method ''showWithSelection'' with default returning value set to ''true''.
  
-It is necessary for check permission for every process items and return exception (ForbiddenEntityException) or result model with NOT_EXECUTED state. This check is for identity done by abstract class (AbstractBulkAction method checkPermissionForIdentity).+Available bulk actions are shown with respect currently logged user authorities - required authority can be specified in bulk action ''getAuthoritiesForEntity'' method. 
 + 
 +After that controller receives a new bulk action request (rest post method), it transforms given map<String, Object> to filter and executes new bulk action as new long running task. Abstract parent of all bulk action classes ''AbstractBulkAction'' provides basic validation method for form attributes and functionality of sending notification message. It also ensures processing of the set filter or received set of IDs. In case of using filter, IDs to process are obtained by findIds method invocation with given filter. From this moment the set of IDs cannot be changed. All bulk actions has implementation of ''processEntities'' method. This method processes supplied entities and returns operation result. If this method throws an exception it is caught by parent method and a new failure log record is created. 
 + 
 +After processing entity (regardless whether successful or not) a new log with result is created. These log items are saved into processed items in the same table as schedulable tasks are but without removing or checking that item exists.  
 +It is necessary to check permission for every processed item and return exception (ForbiddenEntityException) or ''ResultModels'' with NOT_EXECUTED state. This check is provided by abstract class method ''checkPermissionForEntity''.
  
 ===== Prevalidate ===== ===== Prevalidate =====
 {{tag> bulk operation action prevalidation validation validate }} {{tag> bulk operation action prevalidation validation validate }}
-In some cases, we need obtain additional informations and show them to the user before bulk operation starts. For example operation for invoke account management for all identities witch the role. In this case we want to show how many identites has that role (before start).+In some cases, we need to obtain additional information and show it to user before bulk operation starts. For example operation invoking account management for all identities with specific role. In this case we want to show how many identities has assigned that role (before operation starts).
  
-Prevalidate feature was developed exactly for this case. Every bulk operations has method `prevalidate`, returns the `ModelResults`.+Prevalidate feature was developed exactly for this purpose. Every bulk operation implements method `prevalidate` which is supposed to be overloaded by developer. Overloaded method implements entire process of validation and its result is stored into ''info'' list of the `ResultModels` object which is returned from this method. Items in the ''info'' list are ''ResultModel'' objects consisting of ''AccResultCode'' and a Map of values which are then rendered on the FE.
  
-<note>Every `ResultModel` in `infos` list will be show on the bulk action detail.</note>+<note>Every `ResultModel` record in `infos` list will be shown on the bulk action detail.</note>
 <note tip>Messages are defined as standard result codes. See code `AccResultCode.ROLE_ACM_BULK_ACTION_NUMBER_OF_IDENTITIES` in the example below.</note> <note tip>Messages are defined as standard result codes. See code `AccResultCode.ROLE_ACM_BULK_ACTION_NUMBER_OF_IDENTITIES` in the example below.</note>
  
Line 80: Line 83:
  
 </code> </code>
 +
 +===== Configuration =====
 +{{tag> configuration }}
 +
 +@since 10.6.0
 +
 +Bulk action order, icon, level and other properties can be configured by [[..:..:application_configuration:dev:backend#bulk_actions|application setting]].
 +
 +Available bulk action can be shown in bulk action agenda available from menu - Settings - Modules - Bulk actions
 +
 +{{ :devel:documentation:bulk_actions:dev:bulk-action-agenda.png?600 |}}
 +
 +<note tip>All configurable properties (e.g. order) are shown in frontend agenda. Bulk Action can be disabled (or enabled) directly from this agenda (other configurable properties will be added in future).</note>
  
  
 ===== How can I add new bulk action? ===== ===== How can I add new bulk action? =====
  
-<note tip>Now is possible add new bulk action **only for identites**. In future will be implement bulk actions for another agendas.</note>+=== New bulk action creation === 
 +For easy start of creating a new bulk action you need just extend the abstract class ''AbstractBulkAction''. Descendant then simply overrides used methods:
  
-For easy start with creating new bulk action you can simple extends from abstract class ''AbstractBulkAction''. Child is simple override methods:+  * **getName** - name of bulk action, it will be used as key in localization 
 +  * **getAuthoritiesForEntity** - required permissions for processing of entities 
 +  * **getOrder** - order in selectbox in agenda 
 +  * **getService** - the service, items of which are processed by bulk action 
 +  * **processEntities** - iterates over all selected items and is supposed to provide check of permissions and processing invocation 
 +  * **processDto** - is called by processEntities method and implements processing of every single item 
 +  * **getLevel** - level for bulk action button (success ​by default) 
 +  * **isDeleteAction** - false by default. Action deletes records (for FE only). Action will be in bottom menu section, is action is included in menu. 
 +  * **isQuickButton** - false by default. Render action as quick button (for FE only). The first available actions are rendered as buttons, if icon is defined. This configuration enforces rendering action as quick button (order is ignored).
  
-  * **processIdentity** - process one identity, 
-  * **getName** - name of bulk action, this will be used for key in localization, 
-  * **getPermissionForIdentity** - required permission for process one identity, 
-  * **getOrder** - order in selecbox in identity agenda. 
-  * **getLevel** - level for bulk action button (success by default). 
  
-If you want use some settings for the bulk action you also must override method **getFormAttributes**. The method returns list of form attributes. With create the list of form attributes you can see example bulk action.+If one wants to use some settings of the bulk action it is necessary to override **getFormAttributes** method too. This method returns list of form attributes displayed in the window on FE.
  
-<note tip>For all bulk actions doesn't exist form definition. Bulk action only return **IdmFormAttributeDto**. The **IdmFormAttributeDto** isn't persist.</note>+<note tip>Bulk actions don't use persistent form definition kept in **IdmFormAttributeDto**. This definition is created ad hoc by calling **getFormAttributes** method.</note>
  
-After you implement all required method's and behavior for bulk action is necessary add localization for bulk action. For bulk actions is separate section in each localization. The section starts with **bulkAction**. Next key is **actions** and then name of your bulk action. For example: **eav.bulk-action.<my-new-bulk-action>**. Localization for form attributes is placed in localization with key: **eav.bulk-action.<my-new-bulk-action>.attributes**.+After implementation of all BE parts enabling support of the required bulk action, it is also necessary to add its localization. It needs to be put into section following this path **eav.bulk-action.<my-new-bulk-action>** in all localization files. 
 +Form attribute localization parts are placed into **eav.bulk-action.<my-new-bulk-action>.attributes** section. 
 + 
 +<code> 
 +"provisioning-operation-cancel-bulk-action": { 
 +   "label": "Cancel operation", 
 +   "help": "Cancel provisioning operations.", 
 +   "icon": "fa:ban", 
 +   "attributes": { 
 +      "retrywholebatch": { 
 +         "label": "Cancel full batch", 
 +         "help": "Cancel all operations for entity in queue? After uncheck will be canceled only selected operation in queue." 
 +      } 
 +   } 
 +} 
 +</code>
  
 ===== How can I add support for bulk action? ===== ===== How can I add support for bulk action? =====
  
-When we need add new agenda that will be support bulk actions on backend is necessary made this required steps:+In order to add support of bulk actions for particular agenda, it is necessary to implement following methods.
  
-  - implements two method's in controller for specific agenda (for example you can check IdmIdentityController): +  - in BE controller class (for example you can check IdmIdentityController): 
-    * **getAvailableBulkActions** - return all available bulk action for the entity, +    * **getAvailableBulkActions** - returns all available bulk actions (mandatory) 
-    * **bulkAction** - process the bulk action. +    * **bulkAction** - processes the bulk action (mandatory) 
-    * **prevalidateBulkAction** - prevalidate the bulk action. +    * **prevalidateBulkAction** - invokes the bulk action prevalidation (optional) 
-  - into frontend service change service's boolean with bulk action to true +  - in FE service class (for inspiration see IdentityService) 
-    * **supportsBulkAction**=true+    * **supportsBulkAction** - has to return true 
 +    * **showRowSelection** - this ''Advanced.Table'' property needs to be set true without any permission conditions (permissions are resolved on BE)
  
  
-Now you can start use bulk actions.+Now you can start using bulk actions.
  
  • by husniko