bitbull/magento2-module-awseventbridge 0.2.1-beta

Magento 2 module for AWS EventBridge integration.

Magento 2 module AWS EventBridge integration

Send Magento events to Amazon EventBridge service to be able to integrate Magento with many different AWS serverless services.

Installation Instructions

Install this module using composer:

composer require bitbull/magento2-module-awseventbridge

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: - https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html

If your are running Magento locally, on-premises or with an other Cloud Provider different from AWS follow these steps:

1. Create a new AWS IAM User
2. Attach the created policy
3. 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 tracking property to data object.
• Enable debug mode if you want a more verbose logging in var/log/aws-eventbridge.log log 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.

These 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..

Events

This module inject observers to listen to Magento 2 events, elaborate the payload and then send the event to AWS services.

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: - https://docs.aws.amazon.com/eventbridge/latest/userguide/content-filtering-with-event-patterns.html

Data specification

Event will be pass data into Details event property:

(
    [sku] => WJ12-S-Blue
    [qty] => 1
)

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] => [email protected]
                )
            [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": "[email protected]"
}

UserLoggedOut An admin user logged out.

{
    "id": 1,
    "username": "admin",
    "email": "[email protected]"
}

UserLoginFailed An admin user failed login.

{
    "username": "admin"
}

Customers events

CustomerLoggedIn A customer user logged in.

{
    "id": 1,
    "email": "[email protected]"
}

CustomerLoggedOut A customer user logged out.

{
    "id": 1,
    "email": "[email protected]"
}

CustomerLoginFailed A customer user failed login.

{
    "username": "[email protected]",
    "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.

{
    "defaultBilling": "",
    "defaultShipping": "",
    "createdAt": "2020-08-24 00:00:00",
    "email": "[email protected]",
    "firstname": "Test",
    "gender": "",
    "id": 3,
    "lastname": "Test",
    "middlename": "",
    "prefix": "",
    "suffix": "",
    "addresses": []
}

CustomerSignedUpFailed A customer user failed sign up.

{
    "email": "[email protected]",
    "firstname": "Test",
    "lastname": "Test",
    "messages": [
        "customerAlreadyExistsErrorMessage"
    ]
}

Newsletter events

NewsletterSubscriptionChanged A customer user change newsletter subscription preference.

{
    "customerId": 1,
    "email": "[email protected]",
    "isSubscribed": true,
    "status": "SUBSCRIBED",
    "unsubscriptionLink": "https://..",
    "code": "1234"
}

{
    "customerId": 1,
    "email": "[email protected]",
    "isSubscribed": false,
    "status": "UNSUBSCRIBED"
}

Order events

OrderPlaced A customer place a new order.

OrderCreated / OrderUpdated An order was saved.

OrderCanceled An order was canceled.

OrderDeleted An order was deleted.

Invoice events

InvoiceCreated / InvoiceUpdated An invoice was saved.

InvoicePayed An invoice was payed.

InvoiceRegistered An invoice was registered.

OrderDeleted An invoice was deleted.

Credit Memo events

CreditmemoCreated / CreditmemoUpdated A credit memo was saved.

CreditmemoRefunded A credit memo was refunded.

CreditmemoDeleted A credit memo was deleted.

Shipment events

ShipmentCreated / ShipmentUpdated A shipment was saved.

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.