Operators Guide
Pull from Manhattan Active Omni¶
Manhattan Active Omni is a unified commerce application from Manhattan Associates that includes order management, point of sale, customer service, and store inventory and fulfillment.
Manhattan Active Omni, also known as MAO, can send orders and order lines to Amperity using the Manhattan Active Omni order search API. Choose which data types to pull. Amperity lands one NDJSON file for each data type that you select.
Orders has one record for each order, without the order’s lines.
Order lines has one record for each line of each order. Every line record has the OrderId of its order.
Each run pulls the orders that were last updated during a time period, as they are at the time of the run. A run for a specific time period pulls the orders that were updated during that time period. A run that loads all data pulls the orders that were updated from the Start date until the run starts. The lines of an order are pulled with the order.
The steps that are required to pull orders and order lines to Amperity from Manhattan Active Omni:
Get details¶
Manhattan Active Omni requires the following configuration details:
The Username, Password, Client ID, and Client Secret that Amperity uses to connect to Manhattan Active Omni.
Get all four values from your Manhattan Active Omni administrator:
The Username and Password of a Manhattan Active Omni user with read access to order search for each organization and location that Amperity pulls from. Use a user that is dedicated to this integration, rather than a person’s account. Amperity signs in with this password, so a password change stops the courier until you update the credential, and repeated failed sign-ins can lock the user out.
The Client ID and Client Secret of an OAuth client in your Manhattan Active Omni environment. Amperity requests access tokens with the OAuth 2.0 password grant, so the OAuth client must allow that grant. Amperity does not request OAuth scopes.
Manhattan describes the password grant in its REST API authentication guide.
The Base URL, which is the HTTPS address of your Manhattan Active Omni API, without a path. For example:
https://yourcompany.omni.manh.com.The Base URL must begin with
https://. It cannot include a path, a user name or password, a query string, or a fragment.The Token URL, which is the full HTTPS address of the OAuth token endpoint for your Manhattan Active Omni environment, including its path. For example:
https://yourcompany-auth.omni.manh.com/oauth/token. The Token URL can be on a different host than the Base URL.The Token URL must begin with
https://and include a path. It cannot include a user name or password, a query string, or a fragment.The Start date, which is the earliest update time of the orders to pull when the courier loads all data. Enter an ISO-8601 timestamp that ends with
Zfor UTC or with an offset from UTC. For example:2025-01-01T00:00:00Z.An order that was last updated before the Start date is not pulled by a run that loads all data.
Optional. The Organization, Provisioning profile, and Location that your Manhattan Active Omni environment requires with each request. Ask your Manhattan Active Omni administrator whether your environment requires them. When Organization is blank, Manhattan Active Omni uses the user’s default organization. Amperity sends each value as the Organization, ProvisioningProfile, or Location request header. A value that is left blank is not sent.
Optional. The Requests per hour, which limits how often Amperity sends requests to Manhattan Active Omni during a run. Enter a positive number, such as
1000. Leave it blank for no limit.Manhattan Active Omni counts API requests for each hour, and that count includes the requests from every integration that uses your Manhattan Active Omni environment. Ask your Manhattan Active Omni administrator for your environment’s hourly limit and how many requests your other integrations send, and then choose a value that leaves room for them. See How data is pulled.
The Data types to pull. Select Orders, Order lines, or both.
If your Manhattan Active Omni environment accepts requests only from IP addresses on an allowlist, add the Amperity IP addresses for allowlists to it.
Tip
Use SnapPass to securely share configuration details for Manhattan Active Omni between your company and your Amperity representative.
Add courier¶
A courier brings data from an external system to Amperity.
To add a courier
From the Sources page, click Add Courier. The Add Courier page opens.
Find, and then click the icon for Manhattan Active Omni. The Add Courier page opens.
Enter the name of the courier. For example: “Manhattan Active Omni”.
From the Credential field, select an existing credential or select Create a new credential.
To add a credential, enter the name of the credential, a description, and the Manhattan Active Omni Username, Password, Client ID, and Client Secret. Click Save.
When finished click Continue.
Under Data types, select the data types to pull.
Enter the Base URL, Token URL, and Start date. Enter the Organization, Provisioning profile, Location, and Requests per hour if you use them.
Leave Load Operations empty. Add load operations after the feeds for this courier are configured.
Click Save.
Note
When you save the courier, and at the start of every courier run, Amperity searches for a single order that was updated during the previous minute. This verifies that Amperity can get an access token and search orders before the run reads any data. If the search fails when you save the courier, the courier is not saved. See Troubleshoot errors.
Get sample files¶
Newline-delimited JSON (NDJSON) is a data format for structured data that defines the structure of JSON data using lines as separators. Each line in a NDJSON file is a valid JSON value.
Every Manhattan Active Omni file that is pulled to Amperity must be configured as a feed. Before you can configure each feed you need to know the schema of that file. Run the courier without load operations to bring sample files from Manhattan Active Omni to Amperity, and then use each of those files to configure a feed.
Amperity names each file after its data type.
Data type |
File name |
Name in load operations |
|---|---|---|
Orders |
|
|
Order lines |
|
|
To get sample files
From the Sources tab, open the menu for a courier configured for Manhattan Active Omni with empty load operations, and then select Run. The Run Courier dialog box opens.
Select Load data from a specific time period, and then choose a recent time period during which orders were updated in Manhattan Active Omni, such as the previous day.
A run for a specific time period returns only the orders that were updated during that time period. A sample file can be empty if no orders were updated, and an empty file cannot be used to configure a feed.
A run that loads all data pulls every order that was updated since the Start date, which can take a long time for a large order history.
Click Run.
The files that the courier pulls are available for selection as an existing source from the Add Feed dialog box.
Add feeds¶
A feed defines how to load data into a domain table, including specifying required columns and columns with semantic tags for customer profile (PII) or transactions data.
Note
A feed must be added for each file that is pulled from Manhattan Active Omni, including all files that contain customer records and interaction records, along with any other files that is used to support downstream workflows.
Amperity requests a fixed set of fields for each order and order line, and lands them as Manhattan Active Omni returns them, including nested objects, arrays, and null values. Amperity does not rename fields or convert their values. Amperity removes OrderLine from each order record, and sets OrderId on each order line record to the OrderId of its order. Use the sample file for each data type to configure its feed.
A field that is not in the following lists is not pulled. Contact your Amperity representative to request another field.
Orders
Identifiers and dates: OrderId, AlternateOrderId, OrgId, CreatedTimestamp, UpdatedTimestamp, CapturedDate, ConfirmedDate, BusinessDate, and ArchiveDate
Customer: CustomerId, CustomerFirstName, CustomerLastName, CustomerEmail, CustomerPhone, and LoyaltyNumber
Totals: OrderTotal, OrderSubTotal, TotalTaxes, TotalCharges, TotalDiscounts, CancelledOrderTotal, CancelledOrderSubTotal, ConfirmedOrderTotal, and CurrencyCode
Type and status: OrderType.OrderTypeId, DocType.DocTypeId, SellingChannel.SellingChannelId, SellingLocationId, PaymentStatus.StatusId, PublishStatus.PublishStatusId, MinFulfillmentStatusId, MaxFulfillmentStatusId, IsConfirmed, IsOnHold, IsCancelled, and Process
Counts: OrderLineCount, ReturnLineCount, CancelLineCount, and PackageCount
Payment and charges: OrderPaymentMethod, Payment.PaymentMethod.Extended.IsApplePay, Extended.AccountDisplayNumber, Extended.PrimaryPaymentMethod, OrderChargeDetail.ChargeDisplayName, and OrderChargeDetail.ChargeType.ChargeTypeId
Order lines
Identifiers and dates: OrderId, OrderLineId, ParentOrderId, ParentOrderLineId, CreatedTimestamp, UpdatedTimestamp, and BusinessDate
Item: ItemId, ItemBarcode, ItemDescription, ItemShortDescription, ItemBrand, ItemStyle, ItemColorDescription, ItemDeptNumber, ItemDepartmentName, UOM, and Quantity
Prices and totals: UnitPrice, OriginalUnitPrice, OrderLineSubTotal, OrderLineTotal, TotalTaxes, TotalCharges, TotalDiscounts, TotalDiscountOnItem, CancelledOrderLineSubTotal, and CancelledTotalDiscounts
Flags: IsReturn, IsCancelled, IsGift, IsGiftCard, IsPreOrder, IsNonMerchandise, and IsOnHold
Fulfillment: FulfillmentStatus, FulfillmentGroupId, DeliveryMethod.DeliveryMethodId, ServiceLevelCode, CarrierCode, SellingLocationId, and ShipToLocationId
Ship-to address: ShipToAddress.AddressName, ShipToAddress.AvsReason, and the FirstName, LastName, Email, Phone, Address1, Address2, Address3, City, County, State, PostalCode, and Country fields in ShipToAddress.Address
Cancellation: CancelReason, CancelComments, CancellationRequestStatus, and the CreatedTimestamp, UpdatedTimestamp, Process, CancelReason, CancelComments, CancelQuantity, and CancellationInitiatedBy.InitiatedBy fields in OrderLineCancelHistory
An order can have more than one Payment, Payment.PaymentMethod, and OrderChargeDetail, and an order line can have more than one OrderLineCancelHistory. Like OrderLine, each of these is landed as an array of objects, so the feed has one array column for each of them rather than one column for each field inside them.
Order and order line records contain names, email addresses, phone numbers, and postal addresses.
Select OrderId as the primary key for the orders feed. Select OrderId and OrderLineId together as the primary key for the order lines feed. An order that Amperity pulls again, which happens each time the order is updated in Manhattan Active Omni, updates the existing records in the domain tables when the feeds have primary keys.
Do not add ParentOrderId or ParentOrderLineId to the primary key for the order lines feed. On a return line, ParentOrderId and ParentOrderLineId identify the original order and the original line, so these fields describe how a line relates to another order rather than identify the line.
Each courier pulls orders from one organization: the Organization setting, or the user’s default organization when Organization is blank. An OrderId might not be unique across organizations. If couriers for different organizations load into the same feeds, contact your Amperity representative before you choose primary keys, because order line records do not include OrgId.
To add a feed
From the Sources tab, click Add Feed. This opens the Add Feed dialog box.
Under Data Source, select Create new source, and then enter “Manhattan Active Omni”.
Enter the name of the feed in Feed Name. For example: “Orders”.
Tip
The name of the domain table will be “<data-source-name>:<feed-name>”. For example: “Manhattan Active Omni:Orders”.
Under Sample File, select Select existing file, and then choose from the list of files. For example: “orders-data.ndjson”.
Tip
The list of files that is available from this dropdown menu is sorted from newest to oldest.
Select Load sample file on feed activation.
Click Continue. This opens the Feed Editor page.
Select the primary key.
Apply semantic tags to customer records and interaction records, as appropriate.
Under Last updated field, specify which field best describes when records in the table were last updated.
Tip
Choose Generate an “updated” field to have Amperity generate this field. This is the recommended option unless there is a field already in the table that reliably provides this data.
For feeds with customer records (PII data), select Make available to Stitch.
Click Activate. Wait for the feed to finish loading data to the domain table, and then review the sample data for that domain table from the Data Explorer.
Add load operations¶
After the feeds are activated and domain tables are available, add the load operations to the courier used for Manhattan Active Omni.
Example load operations
Load operations must specify each file that is pulled to Amperity from Manhattan Active Omni.
Refer to each file by its name in load operations, as shown in the table in Get sample files. Add a load operation for each data type that the courier pulls.
Do not add a truncate operation. A run for a specific time period, including every scheduled run, pulls only the orders that were updated during that time period. A truncate operation would replace every order in the domain table with only those orders.
For example:
{
"df-A1B2C3": [
{
"type": "load",
"file": "orders-data"
}
],
"df-D4E5F6": [
{
"type": "load",
"file": "order-lines-data"
}
]
}
To add load operations
From the Sources tab, open the menu for the courier that was configured for Manhattan Active Omni, and then select Edit. The Edit Courier dialog box opens.
Edit the load operations for each of the feeds that were configured for Manhattan Active Omni so they have the correct feed ID.
Click Save.
To pull another data type later, edit the courier to select it under Data types, run the courier to get a sample file, add a feed for that file, and then add a load operation for it. Then run the courier with Load all data, so that the new domain table has every order that was updated since the Start date.
Run courier manually¶
Run the courier again. This time, because the load operations are present and the feeds are configured, the courier will pull data from Manhattan Active Omni.
Important
Select Load all data for the first run. A run for a specific time period pulls only the orders that were updated during that time period, so a first run for a specific time period loads only part of your order history.
To run the courier manually
From the Sources tab, open the menu for the courier with updated load operations that is configured for Manhattan Active Omni, and then select Run. The Run Courier dialog box opens.
Select the load option, either for a specific time period or all available data. Actual data will be loaded to a domain table because the feed is configured.
Click Run.
This time the notification will return a message similar to:
Completed in 5 minutes 12 seconds
Add to courier group¶
A courier group is a list of one or more couriers that run as a group. A courier group can act as a constraint on downstream workflows and can run automatically as part of a scheduled workflow.
To add the courier to a courier group
From the Sources tab, click Add Courier Group. This opens the Create Courier Group dialog box.
Enter the name of the courier. For example: “Manhattan Active Omni”.
Add a cron string to the Schedule field to define a schedule for the orchestration group.
A schedule defines the frequency at which a courier group runs. All couriers in the same courier group run as a unit and all tasks must complete before a downstream process starts. Define a schedule using cron.
Cron syntax specifies the fixed time, date, or interval at which cron runs. Each line represents a job.
30 8 * * *represents “run at 8:30 AM every day” and30 8 * * 0represents “run at 8:30 AM every Sunday”.For example:
┌───────── minute (0 - 59) │ ┌─────────── hour (0 - 23) │ │ ┌───────────── day of the month (1 - 31) │ │ │ ┌────────────── month (1 - 12) │ │ │ │ ┌─────────────── day of the week (0 - 6) (Sunday to Saturday) │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ * * * * * command to execute
Amperity validates the cron syntax and shows you the results. You may also use crontab guru to validate cron syntax.
Set Status to Enabled.
Specify a time zone.
A courier group schedule is associated with a time zone. The time zone determines the point at which a courier group’s scheduled start time begins. A time zone should be aligned with the time zone of system from which the data is being pulled.
Use the Use this time zone for file date ranges checkbox to use the selected time zone to look for files. If unchecked, the courier group uses the current time in UTC to look for files to pick up.
Note
The time zone that is chosen for an courier group schedule should consider every downstream business processes that requires the data and also the time zones in which the consumers of that data will operate.
Add at least one courier to the courier group. Select the name of the courier from the Courier dropdown. Click + Add Courier to add more couriers.
Click Add a courier group constraint, and then select a courier group from the dropdown list.
A wait time is a constraint placed on a courier group that defines an extended time window for data to be made available at the source location.
Important
A wait time is not required for a bridge.
A courier group typically runs on an automated schedule that expects customer data to be available at the source location within a defined time window. However, in some cases, the customer data may be delayed and is not made available within that time window.
For each courier group constraint, apply any offsets.
A courier can be configured to look for files within range of time that is older than the scheduled time. The scheduled time is in Coordinated Universal Time (UTC), unless the “Use this time zone for file date ranges” checkbox is enabled for the courier group.
This range is typically 24 hours, but may be configured for longer ranges. For example, it is possible for a data file to be generated with a correct file name and datestamp appended to it, but for that datestamp to represent the previous day because of how an upstream workflow is configured. A wait time helps ensure that the data at the source location is recognized correctly by the courier.
Warning
This range of time may affect couriers in a courier group whether or not they run on a schedule. A manually run courier group may not take its schedule into consideration when determining the date range. Only the provided input days to load data from are used as inputs.
Click Save.
Important
Each scheduled run pulls the time period since the schedule’s previous run time, whether or not that run succeeded. Orders that were updated during the time period of a failed or missed run are not pulled until you run the courier for that time period. Pulling the same time period again updates records rather than duplicating them, because the feeds have primary keys.
Leave Only retrieve files dropped in the past day? cleared unless the courier group runs daily. When it is selected, each scheduled run pulls only the 24 hours before the run, so a schedule that runs less often than daily skips the orders that were updated before those 24 hours.
The courier group settings do not offer a look-back period longer than one day. Contact your Amperity representative to set a look-back period that is at least twice the schedule interval, so that each run also pulls the time period of the run before it.
How data is pulled¶
Orders are selected by UpdatedTimestamp. Each run pulls every order whose UpdatedTimestamp is at or after the start of the time period and before its end, in UTC, to the millisecond. A time period that ends in the future ends when the run starts instead. An order that is updated while a run is in progress is pulled by the next run.
Each order is pulled as it is when the run reads it. An order that is updated again is pulled again by a later run, with all of its lines, and the feeds’ primary keys update the existing records. A line that was removed from an order in Manhattan Active Omni stays in the order lines domain table, because a later run does not pull it and nothing removes it.
Some changes might not update UpdatedTimestamp. A change to an order line, a payment, or an Extended field might not change the order’s UpdatedTimestamp. A run for a specific time period does not pull a change that leaves UpdatedTimestamp as it was. A look-back period pulls each order again on later runs, which picks up changes made soon after the order was updated. A run that loads all data pulls every order again.
Archived orders might not be pulled. A run that loads all data pulls the orders that the order search returns, which might not include orders that Manhattan Active Omni has archived. Ask your Manhattan Active Omni administrator how long orders stay before they are archived, and choose a Start date within that time.
Searches. Amperity reads orders from the order search endpoint, /order/api/order/order/search, up to 200 orders in each search. Amperity divides the time period into parts of up to 3 hours and searches up to three parts at the same time. Within each part, Amperity keeps each query below 10,000 orders, which is the most that Manhattan Active Omni returns for one query. The first query in a part covers 1 hour. Amperity widens the next query while queries find fewer than 5,000 orders, and halves a query that reaches 10,000 orders.
Requests are limited by Requests per hour. Up to three searches run at the same time. When Requests per hour is set, Amperity spaces its requests to Manhattan Active Omni so that a run sends about that many requests in an hour, including requests that are sent again after a failure. When it is blank, Amperity does not pause between requests. When Manhattan Active Omni responds that the hourly limit is used up, Amperity waits 5 minutes and sends the same search again, and keeps waiting for up to 1 hour for each search. If Manhattan Active Omni is still over its limit after 1 hour, the run fails and is not retried automatically.
Runs succeed or fail as a whole. When a search fails with a server error, a timeout, or a connection error, Amperity sends it again up to 5 times. If the search still fails, Amperity stops the run and starts it again from the beginning, every 10 minutes for up to 1 hour. If the run has not succeeded by then, the courier run fails. Amperity never loads part of a time period. Amperity also stops the run when Manhattan Active Omni returns orders that are not sorted by UpdatedTimestamp, an order without an OrderId, or an order whose UpdatedTimestamp is outside the time period of the search, so that the run cannot skip orders.
Troubleshoot errors¶
The following errors may occur when a courier is saved or when it runs.
When you save the courier, a setting that is not valid shows an error that begins with “Courier failed validation:”. If the connection search fails, the error begins with “Failed to connect to external service manhattan-active-omni with error(s):”, and the courier is not saved.
When a courier run starts, an error from the connection search begins with “Failed to connect:”.
Error |
Resolution |
|---|---|
Base URL must be an external HTTPS API origin without a path, credentials, query, or fragment. |
Shown when the courier is saved. Enter the address of your Manhattan Active Omni API with |
Token URL must be a full external HTTPS endpoint without credentials, query, or fragment. |
Shown when the courier is saved. Enter the full address of the OAuth token endpoint, including its path. |
Start date must be an ISO-8601 timestamp with a UTC Z or explicit offset, such as 2025-01-01T00:00:00Z. |
Shown when the courier is saved. Enter a timestamp that ends with |
Context headers must be strings without line breaks. |
Shown when the courier is saved. Remove any line breaks from Organization, Provisioning profile, and Location. |
Requests per hour must be a positive number, such as 1000. |
Shown when the courier is saved. Enter a number greater than zero, such as |
Data types must be a non-empty subset of the available types. |
Shown when the courier is saved. Select Orders, Order lines, or both. |
Manhattan Active Omni rejected the OAuth client or account credentials. |
The client ID, client secret, username, or password is incorrect, or the OAuth client does not allow the password grant. Ask your Manhattan Active Omni administrator to confirm all four values and the password grant, and then update the credential. |
Manhattan Active Omni returned no access token. Check the OAuth client and account credentials. |
The token endpoint responded without an access token. Check that the Token URL is the full address of the OAuth token endpoint for your Manhattan Active Omni environment, and not another page on that host. Then ask your Manhattan Active Omni administrator to confirm the OAuth client and the user. |
Manhattan Active Omni rejected the request. Check the endpoint and organization context. |
Check the Base URL and the Organization, Provisioning profile, and Location with your Manhattan Active Omni administrator. |
Manhattan Active Omni rejected the credentials. Check the username, password and OAuth client. |
Manhattan Active Omni rejected a search, and rejected it again after Amperity requested a new access token. Ask your Manhattan Active Omni administrator to check that the user is active and that its password is current, and then update the credential. |
Manhattan Active Omni denied access. Check the account permissions and organization context. |
The user is not allowed to search orders with the Organization, Provisioning profile, and Location that the courier sends, or the OAuth client is not allowed to request tokens, or your Manhattan Active Omni environment accepts requests only from IP addresses on an allowlist that does not include Amperity. A blocked address is refused before Amperity can sign in. Ask your Manhattan Active Omni administrator to check the user’s permissions, those values, the OAuth client, and that the Amperity IP addresses are on the allowlist. |
Manhattan Active Omni endpoint was not found. Check the API and token URLs. |
The Base URL or the Token URL points to the wrong host or path. The Base URL must not include a path. |
Manhattan Active Omni stayed over the tenant’s hourly API entitlement. Check the MAO API usage of other integrations, then rerun the pull. |
Manhattan Active Omni stayed over its hourly limit for more than 1 hour. Amperity does not retry this run. Check how many requests your other integrations send to Manhattan Active Omni, set or lower Requests per hour, and then run the courier again for the same time period. |
Manhattan Active Omni is temporarily unavailable; retry the pull later. |
A problem on the Manhattan Active Omni side. When it occurs while the run reads orders, Amperity restarts the run every 10 minutes for up to 1 hour. When it occurs in the connection search at the start of a run, Amperity repeats the search every 30 seconds for up to 5 minutes. When it occurs as you save the courier, save the courier again later. If the error recurs, contact your Amperity representative. |
The Manhattan Active Omni request could not complete; retry the pull later. |
Amperity could not reach Manhattan Active Omni, or a request timed out. When it occurs while the run reads orders, Amperity restarts the run every 10 minutes for up to 1 hour. When it occurs in the connection search at the start of a run, Amperity repeats the search every 30 seconds for up to 5 minutes. When it occurs as you save the courier, save the courier again later. If the error recurs, check the Base URL and Token URL. |
MAO start date must be earlier than the end date. |
The Start date, or the start of the time period that you selected, is not before the end of the time period. Choose a start date in the past. |
Manhattan Active Omni’s 10,000-order search cap is saturated at a single millisecond. Narrow the extraction or arrange a vendor export. |
More than 10,000 orders have the same UpdatedTimestamp, to the millisecond, so Amperity cannot read all of them. Contact your Amperity representative. |
Manhattan Active Omni rejected the order query or projection. |
Manhattan Active Omni did not accept the search or the fields that Amperity requests. Contact your Amperity representative. |
One of the following:
|
Manhattan Active Omni returned a response that Amperity does not expect. The run stopped rather than load an incomplete set of orders. Contact your Amperity representative. |
One of the following:
|
Contact your Amperity representative. |