1C-Bitrix module

aacworkflow.aacsearch runs inside a Bitrix site. It reads the catalogue, queues every change and sends it to AACSearch through a connector. It also provides search, a smart filter, suggestions, recommendations and query analytics on the storefront. The module does not search by itself. The index, morphology, typo tolerance and recommendations live on the AACSearch side, so without a key the module installs but stays idle.

Requirements

On editions without catalog (Start), elements of information blocks are indexed, but prices and stock do not exist, so the rules about them do nothing and are hidden.

Install

The module is built for the Bitrix Marketplace but is not yet published there. Once it is: Marketplace → Installed solutions → Install. A build of the module (marketplace/build-last-version.sh --archive) produces the full package and an update package with the same contents.

Installation:

• creates the module tables;
• copies the components to /bitrix/components/aacsearch/, the admin pages to /bitrix/admin/ and the public endpoints to /bitrix/tools/aac.search/;
• registers the event handlers and the background agents;
• adds the URL rewrite rule for the storefront proxy at /aacsearch/api/.

The menu lives under Services → AACSearch. Updating from the Marketplace replaces the module files without running the installer. On the next admin hit the module detects the version change and repeats the idempotent install steps: files, the rewrite rule, events, agents and default settings. If any of these went missing, Diagnostics offers Complete the installation.

The agents run on Bitrix's own agent mechanism, on page hits or on a configured cron. A site with no visits and no cron does not sync.

Connect

There are two ways, and the key you paste decides which one the module uses.

Installation key (1.8.1+, recommended)

With an installation key, the settings page only has Connect, Check Console settings and Enable/Disable module. It shows the applied configuration revision and the latest error. Catalogue, search, recommendation and billing settings belong to the console. The InstallationAgent (every 30 seconds) reads the published configuration, applies it and acknowledges the revision, then starts the first full export of each bound source and runs console commands.

What the console switches do on the site:

Existing installations with an aac_sk_… key keep the classic settings page below. An installation key cannot call the tenant API or be used from another domain.

Classic API key and connector

Older installations use a server API key from Settings → API keys and the five-step Setup wizard: key, connection check, catalogue, first export, storefront. Connect on the first step does everything at once. It checks the connection, maps every product information block, creates the collection, provisions recommendation models and the assistant (best effort), creates the connector, and queues the first export.

The wizard creates a bitrix push connector for the primary collection and stores its id and secret. If the platform already has a bitrix connector for that collection but the site lost the secret, the wizard stops. Paste the id and secret from Sources into the settings instead. Until a connector is configured, the module falls back to a direct import, and Diagnostics reports the export route as a warning.

Settings page

The classic settings page is per site (a site switcher appears when there is more than one) and has five tabs.

General settings

Iblock mapping — which information block goes to which collection, with its search fields (query_by) and facet properties. Each row has a Reindex button.

What not to export — applied on every export. After changing a rule, run a reindex so it also applies to products already exported.

Security

One connector serves one collection. A store with several catalogues needs a connector per collection. Filling Connector collection keeps other information blocks off that connector, and they keep their previous route until they get their own.

Advanced

Buttons: Detect catalog automatically (adds missing mappings without overwriting existing ones) and Reindex all iblocks.

Initial and delta indexing

Every path into the index goes through the module's queue. The Sync queue page shows how many rows are pending, being processed or failed.

Deactivating an element, or leaving its active-date window, removes it from the index. A 1C exchange (OnSuccessCatalogImport1C) triggers a full check, because per-element events are unreliable after it. Changing a property definition reindexes that information block.

A failed row is retried after 0 s, 1 min, 5 min, 30 min and 2 h (±25% jitter), at most five times. Responses that retrying will not fix (400, 401, 402, 403, 404, 409, 413, 422) are not retried. The row stays failed until the cause is fixed and it is retried from the queue page.

For large catalogues, process the queue from cron instead of page hits (CLI only; the web request answers 404):

*/5 * * * * php /path/to/site/bitrix/tools/aac.search/queue_worker.php 1000

The worker and the agent share a lock, so a row is never processed twice.

Pull mode when the host blocks outgoing calls

Set Access token on the Security tab. Then create a connector in Sources with sync mode pull, pull URL https://your-site/bitrix/tools/aac.search/pull-outbox.php and the same token. The platform polls that URL on the connector's schedule, as described in Pull. pull-export.php uses a different protocol, and the platform's pull job does not read it.

Components

Components are in the visual editor under AACSearch. To switch a template, change the component namespace:

The rest: instant.search, search.app, assistant.chat, ai.assistant, no.results.assistant, product.advisor, image.search, voice.search, similar.products, seo.filter, seo.links, search.analytics, search.funnel.

Key parameters (all components also take SITE_ID; empty COLLECTION or IBLOCK_ID means the main one from settings):

All components support composite mode. Results and facets are dynamic zones, so the static cache does not serve stale prices. In edit mode (Hermitage), results get Edit and Delete buttons, checked against information block permissions.

