Integrate your Manhattan Active solution with common third party services such as tax calculations, promotions, and payment processing. Additional capabilities beyond what is available in the existing apps can be addressed by the services project team.

2.1 - Manhattan Active® Omni

Manhattan Active® Omni Integration Apps

Integrate your Manhattan Active Solution with common third party services such as tax calculations, promotions, and payment processing. Additional capabilities beyond what is available in the existing apps can be addressed by the services project team.

Please select a category from the list below for a summary of functionalities within the category. Within each category, select the third party vendor to understand what app functionalities are currently available.

2.1.1 - Alternate Payments

Manhattan Active Omni solutions provide clients the ability to manage the payment processing of an order paid for with alternative payment methods to traditional credit card and gift cards, such as buy now and pay later or secure digital wallets. Throughout the life cycle of each order, MAO uses the token information for the alternative payment method to process authorizations, settlements, and refunds through integration with the 3rd party payment gateway.

Manhattan Active Omni has pre-built apps with many 3rd party Alternative Payment Gateways for one or more of the above functionalities which can be leveraged out of the box. Please see each 3rd party vendor to view what functionalities are available.

Third Party Integrations

2.1.1.1 - Afterpay

What is Afterpay?

Afterpay is a payment processor which enables retailers to offer their customers the option to place an order now and pay in four installments with one installment due on order placement.

What does this integration include?

Manhattan Active Omni is not integrated with Afterpay out of the box. This integration enables communication with Afterpay version 2 by altering the base functionality in the following ways:

Capture: Performs a capture (settlement) against an authorization. Multiple captures against the authorization are supported.
Refund: Full or partial refunds.
Void: Perform a void against an authorization. Afterpay only supports voiding the full authorization or if a payment has been partially captured then the remainder of the authorization.
Update Shipping Courier: Updates Afterpay with a record of a fulfillment.

Capture

Manhattan Active Omni sends a capture request to Afterpay after a quantity is shipped for the shipment invoice amount. For split shipments, Manhattan Active Omni sends multiple capture requests against the single initial authorization and the order’s Afterpay transaction ID.

Refund

Manhattan Active Omni sends a refund request to Afterpay in the cases of return order creation after the entire authorization is captured as well as appeasements/adjustments created after the entire authorization is captured. Afterpay supports full or partial refunds against the order’s Afterpay transaction ID.

Void

Manhattan Active Omni sends a void request to Afterpay in the case that the order is cancelled, or the order completes with a final order total lesser than the initial order total. Afterpay only supports a full void of the remainder of an authorization, therefore the void amount is always sent for the difference between the initial and final order totals (which is $0 in the case of an order cancellation).

Update Courier

Manhattan Active Omni sends the shipping details to Afterpay as items ship using the Update Shipping Courier API, which allows Afterpay to provide better customer service.

2.1.1.2 - Amazon Pay

What is Amazon Pay?

Amazon Pay is an industry-leading payment solution that integrates with order creation host systems to handle payment processing for specific tenders. Amazon Pay is a commonly used online payment processing service that is owned by Amazon. Amazon Pay gives customers the option to pay with Amazon accounts on external merchant websites.

What does this integration include?

Manhattan Active Omni is not integrated with Amazon Pay out of the box. This integration enables communication with Amazon Pay using ILS Core version 6.05 by altering the base functionality in the following ways:

Advanced Authorization
Settlement
Refund
Notifications

This integration does not include Authorization or Void transactions and Amazon Pay is not an available payment tender through Manhattan Active Omni call center (imported orders only).

Advanced Authorization

MAO generates an Advanced Authorization synchronous call to Amazon Pay in the event of a split shipment. Amazon Pay accepts only one settlement record per authorization. Therefore, if a split shipment occurs and is settled in the same day, MAO obtains a new authorization for the remaining amount for that payment tender on the order.

Settlement

MAO generates synchronous settlement requests to Amazon Pay, in the Amazon Pay expected format, for open shipment invoices requiring capture. MAO is responsible for receiving the response and updating the payment transaction appropriately.

Refund

MAO generates synchronous refund requests to Amazon Pay, in the Amazon Pay expected format, for open refund invoices (for returns and appeasements) requiring capture. MAO is responsible for receiving the response and updating the payment transaction appropriately.

Notifications

In the event Amazon Pay initially sends MAO a capture or refund pending response, Amazon Pay later sends an asynchronous message containing the final transaction decision. This message is passed to MAO in JSON format, with the expectation that it is translated by a middleware. MAO is responsible for consuming the JSON message from a MAO queue and updating the payment transaction appropriately.

2.1.1.3 - Klarna

What is Klarna?

Klarna is a payment provider that allows customers to pay for orders in installment plans.

What does this integration include?

Manhattan Active Omni is not integrated with Klarna out of the box. This integration enables communication with Klarna by altering the base functionality in the following ways:

Capture funds
Refund
Release Authorization
Cancel

Capture

MAO generates synchronous settlement requests to Klarna, in the Klarna expected format, for open shipment invoices requiring capture. MAO is responsible for receiving the response and updating the payment transaction appropriately.

Cancel

When the order is cancelled prior to any part of it being shipped, Active Omni generates a cancellation call to Klarna.

Release Authorization

Release Authorization transactions occur anytime the remainder on the order has been cancelled after an initial capture is received. When the remaining unshipped order is cancelled, an authorization reversal transaction is generated. If this transaction amount is equal to the remaining to be paid, a void transaction is generated to Klarna to inform that this amount is no longer due by the customer.

Refund

MAO generates synchronous refund requests to Klarna in the Klarna expected format, for open refund invoices (for returns and appeasements) requiring capture. MAO is responsible for receiving the response and updating the payment transaction appropriately.

2.1.1.4 - PayPal

What is PayPal

PayPal is an online payment platform that facilitates payments between individuals and businesses.

Fueled by a fundamental belief that having access to financial services creates opportunity, PayPal (NASDAQ: PYPL) is committed to democratizing financial services and empowering people and businesses to join and thrive in the global economy. Our open digital payments platform gives PayPal’s 325 million active account holders the confidence to connect and transact in new and powerful ways, whether they are online, on a mobile device, in an app, or in person.

What does this integration include?

This integration enhances the current MAO out of box integration with PayPal as follows:

To process full authorization reversals for the following scenarios:
- Cancelling an order
- Performing an order edit which results in the full or remaining authorization amount being voided. This can include cancelling an order line, applying an appeasement, reducing an order line quantity, etc.
To process re-authorization of funds once the honor period expires but within the authorization validity period.

This integration implements additional functionality for Manhattan Active Omni (MAO) Point of Sale (POS) & ECOM / Call Center card payment flows with PayPal’s payment platform. The features include:

POS Omni Cart Sale
Follow On Refund
POS Refund by Card Entry
POS Mid Transaction Void
POS Post Void
POS End of Day Reconciliation
Contact Center Hosted Checkout
Authorization
Re-authorization
BOPIS Card on File

What is PayPal DoVoid?

PayPal is used as a payment method for placing an order on the retailer’s website. During the order creation, an authorization is performed by the merchant that applies a hold on the buyer’s funds which is typically valid for 29 days. PayPal allows settlement i.e., capturing less than the original authorization, full authorization amount, or even more than the authorization amount (up to 115% of the original authorization or $75 USD more, whichever is less).

However, during the order lifecycle if an order edit results in the full or partial authorized amount being voided then the funds can be released via a DoVoid call to PayPal.

MAO provides an out of box integration with PayPal using REST Service APIs for Signature and Certificate mode to process the payment transactions for Settlement and Refund. However, during scenarios when order edits result in the authorized amount being reversed to the buyers account, base MAO generates an authorization reversal transaction but does not send it to PayPal, or any Payment Gateway out of the box as a result of which the customer amount is held and unavailable for use till the authorization expires.

This feature adds the ability for MAO to send a PayPal DoVoid call to reverse (releases) complete or partial authorization amount on the buyer’s account when an authorization reversal is generated.

What is PayPal DoAuthorization?

For PayPal, an authorization places a hold on the funds and is valid for 29/90 days. After a successful authorization, PayPal recommends that you capture the funds within the honor period. Success of the capture is subject to risk and availability of funds on the authorized funding instrument.

Within the 29/90-day authorization period, a client can issue multiple re-authorizations after the honor period expires. A re-authorization generates a new authorization ID and restarts the honor period, and any subsequent capture should be performed on the new authorization ID. This feature adds logic for MAO to send the reauthorization API to PayPal.

POS OMNI-Cart Sale

This feature allows the POS application to process card present payment capture (settlement) for Pay & Carry lines and card not present payment authorization for Save the Sale lines with a single swipe of a credit card.

Follow-On Refund

Refunds are executed in MAO to process returns or negative exchanges. The Follow-on Refund, or Referenced Refund, refunds the original card that was used to execute the sale without the card being present. This applies to both POS and Call Center flows.

POS Refund by Card Entry

Refund by Card Entry, or Unreferenced Refund, refunds the card that is entered in the payment terminal via insert, tap or swipe, at the time of the transaction being executed. This flow applies only to POS not Call Center.

Note standalone refunds by card token is not required for this App since PayPal’s transaction tokens do not expire and therefore all card not present refunds can be processed as follow-on refunds using transaction token regardless of the age of the return.

POS Mid-Transaction Void

This feature allows the store user to void or cancel a partial card payment applied to a POS transaction.

POS Post Void

This feature allows the POS application to reverse payments captured for a Pay & Carry Sale transaction that was completed and later post voided. Post Void is permitted only on the same business day as the original Sale.

POS End of Day Reconcilation

This feature allows POS to determine and record the result of an abandoned payment in order for the Cancel Order process to reverse it. Cancel Order process reverses any payments that were captured for orders that are eventually voided.

Contact Center Hosted Checkout

This feature allows the Contact Center application to capture a credit card payment method for an order which upon confirmation of the order is used to Authorize payment for that order. Card information is entered on an iframe that is hosted on the PayPal gateway and is tokenized by PayPal before returning to MAO.

Authorization

This feature allows MAO to Authorize funds for an order using a tokenized payment method. The funds authorized are to be captured upon fulfilment.

Re-Authorization

This feature allows MAO to obtain a new authorization in scenarios where a previous authorization expires before funds are captured for the same.

BOPIS Card on File

This feature allows the POS application to leverage an existing credit card payment method to complete a card not present charge for Pay & Carry orderlines added in-store to a BOPIS order upon fulfilment.

2.1.2 - Address Verification

Manhattan Active Omni solutions provide clients the ability to verify entered addresses across Manhattan solutions to prevent bad data and to ensure timely delivery by leveraging integration with an external Address Verification Service provider.

Manhattan Active Omni has pre-built apps with many 3rd party AVS providers which can be leveraged out of the box. Please see each 3rd party vendor to view what functionalities are available.

Third Party Integrations

2.1.2.1 - Avalara

What is Avalara?

Avalara is an industry-leading tax solution that integrates seamlessly with host systems to handle all tax calculation needs for eCommerce.

What does this integration include?

Manhattan Active Omni is not integrated with Avalara out of the box. This integration enables communication with Avalara by altering the base functionality in the following ways:

Address verification request is sent in Avalara acceptable format when a user enters a shipping address in the Customer Service UI

Address Verification (AVS)

This feature adds integration with Avalara from Manhattan Active Omni to validate addresses entered in the Point of Sale and Contact Center applications. This support is provided for any address values that are entered initially or edited by the Point of Sale or Contact Center modules.

When a user adds or modifies an address in the Manhattan Active Omni Contact Center or POS, a web service call is made to Avalara AVS containing the address information captured by the UI. A response is received from Avalara AVS that indicates whether the address that was entered can be fully verified or if recommended address(es) are present as alternatives. These values, if returned, are displayed to the user in the UI for confirmation.

This feature is not extended to include other values that may be offered during verification such as email addresses or billing addresses. This feature is also not applied to orders interfaced into Manhattan Active Omni from external systems

2.1.2.2 - Experian QAS

What is EXPERIAN QAS?

Experian QAS is an address verification and email verification vendor who provides services to enable verification of customer shipping addresses and emails to ensure accurate data. This module provides integration with this vendor tool to augment the Manhattan Active Omni system and enable these verifications.

What does this integration include?

Manhattan Active Omni is not integrated with QAS AVS out of the box. This integration enables communication with QAS AVS by altering the base functionality in the following ways:

Address verification request is sent in QAS acceptable format when a user enters a shipping address in the Customer Service UI or POS UI
Email address verification request is sent in QAS acceptable format when a user enters an email address in the Customer Service UI

This feature is not extended to include other values that may be offered during verification such as billing addresses. This feature is also not applied to orders interfaced into Manhattan Active Omni from external systems.

Address Verification (AVS)

When a user adds or modifies an shipping address in the Manhattan Active Omni Contact Center or POS, a web service call is made to Experian QAS containing the address information captured by the UI. A response is received from Experian QAS that indicates whether the address that was entered can be fully verified or if recommended address(es) are present as alternatives. These values, if returned, are displayed to the user in the UI for confirmation.

Email Address Verification

When the CSR/User adds or edits email address on the customer order through Manhattan Call Center UI or through Manhattan Customer Engagement UI, a web service call is made to Experian QAS containing the email address information captured by the UI. A response is received from Experian QAS that indicates whether the email address that was entered was verified or not. If the Experian QAS system is unable to verify the email address or if it is incorrect, an error is displayed on the Manhattan UI confirming that the email address was not verified or is incorrect. User can then edit the email address or ignore and proceed

2.1.2.3 - Loqate

What is Loqate?

Loqate is an address verification vendor and leading specialist for location data. Their solutions provide customers with the capability to verify addresses at the point of capture via API and cleanse customer data via batch processing. The global API covers 130 address formats, 3000+ languages, and 245 countries and territories.

What does this integration include?

Manhattan Active Omni is not integrated with Loqate AVS out of the box. This integration enables communication with Loqate AVS by altering the base functionality in the following ways:

Uses the International Batch Cleanse (v1) API within the Data Cleanse product suiteto validate shipping addresses entered initially or edited within the Call Center application

Verification for imported order addresses, billing addresses, phone numbers, and email addresses are not supported within this feature.

Delivery Address Verification (AVS)

When a user adds or modifies a shipping address in the Manhattan Active Omni Contact Center, a web service call is made to Loqate containing the address information captured by the UI. A response is received from Loqate that indicates whether the address that was entered can be fully verified or if a recommended address is present as alternative. When the Loqate cleanse API returns one or more results, the address pop-up is shown. When multiple addresses are returned in the web service response with acceptable data match scores, the Call Center user is presented with the option to select between the original address and the highest quality address match from Loqate. If the API request is not successfully processed to Loqate, or if a response is returned with an error code or an indicator that the address does not meet necessary verification standards, the AVS pop-up displays with failure message. No recommended address is provided in these failure scenarios

2.1.2.4 - Strikeiron

What is Strikeiron?

Strikeiron Address Verification (acquired by Informatica) is the only service that combines postal certifications in one engine from all six global postal organizations: USPS, Canada Post, La Poste in France, New Zealand Post, Australia Post, and Eircode in Ireland. It’s able to parse, analyze, verify, correct, and format addresses according to local postal standards—ensuring that correct elements appear in the appropriate hierarchical alignment. Only with the right address format can you be sure a mailing gets to its addressee.

What does this integration include?

Manhattan Active Omni is not integrated with Strikeiron AVS out of the box. This integration enables communication with Strikeiron AVS by altering the base functionality in the following ways:

Address verification request is sent in Strikeiron acceptable format when a user enters a shipping address in the Customer Service UI

Address Verification (AVS)

When a user adds or modifies an shipping address in the Manhattan Active Omni Contact Center, a web service call is made to Strikeiron containing the address information captured by the UI. A response is received from Strikeiron that indicates whether the address that was entered can be fully verified or if recommended address(es) are present as alternatives. These values, if returned, are displayed to the user in the UI for confirmation

2.1.2.5 - UPS

What is UPS AVS?

UPS Address Validation System APIs enable Manhattan Active Omni to check a customer’s address and provide suggested alternatives if an error is discovered. This helps the clients reduce operating costs and improve customer service by primarily reducing the chances of mis-shipped orders.

What does this integration include?

Manhattan Active Omni is not integrated with UPS AVS out of the box. This integration enables communication with UPS AVS by altering the base functionality in the following ways:

Address verification request is sent in UPS acceptable format when a user enters a shipping address in the Customer Service UI

Address Verification (AVS)

When a user adds or modifies an shipping address in the Manhattan Active Omni Contact Center, a web service call is made to UPS containing the address information captured by the UI. A response is received from UPS that indicates whether the address that was entered can be fully verified or if recommended address(es) are present as alternatives. These values, if returned, are displayed to the user in the UI for confirmation

2.1.3 - Credit Card Payments

Manhattan Active Omni solutions provide clients the ability to manage the payment processing of an order paid for by credit card . The card number must be tokenized where the corresponding token is stored within MAO. Throughout the life cycle of each order, MAO uses the card token to process authorizations, settlements, and refunds through integration with the 3rd party payment gateway.

Manhattan Active Omni has pre-built apps with many 3rd party Credit Card Payment Gateways for one or more of the above functionalities which can be leveraged out of the box. Please see each 3rd party vendor to view what functionalities are available.

Third Party Integrations

2.1.3.1 - Alliance (ADS)

What is ADS?

ADS, or ‘Alliance Data Systems’ is a provider of integrated credit and marketing services including Private Label, co-branded and commercial credit card programs.

What does this integration include?

Manhattan Active Omni is not integrated with Alliance out of the box. This integration enables communication with Alliance Private Label payment processing by altering the base functionality in the following ways:

Authorization (XML)
Authorization Reversal (XML)
Refund Authorization (XML)
Account Lookup (XML)
End of Day Settlement File (FLAT)
Re-send Mechanism for End of Day Settlement File (via MAO UI)

Authorization

An authorization is required to reserve funds to cover the cost of the transaction. This typically occurs during order capture. For Private Label Credit Cards, a call center agent uses the call center screens in MAO to capture the card details. This feature adds the ability for MAO to send the authorization request in the ADS required format via SOAP HTTP web service APIs and update the order based on the response from ADS.

Authorization Reversal

An authorization reversal occurs when a merchant reverses the authorization step of the transaction, before settlement has begun. Manhattan Active Omni (MAO) creates internal authorization reversals when the order total decreases. This feature adds the ability for MAO to externalize the authorization reversal transactions when the full amount on the auth is being reversed in case of an order cancelation. MAO sends the ADS required format via SOAP HTTP web service APIs when an auth reversal is required.

Refund

A refund is generated when compensation is owed to a customer. This is typically triggered by a return, uneven exchange, or appeasement. This feature adds the ability for MAO to send the refund request in the ADS required format via SOAP HTTP web service APIs and update the order based on the response from ADS.

Account Lookup

Account Lookup provides the CSR an option to lookup a customer’s Private Label Account Number in case the customer cannot is unable to locate their account number. This feature adds the ability for MAO to send an account lookup request based on the customer’s information in the ADS required format via SOAP HTTP web service APIs and update the Account number based on the response from ADS.

End of Day Settlement Batch

A settlement occurs when the authorized funds are actually taken out of the customer’s account. This is typically triggered by a shipment or transfer of goods to the customer. This feature adds the ability for MAO to send a batch end of day settlement file to ADS.

Resend Mechanism for End of Day Settlement

With the end of day settlement performed in batch, this App also includes a UI feature to manually resend End of Day Settlement files from Manhattan Active Omni (MAO) in the event the initial files are lost in transit or incomplete.

2.1.3.2 - Adyen

What is Adyen?

Adyen is a global payment company that allows retail businesses to accept e-commerce, mobile, and point-of-sale payments.

What does this integration include?

For Credit Card payment processing integration, Manhattan Active Omni, MAO for short, integrates with Adyen to process payment transactions. MAO generates the transactions in the format required by Adyen and integrates via Rest APIs.

Additionally, MAO Hosted Checkout capabilities in the call center application are added, which is used to capture and tokenize credit card information via Adyen Gateway from the MAO call center application. During Hosted Checkout, Adyen responds back with the payment token which can then be used for further transactions.

