How To Call an AWS Lambda Function To Perform Customizations

This guide demonstrates how you can hook into the SoftSlate Cloud Platform (SCP) system and execute customizations using AWS Lambda. In this walkthrough, you'll learn how to set up a Site Function in SCP so that it calls an AWS Lambda function whenever an order is placed.

For this example, our use case is: whenever a new order is placed, we want to add a flag to prior orders that match the new order's delivery email address and products. The flag simply indicates that those prior orders have been superseded by the new order.

Note: The specifics of what we are doing are less important than illustrating the process. The goal is to show how you can hook into the SCP system and add custom functionality.

We'll create a Site Function that invokes an AWS Lambda function every time an order is updated. It sends the Lambda function information about both the prior state and the new state of the order, allowing you to implement your own workflow or logic as needed.

Create the AWS Lambda Function

First, we'll create the AWS Lambda function where our custom logic will live. If you're unfamiliar with AWS Lambda, there are many resources and examples available online to help you get started. You can use any runtime supported by Lambda, such as Node.js, Java, or Python.

Within your AWS account, follow these steps to set up the Lambda function and an IAM user permitted to invoke it. Note that the AWS interface may change over time, so these steps are a general guide.

1. Create a Lambda Function in the US-East-1 region.

2. On the Lambda Function's details screen, select Copy ARN and save the ARN for later.

3. Go to the IAM interface to create a new user with access to invoke the Lambda function:

   • Create a new User.

   • Select No for console access.

   • For permissions, choose Attach policies directly.

   • Click Create Policy.

     • Edit the policy in JSON and paste the following, replacing the resource ARN with your Lambda function's ARN:

     {
         "Version": "2012-10-17",
         "Statement": [
             {
                 "Effect": "Allow",
                 "Action": [
                     "lambda:InvokeFunction"
                 ],
                 "Resource": [
                     "arn:aws:lambda:us-east-1:000000000000:function:xxxxxxxxxxxxxxxxxxxx"
                 ]
             }
         ]
     }
     

     • Name your policy (e.g., "my-lambda-functions").

     • You can later use this same user with other Lambda functions by adding their ARNs to the permissions policy.

   • Back on the user creation screen, refresh the permissions policies and select your new policy.

   • Add an access key:

     • Find the user under IAM → Users, click into it, and select Security Credentials.

     • Under Access Keys, select Create Access Keys. On the next screen, select Other.

     • Create the access key and make a note of both the access key ID and the secret key for later steps.

Create an API User in SCP That the Lambda Function Can Use

In the SCP administrator, we need an API User that can query orders, order items, and save order settings. The Lambda function will use this account to make API requests back to SCP.

1. Under Operations → API Users, click the plus icon to create a new user.

2. For User Name, we suggest entering a descriptive name, such as "AWSLambdaUser".

3. For Api User Roles, select the following API Roles for the user:

   • Order Settings Editor (allows creating and updating order settings, which is how we set flags).

   • Orders Viewer.

   • Order Items Viewer.

4. Click Save Changes and make a note of the generated password for use in the following steps.

5. Create the user's encoded Basic Authentication token:

   • SCP supports Basic Authentication for API calls. To use it, Base64-encode the user's username and password in the format: username:password.

   • For example, if your username is FHOWIUHQOWIBNF and the password is EFBNGWEBUVWEINROWEINWIENGOFNOD, encode the string: FHOWIUHQOWIBNF:EFBNGWEBUVWEINROWEINWIENGOFNOD.

   • You can use many online tools or command-line utilities to do the encoding. For this example, the result might look like: RkhPV0lVSFFPV0lCTkY6RUZCTkdXRUJVVldFSU5ST1dFSU5XSUVOR09GTk9D.

   • Save the encoded value for later steps.

   Tip: You could also perform this encoding in the Lambda function itself by pasting the username and password there, but encoding it beforehand adds a small layer of obscurity.

Program the AWS Lambda Function

