نحوه ساخت یک برنامه اتوماسیون سفارشی و رویداد-محور (اکشنهایی مثل ایمیل/پیامک/واتساپ/وبهوک همراه با شرطهای اجرا) و اتصال آن به موتور اتوماسیون LA24Core و گزارشهای اتوماسیون.
مرور کلی
یک "برنامه اتوماسیون" در واقع یک قانون قابلتنظیم است که از سه بخش تشکیل شده: یک **نوع** (چه چیزی آن را فعال میکند)، مجموعهای از **شرطها** (چه زمانی اجازه اجرا دارد) و مجموعهای از **اکشنها** (چه اتفاقی میافتد — ارسال ایمیل، ارسال پیامک، باز کردن تیکت، فراخوانی یک وبهوک و غیره). همهی انواع برنامه از یک جدول ذخیرهسازی، یک صفحه مدیریتی "برنامه جدید"، همان کلاسهای شرط، همان کلاسهای اکشن/رویداد و همان گزارشهای اتوماسیون استفاده میکنند — شما فقط بخشی را مینویسید که مختص محرک (trigger) خودتان است.
> **نکته:** موتور اتوماسیون بخشی از ماژول اتوماسیون LA24Core است. پیش از آزمایش، مطمئن شوید که این ماژول (یا ماژول تیکت که از همین موتور استفاده میکند) از مسیر **تنظیمات ← ارتقای سیستم** فعال شده باشد.

