Support and Docs

Menu

Design

This category contains topics regarding design and styling of the eSeller Cloud webshop. Topics could include subjects such as for instance CSS styling, page designs and content design.

3 Topics
Last post 11 November 2014 By Nadja Kristiansen

Integration

All topics regarding integration appear in this category. Here you are able to discuss ERP systems, data import/export, data transformation etc.

1 Topics
Last post 20 March 2014 By Carsten E. Madsen

Marketing

This category holds all topics related to marketing, such as for instance SEO, AdWords, advertising and promotions.

0 Topics
Last post N/A By N/A

eSeller Cloud features

All topics relating to eSeller Cloud features such as coupon functionality, product sorting and product filtering.

0 Topics
Last post N/A By N/A

Miscellaneous

This category contains all topics not falling under any of the other categories.

1 Topics
Last post 02 April 2014 By Carsten E. Madsen

Categories

Criteria Files

  • 11/11/2014

The Criteria Files feature enables integrated shops to easily retrieve information about orders, customers and payment transactions via the FTP interface.

What can I do with Criteria files?

  • Get a list of specific orders/customers/gift cards/payment transactions based on IDs
  • Get orders/customers/gift cards/payment transactions that have been created since a particular date
  • Get orders/gift cards/payment transactions that have been created within a certain time frame

Example use cases

  • You wish to retrieve the orders with IDs 1152, 1153 and 1154
  • You wish to retrieve all orders created since yesterday noon
  • You wish to retrieve all orders created during the month of October

Although it is possible to let the eSeller Cloud Platform keep track of downloaded orders by simply downloading the order files, we strongly recommend that all order downloads use criteria files to fetch orders downloaded since last download. The reason we recommend this is that if an error occurs during the transfer, eSeller Cloud may erroneously think that the orders have been fetched by the ERP system while the ERP system haven’t received the orders. The only safe way to fetch orders periodically is to use criteria files.

Criteria files

What are Criteria files?

Criteria files contains rules of what data should be exported when exporting orders, customers or payment transactions from eSeller Cloud. A criteria file for each of these four export types exists per default and they are configured to retrieve only new orders/customers/payment transactions – meaning the ones that have not previously been exported.

Per default, the criteria files contain the following information:

OrdersCriteria.xml

<integrationData version="1.0">
  <placedOrdersCriteria type="NewOrders" />
</integrationData>

CustomersCriteria.xml

<integrationData version="1.0">
  <customersCriteria type="NewCustomers" />
</integrationData>

PaymentTransactions.xml

<integrationData version="1.0">
  <paymentTransactionsCriteria type="New" />
</integrationData>

GiftCardsCriteria.xml

<integrationData version="1.0">
  <giftCardsCriteria type="NewGiftCards" />
</integrationData>

As you can see, the type of the criteria files is “New”. This means that only data that has not previously been exported, will be exported. By changing the type of a criteria file and adding some elements to the file, you are able to specify what data you wish to export in stead.

Note that using Criteria files will only extract data related to the Data Origin. In the following cases, the Criteria file will not extract data:

- If a customer is created in the shop administration, this customer will no be included in the data.
- If an order is made on a product that does not originate from the Data Origin (e.g. if it originates from another
Data Origin or from the shop administration), the order will not be included in the data.

When exporting gift cards, special rules apply for the data origin. This means that even if the gift cards have been created in the shop administration or in the webshop (and hence have not been imported via the data origin), these will still be exported.

When exporting customers using the "NewCustomers" criteria whilst logged in as a Data Origin, only customers that have not previously been exported are exported - and upon export ownership of the exported customers changes to the current Data Origin, which means that customers may subsequently be exported using the "CreatedSince" criteria.

OrdersCriteria.xml

The OrdersCriteria.xml file defines what data the Orders.xml file should contain. Below you see examples on how to use the different OrdersCriteria.xml criteria types.

List

The Orders Criteria type “List” defines a list of orders to retrieve. 

<integrationData version="1.0">
	<placedOrdersCriteria type="List">
		<orderId>1131</orderId>
		<orderId>1132</orderId>
		<orderId>1133</orderId>
		<orderId>1134</orderId>
	</placedOrdersCriteria>
</integrationData>

For each order you wish to retrieve, you have to create an element and add the ID of the order.

