Switching from EvoLink to Prima API Sync is now possible with EvolutionX App Store and the Prima API.
⚠️ Note — This integration is now available. A migration from EvoLink may be required and you should work with Prima and EvolutionX to cary this out. Details of the migration steps are below.
Customers who run more than one EvolutionX store should consult with Prima Software before using this integration method. Prima Software customer Sync does not support multiple stores but this may come in future versions.
Features and Notes about the Prima API Sync with EvolutionX
Scheduled and On Demand Sync of Records
The customers updated in Prima will be sync'd to EvolutionX throughout the day or as requested by a Prima users. Discuss the schedule and options with Prima Software support.
Customer Sync can also be performed on demand by clicking the refresh button in the balances screen in Prima.
Customer Accounts & Prima Companies
Prima → EvolutionX — The sync is one way and customers created in EvolutionX do not become companies in Prima.
Prima "Customer" Type Record — All "Customer" type records are added and updated from Prima. You can choose which are available for use on the website by setting contacts as web enabled.
Prima Account Manager — One Primary Account Manager is now updated on the customer record from the company record in Prima. Note that you must already have your Account Managers loaded in EvolutionX Settings with their Prima Login value as the Seller Reference.
Prima "PO Required" Option is Not Supported — The Prima PO required feature, in the company record, is a separate, unlinked, feature from the user PO settings in EvolutionX. Use the EvolutionX admin to control this feature. This is because the Prima feature is customer based and the EvolutionX feature is user based and thus the EvolutionX feature can't be controlled from Prima.
Prima Company Trading Status — This feature has been deprecated and is no longer used, for credit status see below Prima Credit Allowed. Any trading status other than "On Hold" will enable the Credit Account on the EvolutionX Account. Setting the prima company trading status to On Hold will require the customer to use Credit Cards in the EvolutionX Checkout.
Prima Credit Allowed — Prima Credit Allowed status will be used to update Credit Account on the EvolutionX Account.
Customer Users & Prima Contacts
Prima → EvolutionX — The sync is one way and users created in EvolutionX do not become Prima Contacts.
Creating Users from Prima Contacts — All Prima Contacts which are Web Enabled will be created and updated as users in EvolutionX. If the web enabled setting is disabled, the user will be set as a disabled user in EvolutionX and will not be able to use the website.
The Prima Contact Email is the Email used for the user in EvolutionX unless the user login value has been set in Prima. Note that this must be a valid email address. EvolutionX usernames are not usually needed and not supported in the sync. If needed, a username can be added using the EvolutionX admin (a username is only needed when a user with the same email address is needed in unrelated accounts).
Prima Contact Email & Login Fields — The Prima Contact email address is used as the email address of the EvolutionX user or, if the login field under the Web Access tab is used, then the login value is used instead. Note that the use of either email or login fields maps to the EvolutionX user email and must be an email address. The EvolutionX username is not a supported field in the sync and can only be managed in the EvolutionX Admin.
Prima Contact Names — Prima has several name fields for each contact but the "Contact" field is the only one that is used for the Name of the EvolutionX user.
Password — A password doesn't need to be set in Prima. The Prima Contact has a password field in the web access tab and, if set, it will be used as a temporary password on the create of a user only. The update of a user will ignore the password field.
Disconnect a User from Prima Updates — If needed, it is possible to prevent Prima API sync from updating an EvolutionX user. This might be needed if customer address restrictions or other settings can't be managed in Prima. In this case you can disconnect the user from Prima Updates and then it will no longer update the EvolutionX user. Follow these steps to prevent Prima from updating the EvolutionX user during a sync:
Edit the Contact in Prima and unselect the "web enabled" option.
Edit the User in EvolutionX and delete the "seller reference" value (this is the Prima ID for the user record).
Order Roles for Users — Due to the support for Live Order History, which shows the full Order History from Prima for the customer account, User Role settings for orders include these effects:
View Orders — This shows order history for the current user who is accessing on the storefront. It will only include orders from that user, using the user "Seller Reference" field.
View All Orders — This shows order history for the current customer account, it will include all orders from any storefront user or telephone order for that account.
Customer Addresses and Prima Company Addresses
Prima → EvolutionX — The sync is one way so addresses created in EvolutionX do not become addresses in a Prima Company. Addresses used on an order, but not in the Prima Company, are created as single-use addresses in Prima.
Active Addresses — Prima addresses with an "Active" status will be created in EvolutionX. An address that created in EvolutionX and then changed in Prima to archived will be disabled in EvolutionX.
New Addresses on Orders stored in Prima — Prima Company addresses are sent to EvolutionX and two-way sync is supported where a new address is used on an order.
New one-off address on an order
Set SaveAddress = N and Location code is set as NULL
Will be added to Prima as a single-use address for the order
Prima Location code returned is ignored by EvolutionX
New saved address on an order
Set SaveAddress = Y and Location code is set as NULL
the address will be saved or updated as an active type in Prima
Prima Location code returned
EvolutionX checks that the location code is new in the account and then updates the EvolutionX customer address record with the location code
Prima will sync the new address during the next company sync.
Existing company address on an order
Set SaveAddress = Y and Location code is set from EvolutionX
Order will be rejected if the address on the order doesn't match the one stored in Prima.
Prima Location code returned is ignored by EvolutionX
Prima company address status values
active — a saved address which will sync Prima→EvolutionX
single-use — an address used on an order but not saved to the EvolutionX Customer account will be added as a single use address
archived — an address, sync'd with Prima, will be marked as an archived address if it's disabled in EvolutionX.
Contract Prices and live Prices
Contract Pricing are sent as Price rules are to EvolutionX daily and on request for an sync of a Prima Account using the Refresh button. If they are no longer being sync'd then they will auto delete after the price rule expiration.
Live Pricing can be enabled on EvolutionX to check pricing for all items that appear on a storefront page, are added to cart, or used in the Admin quotes screen.
Checkout Integration
Taxes Integration with Prima — After the shipping step of the checkout the integration will get the taxes for the order from Prima and update the cart summary on the page before the payment step. Note that distributors selling in VAT markets (e.g. Ireland, UK, Canada) should also setup VAT rules in EvolutionX so that VAT inclusive prices can be shown in the web catalog.
Shipping Fees Integration with Prima — In the app store settings you can select if the shipping fee is generated using the EvolutionX rules or the Prima shipping fee.
Note: For the Prima integration when setting up your delivery charges in Evolution, it is important that they are set NOT to include VAT on delivery
Web Order Processing
Credit Card Payments
Authorize.net is integrated into Prima. EvolutionX can be set to pre-auth the value of the order and the capture step is completed by Prima ERP.
Pre-auth and Capture on Dispatch — this setting holds the value of the order until Prima does the Capture step as part of the integration with Authorize.net. Talk to Prima Software for more information about this integration.
Other CC payment methods can be used in EvolutionX. Prima does not integrate with them but does note that the order is paid by CC as it processes the order. In EvolutionX set these payment methods as either
Pre-auth and Charge Now — this setting fully charges the card during checkout and requires no manual steps unless a refund or additional charge is required.
Pre-auth and Capture on Dispatch — this setting requires manual steps staff must take to capture the payment otherwise the order may be shipped without payment.
Stripe integration is coming soon to Prima.
Order Status Updates — Order status in EvolutionX is not shown to the customer since we use Live Lookup to Prima to show the Prima order status. EvolutionX does get limited update about order status of web orders so that loyalty/reward points can be allocated correctly. The order status updates happen during the overnight sync or when the "refresh" button is clicked in Prima in the Customer account. The EvolutionX Admin order statuses supported in the integration are as follows:
New Order — order is not yet sent to Prima
On Hold — order was sent to Prima but an error was returned, this should be reviewed by staff and either changed to "New Order", which triggers processing of the order to Prima, changed to "In Progress" if the order did go into Prima and is valid, or changed to "Cancelled" if the order is a duplicate or is not going to be processed.
In Progress — this is the status that EvolutionX sets the order to once it's been sent to Prima.
Completed — once any shipment is made on an order it is set to Completed in EvolutionX by Prima so that loyalty/rewards points can be allocated to the account. Any changes to the points balance because of cancelled items must be made manually by staff.
Cancelled — if the Prima order has been marked as cancelled (not items shipped) then the EvolutionX order is marked as cancelled and the loyalty/rewards points are discarded.
Setup Of Prima API Sync
This process will setup and start the Prima API Sync to EvolutionX as described above. Contact Prima and ES Tech Group for support on the following steps.
Prepare for Go Live Steps
These steps should be done ahead of the golive call.
Ask Prima staff if the Prima software and Database is a supported version for the API Sync.
Evaluate your data for compatibility with the API Sync by discussing these with EvolutionX Customer Success Staff:
Dealers with an exiting EvolutionX Store who are moving to Prima: EvolutionX Store Customers who are migrating from another ERP to Prima should ask to have their data checked for compatibility with the sync. It would be common to require that existing data is exported from the EvolutionX store and matched with Prima references. After migration of customer data to the Prima ERP run an export of Customer Accounts Only and Customer Addresses in EvolutionX (EvolutionX Admin → Customers → Accounts → Export). Check the files for the following and if any are missing, use EvolutionX exports from EvolutionX and sent them to Prima so the EvolutionX Store can be updates):
Existing EvolutionX Accounts must have the Prima Account Codes — Use Accounts Only Export to fix
Existing EvolutionX Account Addresses must have the Prima Address Code — Use Accounts Addresses Export to fix
Existing EvolutionX Users email address should match with a Prima Contact with the same email address. If it doesn't the user won't sync but will still work on EvolutionX.
Dealers using EvoLink to sync with EvolutionX and Prima: You will not need to take any steps to clean up account data but will need to consider the step below which disconnects users who have address restrictions.
Dealers using Prima and starting a new EvolutionX stores: No preparation of account data is needed since the data will come from the Prima API sync.
Customers who run more than one EvolutionX store: You should consult with Prima Software before using this integration method. Prima Software customer Sync does not support multiple stores but this may come in future versions.
Account Managers
Set up EvolutionX with Account Managers and use the Prima Account Manager Login value as the EvolutionX Account Manager Code. The Prima Account Managers are edited in the Users area of Prima and the Login value must be a match to the EvolutionX Account Manager's Seller Reference value in the EvolutionX Admin.
Mark the Prima contacts as web-enabled = false if they match an EvolutionX user who is restricted to customer addresses. This is because EvolutionX is the system of record for address restrictions until staff review the user setup in Prima.
Time Required: 1 hrIn EvolutionX, run a report "Users with settings all accounts" (no parameters needed).
Download and identify users where "BILLING ADDRESSES RESTRICTED" = "Y". Ask Prima to set the matching contacts in Prima as Web Enabled = False.
Set PO as Required — all orders in the store will require a PO value using the general store settings. This is recommended if your Prima ERP is set to require a PO on all orders regardless of customer settings.
Admin → Store Settings → Store Preferences → Default PO Structure
Set PO Structure Regex value to:
^([a-zA-Z0-9]+.*)$
Fix EvolutionX orders having a "New" order status — In EvolutionX Order list view, filter for orders with a order status of "New". Use the build update tools to set these orders with an order status of "In Progress" or "Completed". Either status if fine as it will not be seen by customers after the API Sync is enabled. As EvolutionX staff if assistance is needed.
Review App Store Settings required during Go Live steps:
Guest Account Code — This is the Prima Account where B2C customer orders will be sent for logged out customers or customers without an EvoutionX Customer Account Code (Prima Account Code).
Prima API Endpoint — Supplied by Prima to enable EvolutionX to read data from Prima API
Database Key — Supplied by Prima to enable EvolutionX to read data from Prima API
User Key — Supplied by Prima to enable EvolutionX to Read data from Prima API
Use EvolutionX Shipping Charges — When toggled as on, EvolutionX rules will be used to determine the shipping/delivery charges, otherwise Prima rules will set these fees in Checkout (at the payment step).
Error Notification settings — If EvolutionX is unable to send an order to Prima, these settings will determine which staff email receives the notification and which email address the email will come from.
Go Live Steps
Ask Prima staff if the Prima software and Database is a supported version for the API Sync.
In EvolutionX, take an Export of the following:
Customer Accounts:
Accounts Only,
Addresses,
Cost Centres,
Users into Existing Accounts
Prepare the EvolutionX store data. Stores running EvoLink Sync, for example, will follows these steps. If the store is new, skip to step 2.
Customer Accounts — Clear all Seller References values
Customer Addresses — Clear all Address Code values.
Customer Users — Clear all Seller Reference values
Cost Center — No action required
Evolink Contracts - Be aware that synced contracts from Prima are priority 10.
Set Prima System Keys using the notes below.
Create an EvolutionX API Key and name it "Prima Production API Sync" or similar. Use it in the this step and do not use it for anything else. This key is a secret and should not be stored.
Find the old API Key used by EvoLink and disable it in the EvolutionX Admin. This will ensure that EvoLink can't be accidentally enabled again. Skip this step if you do not have a legacy sync using EvoLink.
Install the Prima ERP App Store in EvolutionX — This enables the Checkout Integration, New Order processing, and Live Order History and Live invoice History features
Install and configure the "Prima ERP" app in the EvolutionX App Store (if not enabled for your store, ask our customer success team to enable it).
Set "6" as the number of months to view in orders and invoice lists, or set higher if the performance is good and customers need more history.
Set Guest Account Code for orders of non Prima customers
Request the Endpoint URL, DB Key and DB User Key from Prima
Set "Use EvolutionX Shipping Charges" if you want the EvolutionX shipping/delivery rules to set the delivery fee. Otherwise Prima will set it.
Set the email address for notifications sent on any errors EvolutionX receives when sending an order to Prima.
Tests and Checks
Test a single customer sync using the Prima Customer "Refresh" button. Review the record created in EvolutionX.
Check the trouble shooting guide if the customer record is not correctly created.
Update roles to enable Account Balances and Invoice History for users who should see these new screens from the Prima Integration and check an example user to see if there are any issues reading:
Live Order history
Live A/R Customer Balances
Live Invoice History
Live pricing — if enabled during the setup, check that it is working as expected
Check example orders processed to see that they are arriving as expected.
Update roles to enable Account Balances and Invoice History for users who should see these new screens from the Prima Integration.
Set VAT rates in Evolution so that VAT is NOT included on delivery.
Post Golive Actions
Any users that were marked as not web-enabled in Prima because they used addresses restrictions in EvolutionX can be reviewed over time, updated in Prima, and enabled for sync.
Prima System Keys
⚠️ Note when updating these values: If you change the system keys in Prima, they will not be in effect until the EDC and Prima Clients have been restarted.
EVOxEnabled = "Y" |
|
EVOxDefaultCountry = {string} |
Set this to the Default ISO country code to be used where country field in addresses are empty. ISO Alpha-2 code must be used. |
EVOxExportWebOnly = {Y/N} | This controls which Customer Accounts in Prima are part of the Sync with EvolutionX.
|
EVOxSendAnyAddress = {Y/N} |
|
EVOxBaseUrl = {string} | UK/EU EvolutionX Store set as: US/CA EvolutionX Store set as Fully qualified domain for the EvolutionX API endpoint. |
EVOxApiKey = {string} | EvolutionX API key. To create one, refer to the EvolutionX API Key documentation. |
EVOxIgnoreUsername | Check with Prima for the recommended value. |
Frequently Asked Questions
How do you retry an order that failed to go into Prima and is no showing an "On Hold" status?
Check first if the order did arrive Prima and if it has, do not resubmit it. If it hasn't, and you need to resubmit it to Prima, then In EvolutionX open the order in the Admin and set the Order Status to "New" and this will retry the order.