Skip to content

Commit 397c982

Browse files
IbochkarevIbochkarev
committed
Enhance documentation and CI workflows
- Added new jobs to the GitHub Actions CI for documentation synchronization, including checks for document structure and content consistency between English and Russian versions. - Updated various documentation files for clarity and accuracy, including changes to phrasing and structure in fronttabs, msppayu, webmoney, and flatfilters components. - Improved examples and descriptions in the mfilter snippets documentation for better usability.
1 parent d903699 commit 397c982

File tree

199 files changed

+20784
-1147
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

199 files changed

+20784
-1147
lines changed

‎.github/workflows/lint.yml‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,3 +34,49 @@ jobs:
3434
cache: 'pnpm'
3535
- run: pnpm install --frozen-lockfile
3636
- run: pnpm run spellcheck
37+
38+
docs-sync:
39+
runs-on: ubuntu-latest
40+
steps:
41+
- uses: actions/checkout@v4
42+
- uses: pnpm/action-setup@v4
43+
with:
44+
version: 9
45+
- uses: actions/setup-node@v4
46+
with:
47+
node-version: '20'
48+
cache: 'pnpm'
49+
- run: pnpm install --frozen-lockfile
50+
- run: node scripts/check-docs-sync.mjs
51+
52+
# Compare EN vs RU doc structure (##/### sections). Fails if EN has fewer sections — possible outdated translation.
53+
docs-structure-sync:
54+
runs-on: ubuntu-latest
55+
continue-on-error: true # Remove once baseline drift is fixed
56+
steps:
57+
- uses: actions/checkout@v4
58+
- uses: pnpm/action-setup@v4
59+
with:
60+
version: 9
61+
- uses: actions/setup-node@v4
62+
with:
63+
node-version: '20'
64+
cache: 'pnpm'
65+
- run: pnpm install --frozen-lockfile
66+
- run: node scripts/check-docs-structure-sync.mjs
67+
68+
# Content/volume diff for selected paths: EN must be within threshold of RU (lines/words). Catches point edits not ported to EN.
69+
docs-content-sync:
70+
runs-on: ubuntu-latest
71+
continue-on-error: true # Remove once baseline volume drift is fixed on critical paths
72+
steps:
73+
- uses: actions/checkout@v4
74+
- uses: pnpm/action-setup@v4
75+
with:
76+
version: 9
77+
- uses: actions/setup-node@v4
78+
with:
79+
node-version: '20'
80+
cache: 'pnpm'
81+
- run: pnpm install --frozen-lockfile
82+
- run: node scripts/check-docs-content-sync.mjs

‎docs/en/components/amoconnector/common-mistakes.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# Common mistakes
2+
3+
## Check that settings are filled
4+
5+
For miniShop2 orders:
6+
7+
- **amoconnector.enabled** — integration on
8+
- **amoconnector.client_id**, **amoconnector.client_secret**, **amoconnector.redirect_uri** — OAuth data
9+
- **amoconnector.subdomain** — amoCRM subdomain
10+
- **amoconnector.default_pipeline_id** — pipeline ID for orders
11+
12+
For forms additionally:
13+
14+
- **amoconnector.form_pipeline_id** — pipeline for forms (or set `default_pipeline_id`)
15+
- Hook `amoConnectorHook` added to FormIt call
16+
17+
## Correct subdomain
18+
19+
**amoconnector.subdomain** must be only the subdomain. For CRM at `mycompany.amocrm.ru` use `mycompany`, not the full URL.
20+
21+
## SSL error with Scheduler
22+
23+
When running Scheduler via cron (CLI) you may see:
24+
25+
```
26+
SSL certificate problem: self signed certificate in certificate chain
27+
```
28+
29+
This is due to missing `curl.cainfo` in the CLI php.ini. Find the CLI php.ini and add the path to CA certificates:
30+
31+
```ini
32+
curl.cainfo = "/path/to/cacert.pem"
33+
```
34+
35+
## OAuth token not received
36+
37+
If the component does not work after authorization:
38+
39+
1. Ensure **Redirect URI** in amoCRM matches `amoconnector.redirect_uri` exactly
40+
2. Clear MODX cache
41+
3. Authorize again from CMP
42+
43+
## Leads not created
44+
45+
Checklist:
46+
47+
1. **amoconnector.enabled** is on
48+
2. Test connection via the "Test" button on the Settings tab in CMP
49+
3. Open the **Log** tab in CMP — look for entries with `action = error`
50+
4. Check MODX log (core/cache/logs/error.log) for `[amoConnector]` errors
51+
5. Ensure pipeline ID is correct
52+
6. Clear cache and try again
53+
54+
## Duplicate leads
55+
56+
The component prevents duplicates: on order creation it checks `amo_order_link`. If the link exists, a new lead is not created. If duplicates still appear — check that `handleNewOrder()` is not called from custom code.