CreatedSince

The Orders Criteria type “CreatedSince” retrieves all orders that have been created since a specific date (that date included). The date must be specified in the format YYYY-MM-DD. 

<integrationData version="1.0">
	<placedOrdersCriteria type="CreatedSince">
		<date>2014-10-31</date>
	</placedOrdersCriteria>
</integrationData>

This Criteria file retrieves all orders that were created since October 31th 2014. Also orders created on this date are included.

CreatedBetween

The Orders Criteria type “CreatedBetween” retrieves all orders that have been created within a specified time period – you have to specify a start and an end of the time period in the format YYYY-MM-DDTHH:MM:SS 

<integrationData version="1.0">
	<placedOrdersCriteria type="CreatedBetween">
		<startDateTime>2014-04-10T08:00:00</startDateTime>
		<endDateTime>2014-04-12T09:30:00</endDateTime>
	</placedOrdersCriteria>
</integrationData>

CustomersCriteria.xml

The CustomersCriteria.xml file defines what data the Customers.xml file should contain. Below you see examples on how to use the different CustomersCriteria.xml criteria types.

List

The Customer Criteria type “List” defines a list of customers to retrieve. 

<integrationData version="1.0">
	<customersCriteria type="List">
		<customerLifetimeId>732</customerLifetimeId>
		<customerLifetimeId>69</customerLifetimeId>
		<customerLifetimeId>27</customerLifetimeId>
	</customersCriteria>
</integrationData>

For each customer you wish to retrieve, you have to create a element and add the Lifetime ID of the customer.

The customer Lifetime ID

CreatedSince

The Customers Criteria type “CreatedSince” retrieves all customers that have been created since a specific date (that date included). The date must be specified in the format YYYY-MM-DD. 

<integrationData version="1.0">
	<customersCriteria type="CreatedSince">
		<date>2013-01-01</date>
	</customersCriteria>
</integrationData>

PaymentTransactionsCriteria.xml

The PaymentTransactionsCriteria.xml file defines what data the PaymentTransactions.xml file should contain. Below you see examples on how to use the different PaymentTransactionsCriteria.xml criteria types.

List

The Payment Transactions Criteria type “List” defines a list of payment transactions to retrieve. 

<integrationData version="1.0">
	<paymentTransactionsCriteria type="List">
		<extReference>1131</extReference>
	</paymentTransactionsCriteria>
</integrationData>

For each payment transaction you wish to retrieve, you have to create a element and add the Ext. Reference of the payment transaction. The Ext. reference is defined in the segment of import files from the ERP system: 

<integrationData>
	<paymentCommands integrationScope="partialIntegration">
		<paymentCommand>
			<command>capture</command>
			<orderId accountId="162">1153</orderId>
			<amountIncVat>125.00</amountIncVat>
			<extReference>123abc</extReference>
			<finalize>true</finalize>
		</paymentCommand>
	</paymentCommands>
</integrationData>

An example of a payment command imported to the shop with the Ext. Reference ”123abc”.

CreatedSince

The Payment Transactions Criteria type “CreatedSince” retrieves all payment transactions that have been created since a specific date (that date included). The date must be specified in the format YYYY-MM-DD. 

<integrationData version="1.0">
	<paymentTransactionsCriteria type="CreatedSince">
		<date>2014-10-01</date>
	</paymentTransactionsCriteria>
</integrationData>
CreatedBetween

The Payment Transactions Criteria type “CreatedBetween” retrieves all payment transactions that have been created within a specified time period – you have to specify a start and an end of the time period in the format YYYY-MM-DDTHH:MM:SS 

<integrationData version="1.0">
	<paymentTransactionsCriteria type="CreatedBetween">
		<startDateTime>2014-04-10T08:00:00</startDateTime>
		<endDateTime>2014-04-12T09:30:00</endDateTime>
	</paymentTransactionsCriteria>
</integrationData>

GiftCardsCriteria.xml

The GiftCardsCriteria.xml file defines what data the GiftCards.xml file should contain. Below you see examples on how to use the different GiftCardsCriteria.xml criteria types.

List

The GiftCards Criteria type “List” defines a list of gift cards to retrieve. You must specify the gift card code as the giftCardId. 

