Create Sales Order Documentation by gurveenbagga · Pull Request #138 · saastechacademy/foundation

gurveenbagga · 2025-09-15T13:17:59Z

No description provided.

…son changes

gurveenbagga · 2025-09-15T13:23:01Z

project-ideas/order-ledger/createSalesOrder.md

    * Input Parameters
-        * orderJson (Map)
-2. Initialize orderContext
-3. Set following to orderContext


removed point 3, since this can be taken care of in mapping service, the input map to create#SalesOrder should already have these values set

gurveenbagga · 2025-09-15T13:48:16Z

project-ideas/order-ledger/createSalesOrder.md

+2. Validate order by checking OrderHeader.externalId to avoid duplication of order
+3. Initialize payload.roles list
+    * Call findOrCreate#Person for payload.customer
+    * Add [partyId:findOrCreatePersonOutput.partyId, roleTypeId:"SHIP_TO_CUSTOMER"] to payload.roles


I have observed the records for order roles to be created for all below roleTypeIds, do we need to create orderRoles for all roleTypeIds ?

Customer - BILL_TO_CUSTOMER, END_USER_CUSTOMER, PLACING_CUSTOMER, SHIP_TO_CUSTOMER

vendor - SHIP_FROM_VENDOR, BILL_FROM_VENDOR

good point.

We don't need all these roles.

Important question is:
What roles do we need?

I think, SHIP_TO_CUSTOMER is all we need.

Ship to and bill to

Thats all Shopify has

gurveenbagga · 2025-09-16T07:21:30Z

project-ideas/order-ledger/createSalesOrder.md

+            "attrDescription": ""
+        }
+    ],
+    "email": "abc@gmail.com",


added field to store for OrderContactMech with contactMechPurposeTypeId:"ORDER_EMAIL"

gurveenbagga · 2025-09-16T07:21:57Z

project-ideas/order-ledger/createSalesOrder.md

+        "partyId": "Doe",
+        "externalId": 22889483207024,
+        "first_name": "John",
+        "last_name": "Doe"


added customer map for basic info, if partyId does not exist, then we findOrCreate#Person

gurveenbagga · 2025-09-16T07:23:55Z

project-ideas/order-ledger/createSalesOrder.md

+        "longitude": -90.07084449999999,
+        "name": "John Doe",
+        "country_code": "US",
+        "province_code": "LA"


added billing_address map for OrderContactMechs BILLING_LOCATION, PHONE_BILLING and BILLING_EMAIL

Do we need this?

I am not saying no we don't.

But,

We know we are not billing from OMS. What is the purpose of tracking this data.

Some systems that we sync orders to occasionally require the customer's billing info along with their shipping info

gurveenbagga · 2025-09-16T07:24:18Z

project-ideas/order-ledger/createSalesOrder.md

+        "longitude": -90.07084449999999,
+        "name": "John Doe",
+        "country_code": "US",
+        "province_code": "LA"


added billing_address map for OrderContactMechs SHIPPING_LOCATION, PHONE_SHIPPING and SHIPPING_EMAIL

We have shipping location data on Ship group. Do we need it at the order level ?

Yes, this should go in shipGroup level. I will update this.

gurveenbagga · 2025-09-16T07:27:21Z

project-ideas/order-ledger/createSalesOrder.md