‎docs/en/components/amoconnector/events.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# Events
2+
3+
The component fires events so you can modify data before send or handle results:
4+
5+
## Leads
6+
7+
- **amoOnBeforeCreateLead** — before creating a lead. You can modify data or cancel
8+
- **amoOnCreateLead** — after lead is created
9+
- **amoOnBeforeUpdateLead** — before updating a lead (status change)
10+
- **amoOnUpdateLead** — after lead is updated
11+
12+
## Contacts
13+
14+
- **amoOnBeforeCreateContact** — before creating a contact. You can modify data or cancel
15+
- **amoOnCreateContact** — after contact is created
16+
17+
## Mapping
18+
19+
- **amoOnBeforeMapFields** — before field mapping
20+
- **amoOnAfterMapFields** — after field mapping
21+
22+
## Webhook
23+
24+
- **amoOnWebhook** — when webhook is received from amoCRM
25+
- **amoOnBeforeSyncStatus** — before syncing status from amoCRM to ms2
26+
27+
## Usage
28+
29+
Data is passed and modified via `$modx->event->returnedValues`. To cancel an operation return any value with `$modx->event->output()`.
30+
31+
```php
32+
switch ($modx->event->name) {
33+
case 'amoOnBeforeCreateLead':
34+
// Params: leadData, sourceType, sourceId, contactId
35+
$leadData = $modx->event->params['leadData'];
36+
37+
// Modify data
38+
$leadData['tags'][] = 'extra_tag';
39+
$modx->event->returnedValues['leadData'] = $leadData;
40+
41+
// Cancel lead creation
42+
// $modx->event->output('cancelled');
43+
break;
44+
}
45+
```

‎docs/en/components/amoconnector/field-mapping.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# Field mapping
2+
3+
The component uses a flexible field mapping system to send order and form data to amoCRM.
4+
5+
## Manager
6+
7+
Mapping is configured in CMP: **Apps** → **amoConnector** → **Field mapping** tab.
8+
9+
Each mapping row has:
10+
11+
| Field | Description |
12+
|-------|-------------|
13+
| **Context** | `order` (ms2 orders) or `form` (forms) |
14+
| **Source field** | Field name in MODX (e.g. `receiver`, `email`, `cost`) |
15+
| **Target entity** | `lead` or `contact` |
16+
| **Target field** | Standard amoCRM field (`name`, `email`, `phone`, `price`) or custom field ID |
17+
| **Active** | Enable/disable this mapping |
18+
19+
## Default mappings
20+
21+
On install, default mappings are created:
22+
23+
### Orders → Contact
24+
25+
| Source field | amoCRM field |
26+
|--------------|--------------|
27+
| `receiver` | `name` |
28+
| `email` | `email` |
29+
| `phone` | `phone` |
30+
31+
### Orders → Lead
32+
33+
| Source field | amoCRM field |
34+
|--------------|--------------|
35+
| `cost` | `price` (budget) |
36+
37+
### Forms → Contact
38+
39+
| Source field | amoCRM field |
40+
|--------------|--------------|
41+
| `name` | `name` |
42+
| `email` | `email` |
43+
| `phone` | `phone` |
44+
45+
## Available order fields
46+
47+
Inactive mappings for all available order fields are also created:
48+
49+
- **msOrder**: `num`, `cart_cost`, `delivery_cost`, `weight`
50+
- **Related**: `status_name`, `delivery_name`, `payment_name`
51+
- **msOrderAddress**: `country`, `index`, `region`, `city`, `metro`, `street`, `building`, `entrance`, `floor`, `room`, `comment`, `text_address`
52+
- **Synthetic**: `_products_text`, `_products_count`
53+
54+
To use them, open CMP, enable the needed fields and set target amoCRM fields.
55+
56+
## Custom amoCRM fields
57+
58+
To map to custom amoCRM fields, put the numeric field ID in **Target field**. Custom field IDs can be found in CMP (when loading from API) or in amoCRM.

