hook_civicrm_searchKitTasks

Summary

This hook is called to allow you to add to or alter the tasks available in search kit.

Definition

hook_civicrm_searchKitTasks(array &$tasks, bool $checkPermissions, ?int $userID)

Parameters

• $tasks (array) - the current set of tasks. You can add/remove existing tasks. Each task is an array and has keys like

  • title - title to display - remember to use ts() in core and E::ts() in extensions
  • icon - associated icon (optional)
  • uiDialog - array containing the path to the templateUrl
  • module - name of the angular module to require.
  • apiBatch - (from 5.56) array describing the action if you are not providing a form (if you just want a generic UI). Has the keys:
    • action - Name of API action to call once per row
    • params- Optional array of additional api params
    • confirmMsg - If omitted, the action will run immediately with no confirmation
    • runMsg
    • successMsg,
    • errorMsg,

Note: the $tasks array is keyed by the entity that it applies to. Depending on context, the array may or may not already be populated with some data. Your hook implementation should add its tasks regardless of what's already in the array.

• $checkPermissions (boolean) - Whether permissions ought to be taken into account. If the tasks you are adding shouldn't be available to all users, perform any necessary permission checks only if this value is true.

• $userID (int|null) - If $checkPermissions is true, will contain the contact ID of the acting user.

Returns

• null

Example: Add a new task with a generic interface

/**
 * Implements hook_civicrm_searchKitTasks().
 *
 * @param array[] $tasks
 * @param bool $checkPermissions
 * @param int|null $userID
 */
function myext_civicrm_searchKitTasks(array &$tasks, bool $checkPermissions, ?int $userID) {
  $tasks['Contact']['myAction'] = [
    'title' => E::ts('My SearchKit Task'),
    'icon' => 'fa-random',
    'apiBatch' => [
      'action' => 'myAction',
      'confirmMsg' => E::ts('Are you sure you want to run myAction on %1 contacts?'),
      'runMsg' => E::ts('Running myAction on %1 contacts...'),
      'successMsg' => E::ts('Successfully ran myAction on %1 contacts.'),
      'errorMsg' => E::ts('An error occurred while attempting to run myAction on %1 contacts.'),
    ],
  ];
}

The myAction is assumed to be a custom APIv4 action provided by your extension. For example, create the file Civi/Api4/Action/Contact/MyAction.php with the following code:

<?php

namespace Civi\Api4\Action\Contact;

use Civi;

class MyAction extends \Civi\Api4\Generic\BasicBatchAction {

  protected function doTask($item) {
    foreach ($item as $key => $contact_id) {
      // todo whatever you need to do
    }

    return $item;
  }

}

Make sure to use the correct namespace for your entity (Contact, Activity, etc), and to flush the CiviCRM cache after adding the new code.

Example: Add a new task with a custom interface

/**
 * Implements hook_civicrm_searchKitTasks().
 *
 * @param array[] $tasks
 * @param bool $checkPermissions
 * @param int|null $userID
 */
function deduper_civicrm_searchKitTasks(array &$tasks, bool $checkPermissions, ?int $userID) {
  $tasks['Contact']['flip'] = [
    'module' => 'dedupeSearchTasks',
    'title' => E::ts('Flip first/last name'),
    'icon' => 'fa-random',
    'uiDialog' => ['templateUrl' => '~/dedupeSearchTasks/dedupeSearchTaskFlip.html'],
  ];
}

This would have a js & a php file ang/dedupeSearchTasks.js that declares the module. These can be generated using civix - eg. civix generate:angular-module --am=dedupeSearchTasks

(function(angular, $, _) {
    angular.module('dedupeSearchTasks', CRM.angRequires('dedupeSearchTasks'));
})(angular, CRM.$, CRM._);