+                {
+                    "externalId": "100097001712202",
+                    "productId": "10022",
+                    "sku": "BLACK_BELL_BOTTOM_S",


Do we create product if productId missing in the json in order creation?

Same,

Application layer will do whatever it needs to ensure system runs predictably.

We know Shopify captured the order.
So the Product on OrderItem has to exist.

We should do whatever it takes to ensure order is recorded,

Then also prepare context information and log so support system can do its job.

what happens if we make order item without product linked to it?

gurveenbagga · 2025-09-16T07:29:06Z

project-ideas/order-ledger/createSalesOrder.md

+    ],
+    "shipGroups": [
+        {
+            "facilityId": "NEW_ERA_HARAJUKU",


Should we always expect facilityId i.e. OMS internal Id for the location for order creation?
As a generic API design rule, we can add facilityId and/or facilityExternalId, but if missing, do we return error and not create order?

the createOrder service in OMS will expect fully resolved data.

the createSalesOrder service is Shopify Integration application service. It has to take responsibility to resolve the data to ensure predictable results including graceful degradation.

patelanil · 2025-09-16T17:27:08Z

project-ideas/order-ledger/createSalesOrder.md

@@ -1,47 +1,210 @@
 ### co.hotwax.orderledger.order.OrderServices.create#SalesOrder (Application Layer - OMS)
-This service will take in the order JSON in OMSNewOrdersFeed and set up a complete order by performing any surrounding crud operations as needed.
+


I agree this service is application level service.

What if we define this service for now, in Shopify connector component.
for this conversation, Let's call it:
shopifyconnector.createSalesOrder

This service will have all the freedom to do whatever it takes to create JSON for createOrder service is OMS.

Later,
We can write worker class to do tasks that we may find reusable for other similar application layer service.

@gurveenbagga
What do you think?

We can do this for now, but yes later we may need to re-think it.

We have another use case to create exchange order wrt Return Exchange v2 work, where we will need oms layer application service to create order. OR NOW that I think of it, the service which will process shopify exchange order json will transform it and prepare the required JSON again for the create Order in OMS.

patelanil · 2025-09-16T17:37:19Z

project-ideas/order-ledger/createSalesOrder.md

-    * If orderJson.billToPhone
-        * Call create#ContactMech for [contactMechTypeId:"TELECOM_NUMBER", infoString:orderJson.billToPhone]
-        * Add [contatctMechId:createContactMechOutput.contactMechId, contactMechPurposeTypeId:"PHONE_BILLING"] to orderContext.contactMechs
+    * Add [partyId:ProductStore.payToPartyId, roleTypeId:"SHIP_FROM_VENDOR"] to payload.roles


If we have customer Party in our database, we may already have all these details.

lookup can be super expensive.

Is it better to just create on every next order by same person?

Or is there efficient algorithm to lookup / compare?

What if we create hash of the elements in contact mach and then compare the hash. We did similar thing in Product sync?

Or may be Shopify has some identifier like we have "contactMechId"

We are creating contact mechs for the order and not for customer. Do you mean we dont need to create the same address eg, shipping address in every order, and check if any way to re-use the same address id and just associate the order and the contact mech id?

but what if the customer updates his/her address? We are not syncing customer and address separately, I think its better to create the contact mechs (address, phone, email) with every order.

The OMS only stores customer information in relation to a single transaction. The only customer related detail re-used across orders is party id. This way, if we ever need to purge a customer from our system all we need to do is sanitize their party and person record without tampering with order related details like ship to address

patelanil · 2025-09-16T17:39:47Z

project-ideas/order-ledger/createSalesOrder.md

-4. Initialize orderContext.roles list
-    * Call findOrCreate#Person for orderJson.customer
-    * Add [partyId:findOrCreatePartyOutput.partyId, roleTypeId:"SHIP_TO_CUSTOMER"] to orderContext.roles
+        * payload (Map)


I believe we are using key word payload to represent the json, The actual JSON will be native to how Moqui service and API handles hierarchical parameters.

Yes this payload will be the order json which will be based on the spec of master of order JSON required by core create#org.apache.ofbiz.order.order.OrderHeader.

patelanil · 2025-09-16T17:45:41Z

project-ideas/order-ledger/createSalesOrder.md

+    "priority": "2",
+    "productStoreId": "STORE",
+    "salesChannelEnumId": "UNKNWN_SALES_CHANNEL",
+    "webSiteId": "WEBSTORE",


Use of attribute entity is good when there is no other option.

Today, we are reengineering our system.

We should spend sometime to understand,

Taxation on Sales order in Apache OFBiz.

better understanding will help consider changes in how we track tax authority details.

…into create-sales-order-doc

gurveenbagga added 2 commits September 15, 2025 18:27

Create Sales Order Documentation

f74fd03

Reverted the formatting changes of createOrder.md and kept only the j…

fa800ef

…son changes

gurveenbagga requested review from dt2patel and patelanil September 15, 2025 13:21

gurveenbagga marked this pull request as draft September 15, 2025 13:22

gurveenbagga commented Sep 15, 2025

View reviewed changes

gurveenbagga commented Sep 16, 2025

View reviewed changes

gurveenbagga marked this pull request as ready for review September 16, 2025 07:29

patelanil reviewed Sep 16, 2025

View reviewed changes

gurveenbagga and others added 4 commits December 9, 2025 21:55

Update identification type keys in createOrder.md

cf78427

Merge branch 'main' of https://github.com/saastechacademy/foundation …

7909059

…into create-sales-order-doc

Improved: Added Shopify Order Import Approach and design details

9c48eb2

Reverted the changes of creatOrder.md as it is pushed in a separate PR

f1b7f39

		@@ -1,47 +1,210 @@
		### co.hotwax.orderledger.order.OrderServices.create#SalesOrder (Application Layer - OMS)
		This service will take in the order JSON in OMSNewOrdersFeed and set up a complete order by performing any surrounding crud operations as needed.

Conversation

gurveenbagga commented Sep 15, 2025

Uh oh!

gurveenbagga Sep 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gurveenbagga Sep 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gurveenbagga Sep 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gurveenbagga Sep 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

gurveenbagga Sep 15, 2025 •

edited

Loading

gurveenbagga Sep 15, 2025 •

edited

Loading

gurveenbagga Sep 16, 2025 •

edited

Loading

gurveenbagga Sep 16, 2025 •

edited

Loading