<integrationData version="1.0">
	<giftCardsCriteria type="List">
		<giftCardId>1234ABCD</giftCardId>
		<giftCardId>JHS72HLSL</giftCardId>
	</giftCardsCriteria>
</integrationData>

For each gift card you wish to retrieve, you have to create an element and specify the gift card code.

CreatedSince

The GiftCards Criteria type “CreatedSince” retrieves all gift cards that have been created (issued) since a specific date (that date included). The date must be specified in the format YYYY-MM-DD. 

<integrationData version="1.0">
	<giftCardsCriteria type="CreatedSince">
		<date>2014-10-31</date>
	</giftCardsCriteria>
</integrationData>

This Criteria file retrieves all gift cards that were created/issued since October 31th 2014. Also gift cards created on this date are included.

UpdatedSince

The GiftCards criteria type "UpdatedSince" retrieves gift cards based on when an event has last occurred (e.g. amount redeemed, gift card activated, gift card locked, gift card expired etc.).

<integrationData version="1.0">
	<giftCardsCriteria type="UpdatedSince">
		<date>2015-02-04</date>
	</giftCardsCriteria>
</integrationData>

This file includes all gift cards where the last event occurred up until the 4th of February 2015.

CreatedBetween

The GiftCards Criteria type “CreatedBetween” retrieves all giftcards that have been created within the specified time period – you have to specify a start and an end of the time period in the format YYYY-MM-DDTHH:MM:SS 

<integrationData version="1.0">
	<giftCardsCriteria type="CreatedBetween">
		<startDateTime>2014-04-10T08:00:00</startDateTime>
		<endDateTime>2014-04-12T09:30:00</endDateTime>
	</giftCardsCriteria>
</integrationData>
UpdatedBetween

The GiftCards Criteria type “UpdatedBetween” retrieves all giftcards for which an event has occurred within the specified time period (e.g. amount redeemed, gift card activated, gift card locked, gift card expired etc.) – you have to specify a start and an end of the time period in the format YYYY-MM-DDTHH:MM:SS 

<integrationData version="1.0">
	<giftCardsCriteria type="UpdatedBetween">
		<startDateTime>2014-04-10T08:00:00</startDateTime>
		<endDateTime>2014-04-12T09:30:00</endDateTime>
	</giftCardsCriteria>
</integrationData>

Criteria file schema documentation

For more documentation on Criteria files, go to:
Documentation on OrdersCriteria.xml
Documentation on CustomersCriteria.xml
Documentation on PaymentTransactionsCriteria.xml
Documentation on GiftCardsCriteria.xml

How do I use Criteria files?

1. Create your Criteria file. You can copy and edit the examples above.
2. Make sure your file is named either OrdersCriteria.xml, CustomersCriteria.xml, PaymentTransactions.xml or GiftCardsCriteria.xml – this is very important as the criteria file will otherwise not work.
3. Open your FTP client (e.g. FileZilla) and log in using your Data Origin credentials. These are found under Base setup > Company info > Account and selecting the “Integration” tab.

4. Open the Export folder
5. Drag your Criteria file to the Export folder.
6. The FTP client will ask you if you wish to overwrite the existing file – say yes.
7. Download the Orders.xml/Customers.xml/PaymentTransactions.xml file dependent on which type of criteria file you uploaded.
8. Open the newly downloaded file and see that it contains the data that was specified in the Criteria file.

Note that uploaded Criteria files are only valid for the session. Once the session ends, the Criteria files will revert to default (new orders/customers/gift cards/payment transactions).

Using criteria files as a non-Data Origin

If you are logged in on the FTP using non-Data Origin credentials (such as the shop administration credentials or the account FTP credentials), you are still able to use the criteria files to retrieve data. Note that when exporting data as a non-Data Origin, the state of whether or not the entity has been exported will not change. This means that exporting data as a shopadmin or account FTP does not interfere with the data origin integration.

Note that the default settings for the criteria files are different from when exporting as a data origin. Below you see in what ways they differ.
When logged in to the FTP as a non-data origin:
- The "NewOrders" criteria for orders gets all orders with the state "New"
- The "NewCustomers" criteria for customers gets no data (you have to specify another criteria)
- The "New" criteria for payment transactions gets no data (you have to specify another criteria)
- The "NewGiftCards" criteria for gift cards gets all gift cards that have been issued in the last seven days.