امضای هوک
php
apply_filters( 'la24_register_automation_program', array $program );**نوع:** Filter
**پارامترها:** `$program` (آرایه) — رجیستری انواع برنامه، با کلید یک رشته منحصربهفرد
**بازگشتی:** آرایه — رجیستری تغییریافته
کلاس پایه AutomationProgram
**کلاس پایهای که باید extend شود:**
`LoyalAxis\classes\services\automation\includes\abstracts\AutomationProgram` (انتزاعی)
هیچ interface جداگانهای برای پیادهسازی وجود ندارد — همین کلاس انتزاعی، قرارداد کامل است. این کلاس دو متد انتزاعی دارد که باید خودتان بنویسید، و سه متد آماده در اختیارتان میگذارد که تقریباً تمام کار واقعی را انجام میدهند:
| متد | خودتان مینویسید؟ | مسئولیت |
|---|---|---|
| `static get_settings( $settings, $program_type )` | **بله — انتزاعی** | HTML فرم تنظیمات را echo میکند؛ همان فرمی که هنگام ساخت/ویرایش یک برنامه از این نوع نمایش داده میشود |
| `static save_settings(): array` | **بله — انتزاعی** | از `$_POST` میخواند و آرایهای برمیگرداند که در ستون `settings` برنامه serialize میشود |
| `static full_get_settings( $settings, $shortcodes, $email_template, $form_id, $happens_item )` | فقط فراخوانی کنید | رابط شرطهای Profile/WooCommerce **و** رابط تنظیمات همهی اکشنها را رندر میکند |
| `static full_save_settings( $settings )` | فقط فراخوانی کنید | رابط شرطها **و** تنظیمات همهی اکشنها را از `$_POST` میخواند |
| `static execute_events( $settings, $profile_id, $type, $program_id, ... )` | فقط فراخوانی کنید | هر اکشنی را که ادمین فعال کرده اجرا میکند (ایمیل، پیامک، واتساپ، پیگیری، تیکت، وبهوک و غیره) |
گام ۱: ساخت کلاس اتوماسیون
php
<?php
namespace MyPlugin\Automations;
use LoyalAxis\classes\services\automation\includes\abstracts\AutomationProgram;
defined( 'ABSPATH' ) || exit;
class WelcomeNewUserAutomation extends AutomationProgram {
public function __construct() {
// محرک (trigger) شما — هر اکشن/فیلتر موجود در کدبیس کار میکند.
add_action( 'la24_user_register', array( $this, 'run' ) );
// این برنامه را در صفحه مدیریتی "برنامه جدید" قابلانتخاب میکند.
add_filter( 'la24_register_automation_program', array( $this, 'register_program_type' ) );
}
}هوک `la24_user_register` دقیقاً یکبار، بلافاصله پس از ساخت یک حساب کاربری جدید در CRM، با پارامتر
`$user_id` اجرا میشود — محرکی ساده و از پیش موجود که برای این مثال مناسب است. برای کاربرد واقعی خودتان
از هر هوکی که با نیازتان همخوانی دارد استفاده کنید (تغییر وضعیت سفارش، ارسال فرم، تیک زمانی cron و غیره).
گام ۲: پیادهسازی get_settings()
برای برنامهای که فیلد اختصاصیای فراتر از شرطها/اکشنهای مشترک ندارد، این متد فقط یک فراخوانی ساده است:
php
public static function get_settings( $settings, $program_type ) {
AutomationProgram::full_get_settings( $settings, la24_available_shortcodes_message() );
}`la24_available_shortcodes_message()` مجموعه پایه شورتکدهای پیام (نام پروفایل، شماره تماس، لینک و غیره)
را برمیگرداند که در اختیار همه برنامهها قرار دارد. اگر پیامهای شما به توکنهای اضافی نیاز دارند، پیش از
پاس دادن این آرایه، شورتکدهای اختصاصی خودتان را به آن اضافه کنید (برای نمونه به
`AutomationAbandonedCart::get_settings()` در برنامه اتوماسیون سبد خرید رهاشده ماژول WooInvoice نگاه کنید
که شورتکدهایی مثل `#cart_items#`/`#cart_total#` اضافه میکند).
گام ۳: پیادهسازی save_settings()
php
public static function save_settings(): array {
return AutomationProgram::full_save_settings( array() );
}اگر برنامه شما فیلدهای اختصاصی دارد (زمان انتظار، انتخاب مقصد و غیره)، پیش از پاس دادن به
`full_save_settings()` آنها را بخوانید و پاکسازی (sanitize) کنید:
php
public static function save_settings(): array {
$settings = array();
$settings['some_custom_field'] = sanitize_text_field( $_POST['some_custom_field'] ?? '' );
return AutomationProgram::full_save_settings( $settings );
}گام ۴: ثبت نوع برنامه
php
public function register_program_type( $program ) {
$program['welcome_new_user'] = array(
'name' => __( 'خوشآمدگویی به کاربر جدید', 'my-crm-ext' ),
'call_back' => '\MyPlugin\Automations\WelcomeNewUserAutomation',
);
return $program;
}| فیلد | نوع | توضیح |
|---|---|---|
| کلید (کلید آرایه) | string | شناسه منحصربهفرد نوع برنامه؛ همان مقداری که در پایگاهداده بهعنوان `program_type` ذخیره میشود |
| `name` | string | برچسبی که در منوی کشویی نوع، در صفحه "برنامه جدید" نمایش داده میشود |
| `call_back` | string | نام کامل کلاس (با namespace) — باید از `AutomationProgram` extend شده باشد |
**نکته مهم:** صفحه مدیریتی "برنامه جدید" فقط متدهای `$call_back::get_settings()` و
`$call_back::save_settings()` را بهصورت **استاتیک** فراخوانی میکند — هیچوقت از کلاس شما نمونه (instance)
نمیسازد. اگر کلاس شما به `add_action()` اختصاصی خودش نیاز دارد (مثل گام ۱)، باید حداقل یکبار بهصورت
صریح از آن نمونه بسازید، مثلاً از کلاس اصلی هوک پلاگین خودتان:
php
new \MyPlugin\Automations\WelcomeNewUserAutomation();گام ۵: اجرای برنامه و بررسی شرطها
php
use LoyalAxis\classes\services\automation\includes\AutomationUtility;
use LoyalAxis\classes\services\automation\includes\SettingsAutomation\ProfileLogic;
use LoyalAxis\classes\services\automation\includes\SettingsAutomation\WooCommerceLogic;
public function run( $user_id ) {
$programs = AutomationUtility::get_automation_by_type( 'welcome_new_user' );
foreach ( $programs as $program ) {
if ( (int) $program->program_status !== 1 ) {
continue; // برنامه توسط ادمین غیرفعال شده است
}
$settings = unserialize( $program->settings );
if ( WooCommerceLogic::run( $settings, $user_id, 'user' ) ) {
continue; // شرط میگوید: این اجرا را رد کن
}
if ( ProfileLogic::run( $settings, $user_id, 'user' ) ) {
continue;
}
AutomationProgram::execute_events( $settings, $user_id, 'user', $program->id );
}
}ثبت شرطها
برای حالتهای متداول نیازی به نوشتن کلاس شرط جدید نیست — از دو کلاسی که فریمورک از پیش ارائه میدهد
استفاده کنید؛ هر دو در گام ۲/۳ از طریق `full_get_settings()`/`full_save_settings()` بهطور خودکار متصل شدهاند:
| کلاس | بررسی میکند | امضا |
|---|---|---|
| `SettingsAutomation\ProfileLogic` | نقش کاربر، فیلدهای سفارشی پروفایل، فیلدهای فرم مسئول | `::run( $settings, $profile_id, $type ): bool` |
| `SettingsAutomation\WooCommerceLogic` | سابقه خرید — خریدن/نخریدن یک محصول یا دسته، تعداد سفارش، مبلغ خرجشده، تازگی خرید | `::run( $settings, $profile_id, $type ): bool` |
هر دو با بازگشت `true` یعنی **این اجرا را رد کن**. مقدار `$type` یکی از `'user'` یا `'clue'` (سرنخ CRM) است؛
اگر محرک شما پروفایل قابلشناسایی ندارد، `$profile_id` را خالی پاس دهید — هر دو کلاس، مقدار خالی را
"مانعی برای اجرا نیست" در نظر میگیرند.
فقط زمانی کلاس شرط اختصاصی بنویسید که برنامه شما به بررسیای نیاز دارد که هیچکدام از این دو پوشش نمیدهند
(از `SettingsAutomation\abstracts\SettingsAutomation` extend کنید و کلاس خود را دقیقاً مانند گام ۵ فراخوانی کنید).
ثبت اکشنها
اکشنها ("رویدادها") نیز استفاده مجدد میشوند، نه بازنویسی. `full_get_settings()`/`full_save_settings()`
(گامهای ۲–۳) از پیش رابط کاربری همه اینها را رندر و ذخیره میکنند؛ `execute_events()` (گام ۵) هرکدام را که
ادمین در چکلیست "چه اتفاقی میافتد؟" فعال کرده اجرا میکند:
| کلید `happens` | اکشن |
|---|---|
| `email` / `sms` / `whatsapp` | ارسال پیام به گیرنده مشخصشده (پروفایل / کاربران خاص / نقش / مسئول) |
| `followup` | ایجاد پیگیری (Follow-up) |
| `card` | ایجاد کارت در کانبان |
| `responsible` | تخصیص یک کاربر مسئول |
| `ticket` | باز کردن تیکت |
| `targetgroup` | افزودن پروفایل به گروه هدف |
| `notification` | ارسال اعلان درونبرنامهای/پوش |
| `salesopportunity` | ایجاد فرصت فروش |
| `webhook` | ارسال JSON به یک آدرس تنظیمشده |
نحوه اجرا
۱. بخشی از کد شما متد محرک (گام ۵) را با یک پروفایل/موجودیت برای ارزیابی فراخوانی میکند.
۲. شما برنامههای فعال از نوع خودتان را میخوانید و روی آنها حلقه میزنید.
۳. برای هر برنامه فعال، `WooCommerceLogic::run()` / `ProfileLogic::run()` تصمیم میگیرند که آیا اجرا رد شود یا نه.
۴. پیش از اجرا، هر شورتکد اختصاصی برنامه خودتان را در `$settings` جایگزین میکنید (مثلاً `#cart_total#` را با مقدار واقعی جایگزین میکنید).
۵. `AutomationProgram::execute_events()` هر اکشنی را که ادمین فعال کرده اجرا میکند: گیرنده را مشخص و پیام را ارسال/رکورد را ایجاد میکند.
۶. گزارشهای اتوماسیون کل این اجرا را بهطور خودکار ثبت میکنند — بدون نیاز به کد اضافی (به بخش زیر مراجعه کنید).
زمانبندی با Cron (اختیاری)
فقط زمانی لازم است که برنامه شما باید **بعداً** اجرا شود نه بلافاصله — مثلاً «۳۰ دقیقه صبر کن» یا «هر چند
دقیقه یکبار بررسی کن که آیا چیزی قدیمی/رهاشده است». بهجای `wp_schedule_event()` خام، از
`LoyalAxis\classes\services\cronjob\CronManager` استفاده کنید تا اجرا در لاگ cron قابلمشاهده برای ادمین ثبت شود:
php
use LoyalAxis\classes\services\cronjob\CronManager;
$cronManager = new CronManager();
// بررسی تأخیری یکباره، بهازای هر موجودیت:
$cronManager->register_cron_job( 'my_delayed_welcome_cron', time() + 1800, false, array( $user_id ) );
// یا یک اسکن تکرارشونده (بهجای ثبت یک زمانبندی جدید، از زمانبندی ۵ دقیقهای موجود استفاده کنید):
$cronManager->register_cron_job( 'my_recurring_scan_cron', time() + 300, 'la24_every_5_min', array() );سپس `add_action( 'my_delayed_welcome_cron', ... )` / `add_action( 'my_recurring_scan_cron', ... )` را به
متدی متصل کنید که همان منطق بررسی شرط و سپس `execute_events()` از گام ۵ را تکرار میکند.
`register_cron_job()` بهطور خودکار از ثبت تکراری جلوگیری میکند، بنابراین فراخوانی مکرر آن (مثلاً روی هر
`init`) کاملاً بیخطر است.
یکپارچگی با گزارشهای اتوماسیون
چیزی برای ساختن نیست. متد `AutomationProgram::execute_events()` از پیش هوکهایی را اجرا میکند که ماژول
گزارشهای اتوماسیون LA24Core به آنها گوش میدهد — بهمحض اینکه برنامه شما این متد را فراخوانی کند، هر اجرا
و نتیجه تکتک اکشنها (موفق/ناموفق/در انتظار) بهطور خودکار:
- در جداول اجرا/رویداد گزارشهای اتوماسیون ثبت میشود
- در داشبورد گزارشهای اتوماسیون و آمار هر برنامه قابلمشاهده است
- مانند هر برنامه دیگری بر اساس نوع/شناسه برنامه شما قابلفیلتر است
مثال کامل: خوشآمدگویی به کاربر جدید
یک برنامه کامل، مینیمال و آماده کپیکردن: پیام ایمیل/پیامک/... تنظیمشده را برای هر کاربر جدید CRM ارسال
میکند، با رعایت کامل شرطهای استاندارد.
php
<?php
namespace MyPlugin\Automations;
use LoyalAxis\classes\services\automation\includes\abstracts\AutomationProgram;
use LoyalAxis\classes\services\automation\includes\AutomationUtility;
use LoyalAxis\classes\services\automation\includes\SettingsAutomation\ProfileLogic;
use LoyalAxis\classes\services\automation\includes\SettingsAutomation\WooCommerceLogic;
defined( 'ABSPATH' ) || exit;
class WelcomeNewUserAutomation extends AutomationProgram {
public function __construct() {
add_action( 'la24_user_register', array( $this, 'run' ) );
add_filter( 'la24_register_automation_program', array( $this, 'register_program_type' ) );
}
public function register_program_type( $program ) {
$program['welcome_new_user'] = array(
'name' => __( 'خوشآمدگویی به کاربر جدید', 'my-crm-ext' ),
'call_back' => '\MyPlugin\Automations\WelcomeNewUserAutomation',
);
return $program;
}
public function run( $user_id ) {
$programs = AutomationUtility::get_automation_by_type( 'welcome_new_user' );
foreach ( $programs as $program ) {
if ( (int) $program->program_status !== 1 ) {
continue;
}
$settings = unserialize( $program->settings );
if ( WooCommerceLogic::run( $settings, $user_id, 'user' ) ) {
continue;
}
if ( ProfileLogic::run( $settings, $user_id, 'user' ) ) {
continue;
}
AutomationProgram::execute_events( $settings, $user_id, 'user', $program->id );
}
}
public static function get_settings( $settings, $program_type ) {
AutomationProgram::full_get_settings( $settings, la24_available_shortcodes_message() );
}
public static function save_settings(): array {
return AutomationProgram::full_save_settings( array() );
}
}
new WelcomeNewUserAutomation();آزمایش برنامه شما
۱. در پنل مدیریت CRM به صفحه **خودکارسازی** بروید و روی **برنامه جدید** کلیک کنید.
۲. برچسب `name` که ثبت کردید (گام ۴) در منوی کشویی **نوع** ظاهر میشود — آن را انتخاب کنید.
۳. حداقل یک اکشن (مثلاً ایمیل) را در بخش "چه اتفاقی میافتد؟" فعال کنید، پیام آن را پر کنید و با
**وضعیت = فعال** ذخیره کنید.
۴. محرک خود را فعال کنید (در این مثال: ثبت یک کاربر جدید در CRM).
۵. **گزارشهای اتوماسیون** را باز کنید و مطمئن شوید اجرای جدیدی برای برنامه شما ظاهر شده و اکشن(های)
فعالشده با وضعیت `success` علامت خوردهاند.

