Shipeezi

shipeezi

Reimagining eCommerce with Assistants - OpenAI GPT-4o Model plus Sitecore OrderCloud

Platforms: .NET When working on multi-language websites or apps, or we have to send personalized confirmation emails, we often store the text as a resource in resource files or a database. This way of working is great to let translators translate the text and the developer build the website/app. The text can hold different placeholders and the following Nuget Package (CodeHelper.Core.PlaceHolder) makes it easy to replace the placeholders with the value of the given object. PreRequisites CodeHelper.Core.PlaceHolder Example Text Let's use an order confirmation email Hi {CUSTOMERNAME},
 
Your order #{ORDERID} is confirmed and will be shipped out of our warehouse on {SHIPMENTDATE}
 
Total Details 
Number of items: {NBOFITEMS} 
Total amount: {TOTALAMOUNT}
 
Items:
{LISTOFITEMS} The OrderInfo Class Let's start with the class, containing the order info The only thing we need to do is Add using CodHelper.Core.PlaceHolder Add a Placeholder Attribute to the class properly A Placeholder Attribute requires the used in the text and optional the placeholder value (string) format (string) using CodeHelper.Core.PlaceHolder;

public class OrderInfo 
 { 
 [Placeholder("{ORDERID}")] 
 public Int64 ID { get; set; }

 public Int64 CustomerID { get; set; }

 [Placeholder("{CUSTOMERNAME}")] 
 public string CustomerName { get; set; } ="";

 [Placeholder("{SHIPMENTDATE}", "MMM dd, yyyy")]
 public DateTime DateShipmentDate { get; set; }

 public DateTime DateOrder{ get; set; }

 [Placeholder("{NBOFITEMS}", "#,##0")]
 public int NbShippedItems { get { return ShippedItemDescriptions.Count; } }

 [Placeholder("{TOTALAMOUNT}", "#,###,##0.00")]
 public double TotalAmount { get; set; }

 [Placeholder("{LISTOFITEMS}")]
 public List<string> ShippedItemDescriptions { get; set; } = new();
 
 public OrderInfo() { } 
 } The Code The replace string extension has the following parameters _order : object with the values false: Indicates if the text is an URL, if true, the empty parameters will be omitted, in our example it is not an URL, so false. FormatTypes.HTML: Text, HTML or Markdown (default: FormatTypes.TEXT) using CodeHelper.Core.PlaceHolder;

//-- get the order info
OrderInfo _order = new() { ID = 99876, DateShipmentDate = DateTime.Today.AddDays(1) 
 , TotalAmount = 1234.50
 , CustomerID=333
 , CustomerName ="CodeHelper"
 , DateOrder= DateTime.Today };
 _order.ShippedItemDescriptions.Add("Product Description #1");
 _order.ShippedItemDescriptions.Add("Product Description # 2");
 _order.ShippedItemDescriptions.Add("Product Description # 3");

//-- Get The Confirmation Email Text
string emailBody = Resources.Translations.EmailConfirmOrder

//-- Replace the placeholder inside the text with the values of 
//-- the _order object
emailBody = emailBody.Replace(_order, false, FormatTypes.HTML); Result: The email is ready to send... Hi CodeHelper, 
Your order #99876 is confirmed and will be shipped out of our warehouse on Sept 09, 2022
 
Total Details 
Number of items: 3 
Total amount: 1,234.50
 
Items:
<ul>
 <li>Product Description #1</li>
 <li>Product Description # 2</li>
 <li>Product Description # 3</li>
</ul> Advantages When the marketing team wants to change the confirmation email, add fields or translate to more languages, the code keeps working. In case of adding a placeholder, simply add the attribute to the field.

Replace the Placeholders in a Text With the Values of the Object