‎docs/en/components/amoconnector/index.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
---
2+
title: amoConnector
3+
description: MODX integration with next-generation amoCRM
4+
logo: https://modstore.pro/assets/extras/amoconnector/logo.png
5+
author: biz87
6+
modstore: https://modstore.pro/packages/import-and-export/amoconnector
7+
8+
items: [
9+
{ text: 'Installation and setup', link: 'setup' },
10+
{ text: 'Submitting form data', link: 'submitting-forms' },
11+
{ text: 'Field mapping', link: 'field-mapping' },
12+
{ text: 'Status mapping', link: 'status-mapping' },
13+
{ text: 'Webhook', link: 'webhook' },
14+
{ text: 'Scheduler', link: 'scheduler' },
15+
{ text: 'Events', link: 'events' },
16+
{ text: 'Common mistakes', link: 'common-mistakes' },
17+
]
18+
---
19+
# amoConnector
20+
21+
Integration component for MODX Revolution sites with amoCRM. Built on the official amoCRM SDK and uses OAuth 2.0.
22+
23+
## Key features
24+
25+
- Auto-create leads from miniShop2 orders
26+
- Create leads from any form via FormIt hook
27+
- Contact deduplication by email and phone
28+
- Two-way order status sync via webhook
29+
- Flexible mapping of order/form fields to amoCRM via CMP
30+
- Map ms2 statuses to amoCRM pipeline stages
31+
- Optional deferred send via [Scheduler](/en/components/scheduler/)
32+
- Event system for plugins to modify data
33+
- Detailed operation log in the manager
34+
- Lead notes with order products or form data
35+
36+
## Quick start
37+
38+
For minimal setup, fill in system settings:
39+
40+
- **amoconnector.client_id** — Integration ID from amoCRM app settings
41+
- **amoconnector.client_secret** — Integration secret
42+
- **amoconnector.redirect_uri** — Redirect URI (must match amoCRM)
43+
- **amoconnector.subdomain** — amoCRM account subdomain (e.g. `mycompany` for `mycompany.amocrm.ru`)
44+
45+
Then complete OAuth in the component CMP.
46+
47+
## miniShop2 orders
48+
49+
After authorization set:
50+
51+
- **amoconnector.default_pipeline_id** — Pipeline ID for orders
52+
- **amoconnector.default_status_id** — Initial lead status in the pipeline
53+
- **amoconnector.enabled** — Enable integration
54+
55+
New ms2 orders will be sent as leads with linked contacts.
56+
57+
## Form data
58+
59+
To send form data, add the `amoConnectorHook` hook to your FormIt call:
60+
61+
```modx
62+
[[!FormIt?
63+
&hooks=`email,amoConnectorHook`
64+
&amoFormName=`callback`
65+
]]
66+
```
67+
68+
See "Submitting form data" for hook parameters.