مرجع سریع
| هدف | هوک/کلاس | نوع |
|---|---|---|
| ثبت یک نوع برنامه | `la24_register_automation_program` | Filter |
| کلاس پایه برای یک برنامه | `AutomationProgram` (`abstracts/AutomationProgram.php`) | کلاس انتزاعی |
| یافتن برنامههای فعال بر اساس نوع | `AutomationUtility::get_automation_by_type( $type )` | متد استاتیک |
| رندر رابط مشترک شرطها + اکشنها | `AutomationProgram::full_get_settings(...)` | متد استاتیک |
| پردازش رابط مشترک شرطها + اکشنها | `AutomationProgram::full_save_settings(...)` | متد استاتیک |
| بررسی شرط "خرید/مبلغ خرجشده" | `WooCommerceLogic::run( $settings, $profile_id, $type )` | متد استاتیک |
| بررسی شرط "نقش/فیلد" | `ProfileLogic::run( $settings, $profile_id, $type )` | متد استاتیک |
| اجرای همه اکشنهای فعال | `AutomationProgram::execute_events(...)` | متد استاتیک |
| زمانبندی با لاگ قابلمشاهده برای ادمین | `CronManager::register_cron_job(...)` | متد کلاس |
| یکپارچگی با گزارشهای اتوماسیون | *(خودکار — نیازی به فراخوانی هوک نیست)* | — |