bitbull / magento2-module-awseventbridge
Magento 2 module for AWS EventBridge integration.
Installs: 174
Dependents: 0
Suggesters: 0
Security: 0
Stars: 3
Watchers: 7
Forks: 2
Open Issues: 1
Type:magento2-module
Requires
- php: ~7.2.0|~7.3.0|~7.4.0
- aws/aws-sdk-php: ^3.110
This package is auto-updated.
Last update: 2024-11-19 22:54:52 UTC
README
Send Magento events to Amazon EventBridge service to be able to integrate Magento with many different AWS serverless services.
Contents
- Installation instructions
- IAM permissions required
- Setup
- Events
- Debug and local testing
- Contributing
Installation instructions
Install this module using composer:
composer require bitbull/magento2-module-awseventbridge
Execute Magento 2 Setup Upgrade:
bin/magento setup:upgrade [--keep-generated]
IAM permissions required
Create a new IAM Policy with these content:
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"events:PutEvents"
],
"Effect": "Allow",
"Resource": "*",
"Condition": {
"StringEquals": {
"events:source": "example.com"
}
}
}
]
}
change events:source according to your module configuration.
read more about IAM permissions at:
- https://docs.aws.amazon.com/en_us/AmazonCloudWatch/latest/events/auth-and-access-control-cwe.html
- https://docs.aws.amazon.com/en_us/AmazonCloudWatch/latest/events/policy-keys-cwe.html
If you are using EC2 instance add this policy to attached IAM Role.
read more about using IAM Role with EC2 at:
If your are running Magento locally, on-premises or with an other Cloud Provider different from AWS follow these steps:
- Create a new AWS IAM User
- Attach the created policy
- Generate access keys for the user
read more about creating IAM users at:
- https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html
- https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_change-permissions.html
- https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html
Setup
Go to "Stores" > "Configuration" > "Services" > "AWS EventBridge", then start configuring this module.
Credentials
You can set your access keys for IAM Users:
Retrieving from environment variables AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY:
Using EC2 Instance Role:
Options
Edit module options:
- Set the correct region where you want to receive events, for example "eu-west-1".
- Set event source name with a value that can be filtered (
events:source) when you connect to these events. - Set event bus name, leave empty to use your account default.
- Enable tracking to add
trackingproperty to data object. - Enable debug mode if you want a more verbose logging in
var/log/aws-eventbridge.loglog file. - Enable CloudWatch Events fallback to use this service instead of EventBridge (for backward compatibility).
- Enable dry run mode to activate the module actions and integrations without actually sending events data.
- Enable Queue mode to send events asynchronously using Magento queue instead of real-time (only available on Magento Enterprise edition).
If you enable the "Queue mode" you also need to enable cron consumer runner into your env.php
'cron_consumers_runner' => [ 'max_messages' => 5, 'cron_run' => true, 'consumers' => [ 'aws.eventbridge.events.send' ] ]
N.B. cron events are always executed synchronously without using queue.
Events
This module inject observers to listen to Magento 2 events, elaborate the payload and then send the event to AWS services.
Enable events
These option sections contain a list of supported events that can be activated and used to trigger Lambda functions, send event to an SNS topic, add message to SQS Queue, execute a StepFunction and so on. Enable events you want to receive to be able to trigger your EventBridge Rules.
Create an AWS EventBridge Rule
In order to connect to an EventBridge event and trigger a target you need to create an EventBridge Rule that match one or more events.
The event name is used in detail-type section of event data, so if you want to match "CartProductAdded" event you need to create a rule like this:
{
"source": [
"example.com"
],
"detail-type": [
"CartProductAdded"
]
}
remember to also match source name to avoid collision with different Magento environment.
You can also match multiple event names, for example if you want to react to all cart events:
{
"source": [
"example.com"
],
"detail-type": [
"CartProductAdded",
"CartProductUpdated",
"CartProductRemoved"
]
}
Is it possible to use a more specific matching rule in order to match, for example, all cart events related to a specific product sku:
{
"source": [
"example.com"
],
"detail-type": [
"CartProductAdded",
"CartProductUpdated",
"CartProductRemoved"
],
"detail": {
"sku": [
"WJ12-S-Blue"
]
}
}
read more about content-based filtering with Event Patterns at:
Data specification
Event will be pass data into Details event property:
(
[sku] => WJ12-S-Blue
[qty] => 1
)
Every event has a metadata property that contain date, timestamp and process mode of the event:
(
[metadata] => Array
(
[date] => 2020-08-26 08:51:18
[timestamp] => 1598431878
[async] => false // true if event was sent asynchronously using Magento Queue
)
)
Additionally (activating tracking option in backend options) every event will be enriched with tracking property that contain infos about client, session and framework, for example:
(
[sku] => WJ12-S-Blue
[qty] => 1
[tracking] => Array
(
[transport] => HTTP
[hostname] => f3a501ad4988
[time] => 1566594699836
[storeId] => 1
[version] => Array
(
[module] => dev-master
[php] => 7.1.27-1+ubuntu16.04.1+deb.sury.org+1
[magento] => 2.2.7
)
[user] => Array
(
[id] => 3
[username] => fabio.gollinucci
[email] => fabio.gollinucci@bitbull.it
)
[ip] => 172.17.0.1
[userAgent] => Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:68.0) Gecko/20100101 Firefox/68.0
)
)
when using Magento CLI user is based on the system user that execute the command:
(
[sku] => WJ12-S-Blue
[qty] => 1
[tracking] => Array
(
[transport] => SHELL
[hostname] => f3a501ad4988
[time] => 1566821355758
[storeId] => 1
[version] => Array
(
[module] => dev-master
[php] => 7.1.27-1+ubuntu16.04.1+deb.sury.org+1
[magento] => 2.2.7
)
[user] => Array
(
[name] => www-data
[passwd] => x
[uid] => 1000
[gid] => 33
[gecos] => www-data
[dir] => /var/www
[shell] => /usr/sbin/nologin
)
)
)
Supported Events
Here a list of supported events that can be enabled:
Cart events
CartProductAdded
A product is added to cart by a customer.
{
"sku": "abc-123",
"qty": 1
}
CartProductUpdated
A cart is updated by a customer.
{
"sku": "abc-123",
"operation": "add",
"value": 1,
"qty": {
"from": 1,
"to": 2
}
}
{
"sku": "abc-123",
"operation": "remove",
"value": 1,
"qty": {
"from": 2,
"to": 1
}
}
CartProductRemoved
A product is removed from cart by a customer.
{
"sku": "abc-123",
"qty": 2
}
Admin user events
UserLoggedIn
An admin user logged in.
{
"id": 1,
"username": "admin",
"email": "admin@example.com"
}
UserLoggedOut
An admin user logged out.
{
"id": 1,
"username": "admin",
"email": "admin@example.com"
}
UserLoginFailed
An admin user failed login.
{
"username": "admin"
}
Customers events
CustomerLoggedIn
A customer user logged in.
{
"id": 1,
"createdAt": "2020-08-24 00:00:00",
"email": "test@example.com",
"firstname": "Test",
"gender": "",
"lastname": "Test",
"middlename": "",
"prefix": "",
"suffix": ""
}
CustomerLoggedOut
A customer user logged out.
{
"id": 1,
"createdAt": "2020-08-24 00:00:00",
"email": "test@example.com",
"firstname": "Test",
"gender": "",
"lastname": "Test",
"middlename": "",
"prefix": "",
"suffix": ""
}
CustomerLoginFailed
A customer user failed login.
{
"username": "test@example.com",
"messages": [
"The account sign-in was incorrect or your account is disabled temporarily. Please wait and try again later."
]
}
CustomerSignedUp
A customer user sign up.
{
"id": 1,
"createdAt": "2020-08-24 00:00:00",
"email": "test@example.com",
"firstname": "Test",
"gender": "",
"lastname": "Test",
"middlename": "",
"prefix": "",
"suffix": ""
}
CustomerSignedUpFailed
A customer user failed sign up.
{
"email": "test@example.com",
"firstname": "Test",
"lastname": "Test",
"messages": [
"customerAlreadyExistsErrorMessage"
]
}
Newsletter events
NewsletterSubscriptionChanged
A customer user change newsletter subscription preference.
{
"customerId": 1,
"email": "test@example.com",
"isSubscribed": true,
"status": "SUBSCRIBED",
"unsubscriptionLink": "https://..",
"code": "1234"
}
{
"customerId": 1,
"email": "test@example.com",
"isSubscribed": false,
"status": "UNSUBSCRIBED"
}
Order events
OrderPlaced
An new order was placed.
{
"id": "000000001",
"status": "pending",
"coupon": null,
"billingAddress": {
"country": "IT",
"region": null,
"street": [
"via di test"
],
"city": "Test",
"postCode": "12345"
},
"shippingAddress": {
"country": "IT",
"region": null,
"street": [
"via di test"
],
"city": "Test",
"postCode": "12345"
},
"shippingAmount": 5,
"taxAmount": 0,
"total": 64,
"items":[{
"sku": "24-MB02",
"name": "Fusion Backpack",
"price": 59,
"qty": 1
}]
}
OrderCreated / OrderUpdated
An order was created or updated.
{
"id": "000000001",
"status": "pending",
"coupon": null,
"billingAddress": {
"country": "IT",
"region": null,
"street": [
"via di test"
],
"city": "Test",
"postCode": "12345"
},
"shippingAddress": {
"country": "IT",
"region": null,
"street": [
"via di test"
],
"city": "Test",
"postCode": "12345"
},
"shippingAmount": 5,
"taxAmount": 0,
"total": 64,
"items":[{
"sku": "24-MB02",
"name": "Fusion Backpack",
"price": 59,
"qty": 1
}]
}
OrderCanceled
An order was canceled.
{
"id": "000000001",
"status": "cancelled",
"coupon": null,
"billingAddress": {
"country": "IT",
"region": null,
"street": [
"via di test"
],
"city": "Test",
"postCode": "12345"
},
"shippingAddress": {
"country": "IT",
"region": null,
"street": [
"via di test"
],
"city": "Test",
"postCode": "12345"
},
"shippingAmount": 5,
"taxAmount": 0,
"total": 64,
"items":[{
"sku": "24-MB02",
"name": "Fusion Backpack",
"price": 59,
"qty": 1
}]
}
OrderDeleted
An order was deleted.
Invoice events
InvoiceCreated / InvoiceUpdated
An invoice was created or updated.
{
"orderId": "000000001",
"status": "OPEN",
"billingAddress":{
"countryId": "IT",
"region": null,
"street": [
"via di test"
],
"city": "Test",
"postCode": "12345"
},
"shippingAmount": "10.0000",
"taxAmount": 0,
"total": 77,
"items": [{
"sku": "WS12-M-Purple",
"name": "Radiant Tee",
"price": "22.0000",
"qty": 1
}]
}
InvoicePayed
An invoice was payed.
{
"orderId": "000000001",
"status": "PAID",
"billingAddress":{
"countryId": "IT",
"region": null,
"street": [
"via di test"
],
"city": "Test",
"postCode": "12345"
},
"shippingAmount": "10.0000",
"taxAmount": 0,
"total": 77,
"items": [{
"sku": "WS12-M-Purple",
"name": "Radiant Tee",
"price": "22.0000",
"qty": 1
}]
}
InvoiceRegistered
An invoice was registered.
{
"orderId": "000000001",
"status": "PAID",
"billingAddress":{
"countryId": "IT",
"region": null,
"street": [
"via di test"
],
"city": "Test",
"postCode": "12345"
},
"shippingAmount": "10.0000",
"taxAmount": 0,
"total": 77,
"items": [{
"sku": "WS12-M-Purple",
"name": "Radiant Tee",
"price": "22.0000",
"qty": 1
}]
}
OrderDeleted
An invoice was deleted.
Credit Memo events
CreditmemoCreated / CreditmemoUpdated
A credit memo was created or updated.
{
"orderId": "000000001",
"shippingAmount": 10,
"taxAmount": 0,
"total": 77,
"status": "OPEN",
"items": [{
"sku":"WS12-M-Purple",
"name":"Radiant Tee",
"price":"22.0000",
"quantity":1
}]
}
CreditmemoRefunded
A credit memo was refunded.
{
"orderId": "000000001",
"shippingAmount": 10,
"taxAmount": 0,
"total": 77,
"status": "REFUNDED",
"items": [{
"sku":"WS12-M-Purple",
"name":"Radiant Tee",
"price":"22.0000",
"quantity":1
}]
}
CreditmemoDeleted
A credit memo was deleted.
Shipment events
ShipmentSaved
A shipment was saved.
{
"id": "000000016",
"tracks": [{
"title": "DHL",
"carrier": "dhl",
"number": "123346457"
}],
"comments": [
"this is a comment"
],
"qty": 1,
"weight": null,
"items": [{
"sku": "MT07-M-Gray",
"name": "Argus All-Weather Tank",
"price": "22.0000",
"qty": 1
}]
}
ShipmentDeleted
A shipment was deleted.
Cache events
CacheFlushAll
An admin user flush the cache.
{}
CacheFlushSystem
An admin user flush system cache.
{}
CacheFlushCatalogImages
An admin user flush catalog images cache.
{}
CacheFlushMedia
An admin user flush media cache.
{}
CacheFlushStaticFiles
An admin user flush static files cache.
{}
Indexer events
StateSaved
An index change state.
{
"index": "catalog_product_price",
"status": "working"
}
{
"index": "catalogsearch_fulltext",
"status": "valid"
}
Debug and local testing
Module log are written in var/log/aws-eventbridge.log log file.
Enable "debug mode" option to increase logging level and retrieve more details about module operations.
[2020-08-26 10:49:36] report.DEBUG: Event 'User/LoginFailed' captured, executing.. [] []
[2020-08-26 10:49:36] report.DEBUG: Event 'User/LoginFailed' executed in 0.002s [] []
Enable "dry run mode" to test module without configuring credentials. This options skip AWS API call and allow you to test locally without need a AWS Account.
[2020-08-26 10:49:36] report.DEBUG: [DryRun] Sending event 'UserLoginFailed' with data: Array
(
[username] => admin@admin.com
[metadata] => Array
(
[date] => 2020-08-26 10:49:36
[timestamp] => 1598438976
[async] =>
)
)
[] []
[2020-08-26 10:49:36] report.DEBUG: [DryRun] Event 'UserLoginFailed' sent with id 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' [] []
Contributing
Any help is appreciated. If you want to contribute first read the contribution guide.