‎docs/en/components/amoconnector/scheduler.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# Scheduler
2+
3+
The component can send data to amoCRM asynchronously via [Scheduler](https://modstore.pro/packages/utilities/scheduler) from modmore. This avoids delaying the server response when placing an order or submitting a form.
4+
5+
## Enabling
6+
7+
1. Install [Scheduler](https://modstore.pro/packages/utilities/scheduler)
8+
2. Enable **amoconnector.use_scheduler**
9+
3. Configure cron to run Scheduler:
10+
11+
```
12+
* * * * * php /path/to/site/assets/components/scheduler/run.php
13+
```
14+
15+
## How it works
16+
17+
With Scheduler enabled, orders and forms are processed in two steps:
18+
19+
1. **On event** (order created, form submitted, status changed) — data is queued in Scheduler
20+
2. **When cron runs** — Scheduler runs the task and data is sent to amoCRM
21+
22+
Tasks are created automatically on first use:
23+
24+
| Task | File | Description |
25+
|------|------|-------------|
26+
| `amoconnector_new_order` | `tasks/sendNewOrder.php` | Send new order |
27+
| `amoconnector_order_status` | `tasks/sendOrderStatus.php` | Order status change |
28+
| `amoconnector_form_submission` | `tasks/sendFormSubmission.php` | Send form data |
29+
30+
## Graceful degradation
31+
32+
If Scheduler is enabled in settings but not installed — the component falls back to synchronous send. A warning is written to the MODX log.
33+
34+
## Optimization
35+
36+
The component avoids unnecessary tasks:
37+
38+
- On order creation only the order send is scheduled. Initial status is not scheduled separately
39+
- Status change is scheduled only when there is a mapping for the new status and the order is linked to a lead
40+
41+
## Webhook
42+
43+
Incoming webhooks from amoCRM are always handled synchronously, regardless of Scheduler. Webhook is a server-to-server request and does not affect site UX.

‎docs/en/components/amoconnector/setup.md‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
# Installation and setup
2+
3+
## System settings
4+
5+
### amoCRM connection
6+
7+
| Name | Description |
8+
|------|-------------|
9+
| **amoconnector.enabled** | Global integration on/off |
10+
| **amoconnector.client_id** | Integration ID (from amoCRM app settings) |
11+
| **amoconnector.client_secret** | Integration secret |
12+
| **amoconnector.redirect_uri** | OAuth redirect URI (must match amoCRM) |
13+
| **amoconnector.subdomain** | amoCRM account subdomain (e.g. `mycompany` for `mycompany.amocrm.ru`) |
14+
15+
### Pipelines and statuses
16+
17+
| Name | Default | Description |
18+
|------|---------|-------------|
19+
| **amoconnector.default_pipeline_id** | | Pipeline ID for order leads |
20+
| **amoconnector.default_status_id** | | Initial lead status |
21+
| **amoconnector.form_pipeline_id** | | Pipeline for form leads. If empty, default pipeline is used |
22+
| **amoconnector.form_status_id** | | Status for form leads |
23+
| **amoconnector.responsible_user_id** | | Responsible user ID in amoCRM |
24+
25+
### Templates and tags
26+
27+
| Name | Default | Description |
28+
|------|---------|-------------|
29+
| **amoconnector.order_lead_name_tpl** | `Order #{num}` | Lead name template for orders. Placeholders: `{num}`, `{id}` |
30+
| **amoconnector.form_lead_name_tpl** | `Request: {form_name}` | Lead name template for forms. Placeholder: `{form_name}` |
31+
| **amoconnector.order_tags** | `miniShop2, site` | Tags for order leads (comma-separated) |
32+
| **amoconnector.form_tags** | `site form` | Tags for form leads (comma-separated) |
33+
34+
### Other
35+
36+
| Name | Default | Description |
37+
|------|---------|-------------|
38+
| **amoconnector.webhook_secret** | | Secret for webhook verification. Auto-generated on install |
39+
| **amoconnector.sync_statuses_from_amo** | `Yes` | Reverse sync: changing lead stage in amoCRM updates ms2 order status |
40+
| **amoconnector.use_scheduler** | `No` | Deferred send via Scheduler |
41+
| **amoconnector.log_retention_days** | `30` | Days to keep log entries |
42+
43+
## OAuth setup
44+
45+
### Step 1 — Create integration in amoCRM
46+
47+
1. Log in to amoCRM as admin
48+
2. Go to **Settings** → **Integrations** → **Create integration**
49+
3. Enter name, description and Redirect URI (your site URL)
50+
4. After creation copy **Integration ID** and **Secret key**
51+
52+
### Step 2 — Fill settings in MODX
53+
54+
Set `amoconnector.client_id`, `amoconnector.client_secret`, `amoconnector.redirect_uri` and `amoconnector.subdomain`.
55+
56+
### Step 3 — Authorize
57+
58+
Open the component CMP (**Apps** → **amoConnector**) and click the authorize button on the **Settings** tab. You will be redirected to amoCRM to grant access.
59+
60+
After success, tokens are stored and refreshed automatically.
61+
62+
## Manager (CMP)
63+
64+
The component adds **Apps** → **amoConnector** with tabs:
65+
66+
- **Operation log** — all sends, errors, skips with filtering
67+
- **Field mapping** — map order/form fields to amoCRM fields
68+
- **Status mapping** — map ms2 statuses to amoCRM pipeline stages
69+
- **Settings** — OAuth, connection test

0 commit comments

Comments
 (0)