This page details Manhattan Active Omni integration with Adyen Payment Gateway for the following processes:

Hosted Checkout – Payment Method capture and tokenization using the Adyen Hosted Payment Page in the MAO Call Center
Authorization – Payment Authorization and Reauthorization when Payment Method expiring
Authorization Extension – Extend expiration date on Authorization
Authorization Reversal – Reduce amount Authorized (complete or partial)
Settlement – Capture amount fulfilled (complete or partial)
Refund – Refund amount settled
Fraud – Payment Method fraud review using Adyen RevenueProtect (RP)

Payment Types

Payment Types included and supported by Adyen as a part of this App are:

Payment Type	Pre-Paid?	Refund Type	Void Behavior	Call Center?	Tokenization
Apple Pay	No	Apple Pay	No	No	Yes
Bancontact	Yes	Bancontact	No	No	Yes
Credit Card	No	Credit Card	No	Yes	Yes
Gift Card	No	Gift Card	No	Yes	Yes
iDeal	Yes	iDeal	No	No	Yes
Klarna	No	Klarna	No	No	Yes
PayPal	No	PayPal	No	No	Yes

Processes by Payment Type

Processes by Payment Type supported by Adyen as a part of this App are:

Payment Type	Hosted Checkout	Authorization	Authorization Extension	Auth Reversal	Settlement	Refund	Fraud
Apple Pay	No	Yes	No	Complete and Partial*	Complete and Partial*	Yes	Yes
Bancontact	No	No	No	No	No	Yes	Yes
Credit Card	Yes	Yes	Yes*	Complete and Partial*	Complete and Partial*	Yes	Yes
Gift Card	Yes	Yes	No	Complete and Partial*	Complete and Partial*	No	Yes
iDeal	No	No	No	No	No	Yes	Yes
Klarna	No	Yes	No	Complete Only	Complete and Partial	Yes	Yes
PayPal	No	Yes	No	Complete and Partial*	Complete and Partial*	Yes	Yes

* Determined by configuration, processes leveraged can be adjusted to meet customer specific Adyen processing requirements. For example, Credit Cards can be configured to only send Complete Auth Reversals.

Hosted Checkout

Hosted checkout is a Payment Gateway / 3rd party owned screen (iFrame) used to capture payment information during the order creation/modification process in the MAO Call Center. Hosted Checkout makes the payment information capture more secure since the payment information is collected on the payment gateway side and the payment page along with the underlying security is owned by the gateway solution where MAO only invokes the Hosted Checkout page with the necessary order information. Once the payment information is submitted on the hosted checkout page, Adyen sends a token back to MAO, which is stored on the order and can be used for subsequent payment transactions – such as Authorization, Settlement and Refund.

Authorization

An authorization, or approval from the card issuer through the payment gateway, is required to ensure the customer has sufficient funds to cover the cost of the transaction. MAO creates authorizations in various scenarios such as order capture/modification through the Call Center application or when an authorization is expiring and requires a new authorization. This feature adds the ability for MAO to send an authorization request to Adyen in the required format when an authorization is required.

Authorization Extension

An authorization of a pre-authorized payment can be adjusted to extend the authorization period. This feature adds the ability for MAO to send an authorization adjustment request to Adyen in the required format when an authorization extension is required.

Authorization Reversal

An authorization reversal may occur when a merchant reverses the authorization step of the transaction for any funds that the merchant does not intend to capture. MAO creates internal authorization reversals when the order total decreases and there are unused funds on the authorization transaction. This feature adds the ability for MAO to externalize the authorization reversal transactions when the remaining amount on the auth is being reversed. MAO sends an authorization reversal request to Adyen in the required format when an auth reversal is required.

Settlement

A settlement transaction (Capture) is created when product on the order is fulfilled, so issuing bank sends funds to the seller’s payment processor, which disperses said funds to the merchant. This feature adds the ability for MAO to send a settlement request to Adyen in the required format when a payment capture is required.

Refund

A refund is required when money is owed to the consumer, triggered by a return, uneven exchange, appeasement, etc. This feature adds the ability for MAO to send a refund request to Adyen in the required format when a refund is required. Usually, a refund is issued for an existing order that is fulfilled and has invoice in Closed status. However, as a part of this App a backend API is included to process a refund without an existing order.

Fraud

Fraud is processed with Ayden RevenueProtect (RP) to provide capabilities to automate and streamline Order Reviews and Fraud Case Management operations. This feature adds the ability to support fraud check and case resolution between MAO and RP. When an order is updated in RP after being placed on fraud hold, RP provides notifications to MAO on any Fraud Status/Result changes.

2.1.3.3 - Aurus

What is Aurus?

Aurus is a leading provider of global payment software and services for retailers.

What does this integration include?

For Credit Card payment processing integration, Manhattan Active Omni integrates with AurusPay Switch to process payment transactions using Web-Service AESDK version 6.13.8. MAO generates the transactions in the format required by Aurus. Additionally, MAO adds logic for Hosted Checkout in the call center application, which is used to capture credit card information via AurusPay Switch. Then, Aurus returns the payment token, which can then be used for further transactions.

This integration also adds logic to process Gift Card, Klarna, Affirm, PayPal, and Digital Wallet (ApplePay/Google Pay) payment transactions, as well as Safety Pay (Bank Transfers in Mexico) and OXXO payments.

This document details MAO integration with AurusPay Switch via the following transactions:

Authorization (PreAuth)
Authorization Reversal (Void)
Settlement (PostAuth)
Sale
Refund
Hosted Checkout
Transaction Lookup
Issue Gift Card
Activate Gift Card
Balance Inquiry of Gift Card
Redeem Gift Card
Chargeback Sale

Authorization

An authorization, or approval from the card issuer through the payment gateway, is required to ensure the customer has sufficient funds to cover the cost of the transaction. Manhattan Active Omni (MAO) creates authorizations in various scenarios like when an authorization expires and requires a new authorization. This feature adds the ability for MAO to send the Aurus required format when an authorization is required.

Authorization Reversal

An authorization reversal occurs when a merchant reverses the authorization step of the transaction, before settlement has begun. Manhattan Active Omni (MAO) creates internal authorization reversals when the order total decreases. This feature adds the ability for MAO to externalize the authorization reversal transactions when the full remaining amount on the auth is being reversed. MAO sends the Aurus required format when an auth reversal is required.

Settlement

A settlement transaction is created when product on the order is fulfilled, so issuing bank sends funds to the seller’s payment processor, which disperses said funds to the merchant. This feature adds the ability for MAO to send the Aurus required format when a settlement is required.

Sale (Combo Call)

A sale is utilized to capture funds when base generates a settlement transaction upon adding a new payment method in the Call Center UI. This feature supports the capture of funds without requiring an authorization transaction.

Refund

A refund is required when compensation is owed to a customer; triggered by a return, uneven exchange, appeasement, adjustment invoice etc. This feature adds the ability for MAO to send the Aurus required format when a refund is required.

Hosted Checkout

Hosted checkout, or a 3rd party owned screen (iFrame) used to capture payment information during the order creation process in the Call Center application, is added as part of this feature. Aurus sends a token back to MAO, which is stored on the order and used for subsequent payment transactions.

Transaction Lookup

In scenarios where a timeout occurs when executing a payment transaction with Aurus, a lookup mechanism is required during retry to check if the transaction was processed. This features supports a lookup API call with Aurus before a new transaction is executed. If the transaction that timed out was processed by Aurus, this API returns the response details. Transaction Lookup calls are made for all the transactions listed in this extension except for the Gift Card Balance Inquiry.

Gift Card – Issuance and Activation Gift Card

For scenarios where a refund must be issued on a gift card as well as scenarios where an E-Gift Card is added to an order as a sellable item, MAO calls Aurus to issue and then activate a new E-Gift Card. The issuance/activation response, which contains the E-Gift Card number and PIN is translated by MAO into a fulfillment order event for the E-Gift Card which generates an outbound message with the E-Gift Card details.

Gift Card – Balance Inquiry

When applying a Gift Card as a payment method in the Call Center application, MAO makes a Balance Inquiry call to Aurus to confirm the card has the funds available. If the available balance is greater than the requested amount, MAO applies the gift card to the order for the requested amount. If the available balance is less than the requested amount, MAO applies the available balance. Additional payment methods are captured to continue the order creation process.

Gift Card – Redeem

When confirming an MAO Call Center order having a Gift Card applied as payment, MAO sends Aurus a Redeem request for the amount applied on the Gift Card in the Balance Inquiry step. The Gift Card Redeem transaction is modeled as a MAO Settlement transaction, and successful Gift Card redemption results in an order moving to Paid status (if the Gift Card covers the entire order total).

Pay by Link

With Pay by Link, customers can input their credit card information using their own mobile device, tablet, or laptop, rather than providing their sensitive credit card information to contact center agents. This reduces the level of risk for customers who are placing orders or making order edits over the phone.

OXXO

With OXXO payments, customers in Mexico receive a barcode on order confirmation which is saved to their mobile phones. The customer can then has 3 days to show the barcode at an OXXO store and pay for the order, at which point the OXXO payment, through Aurus, is posted to the MAO orders asynchronously. MAO executes payment cancellations for orders fully cancelled prior to payment being posted and refunds for any returns or adustments after payment has been posted.

2.1.3.4 - Chase

What is Chase Paymentech?

Chase is the a leading provider of merchant services with over $1 trillion in annual processing volume. Chase Paymentech is a credit card processing solution aimed at larger enterprise businesses.

What does this integration include?

For Credit Card payment processing integration, Manhattan Active Omni, MAO for short, integrates with Chase Paymentech’s Orbital Gateway to process payment transactions using SOAP Web-Service APIs on version 2.9. MAO generates the transactions in the format required by Chase Paymentech. Additionally, MAO adds logic for Hosted Checkout in the call center application, which is used to capture credit card information via Chase PaymenTech’s Orbital Gateway. Then, Chase returns the payment token, which can then be used for further transactions.

This document details MAO integration with Chase Paymentech Gateway via the following transactions:

Authorization
Authorization Reversal
Settlement (Mark for Capture)
Settlement Retry (Auth + Capture)
Refund
Hosted Checkout

Authorization

An authorization, or approval from the card issuer through the payment gateway, is required to ensure the customer has sufficient funds to cover the cost of the transaction. Manhattan Active Omni (MAO) creates authorizations in various scenarios like when an authorization expires and requires a new authorization. This feature adds the ability for MAO to send the Chase Paymentech required format when an authorization is required.

Authorization Reversal

An authorization reversal occurs when a merchant reverses the authorization step of the transaction, before settlement has begun. Manhattan Active Omni (MAO) creates internal authorization reversals when the order total decreases. This feature adds the ability for MAO to externalize the authorization reversal transactions when the full remaining amount on the auth is being reversed. MAO sends the Chase Paymentech required format when an auth reversal is required.

Settlement

A settlement transaction is created when product on the order is fulfilled, so issuing bank sends funds to the seller’s payment processor, which disperses said funds to the merchant. This feature adds the ability for MAO to send the Chase Paymentech required format when a settlement is required.

Settlement Retry

In specific scenarios when the settlement call fails, it may be required to re-authorize the payment transaction in order to settlement. This feature adds the ability for MAO to send the Chase Paymentech required format for scenarios where a failed settlement needs re-processing systematically.

Refund / Standalone Refund

Hosted Checkout

Hosted checkout, or a 3rd party owned screen (i frame) used to capture payment information during the order creation process in the Call Center application, is added as part of this feature. Chase Paymentech sends a token back to MAO, which is stored on the order and used for subsequent payment transactions.

2.1.3.5 - CyberSource

What is CyberSource?

CyberSource helped kick start the eCommerce revolution in 1994 and has not looked back since. Through global reach, modern capabilities, and commerce insights, CyberSource creates flexible, creative commerce solutions for everyday life—experiences that delight your customers and spur growth globally.

What does this integration include?

This App adds additional options to the base integration with CyberSource from Manhattan Active Omni Application for the following features:

Authorization Reversals – Ability to release the funds on the customer’s credit card in the event the full authorization amount is no longer required
PayPal integration via CyberSource – Ability to integrate to PayPal through CyberSource for Settlement, Refund, Reauthorization, and Authorization Reversals
Klarna integration via CyberSource – Support for MAO to call CyberSource for Settlement, Refund, Reauthorization, and Authorization Reversal for Klarna payment method
Bancontact integration via CyberSource – Support for MAO to call CyberSource for Refund for Bancontact payment method
iDEAL integration via CyberSource – Support for MAO to call CyberSource for Refund for iDEAL payment method
Przelewy24 integration via CyberSource – Support for MAO to call CyberSource for Refund against Przelewy24 payment method, and Refund Check Status call to update Pending Refund transactions to Refunded

Authorization Reversals

An authorization reversal occurs when a merchant reverses the authorization step of the transaction, before settlement has begun. Manhattan Active Omni (MAO) creates internal authorization reversals when the order total decreases. This feature adds the ability for MAO to externalize the authorization reversal transactions when the full amount on the auth is being reversed for the credit card. MAO sends the CyberSource required format when an auth reversal is required.

PayPal Integration through CyberSource

Manhattan Active Omni (MAO) out of box integrates directly with PayPal to process settlement & refund transactions. As part of this feature, MAO integrates with CyberSource Payment Gateway to process PayPal payment transactions via the Alternative Payment PayPal Express using Simple Order API. Manhattan Active Omni sends the request to the CyberSource Payment Gateway, which acts as a middle layer and directly integrates with PayPal. This service captures all payment messages sent from MAO, passes these messages to PayPal, and returns the response to MAO. This includes settlement, refund, and full authorization reversal payment transactions.

Klarna alternative payment methods IN CyberSource

Some clients may wish to support alternative payment methods via CyberSource. This feature adds support for Klarna, a Buy Now, Pay Later solution. Manhattan Active Omni sends the request to the CyberSource Payment Gateway using the Alternative Payment Simple Order API, which acts as a middle layer and directly integrates with Klarna. This service captures all payment messages sent from MAO, passes these messages to Klarna, and returns the response to MAO. This includes settlement, refund, reauthorization, and full authorization reversal payment transactions.

Bancontact online bank transfer integration through CyberSource

Clients may wish to support Bancontact, an e-commerce payment system in Belgium that enables customers to pay for goods using direct bank transfer from their bank accounts directly to your account. MAO integrates with CyberSource Online Bank Transfers using the Simple Order API to process payment transactions. Manhattan Active Omni sends the request to the CyberSource Payment Gateway, which acts as a middle layer and directly integrates with Bancontact. This service captures all payment messages sent from MAO, passes these messages to Bancontact, and returns the response to MAO. This includes follow-on refund transactions against Bancontact payment method settlements.

iDEAL online bank transfer integration through CyberSource

Clients may wish to support iDEAL, an e-commerce payment system in the Netherlands that enables customers to pay for goods using online bank transfers from their bank accounts directly to your account. MAO integrates with CyberSource Online Bank Transfers using the Simple Order API to process payment transactions. Manhattan Active Omni sends the request to the CyberSource Payment Gateway, which acts as a middle layer and directly integrates with iDEAL. This service captures all payment messages sent from MAO, passes these messages to iDEAL, and returns the response to MAO. This includes follow-on refund transactions against iDEAL payment method settlements.

Przelewy24 online bank transfer integration through CyberSource

Clients may wish to support Przelewy24, an e-commerce payment system in Poland that enables customers to pay for goods using direct online bank transfers from their bank accounts directly to your account. MAO integrates with CyberSource Online Bank Transfers using the Simple Order API to process payment transactions. Manhattan Active Omni sends the request to the CyberSource Payment Gateway, which acts as a middle layer and directly integrates with Przelewy24. This service captures all payment messages sent from MAO, passes these messages to Przelewy24, and returns the response to MAO. This includes follow-on refund transactions against Przelewy24 payment method settlements.

2.1.3.6 - Fiserv

What is Fiserv CardConnect?

CardConnect is a payments platform of Fiserv, focused on helping businesses of all sizes grow through the seamless integration of secure payment processing.

What does this integration include?

This integration enables communication for Manhattan Active Omni (MAO) Point of Sale (POS) card payment flows with Fiserv’s CardConnect platform (API version V3). Card payment types supported through this integration include Credit Cards and Debit Cards.

Integration between MAO POS and Fiserv’s CardConnect Platform is implemented using REST Web-Service APIs. Card-present payment transactions are integrated from the POS register application in the store to CardConnect’s BOLT REST APIs while Card-not-present payment transactions are integrated from the MAO Cloud Server to CardConnect’s CardPointe REST APIs.

MAO sends requests to Fiserv CardConnect in the format required by Fiserv and processes responses from Fiserv back into MAO.

This document details MAO integration with Fiserv CardConnect Gateway via the following transactions:

