From 12ccb846e82815c4a40b400fc5a86ee1fb033aee Mon Sep 17 00:00:00 2001
From: Rich Lott / Artful Robot <code.commits@artfulrobot.uk>
Date: Mon, 31 Mar 2025 09:58:34 +0100
Subject: [PATCH] Add Scheduled Job

---
 api/v3/Job/Contactcatsync.mgd.php             | 21 ++++++++
 api/v3/Job/Contactcatsync.php                 | 36 +++++++++++++
 .../phpunit/api/v3/Job/ContactcatsyncTest.php | 54 +++++++++++++++++++
 3 files changed, 111 insertions(+)
 create mode 100644 api/v3/Job/Contactcatsync.mgd.php
 create mode 100644 api/v3/Job/Contactcatsync.php
 create mode 100644 tests/phpunit/api/v3/Job/ContactcatsyncTest.php

diff --git a/api/v3/Job/Contactcatsync.mgd.php b/api/v3/Job/Contactcatsync.mgd.php
new file mode 100644
index 0000000..3134dc2
--- /dev/null
+++ b/api/v3/Job/Contactcatsync.mgd.php
@@ -0,0 +1,21 @@
+<?php
+
+// This file declares a managed database record of type "Job".
+// The record will be automatically inserted, updated, or deleted from the
+// database as appropriate. For more details, see "hook_civicrm_managed" at:
+// https://docs.civicrm.org/dev/en/latest/hooks/hook_civicrm_managed
+return [
+  [
+    'name' => 'Cron:Job.Contactcatsync',
+    'entity' => 'Job',
+    'params' => [
+      'version' => 3,
+      'name' => 'Contact Category sync',
+      'description' => 'Keeps contacts’s categories updated daily, recording change activities to track over time. Should be run hourly but will only actually work around 3am.',
+      'run_frequency' => 'Hourly',
+      'api_entity' => 'Job',
+      'api_action' => 'Contactcatsync',
+      'parameters' => '',
+    ],
+  ],
+];
diff --git a/api/v3/Job/Contactcatsync.php b/api/v3/Job/Contactcatsync.php
new file mode 100644
index 0000000..e8f71c2
--- /dev/null
+++ b/api/v3/Job/Contactcatsync.php
@@ -0,0 +1,36 @@
+<?php
+
+use Civi\Api4\ContactCategory;
+
+/**
+ * Job.Contactcatsync API specification
+ *
+ * This ensures that the contact categories are applied each night. It is a simple wrapper
+ * around ContactCategory.Sync api4 action. It can be called hourly but the api4 activity
+ * will ensure it only runs once a day, around 3am (server timezone).
+ *
+ * @param array $spec description of fields supported by this API call
+ *
+ * @see https://docs.civicrm.org/dev/en/latest/framework/api-architecture/
+ */
+function _civicrm_api3_job_Contactcatsync_spec(&$spec) {
+}
+
+/**
+ * Job.Contactcatsync API
+ *
+ * @param array $params
+ *
+ * @return array
+ *   API result descriptor
+ *
+ * @see civicrm_api3_create_success
+ *
+ * @throws CRM_Core_Exception
+ */
+function civicrm_api3_job_Contactcatsync($params) {
+  $returnValues = ContactCategory::sync(FALSE)
+    ->execute()->getArrayCopy();
+
+  return civicrm_api3_create_success($returnValues, $params, 'Job', 'Contactcatsync');
+}
diff --git a/tests/phpunit/api/v3/Job/ContactcatsyncTest.php b/tests/phpunit/api/v3/Job/ContactcatsyncTest.php
new file mode 100644
index 0000000..2432e9a
--- /dev/null
+++ b/tests/phpunit/api/v3/Job/ContactcatsyncTest.php
@@ -0,0 +1,54 @@
+<?php
+
+use Civi\Test\CiviEnvBuilder;
+use Civi\Test\HeadlessInterface;
+use Civi\Test\HookInterface;
+use Civi\Test\TransactionalInterface;
+
+/**
+ * Job.Contactcatsync API Test Case
+ * This is a generic test class implemented with PHPUnit.
+ * @group headless
+ */
+class api_v3_Job_ContactcatsyncTest extends \PHPUnit\Framework\TestCase implements HeadlessInterface, HookInterface, TransactionalInterface {
+  use \Civi\Test\Api3TestTrait;
+
+  /**
+   * Set up for headless tests.
+   *
+   * Civi\Test has many helpers, like install(), uninstall(), sql(), and sqlFile().
+   *
+   * See: https://docs.civicrm.org/dev/en/latest/testing/phpunit/#civitest
+   */
+  public function setUpHeadless(): CiviEnvBuilder {
+    return \Civi\Test::headless()
+      ->installMe(__DIR__)
+      ->apply();
+  }
+
+  /**
+   * The setup() method is executed before the test is executed (optional).
+   */
+  public function setUp(): void {
+    parent::setUp();
+  }
+
+  /**
+   * The tearDown() method is executed after the test was executed (optional)
+   * This can be used for cleanup.
+   */
+  public function tearDown(): void {
+    parent::tearDown();
+  }
+
+  /**
+   * Simple example test case.
+   *
+   * Note how the function name begins with the word "test".
+   */
+  public function testApiExample() {
+    $result = civicrm_api3('Job', 'contactcatsync', array('magicword' => 'sesame'));
+    $this->assertEquals('Twelve', $result['values'][12]['name']);
+  }
+
+}