Introduction has become a prominent technology in implementing data APIs. It provides a convenient and intuitive approach for querying data. Let’s look at a sample use case using the programming language and see how GraphQL compares to other traditional approaches such as implementing REST-style HTTP APIs. GraphQL Ballerina Use Case: E-commerce Data Query Let’s take a typical e-commerce scenario of processing orders in an online store. The entity-relationship diagram below shows a typical representation that can be used in a relational database. This is of course a simplified representation of a real-life implementation. One approach for exposing such a data set would be to create a service with operations for each database table. This would be similar to the following. getOrder(id): OrderInfo getCustomer(id): CustomerInfo getShipper(id): ShipperInfo In this manner, we do get rather granular access to the data where we can query each table’s records as we need. However, we have to read the full table record at a time. If we have a large number of fields in a table, this may result in a larger message transported to the user, even if most of the fields may not be used by the application. This is an over-fetching scenario, but generally, it’s not a big problem in this type of situation. Now, let’s say the application needs to look up order details as well as the information about the customer. Then it needs to do two separate service operations “getOrder” and “getCustomer”. The following sequence diagram shows this interaction. Note that the service operations are done sequentially since we need the “OrderInfo” to look up the “customerId” to do the “getCustomer” operation. So for the application, this means two network round trips to look up both order and customer information. This becomes worse as we need more information, such as looking up “shipper” information also at once. For applications such as mobile apps where this communication is happening through a high-latency network, such as the Internet, it would hamper the user-experience. So ideally, we need to cut back on the number of service calls we do when a user interacts with an application. In order to reduce the number of service calls, we can have an operation such as “getFullOrderInfo” which will load all the data in connection with an order from the service and send them at once. This would definitely solve our multiple request problem. But, if we just have this single operation, even when we want to look up something like the order date, we will receive lots of unwanted data. This is a potentially problematic over-fetching scenario. If we want to properly fix this situation, we need separate individual operations for all the combinations that are possible, such as “getOrderAndCustomer”, “getOrderAndShipper”, etc. This is obviously not a practical solution for a service developer. If only there is an approach, where the application can dynamically query the service on which parts of the data set is required. This is exactly what GraphQL does. Solution: GraphQL In GraphQL, we can define an object graph in our service, where a client can query the specific fields of an object. These fields can be queried at any nested level. Optionally, we can pass in parameters for these fields as well. A definition of these objects for our use-case can be shown below. type Query {
   order(id: Int): Order
} Order {
   id: Int
   notes: String
   customer: shipper: Shipper
} {
   name: String
   address: } Shipper {
   name: String
   phone: String
} type Customer type Customer Address type The above is actually written in the GraphQL schema format used to define object types. GraphQL “Query” is a special object type, which must exist for the schema. This is basically the root level object that a user will query. So in GraphQL queries, we provide the fields inside the “Query” object to look up the required data. Provided that we have a GraphQL service with the schema above, we would send the following query to get a similar effect to our earlier “getOrder” operation. {
   order( ) {
       notes,
       date
   }
} id: 1 Here, we instruct our service to lookup the “order” field from the root query object and pass in ‘1’ as the value for parameter “id”. This field returns an object type, so we need to list all the fields we require from the object, where we provide “notes” and “date” above. If we need to only look up the date field, our GraphQL query would be the following. {
   order( ) {
       date
   }
} id: 1 We can drill into more fields and get their values as well. The following query, looks up full order information, including the customer and shipper information. {
   orders(id: 2) {
       notes,
       date, {
           name, },
       shipper {
           name,
           phone
       }
   }
} customer address Now that we understand the basics of how GraphQL works, let’s take a look at how to do the actual implementation using some code. We will use for this task. It is a programming language that has GraphQL as part of its built-in language-level services support. Ballerina Implementation: Ballerina GraphQL Services In Ballerina, the GraphQL object structure is modeled using services. A Ballerina GraphQL service contains resource methods that map to the fields of the GraphQL objects and work as resolver functions to provide its data. The GraphQL schema is automatically derived from this service structure and its resources. : GraphQL support is available from Ballerina Swan Lake release and onwards. NOTE The following code shows a simple GraphQL service we can write in Ballerina. import ballerina/graphql; graphql:Service /query on new graphql:Listener(8080) { function name() returns string {
       return ;
   }

} service resource get "Jack" The code above exposes a GraphQL service at the endpoint. Its GraphQL schema is similar to the following. { : String
} type Query name We can send the following GraphQL query to lookup the exposed “name” field in the root query object. { } name Let’s run the Ballerina code above for a sample test run. $ bal run demo.bal
Compiling demo.bal
Running executable
[ballerina/http] started HTTP/WS listener 0.0.0.0:8080 source A GraphQL request can be executed by sending an HTTP request similar to the following. $ curl -X POST -H -d http://localhost:8080/query
{ :{ : }} "Content-type: application/json" '{"query":"{name}"}' "data" "name" "Jack" The resource functions here can be provided with parameters to correlate with the GraphQL field parameters as well. Also, in the case of returning objects in fields, the resource method can return a service object to represent this. Let’s see how we implement our order information query scenario using a Ballerina service. We start with the Ballerina GraphQL service implementation, which represents the GraphQL root “Query” object fields. import ballerina/graphql;