Keys on the storefront

The module's server key (API key or installation key) never reaches a page. The storefront reaches AACSearch in one of two ways:

• Directly, with a browser key. The widget, the assistant chat and UI=Y blocks use a key the module mints with POST /browser-keys. It is search-scoped and limited to the site's collections and origins. It expires after at most seven days, and the hourly health agent renews it when less than two days remain. Its state is shown on the Widgets page.
• Through the site. Server-rendered components query AACSearch from PHP. Voice and image uploads go to /bitrix/tools/aac.search/media.php, and the widget proxy lives at /aacsearch/api/. Each of these is rate limited per IP and accepts only a fixed set of actions.

The browser never gets a full key, and never calls the search engine directly.

Widgets without editing the template. On the Widgets page, auto-injection (widget_autoinject, on by default in classic mode) adds one script to every public page. The script attaches suggestions to the standard bitrix:search.title box and replaces bitrix:search.page results with the widget's. Pages that already use aacsearch:instant.search are left alone. If autodetection misses, the selectors can be set by hand.

Smart filter

There are two ways to get facet counts from AACSearch.

Drop-in, no template changes. On Native search, Calculate the smart filter in AACSearch (native_filter, off by default; the Smart filters switch in installation mode) installs a thin subclass of the native component into /local/components/bitrix/catalog.smart.filter. Bitrix resolves the component there first, under the same bitrix:catalog.smart.filter call. The subclass loads the core class and component file and replaces only the facet source, so templates, markup and parameters stay the core's.

• Enumerable properties are counted by AACSearch, taking the visitor's current selection into account. Ranges (price, numeric properties) stay with the core.
• Counts arrive only for information blocks exported to AACSearch; others show native numbers.
• If the platform fails or a property is unknown, the filter still renders with the native counts.
• If another override already exists at that path, the module does not overwrite it and warns you. Clearing the box removes the subclass.

The neighbouring option, Select catalog products in AACSearch (native_catalog), installs subclasses of catalog.section, catalog.top, catalog.element and news.list the same way. The index picks the page of products, and the core still loads the elements and checks activity, dates and permissions. If an information block is not exported, a sort cannot be reproduced or the platform is down, the core does the selection.

Component. aacsearch:smart.filter renders its own form from the platform's facets. Next to aacsearch:search.results it takes the facets through the FACETS parameter and makes no extra request. On a section page, where no results are next to it, it queries AACSearch itself.

SEO filter pages

• SEO pages → filter page meta tags stores rules per information block. Each rule has title, description and similar templates with placeholders such as #SECTION#, #PROPERTY#, #VALUE#, #SECTION_CODE# and #SITE_DIR#. A rule containing an unknown placeholder is not saved.
• aacsearch:seo.filter renders a landing page for a filter combination. It looks up the prepared page for the current URL (or URL), and sets the title, description, keywords, robots and <link rel="canonical"> before <head> is printed. A combination is materialised lazily on its first visit, so its meta tags apply from the second visit.
• Page addresses use the human-readable filter form (/catalog/noutbuki/filter/brend-lenovo/apply/), built from the site directory, with the filter values sorted. The same conditions always give the same URL.
• The SEO pages admin page lists the generated pages, runs bulk generation and an audit, and exports a sitemap file. aacsearch:seo.links shows links to related filter pages.

Voice search

aacsearch:voice.search adds a microphone button. The browser records the audio and posts it to /bitrix/tools/aac.search/media.php. The module sends it to POST /collections/{collection}/documents/search/by_voice with its server key and returns the transcript and the hits. The button is shown only when all of these hold:

• Voice search is enabled (enable_voice_search, off by default);
• the plan includes voice_search and there are credits (voice is billed per audio minute, see credits);
• the page is served over HTTPS (browsers do not give microphone access otherwise).

Recommendations

aacsearch:recommendations shows a block for PRODUCT_ID of the chosen RECOMMENDATION_TYPE: similar, also_bought, personal, trending or recently_viewed. It requires enable_recommendations.

• With UI=Y (the default) the block is the platform element <aacsearch-recommendations>. It renders in the browser from platform models, using the browser key.
• With UI=N, or when no browser key is available, the module fetches the ids on the server and builds the cards from Bitrix (CardReader), with live prices and access checks.

The wizard provisions the models with fixed ids bitrix_<strategy>, so running it again does not duplicate them: similar → looking_similar, also-bought → bought_together, personal → session, trending → trending. Recently viewed is the visitor's own history, not a model. aacsearch:similar.products finds similar items from the search index by name and properties.

Troubleshooting

Start with Services → AACSearch → Diagnostics. It runs the checks (connection, environment, edition, information blocks, permissions, queue, secrets and the export route) and says what to fix. It also has Restore agents, Encrypt now and Complete the installation buttons. Then read Log: filter by level ("this and more severe"), source and text. Export refusals, failed API calls and secret errors all land there.

Support: support@aacsearch.com.