Bolt
- Connect and Disconnect
- Display cart on terminal screen
- Confirm Address on terminal
- Card Payment Capture
- Refund By Card Entry
- Offline Payment Processing
Card Payment Capture
Card Payment Refund
CardPointe
- Follow on Refund (referenced refund to original card by transaction token)
- Standalone Refund (unreferenced refund to original card by card token
- Void Capture
- Void Refund

Connect and Disconnect with Payment Terminal

The Bolt API Connect initiates a session between POS register and the Payment Terminal (terminal). The session key returned by the Connect API is required to be included in all subsequent API requests to the Bolt webservice. MA POS initiates the session when a transaction is created in POS and closes the session once the transaction is completed, voided or suspended. The Bolt API Disconnect is executed to close the session between the register and terminal.

Display Cart on Payment Terminal

The Bolt API Display is executed by POS to display the latest updates to the shopping cart on the payment terminal. Each time the cart is modified, such as by adding an item or overriding a price, the POS register calls the display API to update the payment terminal screen with the details of the current state of the cart.

This applies only to Fixed POS Registers where the customer typically cannot see the cart on the POS register UI. In case of Mobile POS Registers, cart is not displayed on the terminal since the user can easily share the POS UI with the customer.

Capture and Settlement

POS executes the authCard Bolt API with the Capture flag set to true to capture payment for a cash and carry transaction. This causes CardConnect to prompt for card entry (among other things) and Authorize and Capture the payment as part of a single API call.

Capture is the process of queuing a payment transaction for Settlement. Settlements are run overnight by Fiserv CardConnect at a pre-configured time agreed to with merchant. Settlement triggers the issuing bank to transfer funds to the merchant’s bank (Acquirer).

Void

A Void operation reverses a payment transaction such as a capture or refund before settlement has occurred. MAO POS executes void in a few different scenarios:

When an order is post-voided
When a partial card payment applied to an order is voided mid-transaction. This may be because customer changed their mind and wants to pay for the transaction with a different tender or card.
During payment reconciliation after store close to void abandoned payments (payments with error conditions)

Refund

Refunds are executed in MAO POS to process returns or negative exchanges. Depending on the type of return different types of refunds are executed:

Refund to original card may be executed in two ways without card being present
- If the settlement is not expired for the original payment then a refund is executed against the original payment transaction (CardPointe API Refund) – this is called a follow-on refund or a referenced refund
- If the settlement has expired for the original payment then a refund is executed using the card token from the original payment transaction (CardPointe API Authorization) – this is called a standalone refund or an unreferenced refund
When card is present, refund is executed by card entry (insert, tap or swipe) through the Bolt API authCard with negative amount

Store and Forward (SAF)

SAF is a mechanism by which a payment can be captured with card present on the payment terminal even while the payment terminal is unable to connect to the gateway (Bolt Service). In such a scenario the payment capture is stored locally on the payment terminal until such time the payment terminal’s connection to the Bolt Service is restored. Then the payment terminal uploads all the captured payments (and refunds) to the gateway.

Display Address Confirmation on Payment Terminal

When capturing or editing a customer address on POS fixed register, this feature allows MAO to display the address on the payment terminal for confirmation by customer before it is saved. It allows the customer to specify if the displayed address is correct or not.

2.1.4 - Customer Master

Manhattan Active Omni solutions maintain a customer entity used for storing customer information needed to track purchases and interactions with the brand. The customer entity stores:

Basic contact information, saved addresses, and payment information to streamline customer service-assisted orders or point of sale endless aisle orders
Customer preferences such as opt-in information and preferred store location
Alternate IDs to cross reference customers who may have more than one account that has been merged

Manhattan Active Omni has pre-built apps with many 3rd party Customer Relationship Management providers which can be leveraged to retrieve and update customer information needed within MAO out of the box. Please see each 3rd party vendor to view what functionalities are available.

Third Party Integrations

2.1.4.1 - Salesforce Commerce Cloud

What is Salesforce Commerce Cloud?

Salesforce Commerce Cloud is an ecommerce web platform.

What does this integration include?

Manhattan Active Omni is not integrated with Salesforce out of the box. This integration enables communication with Salesforce by altering the base functionality in the following ways:

Search Customer
Create Customer

These services are invoked when a new customer is created via the MAO Point of Sale or Customer Service modules.

Search Customer

This service to SFCC is invoked in POS or Customer Service modules when the user is searching for an existing customer and returns a list of customers for the user to choose from and eventually apply the customer to the order.

Create Customer

This service to SFCC is invoked when in POS or Customer Service modules when a new customer is created and returns a customer ID, which is saved on the customer record.

2.1.5 - Fraud

Manhattan Active Omni solutions provide clients with a framework to integrate with 3rd party fraud detection services to hold orders which are flagged as fraudulent, ensuring they are not released for fulfillment until a fraud review is performed. If an order has been put on hold due to potential fraud, then a fraud analyst can analyze the situation and take steps to resolve the alert.

Manhattan Active Omni has pre-built apps with many 3rd party fraud providers which can be leveraged out of the box. Please see each 3rd party vendor to view what functionalities are available.

Third Party Integrations

ClearSale

2.1.5.1 - Adyen

What is Adyen?

Adyen is a global payment company that allows retail businesses to accept e-commerce, mobile, and point-of-sale payments.

What does this integration include?

This page details Manhattan Active Omni integration with Adyen Payment Gateway for the following processes:

Fraud – Payment Method fraud review using Adyen RevenueProtect (RP)

Processes by Payment Type

Processes by Payment Type supported by Adyen as a part of this App are as follows:

Payment Type	Fraud
Apple Pay	Yes
Bancontact	Yes
Credit Card	Yes
Gift Card	Yes
iDeal	Yes
Klarna	Yes
PayPal	Yes

Fraud

2.1.5.2 - ClearSale

What is ClearSale?

ClearSale is a fraud management and chargeback protection services company.

What does this integration include?

Manhattan Active Omni is not integrated with ClearSale out of the box. This integration enables communication with ClearSale by altering the base functionality in the following ways:

Fraud Call
Fraud Retry
Manual Review from ClearSale
Manual Updates in MAO

Fraud Call

For the defined order types MAO makes a call to ClearSale for fraud check before the order is released. ClearSale responds with a fraud decision - accept, failure, or review. For accept, the fraud hold is removed and the order is eligible for release. For failure, MAO cancels the order, and for review, the order is updated with a fraud review hold that requires a manual fraud review.

Fraud Retry

If no response is received from the fraud call to ClearSale, MAO has a retry scheduler to retry the fraud call on a configurable schedule.

Manual Review

If a manual fraud review is required, ClearSale sends an asynchronous message when the fraud analysts makes a final decision. MAO processes the message and updates the order with the fraud details according to the fraud response - accept or failure. The asynchronous message must be translated to the format defined as part of this integration.

Manual Update

In an exception scenario where ClearSale is unavailable for an extended period, a fraud analyst may remove a fraud hold in MAO directly given that the user has the newly added permission. Without this permission, the user is prevented from editing orders on a fraud hold or removing the fraud specific holds from the order.

2.1.5.3 - CyberSource

What is Decision Manager?

CyberSource’s Decision Manager is a fraud protection platform, which features a flexible rules engine. Decision Manager allows customers to screen orders for risk to help prevent fraud.

What does this integration include?

This integration extends the base-supported authorization integration with CyberSource by utilizing three methods:

Combo Call (Adding Fraud fields to Authorization Call)
Review Fraud Status Calls
Stand Alone Fraud Calls

The Decision Manger API allows for integration between Manhattan Active Omni and CyberSource’s Decision Manager. The integration with Decision Manager (DM) provides the client capabilities to automate and streamline Order Reviews and Fraud Management operations.

Combo Call

For orders placed in the MAO Customer Servic emodule, a call to CyberSource for authorization is made with the additional fields added for CyberSource to perform the fraud check before the order is released. CyberSource responds with a fraud decision - accept, failure, or review. For accept, the fraud hold is removedand the order is eligible for release. For failure, MAO cancels the order, and for review, the order is updated with a fraud review hold that requires a manual fraud review.

Review Status Call

MAO periodically checks the fraud status of any order that is in Fraud Review with CyberSource DM. This task utilizesthe DM API to check the status of the order and allows MAO to process any updates based on manual review of the order.

Standalone Calls

For order edits where no new authorization is required, MAO sends a standalone fraud call to CyberSource DM and updates the order based on the fraud response.

2.1.5.4 - Signifyd

What is SIGNIFYD?

Signifyd is a software as a service fraud and chargeback prevention technology. Signifyd’s technology helps detect and prevent fraud.

What does this integration include?

Manhattan Active Omni is not integrated with Signifyd out of the box. This integration enables communication with Signifyd by altering the base functionality in the following ways:

Ability to perform Fraud Check for orders created via Active Omni Call Center Application and order modifications done during the remorse period
Fraud Retry
Manual Fraud Review
Manual Fraud Update

Fraud Check

For the defined order types MAO makes a call to Signifyd for fraud check before the order is released. Signifyd responds with a fraud decision – accept, failure, or review. For accept, the fraud hold is removed and the order is eligible for release. For failure, MAO cancels the order, and for review, the order is updated with a fraud review hold that requires a manual fraud review.

Fraud Retry

If no response is received from the fraud call to Signifyd, MAO has a retry scheduler to retry the fraud call on a configurable schedule.

Manual Review

If a manual fraud review is required, Signifyd sends an asynchronous message when the fraud analysts makes a final decision. MAO processes the message and updates the order with the fraud details according to the fraud response – accept or failure. The asynchronous message must be translated to the format defined as part of this integration.

Manual Update

In an exception scenario where Signifyd is unavailable for an extended period, a fraud analyst may remove a fraud hold in MAO directly given that the user has the newly added permission. Without this permission, the user is prevented from editing orders on a fraud hold or removing the fraud specific holds from the order.

2.1.6 - Gift Cards

Manhattan Active Omni solutions provide clients the ability to sell or to transact with gift cards.

Selling gift cards

Physical or electronic gift cards may be purchased through the website, Contact Center, or POS, which leverages integration with the external gift card provider to activate the gift card.

Transacting with gift cards

Gift card as a tender is supported with integration to the external gift card provider to process the payment. This includes:

Balance check to verify available funds prior to accepting as form of payment
Reducing the funds on the gift card upon fulfillment
Refunds to existing or new gift card upon cancelation or returns

Manhattan Active Omni Point of Sale provides additional capabilities for store users to perform balance inquiries, reload or activate a gift card, and cash out remaining balance under a defined threshold.

Manhattan Active Omni has pre-built apps with many 3rd party gift card providers which can be leveraged out of the box for one or more of the above functionalities. Please see each 3rd party vendor to view what functionalities are available.

Third Party Integrations

2.1.6.1 - Clutch

What is Clutch?

Clutch is an innovative data-centric marketing solution platform empowering brands with the best technology so that they can identify, understand, and motivate their customers. Clutch provides traditional marketing CRM, loyalty, gift card, mobile, email, and direct mail solutions individually or as part of a unified platform.

What does this integration include?

This Clutch integration enables Manhattan Active to support the following features:

Balance Check – Check the available balance on a Gift Card
Hold – Place a hold on the funds on a Gift Card to pay for an order
Redeem – Redeem the held funds on a Gift Card upon the fulfillment of the order that was paid using the gift card
Hold Reversal – Release funds that are held on a Gift Card
Gift Card Processing – Activation and Issuance of Physical and Electronic Gift Cards

Balance Check

When a CSR adds a gift card to an order in the Call Center UI, Manhattan Active Omni generates a payment transaction to determine the available funds on the card. MAO makes a synchronous call to Clutch and sends only one message per gift card. If the available balance is greater than the requested amount, Manhattan Active Omni applies the gift card to the order for the requested amount. If the available balance is less than the requested amount, Manhattan Active Omni applies the available balance. Additional payment methods are captured to continue the order creation process.

Hold

In the Call Center UI, when a CSR places an order requiring a gift card tender authorization, MAO sends an authorization/hold transaction to place a hold on the funds to Clutch. If the approved amount is less than the requested amount, then MAO accepts the response to make the appropriate updates. The correct available, applied, and remaining amounts are displayed in the payment tab of the Call Center UI.

Redeem

A settlement request to Clutch is sent to redeem gift card payment transactions. When an order is shipped, an invoice is generated to mark the sale of goods. If an order is fully shipped, MAO uses the invoice to generate a settlement transaction. If the order is partially shipped, a scheduled job is configured to batch process any open settlement transactions, generating individual calls for each open transaction to Clutch. The redeem transaction releases the remaining funds from the related hold transaction. If all order lines are not shipped, Manhattan Active Omni generates an advanced hold transaction upon a successful response. The advanced hold record is used for any subsequent settlement transactions, until a new hold is generated, or the order is fully shipped or canceled.

Hold Reversal

Manhattan Active Omni uses the authorization reversal interface when an authorization reversal transaction is generated for a gift card authorization. The message interfaced to Clutch is like the settlement request, however, the requested amount is always $0. MAO closes the authorization record and releases the funds for the related hold in Clutch.

Gift Card Processing

When a customer purchases a Gift Card both Electronic / Physical, there are a series of steps involved in fulfilling and activating the Gift Card for the customer to Use. Manhattan Active Omni orchestrates the fulfillment of both the Physical and Electronic Cards and handles the activation of the same.

When a Gift Card order is Released to Fulfillment based on the type of Gift Card the following steps are performed

Allocate

Only applicable for Electronic Gift Card, when an Electronic Gift Card is released MAO makes an Allocate call to Clutch using the CardsetID, which returns the Gift Card Number and optional PIN.

Activate

A Gift Card Activation request to Clutch is generated when the fulfillment center ships the physical gift card. For electronic gift card, the call is generated after a successful Allocate call. This message includes the Gift Card Number and Pin, if available.

Issuance

For both types of gift cards, once the gift card is activated, a Gift Card Issuance request to Clutch is generated to issue the value to the card . MAO makes a synchronous call to Clutch and sends one message per gift card. If multiple gift card issuances are required, multiple messages are sent.

2.1.6.2 - Eigen

What is Eigen?

Eigen is a payment management service that can be used for Gift Card issuing and management.

What does this integration include?

This Eigen integration enables Manhattan Active to support the following features:

Issuing a New E-Gift Card on Refund
Retry Scheduler for Failed E-Gift Card Issuance

Issueing a New E-Gift Card on Refund

After customers make purchases using a gift card, they generally discard the gift card. Therefore, when a refund or appeasement is processed for the customer, the funds are not put back on the original gift card. If the payment method on the original order is a gift card and a refund transaction is created, a new electronic gift card is issued. In addition, new gift cards are issued as a refund tender when gift recipients return items. For example, if a customer purchases an item as a gift and pays using a credit card, and the gift recipient returns the item, the refund is also issued as a new gift card.

Failed E-Gift Card Retry Scheduler

When the call to Eigen to activate and issue a new E-Gift Card fails with an unavailable response, MAO retries the call to Eigen on a configurable schedule up to the max retry attempts.

2.1.6.3 - Givex

What is Givex?

Givex offers gift card, loyalty and stored value ticketing solutions which drive sales for clients, help them better understand, reward and entice their customers and ultimately make better-informed business decisions.

What does this integration include?

This integration enables integration to Givex for two Payment Methods:

Gift Card (GC)
Store Card (SC)

In the context of this integration a Store Card is essentially a Gift Card except it must be redeemed within the store only and not through other channels. This is managed in Givex by assigning a Gift Card to a Group. By the virtue of the card being associated to the group it is limited to be redeemed only from stores. The details of the mechanisms / configurations by which this is accomplished is outside the scope of this document and is managed between the Retailer and Givex.

The features within this integration explained more below include: • Card Entry • Redemption • Cash Out • Refund • Balance Inquiry • Activation • Reload • Exchange Tender

Card Entry

This feature provides the ability for the customer to barcode scan a Gift Card or Store Card into the Manhattan Active Omni POS UI. This feature requires integration with a barcode scanner to be implemented outside the scope of this integration.

Redemption

Redeeming is the process of using a Gift Card or Store Card to pay for a purchase in the Manhattan Active Omni POS Application. Funds equal to the redemption amount is reduced from the available funds on the card following a successful redemption.

Cash Out

Immediately following a redemption, if the balance remaining on the card (GC or SC) is below a threshold value (configured in MAO) then customer has the option to cash out the remaining balance in Manhattan Active Omni POS Application. This function is used to redeem (Forced Cashback Redemption) the remaining amount on the Gift Card or Store Card.

Refund

Refund results from processing a return or a negative exchange where customer is issued funds to an existing or new card (Gift Card or Store Card).

Balance Inquiry

Balance Inquiry is a function in the Manhattan Active Omni POS Application that allows the user to query the balance of an existing Gift Card or Store Card.

Activation

Activation is the process of adding funds to a new gift card and making it available to be redeemed. In the Manhattan Active Omni POS application activation is performed once the balance due becomes zero, for an order that contains a Gift Card line item. Note activation is supported only for Gift Cards and not for Store Cards since Store Cards are not sold as line items.

Reload

Reloading is the process of adding funds to an existing card (an activated card that the customer already owns). This process does not require activation since the card is already activated, it simply adds more funds to the card.

Exchange Tender

This function is utilized to return cash to a customer for a Gift Card or Store Card that they own. Alternately this function may also be utilized if a customer has multiple Gift Cards (or Store Cards) and wants to consolidate the funds in those cards to a single card

2.1.6.4 - SmartClixx

What is SmartClixx?

SmartClixx is a gift card provider and payment gateway used to issue, charge against, check balances, and other miscellaneous gift card transactions.

What does this integration include?

This SmartClixx integration enables Manhattan Active to support the following features:

Physical Gift Card activation
Electronic Gift Card activation
Settlement (Capture) of Gift Card Funds
Authorization Reversal of Gift Card Funds

Physical Gift Card Activation

When physical gift cards are added to the order, they are fulfilled by a fulfillment center who scans the card during picking to add the serial number (card number) to the order. This information is passed back to Active Omni on the Order Event (ship confirmation) message. An interface is used to relay the Gift Card Activation request to SmartClixx in the required format. The MAO generates the activation call, consumes the response, and passes the order event message along to mark the physical gift card as shipped.

Electronic Gift Card Activation

When electronic gift cards are added to the order, they are fulfilled virtually through integration with SmartClixx. Active Omni sends a request to SmartClixx to retrieve a card number and CVV2 value from SmartClixx. This information is passed back to Active Omni in the response and used to generate the next call, Activate, to load value to the card. Once the response is received back, the App forms an Order Event message that completes the lifecycle of the order line(s) with the card number and CVV2 value included.

Gift Card Settlement

When parts of the order ship, Active Omni reaches out to SmartClixx to inform them that the gift card has less funds available. Each shipment that occurs results in an individual settlement (capture) transaction reaching out to SmartClixx, further reducing the available funds remaining on the gift card.

Authorization Reversal

When an order is canceled or partially canceled, SmartClixx expects an authorization reversal transaction initiated from Active Omni to release the funds. Active Omni calls SmartClixx on a scheduled basis to perform authorization reversal to remove the hold on the gift card funds.

2.1.6.5 - SVS

What is SVS?

SVS (Stored Value Solutions) is a global provider of gift card and stored value services.

What does this integration include?

This SVS integration enables Manhattan Active to support the following features: • Balance Check • Pre-Authorization (Authorization) • Pre-Authorization Complete (Settlement) • Pre-Authorization Complete $0 (Authorization Reversal) • Issue Virtual Gift Card • Activate Physical Gift Card

Balance Check

When a CSR adds a gift card to an order in the Call Center UI, Manhattan Active Omni generates a payment transaction to determine the available funds on the card. MAO makes a synchronous call to SVS and sends only one message per gift card. If the available balance is greater than the requested amount, Manhattan Active Omni applies the gift card to the order for the requested amount. If the available balance is less than the requested amount, Manhattan Active Omni applies the available balance. Additional payment methods are captured to continue the order creation process.

Pre-Authorization (Authorization)

In the Call Center UI, when a CSR places an order requiring a gift card tender authorization, MAO sends an authorization/hold transaction to place a hold on the funds to SVS. If the approved amount is less than the requested amount, then MAO accepts the response to make the appropriate updates. The correct available, applied, and remaining amounts are displayed in the payment tab of the Call Center UI.

Pre-Authorization Complete (Settlement)

A Pre-Authorization Complete (settlement) request to SVS is sent to redeem gift card payment transactions. When an order is shipped, an invoice is generated to mark the sale of goods. If an order is fully shipped, MAO uses the invoice to generate a settlement transaction. If the order is partially shipped, a scheduled job is configured to batch process any open settlement transactions, generating individual calls for each open transaction to SVS. The Pre-Authorization Complete transaction releases the remaining funds from the related hold transaction. If all order lines are not shipped, Manhattan Active Omni generates an advanced hold transaction upon a successful response. The advanced hold record is used for any subsequent settlement transactions, until a new hold is generated, or the order is fully shipped or canceled.

Pre-Authorization Complete $0 (Authorization Reversal)

Manhattan Active Omni uses the authorization reversal interface when an authorization reversal transaction is generated for a gift card authorization. The message interfaced to SVS is like the settlement request, however, the requested amount is always $0. MAO closes the authorization record and releases the funds for the related hold in SVS.

Issue Virtual Gift Card

MAO issues a new Electronic Gift Card for many refund scenarios. MAO utilizes the release of the Electronic Gift Card item to trigger the custom activation calls for Electronic Gift Card. This synchronous call to SVS receives either a successful, failure, or unavailable response from SVS. MAO updates orders to shipped for successful scenarios. MAO also handles scenarios in which SVS is unavailable and resends the request based on the number of retries available.

Activate Physical Gift Card

MAO activates a Physical Gift Card upon receiving the ship event from the fulfillment center. MAO utilizes the Gift Card Number and optional PIN on the ship event to send the custom activation call for Physical Gift Cards. This synchronous call to SVS receives either a successful, failure, or unavailable response from SVS. MAO updates orders to shipped for successful scenarios. MAO also handles scenarios in which SVS is unavailable and resends the request based on the number of retries available.

2.1.6.6 - ValueLink (First Data)

What is ValueLink?

First Data, now Fiserv, is a global leader in payments and financial technology, where ValueLink is their proprietary gift card solution.

What does this integration include?

This ValueLink integration enables Manhattan Active to support the following features:

Physical Gift Card Activation
Electronic Gift Card Activation
Balance Inquiry
Redemption

Physcial Gift Card Activation

An interface is used to relay the Gift Card Activation request to ValueLink in the required format. The MAO generates the activation call, consumes the response, and passes the order event message along to mark the physical gift card as shipped.

Electronic Gift Card Activiation

When electronic gift cards are added to the order, they are fulfilled virtually through integration with ValueLink. MAO sends a Gift Card Activation request to ValueLink in the required format, consumes the response, and passes the order event message along to mark the electronic gift card as shipped.

Balance Inquiry

When a CSR adds a gift card to an order in the Call Center UI, Manhattan Active Omni generates a payment transaction to determine the available funds on the card. MAO makes a synchronous call and sends only one message per gift card. If the available balance is greater than the requested amount, Manhattan Active Omni applies the gift card to the order for the requested amount. If the available balance is less than the requested amount, Manhattan Active Omni applies the available balance. Additional payment methods are captured to continue the order creation process.

Redemption

When the order is shipped or partially shipped, the MAO reaches out to ValueLink to inform them that the gift card has less funds available. Each shipment that occurs results in an individual settlement (capture) transaction reaching out to ValueLink, further reducing the available funds remaining on the gift card.

2.1.6.7 - Voucher Express

What is Voucher Express?

Voucher Express is an industry-leading e-commerce solution that manages the online sale of gift vouchers, gift cards, and electronic gift cards.

What does this integration include?

This Voucher Express integration enables Manhattan Active to support the following features:

Refund – Issue a refund against a new electronic gift card

Refund

2.1.6.8 - Worldpay

What is Worldpay?

Worldpay is the world’s largest processor and payments advocate and provides services to merchants and financial institutions in the US.

Worldpay provides tools to simplify payment strategies including credit cards, ATM processing, and merchant services as part of a unified platform.

WHAT DOES THIS INCLUDE?

This feature adds integration with Worldpay for Gift Card processing including the following capabilities:

Giftcard Reload Transaction: Loading the funds onto an active gift card (for Physical Gift Cards) on Fulfillment of Purchased Gift Card and Refund Gift Card

Reload Gift Card

As part of this feature, MAO integrates with Worldpay to send Gift Card Reload Transactions via the Native RAFT API. Manhattan Active Omni sends data to Worldpay Payment Component that is required to generate request to load funds onto Physical Gift Cards. This service captures Order Event data from MAO for pGC shipments and generates and transmits request to Worldpay and returns the response to MAO.

2.1.7 - Loyalty & Rewards

Manhattan Active Omni solution provides clients the ability to maintain customer loyalty information used for various reward incentives. Many clients integrate with a 3rd party loyalty system to manage tracking loyalty points based on purchases, as well as the ability to redeem earned rewards on future orders.

Manhattan Active Omni has pre-built apps with many 3rd party loyalty systems which can be leveraged out of the box. Please see each 3rd party vendor to view what functionalities are available.

Third Party Integrations

2.1.7.1 - 500friends

What is 500friends?

500friends is a loyalty marketing platform that helps you retain, engage, understand, and connect to your customers. 500Friends integrates seamlessly with host systems to handle all customer loyalty metrics such as how many loyalty points a customer has earned per transaction committed & how much remaining value is available on a customer’s loyalty certificate.

What does this integration include?

Manhattan Active Omni is not integrated with 500Friends out of the box. This integration enables communication with 500Friends by altering the base functionality in the following ways:

Validate – Ensure certificate ID is valid and mark them as “Used” when redeemed
Monitor – Sends necessary data in the Balance Check for 500Friends to determine how many loyalty points a customer has earned
Payment Transactions – 500Friends authorizes and settles transactions that contain a loyalty certificate as a form of payment on the order

Validate

There is a Custom SOAP API to 500 Friends to validate certificate Ids upon loyalty certificates being used as a payment method on the order. Request Parameters include Certificate Id and Amount of Certificate. Response Parameters include the status and actual amount of the certificate. MAO makes this call when a user enters a loyalty certificate as a payment method on the call center UI. Whenever a Loyalty Certificate is applied, a tax call must be made to recalculate taxes. The Loyalty Certificate amount is prorated by weight across all items while making the tax call. This is a temporary proration and is not saved after the tax call is made.

Monitor

Manhattan Active Omni performs a synchronous Balance Check transaction call when a Loyalty Certificate tender is added to an order. When adding a Loyalty Certificate tender to an order, a CSR will capture a card number and pin and enter those into the payment details in the Call Center UI. Active Omni then generates a Balance Check transaction in the 500Friends format when a CSR presses “Add” to confirm the addition of the Loyalty Certificate tender.

Payment Transactions

Manhattan Active Omni performs an Authorization transaction call for a Loyalty Certificate tender when either an order is placed or updated in the Call Center UI, which contains a Loyalty Certificate tender that has yet to be authorized. MAO also performs an Authorization call if an order is sent with a valid Loyalty Certificate number without an authorization transaction record. If an order or portion of the order is canceled where an Authorization Reversal transaction is generated, MAO sends a call in the 500Friends format to mark the payment as no longer valid. Dummy Settlement and Refund transactions are generated for Loyalty Certificates and are closed by MAO with no calls to 500Friends.

2.1.8 - Parcel Carrier

Manhattan Active Omni solutions provide clients the ability to integrate with external parcel carriers for label generation and package tracking visibility. Use cases include:

Generation of shipping labels if leveraging stores as fulfillment centers for orders (ship from store)
Generation of return labels to include proactively in customer shipments from stores
Real time tracking services for shipments executed in MAO or for interfaced shipments from fulfillment locations

Manhattan Active Omni has pre-built apps with many 3rd party Parcel Carriers for one or more of the above functionalities, which can be leveraged out of the box. Please see each 3rd party vendor to view what functionalities are available.

Third Party Integrations

2.1.8.1 - Blue Express

What is Blue Express?

Blue Express provides door-to-door service to distribute products to more than 300 cities throughout Chile in an agile and safe way. The Blue Express shipping network provides national and international distribution, retail distribution, home delivery and commercial deliveries.

What does this integration include?

This integration adds functionality for Manhattan Active Omni to call Blue Express Tracking Pull web service, specifically the obtainDocument Service Method (Método obtenerDocumento). This provides the capacbility to track shipments within Manhattan Active Omni Digital Self Service (DSS) when a customer tracks a package associated to a Blue Express service order (OS).

Shipment Tracking

Retailers may provide the ability to track shipments via MAO DSS. To access the Shipment Tracking UI, a customer can use the “Track Package” link provided in the shipment confirmation email/text or via the link provided in an e-commerce site. One Shipment Tracking page is displayed per package.

The Digital Self-Service Shipment Tracking page displays details about a package, including:

Package status (e.g. in transit or delivered)
ETA or delivered date
Details about items in the package (Currently the UI displays item short description, size, color, price, and shipped quantity. Other attributes are not supported).
Tracking details

Self-Service makes a real time API call to the carrier such as FedEx to retrieve the latest package status. Out of the box integration exists for FedEx, UPS, and USPS.

This feature provides additional integration for 3rd party carrier, Blue Express. When a user accesses the Shipment Tracking UI for a package shipped via Blue Express, a real time call is made to the Blue Express obtainDocument web service to retrieve the latest status of the package as well as the tracking history using the Blue Express service order (OS) as tracking number.

2.1.8.2 - Canada Post

What is CANADA POST?

Canada Post is a carrier that acts as the primary postal operator in Canada.

What does this integration include?

Manhattan Active Omni is not integrated with Canada Post out of the box. This integration enables communication with Canada Post by altering the base functionality in the following ways:

Call Center Return Label
Store fulfillment Shipping & Return Label
Tracking
Void Shipment

Call Center Return Label

When a user initiates a return in Manhattan’s Contact Center the customer needs a return shipping label to ship their items to the return center. When a return order with receipt expected is initiated and confirmed in EOM, a call is made to the carrier to create and retrieve a return shipping label as well as generate a tracking number. Upon a successful response from Canada Post, the return label is stored within the EOM Document Component, and the return tracking number is saved against the order. Each return label contains the customer’s address, return center address, return order id and return tracking number. Canada Post requires that two calls be made to obtain a return tracking number: Create Authorized Return and Get Artifact.

Shipping and Return Label

When a user completes a package in Manhattan’s Store Fulfillment module, a ship request is generated, which communicates the service level, ship from and ship to address and other relevant package information. This ship request is generated to the required format for the two calls to Canada Post to get the tracking number and shipping label. The Canada Post response is translated back to the Store Fulfillment format where the tracking number is saved against the package, and the 4 X 6 PNG shipping label is saved in the document repository to be printed with the pack slip.

Additionally, based on configuration, a return label will be generated to be sent to the customer along with the shipping label. This will be two separate calls to Canada Post that will happen simultaneously to the calls made for the shipping label if configured to do so. The Canada Post response is translated back to the Store Fulfillment format where the return tracking number is saved against the package and the 4 X 6 PNG return label is saved inn the document repository to be printed with the pack slip.

Tracking Request

Once a package is built and has a tracking number for the Create Shipment response, a batch job scheduler runs periodically and pings Canada Post with this information. The frequency of this scheduler is configurable as a cron expression. The status code from the Canada Post Get Tracking response is mapped back to the payload. If the status code indicates possession from the carrier, it is configured with the status “InTransit” and the OMNI Fulfillment API updates the package to “Shipped” status. If any packages have not updated to an in-transit status, the package status remains in “Built”. Any packages that remain in “Built” status should be included in the subsequent requests triggered by the job scheduler.

Void Shipment

Store associates might need to print a new label for a package that was already prepared in store. In that case, they can use the ‘Reprint’ menu in the store application where they have the option to either reprint the label that was already printed or to update the Carrier details before submitting a new call to Canada Post to generate a new label. In the event where they decide to update the Carrier details and print a new label, a Void Shipment call is made to Canada Post to void the previous label.

2.1.8.3 - Channel Advisor

What is Channel Advisor?

Channel Advisor is a provider of cloud-based solutions to e-commerce companies. Channel Advisor helps global brands and retailers solve their marketplaces, digital marketing, direct-to-consumer, first-party retail, drop ship and fulfillment needs — all in a single, centralized platform.

What does this integration include?

Manhattan Active Omni is not integrated with Channel Advisor out of the box. This integration enables communication with Channel Advisor by altering the base functionality in the following ways:

Shipping Labels from SOF

Shipping Labels

During fulfillment from the SOF (Store Order Fulfillment) system, the Manhattan Active Omni system evaluates the carrier required for fulfillment. After a package has been created and closed, a call is made to a carrier to receive the appropriate tracking information and label. This integration allows for carrier configuration to determine when Channel Advisor calls should be executed versus other carriers (such as FedEx, UPS, etc.).

2.1.8.4 - Chilexpress

What is Chilexpress?

Chilexpress is the leading Chilean private company in the courier market and in express shipping services. Chilexpress provides clients with express distribution services, logistics transport and international trade, as well as money transfers, collections and electronic commerce.

What does this integration include?

Manhattan Active Omni is not integrated with Chilexpress out of the box. This integration enables communication with Chilexpress using the REST Transport APIs by altering the base functionality in the following ways:

Shipment Tracking
Self-Service and Call Center Return Labels

Shipment Tracking

Retailers may provide the ability to track shipments via MAO DSS. To access the Shipment Tracking UI, a customer can use the “Track Package” link provided in the shipment confirmation email/text or via the link provided in an e-commerce site. The Digital Self-Service Shipment Tracking page displays details about a package, including:

Package status (e.g. in transit or delivered)
ETA or delivered date
Details about items in the package (Currently the UI displays item short description, size, color, price, and shipped quantity. Other attributes are not supported).
Tracking details

Self-Service makes a real time API call to the carrier to retrieve the latest package status. Out of the box integration exists for FedEx, UPS, and USPS. This feature provides additional integration for 3rd party carrier, Chilexpress. When a user accesses the Shipment Tracking UI for a package shipped via Chilexpress, a real time call is made to the Chilexpress Individual Shipping Consultation API to retrieve the latest status of the package as well as the tracking history.

Self-Service and Call Center Return Labels

Retailers may provide the ability to create returns and same-style exchanges via DSS. Customers can initiate the self-service exchange flow in a few different ways. One is via the link provided in the shipment confirmation email. Another is if the retailer provides a link to return in the customer’s My Account page in e-commerce. A third way to initiate the flow is if the retailer offers a link in e-commerce to initiate returns, even for customers who are not logged in.

Customers can select items to return or exchange, quantity to return, and reason for return. After confirming the return, the customer is emailed a return label. The customer can also download a copy of the return shipping label and use it to ship the return items back. Customers can view and print the return label by using built-in browser functionalities to save or print the return label. In case the return label cannot be created or retrieved, an appropriate error message is displayed to the customer so that they can reach out to the contact center for help.

Base Return label generation is supported for FedEx, UPS, and USPS (the same carriers which are supported in customer service). This feature enables DSS Self-Service returns using Chilexpress as Return Carrier. If the Return Shipping Method is tied to a Chilexpress Carrier Service, upon confirming the DSS return, the Chilexpress App is invoked to generate a return label using the Generate Shipment API.

2.1.8.5 - CrossLog

What is CrossLog?

Expert in e-commerce logistics and transport management for individuals (BtoC) and professionals (BtoB), CrossLog International offers its customers a scalable offer for their e-shop. As a WMS and TMS software editor, CrossLog International provides its customers all the necessary tools to drive their business and communicate dynamically with their consumers.

What does this integration include?

Manhattan Active Omni “MAO” is not integrated with Crosslog out of the box. This integration enables communication Crosslog by altering the base functionality in the following ways:

Print Shipping & Return labels – To be able to print those labels, 3 requests are needed:
- Import Customer Order - Create a customer order in Crossdesk for tracking purposes
- Create Packs - Request the package tracking number and shipping label from Crosslog
- Get Parcel Return - Request the package return tracking number and return label from Crosslog
Print the Crosslog edited Packing Slip – Request the packing slip PDF document from Crosslog. This feature can be enabled and disabled through configuration via API.
Move the orders to shipped using the Get Order State call to Crosslog.

Shipping & Return labels

When a user completes a package in Store Inventory & Fulfillment “SI&F”, a ship process is initiated in MAO, which communicates the relevant data to Crosslog to get the shipping and return tracking numbers and labels. Crosslog requires a Customer Order to be created in their database before any ship or return request can be done. The customer order creation, CreatePacks and GetParcelReturn are translated to the Crosslog required format with the expected data for Crosslog to generate those labels. The Crosslog response is translated back to Store Fulfillment format where the tracking numbers are saved against the package, and the PDF labels are saved in the Supply Chain Document Management API to be printed with the packing slip.

Packing Slip

In the same sequence as the labels printing, MAO also communicates with Crosslog to get the Crosslog edited Packing Slip. This Packing Slip is added to the collate and printed within the same PDF file via a popup on the app. All the documents are stored separately in MAO but merged together in one document to be printed by the store associate.

Move Orders to Shipped

Once the labels are printed in store, the orders are Packed in MAO. Later in that day the carrier comes to collect the Packed orders and scans them to ensure the transfer of ownership is properly done. The carrier then updates Crosslog’s order status to a specific code that marks the order as in transit to the end customer.

MAO runs a scheduled job to get the order state of all Packed orders and moves those orders to Shipped when Crosslog returns this specific code.

2.1.8.6 - Cycleon

What is Cycleon?

Cycleon is an industry-leading, international returns management solution which integrates seamlessly with host systems to handle return label generation for multiple carriers.

What does this integration include?

Manhattan Active Omni is not integrated with Cycleon out of the box. This integration enables communication with Cycleon using ILS Core version 6.05 by altering the base functionality in the following ways:

Return Label Generation + Retry Failed Label Generation in the Store Fulfillment Module

Return Label Generation

When a package is created in SI&F (Store Inventory & Fulfillment), and the user finishes packing a package, MAO calls Cycleon who returns the return label in the format configured within MAO for the corresponding store. The return label size is the standard 4” X 6” or 4” X 4” labels provided by the carriers. SI&F does not resize the label. Although, the return label size is configurable via the custom Configstore API.

EOM will send a return label message for each package that is to be processed. If successful, the response nodes are returned and the Cycleon Id is persisted to the fulfillment detail; otherwise an ERROR node will be returned with a human-readable message.

The language on the label is determined by the address from where the label is mailed.

Retry Failed Label Generation

The reprint option is also available per base Manhattan Active Omni in case the label is damaged or unsuccessfully printed in any way. If the label has previously been printed, it is persisted in the Document Management Server and MAO can pull the previously generated label. If the label has failed to generate, a new request is sent to Cycleon.

2.1.8.7 - DHL

What is DHL?

DHL is an industry-leading carrier shipping solution that integrates seamlessly with host systems to handle all small parcel, LTL and TL return orders.

What does this integration include?

Out of the box, Manhattan Active Omni Store Fulfillment does not integrate with DHL. This integration enables communication with DHL by altering the base functionality in the following ways:

Generate the Return Order Tracking number & Shipping Label

Return Tracking Number and Label Generation

This feature adds integration with DHL to track the delivery status and to make a call to DHL Rate and Shipment service to initiate a Return. DHL receives the request and responds with the Return Tracking Number and Return Label. Return Label is saved as a PDF file in the Document API of Manhattan Active Omni. This document covers two returns processes:

CSR initiated returns in call center
Website (import order) initiated returns

2.1.8.8 - FedEx

What is FedEx?

FedEx Corp. provides customers and businesses worldwide with a broad portfolio of transportation, e-commerce and business services. FedEx Express and FedEx Express are the business segments that provide parcel shipping services.

What does this integration include?

This integration extends the base-supported Store Fulfillment integration with FedEx by adding the following:

Pickup Service

Pickup Service

Retailers may schedule reoccurring Pickups if their Store Locations are eligible for the service. Other businesses may require On-Call Pickup Requests if they are not eligible for scheduled Pickup.

The Pickup Service WSDL allows you to schedule a courier to pick up a shipment, cancel a pickup request, or check for pickup availability. As part of this feature, the Pickup Service is used to check for pickup availability and schedule courier pickup of a shipment at the location specified in the transaction.

When a Store has at least one Package manifested with FedEx Express Service Level, a PickupAvailabilityRequest is made to determine whether Pickup Service is available that day at the given Store Location. Based on the PickupAvailabilityReply, a CreatePickupRequest call is made.

2.1.8.9 - Logistyx

What is Logistyx?

Logistyx TME is a SaaS-based Transportation Management Solution for global parcel shipping that guarantees carrier compliance, streamlines transportation booking, monitors parcel delivery movements, and identifies ongoing opportunities to increase profits per shipment. 

What does this integration include?

This integration enables communication with Logistyx by altering the base functionality in the following ways:

Rate Shop – Sends necessary data in the Ship Request for Logistyx to rate shop from the Store Fulfillment Module of Manhattan Active Omni

Rate Shop

When a user completes a package in Store Fulfillment, a ship request is generated, which communicates the ship from, ship to address and other relevant package information. This ship request is translated to the Logistyx required format with the expected data for Logistyx to select the carrier and generate the shipping label. The Logistyx response is translated back to the Store Fulfillment format where the tracking number is saved against the package, and the 4 X 6 PNG shipping label is saved in the document repository to be printed with the pack slip.

Rate Shopping allows Logistyx to compare carriers and service levels that meet the expected commitment date and ultimately choose the lowest-cost method to ship a package. There is a rate group assigned to each service level, where the corresponding Logistyx Rate Group Name and Id are configured in MAO. The rate group information is sent in the request to Logistyx for each package.

2.1.8.10 - MetaPack

What is MetaPack?

MetaPack is a leading provider of eCommerce delivery management technology to enterprise retailers and brands. The MetaPack platform integrates over 470 carriers and 5,500 delivery services to ensure that retailers and brands can offer delivery options and convenience for their customers.

What does this integration include?

Manhattan Active Omni is not integrated with Metapack out of the box. This integration enables communication with MetaPack Manager 5.x from Manhattan Active Omni “MAO” and Manhattan Active Warehouse Management “MAWM” for:

Rate Shop – Sends necessary data to MetaPack to rate shop amongst carriers and shipping methods in order to determine the most optimal shipping service
Shipping – Createsthe consignment in MetaPack for shipping visibility
Print – Requeststo print the shipping label from MetaPack for the consignment previously created using the Shipping call
Void – Request to void a package with MetaPack in case a user needs to unpack the order or change the shipping method
EOD Manifesting – Request to manifest the package(s) created with MetaPack for each location

Rate Shop

Rate Shopping allows MetaPack to compare carriers and service levels that meet the expected commitment date and ultimately choose the lowest-cost method to ship the package or order based on the business rules set up in MetaPack. If enabled - a rateshop group is sent to MetaPack that corresponds to a Service Group on the MetaPack Side, which allows MetaPack to perform rate shopping amongst similar shipping methods.

Shipping

When a user completes a package, a ship request is generated that communicates the service level, ship from, ship to address and other relevant package information to MetaPack. The base ship request from the Parcel API is updated to allow integration with MetaPack. A shipment call is sent in MetaPack’s required format, where MetaPack creates the consignment for visibility to the carrier’s open manifest, and a shipping label is returned from this call.

Print

After the packing process is completed and the consignment is created in MetaPack, the MAO/MAWM MetaPack App sends a request to MetaPack to provide the additional customs documentation (if required).

Void

A user may wish to change the shipping method or undo the packing due to reasons such as damage to the package or order cancelation. If a consignment was created in MetaPack and now the tracking number will not be used, MetaPack requires a Void request to remove or invalidate the package from a carrier’s open manifest.

Note: The user can only void the package if the package has not been manifested.

EOD Manifesting

The MAO/MAWM MetaPack AP runs a scheduled job to send a manifest request to MetaPack to mark the open consignments as ready to manifest. Alternatively, the base End of Day UI can be utilized to generate the EOD request per carrier. The actual manifesting is handled by Metapack through Delivery Manager and is not communicated back to MAO/MAWM.

Note: It is up to the Manhattan project team & customer to define the preferred approach (scheduler or End of Day UI) as part of the project. It is advised to only use one of these methods.

2.1.8.11 - Proship

What is ProShip?

ProShip is an industry-leading multi-carrier shipping solution that integrates seamlessly with host systems to handle all small parcel, LTL and TL shipments.

What does this integration include?

Manhattan Active Omni is not integrated with ProShip out of the box. This integration enables communication with ProShip by altering the base functionality in the following ways:

Shipping
Rate Shop
Void

Shipping

When a user completes a package in SI&F, a ship request is generated, which communicates the service level, ship from and ship to address and other relevant package information. This ship request is translated to the ProShip required format with the expected data for ProShip to select the carrier and generate the shipping label. The ProShip response is translated back to the Store Fulfillment format where the tracking number is saved against the package, and the 4 X 6 PNG shipping label is saved in the document repository to be printed with the pack slip.

Rate Shop

Rate Shopping allows ProShip to compare carriers and service levels that meet the expected commitment date and ultimately choose the lowest-cost method to ship a package. If enabled, the rate shop ship via is sent to ProShip instead of the service level, which allows ProShip to perform rate shopping.

Void

A user may wish to undo the packing process for a fulfillment or package due to reasons such as damage to the package or order cancelation. If a tracking number will not be used due to the user canceling the packing process, SI&F sends a void request to ProShip who removes or invalidates the package from a carrier’s open manifest.

2.1.8.12 - Purolator

What is Purolator?

Purolator is one of Canada’s leading integrated freight, package and logistics solutions provider.

What does this integration include?

Manhattan Active Omni is not integrated with Purolator out of the box. This integration enables communication with Purolator by altering the base functionality in the following ways:

Tracking Information – Request updated tracking information for packages in transit to the customer
Return Label Generation

Tracking Updates

When a user completes a package in SI&F (Store Inventory & Fulfillment Module), a tracking number is assigned to the package in transit to the customer. This tracking number is stored on the order and displayed on the call center UIs to provide updated delivery information to the call center agent. SI&F makes a call to Purolator in the Purolator required format with the expected data, including a list of SI&F’s in transit tracking numbers, for Purolator to respond with the latest tracking information on each. Based on the response for each tracking number, SI&F makes corresponding updates to the tracking details on the order, in addition to updating the order to ‘Delivered’ status upon final confirmation of delivery.

Returns

When a return order is confirmed, MAO makes a return shipment request to Purolator and Purolator responds with a return tracking number. SI&F sends a subsequent request to Purolator using the tracking number provided in order to obtain the return label. The return tracking number is stored in MAO and the return label is stored in doc management to be retrieved by the external system sending the email to the customer. The customer prints the label and uses it to ship the product back to the return center.

2.1.8.13 - UPS

What is UPS Mail Innovations?

UPS Mail Innovations Returns is a contractual postal returns solution that offers convenience and efficiency to clients’ customers by enabling them to return their orders through the United States Postal Service.

What does this integration include?

Online Orders, bridged into MAO, can be fulfilled by a Distribution Center or a Customer Store. Out of the box, Manhattan Active Omni Store Fulfillment supports FedEx and UPS carrier integrations. This integration extends the base-supported parcel integration with UPS by adding:

Return Labels

Return Labels

This feature facilitates integration with UPS Mail Innovation Returns to generate return labels for each package fulfilled by Manhattan Active Omni Store Fulfillment Application.

2.1.8.14 - United States Postal Service

What is USPS?

The United States Postal Service (USPS) is a vital delivery platform that enables American commerce by providing service to every American business and address.

What does this integration include?

This integration enables communication with USPS by altering the base functionality in the Manhattan Active Omni Store Fulfillment Application in the following ways:

Shipping - Request the package tracking number and shipping label from USPS
Tracking Information – Request updated tracking information for packages in transit to the customer
Cancel Label – Cancels the purchased label in cases where required

Shipping

When a user completes a package in SI&F, a ship request is generated, which communicates the service level, ship from and ship to address and other relevant package information. This ship request is translated to the USPS required format with the expected data for USPS to generate the shipping label. The USPS response is translated back to the Store Fulfillment format where the tracking number is saved against the package, and the 4 X 6 PNG shipping label is saved in the document repository to be printed with the pack slip.

Tracking Updates

When a user completes a package in SI&F, a tracking number is assigned to the package. SI&F compiles the list of open tracking numbers and calls USPS in the required format for status updates on each package. USPS responds with the latest tracking information on each. If the carrier status is configured as ‘In Transit’ in MAO, the package is updated to ‘In Transit’ and the fulfillment is updated to Shipped.

Cancel Package

This is a service exposed to allow for MAO to call and cancel a label printed with USPS when the store associate requests to reprint the label with an updated Carrier and/or Service Level value. This service can either be invoked directly via API call or through an additional extension at the desired event point.

Package Pickup Request

This service allows retailers to schedule reoccurring pickups if their store locations are eligible for the service (based on address). This service allows you to check for pickup availability and to schedule USPS to pick up a shipment. When a store location has at least one package manifested with USPS express shipping, a Pickup Availability Request is made to determine whether pickup service is available that day at the given store location. Based on the response, a package pickup schedule request call is made.

2.1.9 - Promotions

Manhattan Active Omni solution provides clients the ability to integrate with a 3rd party external promotions engine to apply automatic promotions as well as promotions tied to a coupon code during order capture or order edits. As changes to the order are made, a new promotion call can be triggered and the discounts associated to the applied promotions are saved on the order and used in order total calculations. These discounts can be applied against the order, specific order lines, specific charges, and directly against the item price.

Manhattan Active Omni has pre-built apps with many 3rd party Promotion Engines which can be leveraged out of the box. Please see each 3rd party vendor to view what functionalities are available.

Third Party Integrations

2.1.9.1 - Oracle Relate

What is Relate?

Oracle’s Relate is a CRM system which is used to manage coupons and promotions and offers services to redeem coupons. The system consuming the coupon is expected to make use of these services.

What does this integration include?

Manhattan Active Omni is not integrated with Relate out of the box. This integration enables communication with Relate by altering the base functionality in the following ways:

Coupon Validation
Coupon Redemption
Coupon Void

Coupon Validation

When a new order is created or an existing order is edited to add a serialized coupon in Manhattan Active Omni, MAO makes call to receive the serialized coupon status from Oracle CE.

Coupon Redemption

The feature offers a service to initiate coupon redemption call for one or more serialized coupons in a transaction after the coupons are deemed valid.

Coupon Void

In the scenario where an order is cancelled, or a line is cancelled, Manhattan Active Omni makes a call to Oracle CE to void the applied coupon(s).

2.1.9.2 - Salesforce

What is Sales Force Commerce Cloud OCAPI?

Sales Force Commerce Cloud (SFCC) has a pricing and promotions offering called ‘OCAPI’ which is used by customers for their Web/ Call Center orders to determine the pricing and promotions.

What does this integration include?

Manhattan Active Omni is not integrated with SFCC OCAPI out of the box. This integration enables communication with OCAPI by altering the base functionality in the following ways:

Pricing & Promotion Evaluation
Calculate S&H
Retrieving SFCC Customer ID

Pricing and Promotion Evaluation

SFCC is used to manage all types of promotions, as well as pricing of the items for the included order types under this integration. SFCC provides a single pricing and promotions engine to have a consistent way of evaluating pricing and promotions across different B2C/B2B channels. This includes evaluating order promotions, coupons, item promotions, pricing, and shipping promotions. Coupons added by the CSR in the UI are evaluated and, if eligible, are applied to the basket. These promotions are applied to a Customer Order via a REST-service call to SFCC OCAPI. SFCC determines if the coupons are eligible (making an internal call to external system for validation) based on the basket details of the order and responds with the applied promotion(s) details and value.

The basket calculation web-service call is triggered whenever an update is made on the order that impacts promotion eligibility (Ex. Add Item/Cancel line, Add Coupon, Enter Shipping Information, Quantity Update). The out-of-the-box MAO UI is utilized to display the promotion details to the CSR. Configuration for MAO to delete the basket is also available as SFCC OCAPI has a limit on the number of open baskets for a given customer.

Calculate Shipping and Handling

This feature adds the ability to bypass MAO Shipping Charge Calculation and instead use SFCC OCAPI for evaluating and apply shipping charges.

Retreiving SFCC Customer ID

As many clients do not maintain the SFCC Customer ID as the main Customer ID in MAO, the SFCC Customer ID needs to be provided back on the first basket call, which MAO stores on the order in an extended attribute. This value is then sent as the Customer ID in all subsequent basket calls to OCAPI.

2.1.9.3 - XCCommerce

What is XCCommerce?

XCCommerce provides a state of the art suite of applications that enable complex promotion and coupon capabilities across all channels and provide a seamless and consistent customer experience at all points of purchase.

What does this integration include?

Manhattan Active Omni is not integrated with XCCommerce out of the box. This integration enables communication with OCAPI by altering the base Point of Sale functionality in the following ways:

View Promotions – Call XCCommerce ‘PEM-L’ Service to display eligible promotions for a given item
Apply Promotions – Call XCCommerce ‘PEM-P’ to reapply promotions based on defined modifications to the cart

View Promotions API

When a store associate is browsing items from the item global search or product catalog in Manhattan Active Omni Point of Sale module, it is important to enable them with promotion information to help upsell to the customer. Whenever an item is selected from the global search or product catalog, this App generates the ‘PEM-L’ call to XCCommerce to return back the eligible promotions for the item to display to the user.

Apply Promotions API

When the store associate is making updates to the Point of Sale cart, such as adding or removing an item or adding a coupon, the cart must be re-evaluated for eligible promotions. MAO generates a ‘PEM-P’ call to XCCommerce to apply any eligible promotions to the cart. The response is translated to the MAO required format to update the cart.

2.1.10 - Tax

Manhattan Active Omni solution provides integration out of the box with Vertex to calculate estimated taxes during order creation, order edits, and final taxes upon invoicing. Some customers may wish to integrate with a different 3rd party tax engine to calculate taxes.

Manhattan Active Omni has pre-built apps with many 3rd party tax engines which can be leveraged out of the box. Please see each 3rd party vendor to view what functionalities are available.

Third Party Integrations

2.1.10.1 - OneSource

What is OneSource?

OneSource is a tax software that integrates seamlessly with host systems to provide quotation and invoice tax detail information for customer order transactions.

What does this integration include?

Manhattan Active Omni allows for base-supported tax integration with Vertex Tax Management. This integration enables communication with OneSource by altering the base functionality in the following ways:

Quotation tax calculation
Invoice tax calculation
Return invoice tax calculations.

Quotation Tax Calculation

When an order is created or edited in Manhattan Active Omni’s Call Center module, a quotation tax call is generated for the order so the appropriate authorized amount of a payment tender can be secured. This quotation tax call is translated to the OneSource required format with the expected data for OneSource to provide the quotation tax calculation. The OneSource response is translated back to the Manhattan Active Omni format where the jurisdiction-level tax details are saved against the order and order line(s).

Invoice Tax Calculation

When an order is shipped in Manhattan Active Omni, an invoice tax call is generated for the order in, so the appropriate amount of the provided payment tender can be settled against. This invoice tax call is translated to the OneSource required format with the expected data for OneSource to provide the invoice tax calculation. The OneSource response is translated back to the Manhattan Active Omni format where the jurisdiction-level tax details are saved against the order and order line(s).

Return Invoice Tax Calculation

When an order is refunded in Manhattan Active Omni, an invoice tax call is generated for the order in so the appropriate amount of the provided payment tender can be settled against. This invoice tax call is translated to the OneSource required format with the expected data for OneSource to provide the invoice tax calculation. The OneSource response is translated back to the Manhattan Active Omni format where the jurisdiction-level tax details are saved against the order and order line(s).

2.1.10.2 - Taxware

What is Taxware?

Taxware is a continuous and connected platform for tax determination, e-invoicing compliance, and tax reporting to governments around the world. All these services are offered as part of a single cloud-based platform.

What does this feature include?

This feature adds integration with Taxware to facilitate Manhattan Active Omni to calculate Quotation, Invoice, and Return taxes.

Quotation

When an order is created or modified using Manhattan Active Omni’s Customer Service or Point of Sale Solutions, a quotation tax call is generated instead of the order so the appropriate authorized amount of a payment tender can be secured. This quotation tax call is translated into the format required by Taxware and comprises all the details that Taxware needs to calculate the quotation tax amount. The Taxware response is then translated back to the Manhattan Active Omni format, and the tax details are saved against the order and the respective order line(s).

Invoice

When an order is shipped in Manhattan Active Omni, an invoice tax call is generated to calculate the tax at the time of shipment so that the appropriate amount can be settled against the provided payment tender. This invoice tax call is translated to the format required by Taxware and comprises all the details needed by Taxware to perform the invoice tax calculation. The Taxware response is then translated back to the Manhattan Active Omni format, and the tax details are saved against the order and the corresponding order line(s).

Return

When an order is returned in Manhattan Active Omni, a return invoice tax call is generated against the order so that the appropriate amount can be refunded to the customer. This return invoice tax call is translated into the format mandated by Taxware and contains all the details that Taxware needs to calculate the return invoice tax amount. The response is then translated back to the Manhattan Active Omni format, and the tax details are saved against the order and the respective order line(s).

2.1.10.3 - Avalara

What is Avalara?

Avalara is an industry-leading tax solution that integrates seamlessly with host systems to handle all tax calculation needs for eCommerce.

What does this integration include?

Manhattan Active Omni is not integrated with Avalara out of the box. This integration enables communication with Avalara by altering the base functionality in the following ways:

Tax management including Quotation, Invoice, and Refund tax calculations
Tax Rate Download

Tax Management

When an order is created in Manhattan Active Omni’s Customer Service or Point of Sale applications, a quotation tax call is generated for the order so the appropriate authorized amount of a payment tender can be secured. When an order is shipped in Manhattan Active Omni, an invoice tax call is generated for the order so the appropriate amount of the provided payment tender can be settled against. When an order is returned in Manhattan Active Omni, an invoice tax call is generated for the order so the appropriate amount of the provided payment tender can be refunded against.

The tax calls are translated to the Avalara required format with the expected data for Avalara to provide the appropriate tax calculation. The Avalara response is translated back to the Manhattan Active Omni format where the jurisdiction-level tax details are saved against the order and order line(s).

Tax Rate Download

Avalara Tax Rate Download is used to support tax calculation in POS Offline mode. A scheduler is created in Manhattan Active Omni to trigger the Avalara Tax Rate Download API on a configurable schedule. MAO sends the list of store locations to Avalara and Avalara returns the applicable tax rates for all valid Store/Product Class combinations.

2.2 - Manhattan Active® Supply Chain

Manhattan Active® Supply Chain Integration Apps

Integrate your Manhattan Active Solution with common third party services such as parcel. Additional capabilities beyond what is available in the existing apps can be addressed by the services project team.

Please select the category from below for a summary of its functionalities.

2.2.1 - Parcel Carrier

Manhattan Active Warehouse Management solutions provides clients the ability to integrate with external parcel providers for flexible rate shopping, shipping label generation, manifest assignment. Use cases include:

Optional rules-based Rate Shop Group determination by MAWM.
Rate shop request at package generation for optimal carrier & service level assignment which meets customer service level agreement.
Flexible tracking number generation timing to fit various business requirements.
Carrier compliant references that provide additional information on shipping labels.
Shipping label document storage in MAWM for real time or delayed printing requirements.
Real time manifest assignment or delayed assignment using Ship to Hold functionality.
Simple ‘End of Day’ process to request closure of carrier manifests from MAWM to ship packages.
Manifest documentation provided by EPI and printed by MAWM at the time of End of Day.

Third Party Integrations

2.2.1.1 - MetaPack

What is METAPACK?

What does this integration include?

Manhattan Active Warehouse Management solutions provides clients with direct integration with one of the leading eCommerce delivery management systems, MetaPack. This integration enables communication with MetaPack Manager 5.x from Manhattan Active Warehouse Management “MAWM” for:

Rate Shop – Sends necessary data to MetaPack to rate shop amongst carriers and shipping methods in order to determine the most optimal shipping service. Rate shopping at package generation compares carriers and services that meet the expected commitment date and selects the lowest cost shipping method.
Shipping – Creates the consignment in MetaPack for shipping visibility. Ship request at package completion creates the consignment visibility to the carrier’s open manifest
Print – Request to print the shipping label from MetaPack for the consignment previously created using the Shipping call. Print requests are sent automatically as packing is complete to obtain the corresponding shipping documents
Void – Request to void a package with MetaPack in case a user needs to unpack the order or change the shipping method.
EOD Manifesting – Request to manifest the package(s) created with MetaPack for each location. Automatic End of Day manifest processes are performed without any user intervention
Direct API communications between MAWM and MetaPack do not require use of middleware

RATE SHOP

SHIPPING

PRINT

After the packing process is completed and the consignment is created in MetaPack, the MAO/MAWM MetaPack App sends a request to MetaPack to provide the additional customs documentation (if required).

VOID

Note: The user can only void the package if the package has not been manifested.

EOD MANIFESTING

The MAO/MAWM MetaPack App runs a scheduled job to send a manifest request to MetaPack to mark the open consignments as ready to manifest. Alternatively, the base End of Day UI can be utilized to generate the EOD request per carrier. The actual manifesting is handled by Metapack through Delivery Manager and is not communicated back to MAO/MAWM.

Note: It is up to the Manhattan project team & customer to define the preferred approach (scheduler or End of Day UI) as part of the project. It is advised to only use one of these methods.

3 - Glossary of key terminology

Become familiar with the key terminology utilized throughout this documentation.

Manhattan Active® Platform, or simply the “Platform” is the underlying runtime that houses the Manhattan Active® applications’ components, and manages them. For an overview of the Platform, see Manhattan Active® Platform Overview. The Platform is informally called the “Cloud Platform”, “CP” or simply, “Active”.

Manhattan Active® Omni

Part of the Platform, Manhattan Active® Omni provides the business functions for Omni-channel commerce and retail. MAO, as it is known in short, includes several business applications including the Order Management, Customer Engagement, Store Inventory & Fulfillment and Point of Sale. For an overview of MAO, see Manhattan Active® Omni Overview

Manhattan Active® Supply Chain

Part of the Platform, Manhattan Active® Supply Chain provides the business functions for Warehouse and Distribution, and Transportation ecosystem. MASC, as it is known in short, includes several business applications including the Warehouse Management, Labor Management, Yard Management, and Transportation Management. For an overview of MASC, see Manhattan Active® Supply Chain Overview

Manhattan Active® Inventory

Environment

An Environment is an isolated “slice” the Manhattan Active® applications as used by a customer, or a tenant. An environment is a logical “container” of the business workflows, custom extensions and business configuration of the application for the given customer. And hence, it is also sometimes referred to as the customer’s environment. Do note, that while an environment may have a one-to-one relationship with underlying compute runtime in certain cases, an environment in many cases may also share compute resources with other environments stood up for that customer or other customers. However, what the term environment does ensure is the isolation of data and business workflows of a customer from other customers - at rest and in transit. Manhattan Active® Platform deployments also ensure that one environment is not impacted adversely – functionally or in performance – because of a neighboring environment if the compute resources are shared among these environments.

Stack

A Stack is a network-isolated collection of compute and physical or virtual resources of the underlying cloud infrastructure. A stack hosts one or more environments depending on the tenancy definition of the stack. Every stack consists of a Kubernetes cluster, a database, a set of essential services, the application microservices, application configuration, and zero or more custom extension components. In other words, a stack is the physical runtime that hosts one or more logical environments. A stack is accessed and managed by the Manhattan Active® Cloud Operations team.

Microservice

A Microservice is a self-contained, immutable, and portable process that can be built, delivered, deployed, run, and managed in isolation from other processes. In Manhattan Active® Platform, most microservices are written in Java, though some microservices use different implementation technologies and programming languages. All microservices in Manhattan Active® Platform are built as Linux containers, orchestrated via Kubernetes, and are accessible via a REST API.

Component

A “Component” is a term used interchangeably with a “microservice”.

Essential Service

Essential Services are specialized microservices, including 3rd party software such as Rabbit MQ or Elasticsearch, that provide runtime support and system services (such as caching, indexing, messaging, time series storage, configuration management etc.) to the application microservices. Without the essential services, the application microservices may not function or perform properly. And hence the term “essential”.

Application Configuration

Application configuration consists of a set of properties files that are maintained in a Key-Value store (Consul), and are injected into the microservice process’s runtime using native configuration instrumentation techniques (such as Spring Cloud Config). Application configuration is managed and delivered just like the way the application code binaries are delivered to the target runtime. Changes to the application configuration are tracked via the built-in change detection & audit mechanisms.

Auth Server

Auth Server is a microservice deployed as part of Manhattan Active® Platform. It performs the role of intercepting the inbound authentication calls, and processes them by redirecting them to the target identity or authentication system (it could be an external system such as a 3rd party identity provider, or could be Manhattan Active® Platform’s native authentication). Upon successful authentication, Auth Server constructs the necessary service context and OAuth access token, and redirects the invocation to the target application (such as Manhattan Active® Omni, Supply Chain or Inventory). All user interface and REST API invocations must authenticate with Auth Server first before they can reach to the application. Unauthenticated requests are returned with HTTP 401 UNAUTHORIZED status code.

Zuul Server

Zuul Server is a microservice deployed as part of Manhattan Active® Platform. It performs the role of a gateway and a router: all user interface and REST API invocations first reach Zuul Server immediately after authentication, and dispatched to the target application microservice based on statically defined routing configuration. Additionally, Zuul Server also performs the resource grants for the requested resource by the user (or system) submitting the request. Zuul Server will only dispatch the invocation downstream if the requester has the grants to access the requested resource. Unauthorized requests are returned with HTTP 403 FORBIDDEN status code.

Organization

Organization is a microservice deployed as part of Manhattan Active® Platform. It performs the role of the bookkeeping of organization hierarchy, application users, user roles and resource grants, locations (such as warehouses or stores), business units of organizations, and authentication information (usernames, passwords, and PINs) applicable to Manhattan Active® Platform’s native authentication mechanism. Organization provides a user interfaces and API to retrieve and manage this configuration, and is used by many other downstream microservices to utilize organization hierarchy and other configuration in business workflows.

User

A User is someone who uses a Manhattan Active® application. Examples of users include employees in a store or a warehouse, or customer service representatives in a call center, or a corporate executive retrieving the operational report. The users are typically the employees, temporary staff, or contractors of the customer of the Manhattan Active® application.

Robot

Robots are specialized user accounts designated to invoke the Manhattan Active® Platform APIs. Robots can be assigned roles and grants just like the “human” users, except that the Robot users can only access the REST API, and not the user interface of the applications.

Resource

Every “function” (such as an API, user interface, or any other URLs that a user may access) is defined as a resource. Every resource is controlled by one or more permission. A user can only access a resource if they have the permission for that resource. A user can only perform a certain action to a resource based on the permissions given to that resource.

Permission

A Permission is a predefined entity for governing access control. A permission defines the type of access (“read”, “write”, “admin”) a specific resource such as a user interface, or an API of the Manhattan Active® Platform. Permissions are static values that must be added to a role, and granted to a user.

Role

A Role is a collection of permissions such that the permissions can be grouped based on business requirements. Roles may be defined as “corporate administrator”, “user administrator”, “store user”, “CSR”, “cashier” etc. When a role is assigned to a user, the user inherits the permissions defined in the role. Roles can also be hierarchical. Roles are typically defined statically as part of business configuration of the application, but can also be modified as part of the routine operation of the applications. Roles can be managed via the Organization user interface, or API.

Grant

A Grant is the assignment of a role to a user. A grant states what resources a user has, and what a user can do with that resource. Grants are typically added, modified or deleted dynamically as users are onboarded, change their responsibilities or when they are removed from the application. Grants can be managed via the Organization user interface, or API.

Stereotype

In a typical deployment, a microservice could have multiple instances running at any given time. We assign specific responsibilities to every instance by setting a stereotype to that instance. During the runtime, the instance can detect the stereotype value, and behave in a certain way, throughout its life cycle. Stereotype values are predefined such as REST that designate certain instances to process the REST API workload including all HTTP invocations from the user interfaces or external systems, QUEUE_PROCESSOR to process asynchronous messages from queuing systems, and ALL to process both REST/HTTP and asynchronous workload.

Extensibility

Extensibility is Manhattan Active® Platform’s ability to extend or modify the default behavior of an application function. Extensibility is a mechanism using which customers can develop additional business functionality to meet their functional requirements, or can adjust them to work within the existing IT landscape. Such changes to out-of-the-box (“base”) functionality is called a Custom Extension.

Extension Point

Manhattan Active® Platform exposes “hooks” in certain places in the base functional flows where a custom extension is plugged in. These hooks are well documented similar to the APIs, and continue to grow in numbers as Manhattan identifies new requirements. These hooks are also known as the extension points.

Extension Handler

In order to use an extension point, it needs to be attached to some handling configuration such as invoking one or more service, or intercepting the incoming payload and modifying it when that extension point is invoked. The handling configuration is defined as an Extension Handler. The handler can utilize the base API, 3rd party APIs, or other custom extensions. If an extension handler is defined for an extension point, the base code will invoke the configured custom flow at that point. Subsequent execution of base code will make use of the modified payload returned from the extension handler’s response. Extension points with extension handlers could cause performance problems. Performance tests should be performed when implementing extension handlers that may cause execution latency.

Synchronous Extension Handler

Synchronous extensions handlers are a type of extension handler that execute the extension flows synchronously. If a synchronous call-out (user exit) is defined for an extension point, the base flow waits for the response from the handler before proceeding to the next step. If the extension handler modified the payload in transit, the subsequent workflow execution will use the modified payload returned from the extension handler for further execution.

Asynchronous Extension Handler

Asynchronous extension handlers are a type of extension handler that execute the extension flows asynchronously. Events are typically used for “fire and forget” workflows (such as notifications of certain milestones), though they can be modeled to orchestrate a workflow that can handle asynchronous invocations. For example, when a new order is placed, the system can send a message to a queue to notify the recipient about the order creation event. The receiving system (the target that subscribes to the asynchronous message) can in turn invoke additional steps in the workflow with or without modifying the payload.

Custom Extension Components

Custom extension components are microservices developed and deployed in the SaaS environment for meeting a customer’s business requirement. A custom extension component runs custom (Java) code as part of the Manhattan Active® Platform’s cloud runtime, and integrates with the base microservices via REST API or messaging. Do note, that only the Manhattan’s professional services team is authorized to develop and deploy the custom extension components as they require internal knowledge of how the system works and depend on restricted resources that are only accessible to Manhattan employees.

AWPF

AWPF stands for Asynchronous Workload Processing Framework. AWPF is Manhattan’s proprietary framework for abstracting the management of asynchronous communication for individual microservices.

Message

A Message is an asynchronous payload either received by, or sent by, a microservice, and is sent or received using a queuing mechanism such as Rabbit MQ. A message has a producer, and usually, zero or more consumers. A message provides an ability for microservices to communicate to one another asynchronously in one of one-to-one, one-to-many or broadcast fashion. A message has two parts: The metadata about the message, or the header, and the actual message content, or the body. The header contains the envelope information (sender and receiver information, metadata about the message and timestamps). The body contains the business contents of the message.

Message Types

Message Types are configuration entities meant to provide an easy-to-use abstraction for queue naming and other connection details. From a microservice’s perspective, it can either produce some messages or consume some messages. Messages produced by a microservice, are called outbound messages, and messages consumed are called inbound messages. These message types are defined technically as OutBoundMessageType and InBoundMessageType, and are available in the runtime of every microservice.

Message Brokers

Message Brokers are the message queueing services or systems that a microservice can integrate with. Manhattan Active® Platform supports Rabbit MQ and Kafka for internal messaging (messaging between microservices), and Google Pub/Sub or Amazon SQS for external messaging (messaging to- and from- the microservices and external systems).

Transactional Messaging

If there is a need to send a message only when the parent transaction succeeds, we can use the Transactional Messaging. The parent transaction can perform different database updates along with sending the message. There are primarily two resources involved in such transactions: the database and messaging. As the transaction does not span both resources (not JTA), Manhattan Active® Platform has its own way of handling such requirement by first writing the message to a database and then sending it to the messaging service.

Non-transactional Messaging

Unlike the transaction messaging, if a message can be sent irrespective of the presence or completion of a parent transaction, Manhattan Active® Platform also supports Non-transactional Messaging. It does not have the overhead of tracking transactionality of a message.

Message Persistence, or TranLog

Manhattan Active® Platform has a way of storing messages in Elasticsearch for future reference and reconciliation. It is recommended to enable message persistence for only external messages as there could be need for reconciliation later. For message types that do not require reconciliation later, or for other replayable messages, message persistence should be disabled as it could lead to over-utilization of resources and performance issues.

Learn More

Author

Kartik Pandya: Vice President, Manhattan Active® Platform, R&D.
Subhajit Maiti: Director, Manhattan Active® Platform, R&D.
Shanthosh Govindaraj: Director, Manhattan Active® Platform, R&D.

4 - Asynchronous Communication with Manhattan Active® solutions via Google Pub/Sub

Recommendations on setting up asynchronous communications with Manhattan Active solutions via Google Pub/Sub and best practices for publishing or consuming messages.

Introduction

Manhattan Active® Platform is API-first, cloud native, and microservices-based. For enterprise systems to integrate and communicate, Manhattan Active Platform provides both synchronous and asynchronous communication options. All asynchronous communication between Manhattan Active solutions and external systems is done via Google Pub/Sub. This document provides guidelines on how to set up asynchronous communication with Manhattan Active solutions over Google Pub/Sub.

What is Google Pub/Sub?

Google Cloud Pub/Sub is a real-time messaging service that allows applications to publish and subscribe to events. It’s a publish/subscribe-based mechanism for sending and receiving messages between applications and services. You can find more information on Pub/Sub on the Google Cloud website here: https://cloud.google.com/pubsub/docs/overview

Integrating with Google Pub/Sub

Google Pub/Sub provides two connectivity approaches:

Google provides an SDK that can be added as a library to your application: https://cloud.google.com/pubsub/docs/reference/libraries
REST API which can be invoked from your application: https://cloud.google.com/pubsub/docs/reference/rest

Authenticating to Pub/Sub

The Manhattan Associates project team will provide a JSON Key file to your integration team. The key file can be used to authenticate against Google Pub/Sub for both the integration approaches mentioned earlier - either the Google Pub/Sub SDK or the REST API. Please review Google Pub/Sub documentation for details on how to use a key file for authentication. Some external applications and middleware systems, such as Boomi, require a .p12 certificate instead for Pub/Sub Authentication, which the Manhattan project team can provide on request.

Pub/Sub Endpoints

The Manhattan Associates project team will create Pub/Sub endpoints for each external interface identified in the solution design. The interfaces may either be “Inbound”, where messages are sent to the Manhattan Active solution, or “Outbound” where messages are sent by the Manhattan Active solution out to external systems.

Outbound Interfaces

The Manhattan Active solution will publish outbound messages to a Pub/Sub topic, and the consumer(s) on the external system will have to read those messages from the corresponding Pub/Sub Subscription. The name of the Subscription will be in the following format: projects/{{project-id}}/subscription/{{interface-name}}

Note:

The project id will differ by environment – STAGE, VPT, or PRODUCTION. The project team will provide the project id value for each environment.
If multiple external systems need to consume a copy of the same message, then the external middleware system can consume the message from a single Pub/Sub subscription and fan out copies of the message to each receiver.

Inbound Interfaces

When external systems have to send messages to the Manhattan Active solution, they must publish those messages to the appropriate Pub/Sub Topic. The name of the Topic will be in the following format: projects/{{project-id}}/topic/{{interface-name}} If multiple systems need to send the same messages, they may send them to the same Topic. For example, if there are multiple Distribution Centers and Stores needing to send Inventory updates to Manhattan Active OMNI, they can all publish to a single Pub/Sub Topic.

The Manhattan project team will create the required Pub/Sub Topics and Subscriptions based on the solution design.

Message Payloads

Google Pub/Sub requires the message payloads to be Base64 encoded. The structure of the payload for each interface is documented in the Interface Mapping Document, created as a part of the Solution Design.

Message Payload Size

Google Pub/Sub limits the maximum size of a message to 10 MB. In case there is a possibility of messages exceeding the 10 MB limit for an interface, Manhattan Active Platform can be configured to send/receive GZIP compressed payloads for that interface. Note that when GZIP compression is enabled for an interface, it will apply to all messages for that interface, irrespective of whether specific messages exceed the 10 MB limit or not.

Message Acknowledgment

Once a consumer reads a message from a Google Pub/Sub Subscription, it must send an acknowledgment must be sent to Pub/Sub. This is used to ensure Guaranteed Delivery of messages. Please refer to Pub/Sub documentation on how to acknowledge receipt of messages.

Messages must be acknowledged even if message processing fails due to any kind of error, including validation errors. If a message is not acknowledged in a timely manner (by default 10 seconds), Google Pub/Sub will not remove the message from the subscription, leading to duplicate reads.

If a message sent from a Manhattan Active solution fails to process on the external system, the external system must not use a NACK response as it can cause infinite looping of that message. Instead, the failed message must be acknowledged and sent to a Dead Letter Queue for offline triage.

Duplicate Messages

To ensure Guaranteed Delivery of messages, Google Pub/Sub depends on message acknowledgments to determine if a consumer has received a message from the subscription. The message acknowledgments must be sent to Google Pub/Sub within a deadline, which by default is 10 seconds. If the acknowledgment threshold is crossed, Google Pub/Sub will assume the message was lost and will re-deliver the message to the consumer, which can lead to message duplication.

Manhattan Active Platform uses a custom Pub/Sub attribute to track inbound messages and identify duplicate messages being re-delivered by Pub/Sub. When sending messages to Manhattan Active solutions via Google Pub/Sub, the sending system must include the MSG_ID_PK attribute populated with a unique value. The unique value for the MSG_ID_PK attribute may be generated from a UUID library. The Manhattan Active solution can be configured to track each MSG_ID_PK value it reads from incoming messages and discard messages that have an MSG_ID_PK value that has been received previously. Since the duplication check works solely on the uniqueness of the MSG_ID_PK value, it is important that if the external system is resending a message, then it must not change the MSG_ID_PK value.

When the Manhattan Active solution sends outbound messages to external systems over Google Pub/Sub, it will include the MSG_ID_PK attribute to help external consumers identify and de-duplicate messages on their side.

Message Attributes

When an external system sends messages to the Manhattan Active solution, it must include the following Pub/Sub Attributes on every message:

Attribute Name	Attribute Value
Organization	Organization at which the message must be processed. This is typically identified during the Solution Design.
User	User-id of an active user account in the Manhattan Active solution, whose PrimaryOrgId matches the Organization value.
MessageType	Interface name, to be provided by Manhattan
MSG_ID_PK	Unique message identifier, which is generated from a UUID library. Max length 50 characters.

Every message sent by a Manhattan Active solution to an external system over Google Pub/Sub will have the following attributes (not an exhaustive list):

Attribute Name	Attribute Value
SelectedOrganization	Org ID from which the message was generated in the Manhattan Active solution. Discard any message without throwing an error, that has an unrecognized value.
MSG_ID_PK	Unique message identifier. May be generated from an UUID library. Max length 50 characters.

Message Sequencing

There is no guarantee of sequencing/ordering of messages sent from the Manhattan Active Solution via Pub/Sub. If the external systems require sequencing of messages being sent by the Manhattan Active solution, it is recommended that the external middleware system stages the incoming messages first locally and then sequences it for its consumption as needed.

Author

Devraj Roy: Architect, Technical Services, PSO.

References

5 - Cloud Networking

Understand how Manhattan configures the networking of customer environments to ensure isolation, prioritize security, and optimize performance.

Introduction

Manhattan Active® Platform is deployed as a distributed application using Google Kubernetes Engine on Google Cloud Platform. When we use Kubernetes Engine to orchestrate the Manhattan Active applications, it’s important to think about the network design of the applications and their hosts.Networking design is critical for architecting the infrastructure because it helps to optimize for performance and secure application communications with internal and external services.

Below are the key networking components we designed and implemented for Manhattan Active® Platform.

VPC

Virtual Private cloud (VPC) is the global private isolated virtual network partition that provides managed networking functionality for each kubernetes cluster. It is the fundamental networking resource created before we deploy the kubernetes cluster. When we create the Google project, a dedicated automode VPC is created, and VPC for each customer environment are unique and independent to restrict access from one environment into another. The network firewall and ACL rules for each environment forbid network-level access across environments. As the VPC mode is auto, automatic subnets are created on the Google region and the kubernetes cluster will use those subnets for creating the cluster nodes.

VPC Flow Logs have enabled for all the VPC, and enabling flow logs records a sample of network flows sent from and received by instances used as Google Kubernetes Engine nodes. These logs can be used for network monitoring, forensics, real-time security analysis, and expense optimization.

Planning the GKE IP address

GKE clusters require a unique IP address for every Pod. In GKE, all these addresses can be routed throughout the VPC network. Therefore, IP address planning is necessary because addresses cannot overlap with private IP address space used on-premises or in other connected environments. The following sections suggest strategies for IP address management with GKE.

Our cluster type is private, and each node has an IP address assigned from the cluster’s Virtual Private Cloud (VPC) network.
/24 is the default CIDR block assigned for each cluster node to assign the GKE pods.
RFC 1918 Ip address range is used for the GKE pods and services.

GKE cluster

Kubernetes clusters created for the Manhattan Active® Platform are private by default. Private clusters use nodes that do not have external IP addresses. This means that clients on the internet cannot connect to the IP addresses of the nodes. It reduces the attack surface and the risk of compromising the workloads. The Master node, which is hosted on a Google-Managed project, communicates with the nodes via VPC peering. The public endpoint for the GKE control plane is not exposed to the outside world, and we have enabled authorized networks by only allowing the secure networks.

Cloud NAT

Private GKE Clusters don’t have any external IP addresses, and all the nodes instances get internal ip addresses by default. Pods running on these node instances can’t access the internet. We are configuring Cloud NAT service to allow private Google Kubernetes Engine (GKE) clusters to connect to the Internet.

Cloud NAT implements outbound NAT (i.e. network translation, mapping internal IP addresses to external IP) to allow instances to reach the Internet. As part of Cloud NAT configuration, we can manually reserve a set of public IP address which would create and release IP based on workloads.

When we integrate the Active Omni or Active supply chain with other third party applications via xbound, which employs IP Whitelisting as part of the access mechanism, we can share the ip addresses of the Cloud Nat instead of sharing the Xbound node pool ip address.

Private Google Access

We have also enabled private Google access by default on the VPC where the GKE cluster has deployed. Private Google Access provides private nodes and their workloads access to Google Cloud APIs and services over Google’s private network.

For example, in all customer environments, Private Google Access is used by clusters to access most of the Google apis.

External communication using Xbound

XBound is a Java, Spring Boot component that wraps Netflix OSS Zuul library to provide an outbound proxy, or router that can forward the incoming HTTP(s) calls to configured external locations. The diagram below explains how the invocation sequence looks:

As shown above, the base (and the custom) components invoke the XBound endpoints, and based on the mapping configuration in XBound, the calls would get routed to the external endpoints. In other words, XBound can also be seen as a â€œNATâ€ gateway into the outer world, but with more flexibility and control than a standard NAT configuration that the IaaS providers have.

XBound can run as one or more containers similar to the application components. However, XBound is always configured to run on a separate, exclusive node pool (called xbound-pool). This node pool has special configuration in place to automatically assign static public IP addresses. Having static public IP addresses allows for a possibility of the external location requiring an IP address restriction (such as a firewall allow-list). Do note, that the nodes on which the components run (the components-pool) do not have static IP addresses

Route Configuration XBound uses Spring properties to define the routes using the Zuul routing syntax. See the example below:

zuul.routes.example.path: /example/**
zuul.routes.example.url: https://example.com

In this simple example, calls made to XBound on path /example/... will get routed to the target https://example.com/... . The ... designates the remainder of the path as is. For example:

curl -s com-manh-cp-xbound:8080/example/foo/bar

…will result in the same call being forwarded to…

https://example.com/foo/bar

Here’s another example to better explain the concept (real example that can be tested):

Properties in XBound:
---------------------

zuul.routes.ifconfig.path: /ifconfig/**
zuul.routes.ifconfig.url: https://ifconfig.co

Invocation to XBound (presumably from a RestTemplate in the component code):
----------------------------------------------------------------------------
curl -s com-manh-cp-xbound:8080/ifconfig

Invocation is routed to:
------------------------
https://ifconfig.co

If the invocation of XBound is changed:
---------------------------------------
curl -s com-manh-cp-xbound:8080/ifconfig/ip

Then the target is routed to:
-----------------------------
https://ifconfig.co/ip

HTTP Authentication method for xbound

For HTTP(s) calls that originate from the application components, but reach the target external endpoint without any HTTP(s) authentication mechanism, nothing additional needs to be configured. However, if HTTP(s) authentication is required, then depending on the type of authentication requirement, additional configuration may be needed:

Basic auth: No additional configuration required. The Authorization: Basic header with the base64 encoded credentials is passed as is to the forwarded invocation. In other words, the external endpoint will receive the authorization header as is.

OAuth token: No additional configuration required. The Authorization: Bearer header with the encrypted access token is passed as is to the forwarded invocation. In other words, the external endpoint will receive the authorization header as is.

Certificate based auth: The client cert configuration is supported by XBound. However, this feature is supported only for custom extension requirements, and not for base calls. The reason for this restriction because the client certificates are typically customer specific versus the base application code will need to be client-agnostic.

Edge Service

An edge service is a service that provides an entry point into an enterprise or the network of a service provider. Edge services can be as simple as a stateless router or a switch and as complex as a full-fledged web application that addresses not only routing but also other concerns such as security, authorization, throttling etc.

Edge services typically address one or more of the following concerns

Network security
User authentication and authorization
Network protocol translation
Payload transformation and/or translation
Rate limiting and Throttling
Resiliency
Performance

Why do we need edge services?

We need edge services for our Active Supply Chain solutions to:

access the devices (i.e. printers, MHE, RF and touch devices, etc.) on the customer’s facility and on the customer’s network
translate between network protocols (i.e. TCP, HTTPS, etc.)
provide a single way to interact with the Active Supply Chain solutions on the cloud
ensure that customer’s applications and devices contact the Active Supply Chain solutions with adequate security and access controls in place
improve user experience

Edge service components

These components should:

communicate with Manhattan Active Supply Chain components (within Manhattan’s VPC) through the public load balancer/gateway using HTTPS protocol
not contain any configuration data and/or should not serve any UIs or HTTPS services for end users
communicate internal state and/or transient events to an auditing system hosted on Manhattan’s VPC
log application logs to an external logging system like StackDriver logging on the Google Cloud Platform (GCP)

Edge Networking

Edge services will be deployed within a Virtual Private Cloud (VPC) on GCP for each facility. This VPC will be peered with the customer’s network at the facility using VPN (IPsec tunnel) or alternative suitable peering mechanisms. Once peered, all the devices on the customer’s facilities network will be discoverable by the edge components for that facility. The following diagram shows the deployment and the network boundaries.

Connectivity to Edge Networking

There are multiple ways to connect the Edge stack and customer network. Cloud VPN and Cloud interconnect are the two options typically used for the connectivity. Cloud Interconnect is an expensive option and generally used for gigabytes bandwidth requirement, whereas Cloud VPN is inexpensive and has enough bandwidth support needed for the SC Edge stack.

Cloud VPN

Cloud VPN securely connects the peer network to the Virtual Private Cloud (VPC) network through an IPsec VPN connection. Traffic traveling between the two networks is encrypted by one VPN gateway and then decrypted by the other VPN gateway.High-Availability is the default options we recommend for all our customers. HA VPN is a high-availability (HA) Cloud VPN solution that securely connect the on-premises network to your VPC network through an IPsec VPN connection in a single region. HA VPN provides an SLA of 99.99% service availability. HA VPN gateway to your peer gateway, 99.99% availability is guaranteed only on the Google Cloud side of the connection. End-to-end availability is subject to proper configuration of the peer VPN gateway.If both sides are Google Cloud gateways and are properly configured, end-to-end 99.99% availability is guaranteed. Default recommended routing model is dynamic and static is not supported.

Google Partner Interconnect

Partner Interconnect provides connectivity between the customer network, and the Edge network through a supported service provider. A Partner Interconnect connection is useful if the client data center is in a physical location that can’t reach a Dedicated Interconnect collocation facility, or the data needs don’t warrant an entire 10-Gbps connection.

Service providers have existing physical connections to Google’s network that they make available for the customers to use. After a customer has established connectivity with a service provider, they can request a Partner Interconnect connection from the service provider. After the service provider provisions the connection, client can start passing traffic between the network by using the service provider’s network. Partner Interconnect supports both Layer 2 and Layer 3 connectivity. Depending on the Redundancy and SLA, we can configure Google partner interconnect on both 99.9% and 99.99% availability.

If customer has a Google cloud presence, then the VLAN adapters for the Google partner interconnect could be terminated on the customer owned Google VPC. Manhattan owned VPC then have to peered with the customer VPC for establishing the connectivity.However, if the customer doesn’t have any Google cloud presence, then the VLAN adapters for Google partner interconnect have to be created on the Manhattan VPC for establishing the connectivity.

Cloud Router

The Cloud Router is the important configuration piece as part of the VPN setup. It is used to dynamically exchange routes between the VPC network and on-premises network through BGP.

By default, Cloud Router advertises subnets in its region for regional dynamic routing or all subnets in a VPC network for global dynamic routing. New subnets are automatically advertised by Cloud Router

Cloud DNS

All the private calls between customer network and Manhattan VPC are using Cloud DNS service from Google for DNS resolution.

DNS peering

DNS peering lets you send requests for DNS records that come from one zone’s namespace to another VPC network. For example, Active SC customer can give Edge stack access to DNS records it manages and similarly, Edge stack can give access for SC customer to DNS records it manages. This is primarily used for all the Edge stack calls going out for Printing and outbound MHE and also the incoming calls for RF and MHE from customer network.

Secured Connectivity GCP Service Using Private Service Connect

Manhattan Active® is offered as SaaS solution to all the customers. We provide access to the application via public URL as HTTPS and an authentication for both user access and application REST calls. There are few customers who wanted to enable a private connectivity between the client network and the mother-ship stack load balancer API endpoints due to the security architecture.

Private Service Connect to access Google APIs

All the Google API calls by default use the publicly available IP address for service endpoints such as pubsub.googleapis.com . Private Service Connect lets you connect to Google APIs using endpoints with internal IP addresses in the VPC network. This architecture is recommended for customers who are expecting all the Pubsub traffic to be private from their host systems.

Secured External Replication

Secured Data streaming

Learn More

Authors

Giri Prasad Jayaraman: Technical Director, Manhattan Active® Platform, R&D
Akhilesh Narayanan : Sr Principal Software Engineer, Manhattan Active® Platform, R&D

6 - Overview of AWPF message types

Basic concepts of your asynchronous workload and the different options available to process them consistently and under very high throughput requirements.

This article describes the concepts of InboundMessageType and OutboundMessageType entities and explains the importance of key fields in this entity that will help you configure the inbound and outbound traffic for a Manhattan Active® Platform microservice.

Fields of InBoundMessageType

Field	Description	Default value	Recommended value
MessageType	Message type for Inbound. This serves as the business key for the entity along with the profileId. InBoundMessageType is a config type entity, belonging to messaging profile purpose.	N.A	Some name that explains the business purpose of the inbound
Description	Functional description of this messageType on its usage.	N.A	Describe the business purpose of the messageType in clear words.
NoOfConsumer	The number of concurrent consumers to be started in a high volume stereotype instance like a QUEUE_PROCESSOR	null	Depends on the business usecase. Any QPROC coming up for this messageType will have this number of consumers. The value should be judiciously put based on the volume consideration. For a fairly high volume queue, it should be in 10s at least.
MinNoOfConsumer	The number of concurrent consumers to be started in a low volume stereotype instance like a LOW_VOLUME or ALL	null	null / 1 If it is set to null, then it is considered to be 1. It should not be more because generally the low volume instances listen to all the queues and adding more consumers just adds to the number of threads running in the container and may not actually help in scaling the queue processing. 0 The value should be specifically set to 0 in case you do not want any low volume instance to listen to this messageType. Only QPROCS will be able to process this messageType.
ServiceId	Service Id mapping to the ServiceDefinition that performs the actual business logic for this messageType.	N.A.	Should be the serviceId(mapped to a ServiceDefinition entry) that is supposed to process the message.
Idempotent	Flag to ensure the message is not processed multiple times on the consumer side. False value means it cannot be processed more than once. Should be used judiciously as it adds extra processing on the system as AWPF has to keep track of the processed messages in the database.	true	true (Unless your business usecase forces processing of the message only once. But if you mark a messageType as non-idempotent, please make sure you generate a messageId for the message on your own (on the producer side application code). Else, the framework generates a messageId on its own. This will not serve the actual purpose of a non-idempotent message as AWPF identifies a message with the messageId. Two identical messages (in terms of content) but having different messageIds will be treated as different messages by AWPF and will be processed separately.)
RetryCount	Maximum retry count for a message to process. You can override the system property level default retries for your messageType with this property if there is a need	3	3
RetryDelay	Retry delay for a message to process. Earlier the default retry delay was set to 500ms between each retry as a system property and all the messageTypes had to follow the same pattern. You can override the default by providing a comma separated list of retry delays (for each retry loop) for your messageType.	20,300,600	20,300,600 Unless there is need for your messageType to change the default delay in each retry loop.
PreFetchCount	Prefetch count for a message type to process. This field lets the user override the default prefetch count set the brokerCluster level at the messageType level	50	50 (Unless your messageType is fairly low volume and heavy processing one. If you have very less number of messages coming in but each message takes a lot of time to process, it is better to set low prefetch count to utilize all the available consumer threads. Else, 50 messages will be given to one consumer thread and other threads will remain idle. Scaling up the processing with QPROCS also will be problematic as very less messages will be in ready state and most of them will be stuck in the unacked state for a long time.)
BrokerClusterName	Used for setting up non-default broker properties. This property maps to the InternalBrokerConfig entity where the broker specific producer URI, consumer URI and other parameters are defined.	null	null (Unless your messageType requires to have a specific broker (like Kafka, SQS, Google pubsub) or you want to override specific properties of the default broker setup. Default NULL would mean RabbitMQ.)
BusinessKeyPath	A JSON path that points to a field on the payload Document that will be sent to this message type. In the event of a failed message, AWPF will evaluate this JSON path and send the value along with the failed message. When CommonUtil listens to the awpf-reprocess queue, it will look for this field and save it on the BusinessKey column in the failed message table. In the event of a batch job message failure, AWPF will evaluate this JSON path and save it on the UniqueIdentifier column in the batch processed message table	null	null (This field is used to quickly show the user messages that have failed for a specific business key. As such, if you want to make use of this feature, you should provide a JSON path that makes sense to the payload that will be processed by this MessageType.)

Fields of InBoundQueues

This table is an optional child of InBoundMessageType where you can define explicit queue names

Field	Description	Default value	Recommended value
QueueName	If you want a specific queue name for your messageType and do not want AWPF to decide the queue name based on your messageType. This is helpful when you have to keep the same “messageType” property in multiple components, but every component has its own queue for this messageType. Mostly used by frameworks.	N.A.	N.A.
FullyQualifiedQueue	In a org-specific environment setup, each messageType corresponds to multiple queues, each queue belonging to a different organization that shares the profile. AWPF prefixes the derived queue name with the organization id to make the actual queues org specific. But, if you do not want AWPF to add any suffix and you want to keep the exact queue name you specify, you have to set this flag to true. This is mostly done while connecting to a SQS or pubsub topic where the queuename is part of the handshake with the third party.	false	N.A.
FullyQualifiedQueueV2	Applicable for a multi-tenant environment. Value of true implies that no prefix including the tenant id should be added to the queue name	false	N.A.

Fields of InBoundMsgToRetransmit

This table is yet another optional child of InBoundMessageType. This will be used to route the inbound message to another queue, without processing it in the current consumer.

Field	Description	Default value	Recommended value
ToMessageType	Maps to the outbound message type where the message will be retransmitted. This is mostly used for external integration. Say you are connecting to SQS/ Googlepubsub through XINT component but the actual processing of the message will happen in some functional component (like order or inventory). The inbound messageType connecting to SQS/Pubsub should be created in XINT and then the message should be retransmitted one of the internal RabbitMQ queues which will be consumed by the functional component. This is the recommended way of connecting to external brokers for ease of scaling.	null	N.A.
TransformServiceId	Maps to a service definition service id which will perform data transformation before retransmitting the message	null	null ()

Authors

Subhajit Maiti: Director, Manhattan Active® Platform, R&D.

7 - Overview of batch job configuration

Basic concepts of how batch jobs can be configured and scheduled for bulk data processing requirements.

This article describes the concepts of JobTypeDefinition and JobSchedule entities and explains the importance of key fields in these entities that will help you configure the batch jobs for a Manhattan Active® Platform microservice.

Entity details

Batch framework has the following entities. The below diagram just captures the Key fields for each entity to depict their relationship. The latter section explains each field in detail. Please note that the one-to-many relationships shown in the diagram are figurative in nature. There is no database level constraint, it is more of a data relation between the entities.

JobTypeDefinition: This entity defines what and the how part of a job. The entity to store the different types of jobs for which schedules can be created. For. e.g “Re-tag Fulfillment”, “Cancel aged orders” etc. Each component is supposed to provide a finite set of such configurable jobs. New job types can be configured as this is a service level entity.

JobSchedule: This entity defines the when part of the job, basically the execution cadence based on the cron expression. It is tied to a particular jobType and there could be multiple schedules created for a job type. This is a service level entity and schedules can be created / updated as required.

JobParameters: This entity is the direct child of JobSchedule entity and is used to provide input parameters for the job as a key-value pair

JobConfiguration: This entity pertains to only batchv2 jobs and defines the how part of the job.

Fields of JobTypeDefinition

Field	Description	Default value	Recommended value
JobTypeId	Unique identifier for a particular job type. This serves as the business key for the entity along with the profileId. JobTypeDefinition is a config type entity belonging to batch profile purpose. For a spring-batch job, the JobConfiguration java file should contain a @Job bean with the same name	N.A.	Some name that explains the business purpose of the JobTypeDefinition.
JobTypeDescription	Brief description about the type of job.	N.A.	Describe the business purpose of the jobTypeDefinition in clear words.
ChunkSize	Chunk size for the particular job. This is applicable for spring-batch jobs and for JpaPagingItemReader type readers. The default QueryReaderBase, provided as part of BatchFramework makes use of this type of reader. Essentially what does it mean? There is a concept of ChunkSize and PageSize in spring-batch. If there is a lot of data to be read and written (to queues in our case), the read and write can happen in multiple threads and pages. The reader threads read as many number of records in one shot as the configured PageSize. The writer threads receive a List of items to be written to the queue, the List size is based on the ChunkSize. For simplicity, BatchFramework has assumed PageSize=ChunkSize for all processing. This document here has more details about the chunk oriented processing : https://docs.spring.io/spring-batch/trunk/reference/html/configureStep.html#chunkOrientedProcessing	null	N.A. The chunksize should be very carefully set based on the volume consideration for this job. If you expect few thousands of records or more to be read during one particular execution, it is better to set the ChunkSize to a higher value (may be in thousands). If you set it too less, the entire dataset will be logically broken into a large number of pages and as many DB hits will be fired to load the data. This can lead to a situation where all the eligible records are not picked up during an execution if the job updates the same column on which the reader query is built (part of the where clause). As the reader and writer can execute concurrently in separate threads, some of the eligible records can be updated while the read is still in progress. This will impact the total count and the page offsets calculated earlier. You can try adding an “oder by” clause on a field that doesn’t change on the update (like the created_timestamp)
StatusMonitorLevel	This field enables status monitoring for your job. Status monitoring implies keeping track of the progress of the job execution and marking the status to OPEN (read start), INPROGRESS (write complete) and COMPLETED (all messages processed). Basically status monitoring should be enabled for only those jobs where you want to take some action after the job execution has been completed and you have defined a callback handler. For all other jobs, setting status monitoring to true may cause un-necessary load on the system. This field supports these values : CHUNK, MESSAGE, NONE. CHUNK : Used to do status monitoring per chunk when t he data was stored at chunk level. Now this implies that status monitoring is enabled. MESSAGE : Not used any more. NONE : This implies that status monitoring is disabled for this job. POINT TO NOTE This feature is supported only when functional jobs have StatusMonitoringJobexecutionListenerBase as JobExecutionListener (for reference Agent Job configuration class	null	NONE Unless you business usecase needs to know the completion status of the job execution and you take some business decision/make some changes (like you have configured a CallBackHandler) based on the outcome of the job execution, it is better to disable the status monitoring by setting it to ‘NONE’. Please note : Leaving it to NULL would imply the value is defaulted to ‘NONE’ in the code.
JobType	This field defines different types of jobs. Supported values are SYSTEM, FUNCTIONAL, SERVICE, AGENT SYSTEM : Reserved for framework jobs and should not be used by components. FUNCTIONAL : For functional spring-batch type jobs. This is the default value that is assumed by BatchFramework if this field is not set. SERVICE : For functional service type jobs. Needs to be set explicitly for jobs that just invoke a ServiceDefinition on trigger. AGENT : Agent jobs. Mostly used by services teams to configure jobs where they need to execute the logic in their extension components.	null	N.A. Should be decided based on the Job. If left to the default value of NULL, the system would assume it is a spring-batch job (FUNCTIONAL).
JobStatusCallbackHandlerBean	This is the bean that will be invoked once the job execution has been completed. This bean should implement this interface : JobStatusCallbackHandler. If you want to configure a JobStatusCallbackHandlerBean for your job, it is mandatory to enable status monitoring for your job type.	null	N.A. Unless you have set the status monitoring levels accordingly for your job and you have some business logic to perform once the job execution completes.
InvocationServiceId	This maps to a ServiceDefinition entry in the system. Once the job trigger time comes, that particular ServiceDefinition will be invoked with all the jobParameters set in the schedule (refer to the section below) as input to the service method. This is tightly coupled with the field JobType (value = SERVICE) and is applicable only for service type jobs and has no bearing on the spring-batch jobs.	null	null Unless you have a SERVICE type job and you have the corresponding ServiceDefinition entry defined in the system
CreateContextFromJobParams	Flag to denote whether the context needs to be created from job parameters. By default, during the job execution, the context will be renewed to the context with which the JobSchedule was created. But in case, there is a need to override the context and execute the job in a custom context created from the JobParameters, this flag should be set to true. Location, Organization, User, and Business Unit can be overridden by the JobParameters.	false	false Unless you have a requirement to override the context with which the JobSchedule was created and you want to renew the context based on the JobParameters when the job executes
IsHeelToToe	Flag to denote whether it is a heel-to-toe job. A heel-to-toe job would only have one schedule of the job executing at any instance of time. Default false implies multiple simultaneous executions of the job is allowed.	false	false Unless you business usecase requires your job to be of heel-to-toe nature.
DropToMessageType	Unique identifier for the outbound messageType where the writer will send the messages.	null	If the DropToMessageType is not specified , the outbound message type will be considered as JobTypeId.
JobConfigurationId	Unique identifier for the job configuration. Required only for batch v2 jobs.	null	null Unless you are configuring a `batchv2` type job. The Job configuration id mandatory for any `batchv2` job to start.
MaxRunDuration	Expected time duration for one execution of the job. Jobs will be auto aborted post that. Should be given like ‘30 MIN’, ‘1 HOUR’ etc	null	null Unless you want to abort the job after a specific period of time if it still doesn’t complete naturally
IncludedOrganization	Comma separated list of organizations for which the JobSchedule will be included for execution. A jobSchedule will execute for all the organization which are sharing the same profileId for which the jobSchedule has been configured. Out of all those organizations, if you wish to execute the job for a particular few, this property needs to be configured	null	null Unless you wish to restrict the job execution only for certain organizations, even if there are many organizations which share the same profile
ExcludedOrganizations	Comma separated list of organizations for which the JobSchedule will be excluded for execution. A jobSchedule will execute for all the organization which are sharing the same profileId for which the jobSchedule has been configured. Out of all those organizations, if you wish to avoid execution of the job for a particular few, this property needs to be configured	null	null Unless you wish to avoid the job execution only for certain organizations, out of all the organizations which share the same profile
IsSyncExecution	Flag to denote if the job execution happens synchronously. Defaulted to false denoting async execution. Once the job trigger message arrives in the JobSchedule queue, the execution is handed over to a separate thread by default. As the trigger message is ACKed in the queue, the message is dequeued. In case the job execution fails due to some reason, we have to wait for the next trigger to happen to resume the execution. If you wish to keep the job trigger message alive in the queue till the time the job execution ends, you need to set this property TRUE	false	false Unless it is a very low frequency and important job that needs to resume immediately if the container processing the job goes down.

Fields of JobSchedule

Field	Description	Default value	Recommended value
JobScheduleId	Unique identifier for a particular job schedule. This serves as the business key for the entity along with the profileId. JobSchedule is a config type entity belonging to batch profile purpose.	N.A.	Some name that explains the business purpose of the JobSchedule.
JobTypeId	Identifier of the job type to which this schedule is tied to. This field maps to a JobTypeDefinition (jobTypeId column). There is no DB relationship between these two tables, JobSchedule and JobTypeDefinition are linked through data only.	N.A.	Should be the JobTypeId of the JobTypeDefinition for which the JobSchedule has been created
CronExpression	String to represent the cron expression for the job schedule. Please refer to http://www.cronmaker.com for creating your cron. This field is used to build the cron trigger	null	Some cron based on the business need that defines the execution cadence for the particular job schedule.
IsDisabled	Flag to denote whether the job schedule is disabled(paused) for the time being. Default value is false, i.e enabled. Is there is a need to stop a schedule from executing for some time and you do not want to delete it yet, this flag can be set to true. This will temporarily disable a schedule until it is enabled back by setting this flag to false	false	false Unless you want to disable a schedule
IsAdhoc	Flag to denote whether the job schedule is a dummy schedule created for adhoc jobs. The schedule will be deleted after the execution has been completed. This flag is used entirely for internal purposes and to support ad-hoc jobs (one time execution jobs that can run with any given parameter provided as input).	false	false
TimeZone	Timezone in which schedule needs to be executed/triggered. UTC is considered by default. POINT TO NOTE There is a specific format that BatchFramework (and component-scheduler) supports for the timezone input. Please refer to this page for the supported values : https://en.wikipedia.org/wiki/List_of_tz_database_time_zones	null	null Unless there is a business need to run your job at a particular timezone. Most of the repeated jobs should not worry about timezones as they would run at specific intervals. Default NULL implies UTC.

Fields of JobParameters

This table is the direct child of JobSchedule entity and is used to provide input parameters for the job as a key-value pair

Field	Description	Default value	Recommended value
InputKey	JobParameters are key-value pairs which are given as input during the job execution. This field is the key field of the pair.	null	N.A.
InputValue	JobParameters are key-value pairs which are given as input during the job execution. This field is the value field of the pair.	null	N.A.

Fields of JobConfiguration

This table is a way of configuring the jobs through DB entities. This configuration pertains to only batchV2 type of jobs.

Field	Description	Default value	Recommended value
JobConfigurationId	Unique identifier for the job configuration. Serves as business key	N.A.	Some name that explains the business purpose of the batchV2-JobConfiguration.
DataListSize	Used by the work distributors to break the data in batches. Each batch is a List of documents. Each batch will be processed independently by the business logic	1	1 Unless you want to group multiple individual entities together to process them as a batch. Your service should be able to handle multiple entities together if you set a higher value
DataFormat	This attribute works in conjunction with DataListSize and will be only applicable when DataListSize=1. If DataListSize=1 and the data needs to be published as a LIST then make the DataFormat=LIST	singleton	singleton Unless you want to group multiple individual entities together.
PageMessageType	Intermediate message type used by readers or workdistributors to break the paged data into chunks. The listener will process each page independently.	batchv2ProcessSegment	batchv2ProcessSegment Unless you wish to route your segment messages to a separate intermediate queue. If not specified otherwise, all BatchV2 jobs configured for a component, will share the same batchv2ProcessSegment queue.

Authors

Subhajit Maiti: Director, Manhattan Active® Platform, R&D.

8 - Extension points and handlers

Detailed overview of how extension points and handlers can be instrumented to customize your business workflows with virtually no code.

Introduction

Manhattan Active® Platform provides a flexible extensible model for customizing the business workflows via Extension Points. Extension points allow the customer or the Manhattan Professional Services organization to extend the base functionality with little to no code, while supports variety of internal and external integration options for invoking, consuming, and orchestrating custom workflows that meet your needs.

Two key constructs that are embedded in the system design of integrating and executing custom workflows as part of the base flows of Manhattan Active® Solutions:

Extension Points: Manhattan Active® application components have built-in extension points for functional customizations. Callouts to custom services can be configured at these extension points such that the custom services are invoked as part of a base workflow. The custom extension points are available throughout the base application functionality for a powerful extension model. Manhattan also evaluates the need for new extension points frequently and continues to insert them as part of application updates every few weeks. Extension points are designed to handle synchronous and asynchronous call-outs from the base flow, respectively

REST API: Every Manhattan Active® Solution microservices publishes a REST API that handles virtually every business function and “CRUD” operation. Collectively, Manhattan Active® Platform exposes thousands of REST API endpoints which can be used as an instrument for integrating 3rd party systems with Manhattan Active® Platform. The REST API supports the same degree of access control that the Manhattan Active® Platform user interface provides. The REST API comes with Swagger documentation that outline the usage and references.

Extension Point

An Extension Point is a pre-defined hook placed in the base application code at specific places where there’s a potential for customization. Extension Points can be configured to invoke custom services, which are instrumented in - and are invoked as part of - the base code flow at runtime.

Customizations can be configured at these points as necessary.
Extension points allows for a powerful execution model to support provides a powerful extension model to support customizations while keeping them external to the base code.
Requirements for the new extension points are considered and evaluated as part of the development process of the base application, and upon approval, they are delivered as part of the routine code delivery. Once added, extension points are never modified or deleted to preserve the compatibility with the potential implementations of these extension points.
The configuration that implements the extension point resides in entity called Extension Handler. An extension point can have zero or more extension handlers.

An extension point can be of two types:

Synchronous call-out (User Exit)

Produces a synchronous call-out at the given extension point. The call-out waits for a response before continuing the base flow.
While a synchronous call-out (user exit) can be configured with multiple extension handlers, only the first matching handler is executed (see more detailed explanation of how the “matching” is performed in the section below)
Synchronous call-outs (user exits) are typically added at points in the base code where there is an expectation that a response containing a new or modified payload will be received in response to the call-out.

Asynchronous call-out (Event)

Produces an asynchronous call-out at the given extension point. Unlike the synchronous call-outs, the call-out does not wait for a response before continuing the base flow.
Unlike synchronous call-outs (user exits), if multiple extension handlers are configured for an event, all matching extension handlers are executed (see more detailed explanation of how the “matching” is performed in the section below)
Additionally, base code may also send messages to queue(s) through ExtPointToMessageType, which are processed after the configured extension handlers are executed. This allows the base application code to execute logic after all potential customizations are executed. This is base functionality and not expected to be customized.

The type of extension point to be introduced in the base code is determined by Manhattan engineering based on the functional and technical requirements, behavior expectations, and throughput calculations.

Extension Handler

Implementation of extension point customization is configured using an entity called Extension Handler. The execution of extension handler is performed as part of the base flow when the base code encounters the extension point. When an extension point is evaluated by the base code, it performs two steps:

Determines the extension handler(s) to be invoked as configured for that extension point
Serializes the business objects and the contextual metadata from the current transaction as a JSON object and passes it to the extension handlers. See the extension point documentation to learn more about what business objects and contextual metadata is passed to the extension handlers.

The extension handler, when executed, utilizes the JSON payload sent from the extension point, and performs the custom flows. When the extension handler completes the custom flow, it responds back with a “return” payload - the returned payload may contain modifications based on the customization requirements. The returned payload is only relevant for the synchronous call-outs (http); for asynchronous call-outs, the returned payload is not relevant.

Extension handlers can be added and managed via a REST API for the ExtensionHandler entity. However, it is recommended that the Configurator UI is used to configure extension handlers for a more intuitive graphical experience, detailed validations, and to avoid human errors. See below for an example screen-shot of the Configurator UI.

Extension Handler Configuration

As described below, an extension handler can be configured for a variety of customization operations:

ENTRY CONDITION

Every extension handler can be configured for an Entry Condition to determine if it is the right handler to execute that call-out. Since multiple extension handlers can be configured at a given extension point, the entry condition serves as a selection criterion to choose the appropriate extension handler for the given business flow.
Entry conditions can be defined using JSONPath or MVEL expression. Environment variables available in the runtime can also be used in the MVEL expressions using the {:env_variable_name} format.

PRIORITY

Priority is an integer number that can be assigned to an extension handler to determine the order in which the extension handlers are sorted for execution of the given extension point. The priority numbers are in ascending order of priority (higher the number, higher the priority).
Extension handlers with the most stringent entry condition should be given the least priority (the smallest number) to ensure these handlers are executed at the very end.

SERVICE DEFINITION

Service definition are configured for extension points to invoke internal or external APIs as part of the execution of an extension handler. An extension handler can be configured to use one or more service definitions.
Service definition are configured via the ServiceDefinition entity and are configured and managed separately from the extension handler configuration. The extension handler configuration simply “points” to a service definition created previously.
A service definition can be configured to be of several types:
- URL: calls an HTTP URL. For example, "Url" : "example.com/some/api?k=v".
- RequestMappingUrl: partial URL of the same component in which the extension handler is configured. For example, "RequestMappingUrl": "/api/ServiceDefinition/inBoundMessageType/search" provides an output similar to an HTTP call, but invokes the underlying Spring bean without making an actual HTTP call.
- CompositeService: points to an extension handler and executes it. Do note, that entry conditions of an extension handlers are ignored when it is invoked as a composite service configuration.

Example of a URL Service configuration in the Configurator UI:

SERVICE CHAINING

An extension handler can invoke a chain of service definitions as described above. The chaining is created by feeding the output of a service execution call as the input to the next service invocation.

CONDITIONAL SERVICE CHAINING

Conditional service chains are service chains that include conditions between execution of two services. The condition is defined using the same format as the Entry Condition described above.

Example of conditionally chained service configuration in the Configurator UI:

INPUT TRANSFORMATION

While chaining services, the input to the next service can be transformed using Velocity or Freemarker templates. This is useful for services whose payload structures are not directly compatible. Functionality supports both inline and pre-saved templates.

Example of input transformation with Freemarker template:

OUTPUT AUGMENTATION

When services are chained, it replaces the whole full payload with the output of a service. In addition, you can also preserve the input payload and augment the new output to it by using the Augment key. An augment key can be any string key in the input JSON payload where the new output payload will be added.

OUTPUT TEMPLATES

A service may produce larger payload than necessary, which could lead to performance concerns. Such payloads can be reduced using response templates. Functionality supports both inline and pre-saved response templates.

OUTPUT QUEUES

Outputs of the services can be posted to a queue at individual services level for further asynchronous processing. Output of the entire extension handler can also be posted to a queue.

SAMPLING

Sampling provides clean visibility into the intermediate results of the services and payloads sent to the queues. As an extension handler can comprise multiple service calls, this feature can be very useful for visualizing payloads and debug at different levels of the chain.

Example of the sampling output:

Learn More

Author

Shanthosh Govindaraj: Director, Manhattan Active® Platform, R&D.
Kartik Pandya: Vice President, Manhattan Active® Platform, R&D.

9 - Overview of scheduler features

Description of features supported by the Scheduler functionality of Manhattan Active® Platform.

Introduction

This article describes the features of the scheduler component.

Features of scheduler

The component-scheduler is the central repository for all job schedules spread across components. scheduler takes care of posting a message to the component specific JobScheduleQueue when a job has to be triggered. The batch framework still holds the responsibility of executing the job, only the scheduling part is delegated to scheduler. As scheduler maintains the schedules and triggers them for all components, we have a better control and visibility of the schedules and their next triggers. To manage this, two new entities have been introduced to store the future runs for a configurable time window (next 4 hours by default) and already triggered jobs.

This is how scheduler triggers jobs for all the components -

High-availability

Even if the master instance of component-scheduler goes down, any other instance can elect itself as a master and continue the job triggers seamlessly. Even if none of the master instances are available at a given point of time, there will be no job triggers for the time it is down and when it is brought up, the pending schedules will be triggered as we have stored them in the DB. So, there is no chance of missing a trigger. At most, it can be delayed a few minutes in case of the component being down.

Scheduler master instance election -

Scheduler internal housekeeping jobs

Scheduler component maintains a few internal jobs that help in maintaining and triggering the job schedules for all the components. Polling data from components: Runs at 00:00 UTC every day to poll the JobSchedule and JobTypeDefinition from all the components. Even though there is a separate process to relay the updates on JobSchedule and JobTypeDefinition on the fly. This job helps in syncing any delta that could have been missed during the relay.

Create Future Data: Runs at the 10th minute of every hour and creates the future execution backlog for the next 4 hours.

Purge Job Executions: Runs every 6 hrs to purge the JobExecution records which are older than 5 days.

Status monitoring for components: Every component can have some jobs configured that need status monitoring. Scheduler triggers a status monitoring for all the inprogress jobs for a component every 1 minute. Once a job execution has been marked as completed, no further status monitoring would happen.

Abort jobs: If a job execution has not been completed even after the MaxRunDuration has elapsed, the corresponding JobExecution record will be marked as aborted. This job runs every 15 minutes

This is how scheduler invokes the internal housekeeping jobs -

Useful API endpoints

Full initialize: This API endpoint will fetch the JobTypeDefinition, JobSchedule and required OutboundMessageTypes for all “managed” components, given as a comma separated list to component-scheduler and for all organizations and persist them in the component-scheduler DB.

POST :  {url}/scheduler/api/scheduler/setup/fullinitialize

Initialize for an Org: This is a lighter version of the full initialize API endpoint and does the initialization for a particular Organization across all managed components.

POST :  {url}/scheduler/api/scheduler/setup/orgId/{orgId}

Initialize for an Org and a component: This is an even lighter version of the full initialize API endpoint and does the initialization for a particular Organization for the input component.

POST :  {url}/scheduler/api/scheduler/setup/orgId/{orgId}/component/{component}

Please note: this API endpoint is expecting the component short name, not the full component name. For example, if you are trying to use this API endpoint for component-order and organization org1, then you would do so by passing “order” as the component name.

Create future jobs: This API endpoint creates the future job execution records based on the cron expression of the jobSchedule and persists them in the SCH_FUTURE_JOB_EXECUTION table. The offset value should be provided as an integer in minutes.

POST :  {url}/scheduler/api/scheduler/setup/createfuturejobs/{offset}

The future calculation will start from currenttime+offset. The offset value essentially signifies the time buffer we keep before recreating the futureJobs. While recreating the futureJobs, if the schedule is supposed to trigger, we might have issues because the same futureJob entry could be getting updated or deleted. The immediate futureJob entries (which fall within the offset period) will remain intact to avoid conflict issues as explained above.

Get the master lock status: As per the Active/Active design, only one of the running scheduler instances will hold the ActiveMasterLock and this instance (master instance) will be responsible for triggering the jobs. The below API endpoint can be used to gather information about the current lock status.

GET :  {url}/scheduler/api/scheduler/schedulerLockStatus

View already triggered jobs: The following API endpoint can be used to search for the JobExecution records, where scheduler stores the already triggered executions.

POST :  {url}/scheduler/api/scheduler/jobExecution/search
{
  "Query": "JobScheduleId='<JobSchduleId>'"
}

Any of the fields can be used for searching the job execution records. This sample takes the JobScheduleId as input.

View upcoming job triggers: The following API endpoint can be used to search for the FutureJobExecution records, where scheduler stores the upcoming triggers for the next 4 hours.

POST :  {url}/scheduler/api/scheduler/futureJobExecution/search
{
  "Query": "JobScheduleId='<JobSchduleId>'"
}

Any of the fields can be used for searching the job execution records. This sample takes the JobScheduleId as input.

Authors

Subhajit Maiti: Director, Manhattan Active® Platform, R&D.

Reference

1 - Manhattan Active® API

2 - Manhattan Active® Apps

2.1 - Manhattan Active® Omni

Categories

2.1.1 - Alternate Payments

Third Party Integrations

2.1.1.1 - Afterpay

What is Afterpay?

What does this integration include?

Capture

Refund

Void

Update Courier

2.1.1.2 - Amazon Pay

What is Amazon Pay?

What does this integration include?

Advanced Authorization

Settlement

Refund

Notifications

2.1.1.3 - Klarna

What is Klarna?

What does this integration include?

Capture

Cancel

Release Authorization

Refund

2.1.1.4 - PayPal

What is PayPal

What does this integration include?

What is PayPal DoVoid?

What is PayPal DoAuthorization?

POS OMNI-Cart Sale

Follow-On Refund

POS Refund by Card Entry

POS Mid-Transaction Void

POS Post Void

POS End of Day Reconcilation

Contact Center Hosted Checkout

Authorization

Re-Authorization

BOPIS Card on File

2.1.2 - Address Verification

Third Party Integrations

2.1.2.1 - Avalara

What is Avalara?

What does this integration include?

Address Verification (AVS)

2.1.2.2 - Experian QAS

What is EXPERIAN QAS?

What does this integration include?

Address Verification (AVS)

Email Address Verification

2.1.2.3 - Loqate

What is Loqate?

What does this integration include?

Delivery Address Verification (AVS)

2.1.2.4 - Strikeiron

What is Strikeiron?

What does this integration include?

Address Verification (AVS)

2.1.2.5 - UPS

What is UPS AVS?

What does this integration include?

Address Verification (AVS)

2.1.3 - Credit Card Payments

Third Party Integrations

2.1.3.1 - Alliance (ADS)

What is ADS?

What does this integration include?

Authorization

Authorization Reversal

Refund

Account Lookup

End of Day Settlement Batch

Resend Mechanism for End of Day Settlement

2.1.3.2 - Adyen

What is Adyen?

What does this integration include?