service graphql:Service /query on graphql: {

   resource get 'order( id) 
                          returns Order load ;

} new Listener(8080) function int |error => Order( ) id Here, we have a single resource function “order”, which takes in the “id” parameter and returns an instance of the “Order” service class. The “loadOrder” function and the “Order” service class is implemented in the following way. function loadOrder(int id) returns Order| {
   stream<record{}, error> rs = dbClient->query(`SELECT id, customerId,
                                                 shipperId, date, notes ORDERS WHERE id = `, OrderData);
   var rec = check rs.next();
   check rs.close(); !(rec is ()) {
       return new Order(<OrderData> rec[ ]);
   } {
       return (string `Invalid order: `);
   }
} class Order {

   private OrderData data;

   function init(OrderData data) {
       self.data = data;
   } function notes() returns string {
       return self.data.notes;
   } function date() returns string {
       return self.data.date;
   } function customer() returns Customer| {
       return check loadCustomer(self.data.customerId);
   } function shipper() returns Shipper| {
       return check loadShipper(self.data.shipperId);
   }

} error FROM ${id} if "value" else error ${id} service resource get resource get resource get error resource get error Here, we execute the required SQL query to load the “Order” table data and populate the “Order” object. Note that, we do not also load “customer” and “shipper” information right away, but rather, these are loaded lazily if and when it is required as expressed through the incoming GraphQL query. The “loadCustomer” function shown below is used in the “customer” resource function to load the customer information from the database and populate a “Customer” object. function loadCustomer(int id) returns Customer| {
   stream<record{}, error> rs = dbClient->query(`SELECT id, name, WHERE id = `, CustomerData);
   var rec = check rs.next();
   check rs.close(); !(rec is ()) {
       return new Customer(<CustomerData> rec[ ]);
   } {
       return (string `Invalid customer: `);
   }
} class {

   private CustomerData data;

   function init(CustomerData data) {
       self.data = data;
   } function name() returns string {
       return self.data.name;
   } function address() returns string {
       return self.data.address;
   }

} error address FROM CUSTOMER ${id} if "value" else error ${id} service Customer resource get resource get Similarly, the “shipper” resource function is implemented to query the corresponding GraphQL object field. The full source code for the scenario above can be found . here Let’s do a test run using our full Ballerina service implementation. We are using a MySQL database to provide the data. Let’s create and populate the database first. Navigate to the “ordersvc” directory which contains the Ballerina package and the database script. $ mysql -u root -p < db.sql Let’s execute the default module of our Ballerina package in the following manner. $ bal run .
Compiling laf/ordersvc:0.1.0
Creating balo
        target/balo/laf-ordersvc-any-0.1.0.balo
Running executable
[ballerina/http] started HTTP/WS listener 0.0.0.0:8080 source Let’s send some GraphQL requests to the service. $ curl -X POST -H -d { : { : { : , : , : { : , : }, : { : , : }
       }
    }
}
$ curl -X POST -H -d { : { : { : , : { : , : }
       }
    }
} "Content-type: application/json" '{ "query": "{ order(id: 2) { notes, date, customer { name, address }, shipper { name, phone } } }" }' 'http://localhost:8080/query' "data" "order" "notes" "Street pickup" "date" "2021/01/25" "customer" "name" "Nimal Perera" "address" "No 22, Galle Road, Colombo 02" "shipper" "name" "UPS" "phone" "(408)275-4415" "Content-type: application/json" '{ "query": "{ order(id: 1) { notes, customer { name, address } } }" }' 'http://localhost:8080/query' "data" "order" "notes" "Doorstep delivery" "customer" "name" "Jack Smith" "address" "No 10, N 1st St, San Jose" Ballerina GraphQL services also support GraphQL introspection. For example, the following query can be executed to lookup the types available in the service. $ curl -X POST -H -d { : { : { : [{ : }, { : }, { : }, { : }, { : }, { : }, { : }, { : }, { : }, { : }, { : }]
       }
    }
} "Content-type: application/json" '{ "query": "{ __schema { types { name } } }" }' 'http://localhost:8080/query' "data" "__schema" "types" "name" "Order" "name" "__TypeKind" "name" "__Field" "name" "Query" "name" "__Type" "name" "Customer" "name" "Shipper" "name" "__InputValue" "name" "String" "name" "Int" "name" "__Schema" Summary GraphQL is a technology that makes data querying tasks much more efficient and intuitive for the users. Here, we have looked at how it solves potential problems such as data over-fetching and solves network latency problems that can arise in a services-based solution. Ballerina provides built-in support for implementing GraphQL services in a quick and easy manner, where the user can just concentrate on the business logic. For more information on Ballerina and its GraphQL support, check out the following resources: Ballerina by Example Ballerina API Documentation GraphQL Sample Also published at https://medium.com/ballerina-techblog/graphql-made-easy-with-ballerina-5ca04d9536d0

Stories, News & Mentions about SHIPEEZI

Shipeezi’s Stories on HackerNoon