OroSmartInsightsBundle
OroSmartInsightsBundle provides the Smart Insights mode of OroIQ. It runs the DQL that the assistant writes through a restricted Doctrine entity manager that exposes only the entities and fields with the Include in Smart Insights option (include_in_smart_insights of the ai_agent entity config scope), with the ACL of the current user applied.
The entity structures contain the translated descriptions of the included entities and fields. The assistant receives only the entity descriptions.
Oro\Bundle\SmartInsightsBundle\Provider\SmartInsightsConfigProvider checks the stored Include in Smart Insights option together with the following rules:
Taggingis included only whenTagis included.ActivityListis included only when at least one activity entity ofOro\Bundle\ActivityListBundle\Provider\ActivityListChainProvideris included.An association field of
ActivityList, such as the link toLead, is included only when its target entity is included. WhenActivityListis included, its organization field is always included for the ACL walker.
The default allowlist includes Tagging, ActivityList, and their fields. An administrator can change the option of these entities and fields as for any other entity. A new activity association of ActivityList is not included automatically.
Query Security
Oro\Bundle\SmartInsightsBundle\ORM\Factory\DqlQueryFactory applies these layers in order:
The restricted entity manager.
Oro\Bundle\SmartInsightsBundle\ORM\SmartInsightsClassMetadataFactoryhides every entity and field that is not included in Smart Insights.The tree walkers of the
oro_smart_insights.dql_tree_walkersoption. They run before the ACL walker and see only the authored DQL. The default walkers of theOro\Bundle\SmartInsightsBundle\ORM\Walkernamespace reject internal entities (RejectInternalEntitiesWalker), UPDATE, DELETE, andSELECT *(EnforceSelectWalker), and fields without field-levelVIEWaccess (RestrictFieldAccessWalker).DqlQueryFactorysets theoro_smart_insights.field_acl_filterquery hint on every query.RestrictFieldAccessWalkerreads the field ACL filter from this hint.AclHelper::apply()with theVIEWpermission and thesmartInsightsoption, which adds the Smart Insights access rules.
Add a Tree Walker
The oro_smart_insights.dql_tree_walkers option is a list of tree walker classes. The walkers run in the listed order. Each configuration file appends its walker classes to the list. To add a walker, list its class in the config/config.yml file or in the Resources/config/oro/app.yml file of a bundle:
oro_smart_insights:
dql_tree_walkers:
- Acme\Bundle\DemoBundle\ORM\Walker\RejectArchivedRecordsWalker
Default Allowlist
The Oro\Bundle\SmartInsightsBundle\Migrations\Data\ORM\UpdateEntityConfigValues data fixture sets the default Include in Smart Insights values from Migrations/Data/ORM/data/smart_insights_entity_config.yml:
A listed entity is included with the fields under its
included_fieldskey. Its other fields are excluded. An entity listed with~is included without fields.A class without entity config is skipped, so the file can list entities of optional packages.
A previously included entity that is no longer listed gets
falsefor itself and its fields.
The fixture does not change a value that an administrator changed in Entity Management. Such changes are detected through the entity config audit log (the oro_entity_config_log_diff table), which the platform writes for changes made by a logged-in user. A value changed by an administrator at any time keeps its current value, even when a later version of the allowlist lists it differently.
The fixture is versioned, so an allowlist change takes effect with an increased fixture version. A run without changes persists and notifies nothing.
Feature Toggles
Feature toggles hide entities from the entity structures only. Oro\Bundle\SmartInsightsBundle\Provider\EntityStructureDataProvider omits an included entity listed in the entities resources of a disabled feature, and every association that targets it. The feature state is checked per request in the organization scope, falling back to the global scope. The back-office API has no current website. For this reason, website-level states are ignored. The stored option is not changed.
The restricted entity manager and the access rules ignore feature toggles. DQL that references an entity of a disabled feature runs with the ACL applied.
SmartInsightsConfigProvider checks the inclusion and the feature state with the following methods:
isIncludedInSmartInsightsEntity()andisIncludedInSmartInsightsField()— Check the inclusion of an entity or a field. They ignore feature toggles.isEntityAvailable()— Checks that an entity is included and is not listed in theentitiesresources of a disabled feature.isAssociationTargetAvailable()— Checks the target entity of an association field. The target entity must be enabled by feature toggles. For an association field ofActivityList, the target entity must also be included. The method returnstruefor a field that is not an association.
Entity Structure Invalidation
These Oro\Bundle\SmartInsightsBundle\EventListener listeners make the microservice re-fetch the entity structures:
IncludeInSmartInsightsAttrConfigListener— Wheninclude_in_smart_insightschanges, orfield_acl_enabledorshow_restricted_fieldsof an included entity. After every extend schema update. Aninclude_in_smart_insightschange and an extend schema update also clear the restricted entity manager metadata and query caches.InvalidateStructuresOnFeaturesChangeListener— When a feature with an included entity is toggled. No cache is cleared.InvalidateStructuresOnAclChangeListener— When root privileges or privileges of an included entity are saved for a user or for a role with assigned users. Storefront privileges are ignored.InvalidateStructuresOnRoleAssignmentListener— When user roles are reassigned or a role is deleted.
Internal Entities
An internal entity is hidden from the assistant but usable in access rule subqueries. SmartInsightsClassMetadataFactory provides it unfiltered, and RejectInternalEntitiesWalker rejects it in the authored DQL with RestrictedDqlException. An entity is internal when its class is in the internal entity list, by default SmartInsightsClassMetadataFactory::INTERNAL_ENTITIES with ActivityOwner.
To add internal entities, call setInternalEntities() on oro_smart_insights.orm.metadata_factory from a compiler pass. The call replaces the list:
$container->getDefinition('oro_smart_insights.orm.metadata_factory')
->addMethodCall('setInternalEntities', [[
...SmartInsightsClassMetadataFactory::INTERNAL_ENTITIES,
AgreementAssignee::class,
]]);
Smart Insights Access Rules
The regular access rules apply too. Rules tagged with smartInsights: true apply to Smart Insights queries only, because DqlQueryFactory passes the smartInsights option (DqlQueryFactoryInterface::SMART_INSIGHTS_ACCESS_RULE_OPTION) to AclHelper::apply(). Use them for entities that the UI shows only inside a visible parent record.
Registered oro_smart_insights.access_rule.* services:
activity_list(ActivityListSmartInsightsAccessRule) — Shows anActivityListrow if it has no owners or the user can view one of its owners. Hides activity types that are not included.tagging(TaggingSmartInsightsAccessRule) — Shows a tag assignment if the tagged record is visible and its entity is included.user_login_attemptandcustomer_user_login_attempt(AclResourceSmartInsightsAccessRule) — Hide login attempts unless theoro_user_login_attemptororo_customer_user_login_attemptACL resource, if defined, is granted. The Enterprise edition grants them in the global organization only.sales_customer,applied_promotion,applied_coupon, andapplied_discount(Oro\Bundle\SecurityBundle\AccessRule\AssociationAwareAccessRule) — Show a row only when its associated record is visible: a salesCustomerbyaccount, anAppliedPromotionorAppliedCouponbyorder, anAppliedDiscountbyappliedPromotion.promotion_ruleandpromotion_discount_configuration(ReferencingEntitySmartInsightsAccessRule) — Show aRuleor aDiscountConfigurationonly through a visiblePromotionthat references it, so shipping and payment method rules stay hidden. IfPromotionor its association is not included, all rows are denied.
Add an Access Rule
Tag the rule with oro_security.access_rule and smartInsights: true. Without this attribute, the rule also applies to every UI query of the entity. A rule that follows one association needs no class:
services:
acme_demo.access_rule.agreement_smart_insights:
class: Oro\Bundle\SecurityBundle\AccessRule\AssociationAwareAccessRule
arguments: ['customer']
tags:
- { name: oro_security.access_rule, type: ORM, entityClass: Acme\Bundle\DemoBundle\Entity\Agreement, smartInsights: true }
ReferencingEntitySmartInsightsAccessRule takes the referencing entity class, the association name, @doctrine, and @oro_smart_insights.provider.smart_insights_config. AclResourceSmartInsightsAccessRule takes the ACL resource ID as its third argument.
A custom rule implements Oro\Bundle\SecurityBundle\AccessRule\AccessRuleInterface. Create a subquery Criteria with isRoot set to false so the ACL walker applies the ownership rules of the subquery entity, and give it a unique alias so the authored DQL cannot reuse it. Every entity in a subquery must be included in Smart Insights or be an internal entity.