Add the following code to your AWS Lambda function. This code:

• Checks if the order status is changing to "Placed".

• Verifies that the new order includes one of the target items.

• Finds prior orders with the same delivery email and for the same items.

• Flags those prior orders as having been replaced by the new order.

You can paste this code directly into the AWS console under the function's Code tab, or follow their instructions for uploading code (e.g., via ZIP).

​x
const baseUrl = "https://YOUR-SCP-DOMAIN-NAME.com/api";
const basicAuthToken = "YOUR-API-USERs-ENCODED-BASIC-AUTH-TOKEN";

export const handler = async (event) => {
    let orderId = event.data.entity.orderId;
    let orderNumber = event.data.entity.orderNumber;
    let deliveryEmail1 = event.data.entity.deliveryEmail1;
    let changingToStatus = event.data.entity.status;
    let existingStatus = event.data.existingDto.status;

    let intFuncResponse = {};

    try {
        // Run only if the order is changing to PlacedOn status
        if (changingToStatus !== existingStatus && changingToStatus === 'Placed') {

            // Authentication headers for all API calls to SCP
            const apiCallHeaders = new Headers();
            apiCallHeaders.append("Content-Type", "application/json");
            apiCallHeaders.append("Authorization", "Basic " + basicAuthToken);

            // Check that the new order includes one of the specified items.
            let newOrderItemsUrl = baseUrl + "/orderItem/v1/list";
            let newOrderItemsData = {
                "filterString": "orderId=='" + orderId + "'",
                "additionalFilterString": "productCode=in=('PRODUCTCODE1','PRODUCTCODE2','PRODUCTCODE3')",
                "size": 1
            };
            let newOrderItemsString = JSON.stringify(newOrderItemsData);
            const newOrderItemsCallOptions = {
                method: "POST",
                headers: apiCallHeaders,
                body: newOrderItemsString
            };
            const newOrderItemsResponse = await fetch(newOrderItemsUrl, newOrderItemsCallOptions);
            console.info("Status from API call", newOrderItemsResponse.status);
            const newOrderItemsJsonResponse = await newOrderItemsResponse.json();
            console.info("Response from API call", newOrderItemsJsonResponse);
            if (!newOrderItemsJsonResponse.data || !newOrderItemsJsonResponse.data.searchList
                || newOrderItemsJsonResponse.data.searchList.length == 0) {
                console.log(`New order does not have one of the items.`);
                intFuncResponse.statusCode = 200;
                intFuncResponse.message = 'New order does not have one of the items.';
                return intFuncResponse;
            }

            // Load prior orders with the same delivery email for the same items and not cancelled
            let priorOrderUrl = baseUrl + "/order/v1/list";
            let priorOrderData = {
                "filterString": "deliveryEmail1=='" + deliveryEmail1 + "' and placedOn!=null and orderId!='" + orderId + "'",
                "additionalFilterString": "orderItems.productCode=in=('PRODUCTCODE1','PRODUCTCODE2','PRODUCTCODE3') and status!='Cancelled'",
                "size": 3
            };
            let priorOrderString = JSON.stringify(priorOrderData);
            const priorOrderCallOptions = {
                method: "POST",
                headers: apiCallHeaders,
                body: priorOrderString
            };
            const priorOrderResponse = await fetch(priorOrderUrl, priorOrderCallOptions);
            console.info("Status from API call", priorOrderResponse.status);
            const jsonResponse = await priorOrderResponse.json();
            console.info("Response from API call", jsonResponse);

            if (jsonResponse.data && jsonResponse.data.searchList && jsonResponse.data.searchList.length > 0) {
                intFuncResponse.statusFromAPICall = priorOrderResponse.status;
                intFuncResponse.statusCode = 200;
                intFuncResponse.searchListLength = jsonResponse.data.searchList.length;
                intFuncResponse.message = "";

                // Loop through prior orders (de-duplicating as needed)
                let previousOrderId = 0;
                for (let i = 0; i < jsonResponse.data.searchList.length; i++) {
                    let priorOrder = jsonResponse.data.searchList[i];
                    if (previousOrderId !== priorOrder.orderId) {
                        console.log(`Prior order number: ${priorOrder.orderNumber}, Prior order id: ${priorOrder.orderId}`);

                        // Create or update an order setting for the prior order
                        let orderSettingUrl = baseUrl + "/orderSetting/v1/createOrUpdate";
                        let orderSettingData = {
                            "orderId": priorOrder.orderId,
                            "code": "ReplacedByNewOrder",
                            "name": "Replaced By New Order",
                            "settingType": "PRIVATE",
                            "valueType": "BooleanValue",
                            "settingValue": "1",
                            "extra1": orderNumber
                        };
                        let orderSettingString = JSON.stringify(orderSettingData);
                        const orderSettingCallOptions = {
                            method: "POST",
                            headers: apiCallHeaders,
                            body: orderSettingString
                        };
                        const orderSettingResponse = await fetch(orderSettingUrl, orderSettingCallOptions);
                        console.info("Status from order setting API call", orderSettingResponse.status);
                        intFuncResponse.message += "Processed order number " + priorOrder.orderNumber + ", ";
                    }
                    previousOrderId = priorOrder.orderId;
                }
            } else {
                console.log(`No prior orders found`);
                intFuncResponse.statusFromAPICall = priorOrderResponse.status;
                intFuncResponse.statusCode = 200;
                intFuncResponse.message = 'No prior orders found';
            }
            return intFuncResponse;

        } else {
            console.log(`Order status not changing to Placed`);
            intFuncResponse.statusCode = 200;
            intFuncResponse.message = 'Order status not changing to Placed';
            return intFuncResponse;
        }
    } catch (e) {
        console.error(e);
        intFuncResponse.error = e;
        return intFuncResponse;
    }
};

Key notes about this Lambda function:

• Replace "YOUR-SCP-DOMAIN-NAME" with your SCP site's domain name, and "YOUR-API-USERs-ENCODED-BASIC-AUTH-TOKEN" with the Basic Auth token you created earlier.

• This example uses Node.js 18, but you can use any runtime environment supported by Lambda.

• The parameters event.data.entity and event.data.existingDto are incoming parameters for the function. They hold information about the order that was just updated and the prior state of the order, respectively.

• You can test your Lambda function in the AWS Console by creating test events. It’s a good idea to test with a variety of input objects to verify that it works as intended.

Create a Site Function in SCP To Communicate With Lambda

The final step is to register a Site Function in SCP. This function will be executed each time an order is updated. After the order update is saved, SCP will call out to your Lambda function.

To create the Site Function:

1. Click the plus icon from the main Site Functions screen, found under Operations → Site Functions and Jobs.

2. Click to use the full add form for Site Functions: Click here for the full Add Form.

3. For Function Event Type, select ENTITY_EVENT for this example.

4. For Entity Name, enter Order to indicate we are listening for when orders change.

5. For Entity Field, enter status to indicate we are listening for when order statuses changes.

6. For Entity Value, enter Placed to indicate we are listening for when order statuses change to Placed.

7. For Entity Event Type, select AFTER_SAVE to indicate our function should be triggered after an order's status changes to Placed.

8. For Function Location, select AWS_LAMBDA.

9. For Function Endpoint, enter the ARN for the Lambda function (use "Copy ARN" from the Lambda function details screen).

10. For Authentication Type, select AWS_CREDENTIALS.

11. For Key Value, enter the Access Key for the IAM user created earlier.

12. For Key Secret, enter the "Secret access key" for the IAM user from the previous step.

Here's a screenshot of the Site Function setup (without credentials):

If you follow these steps, you'll have a working integration between SCP and AWS Lambda, allowing you to run custom logic every time an order is updated. Feel free to tweak the Lambda code for your own workflow or business logic!