The Data space feature makes it possible to import any kind of data to an account, that can be used in the shop front-end using script. Data space is an account-specific no-SQL elasticsearch database, that can hold a huge amount of data and offers amazing performance for retrieving data using the Data space API or runtime values.

Each account has one data space, which in turn may contain several different tables. Accounts will be billed according to disc space consumption and usage (e.g. number of requests/traffic).

Importing and maintaining data space tables

Data is currently imported to a data space via FTP XML integration, hence the data may come from the ERP system or any other system capable of delivering data in the required format.

It is possible to create complex objects with nested objects and arrays. It is even possible to import data already formatted as JSON using the XML import. See the XML schema documentation for more information about importing data space tables.

Have a look at this example import file containing a data space table named “ShopLocations”, which contains information about three different physical (imaginary) shops.

Each of the entries in the file will upon import be transformed and stored as JSON in the data space table, and each entry will look somewhat like this:

Accessing data from a data space table

Information from a data space table may be accessed via the Data space API using script or by using runtime values (e.g. in a content design).

Getting data from a Data space using the API

The Data space API has the service URL:
/services/v1/dss/

It accepts the following URI parameters, which map directly to elasticsearch URI search.

• q: optional
  The query string – is passed to elasticsearch as-is. Defaults to "*".
• _source: optional
  Allows you to specify fields to return in the response. It often makes sense to limit the result fields to what is actually needed, in order to improve performance, reduce the data amount and minimize bandwidth consumption.
  Example:
  /services/v1/dss/shoplocations?_source=Shop.Name,Shop.GeoLocation.Latitude,Shop.GeoLocation.Longitude
  - Returns only the fields Name, Latitude and Longitude.
• sort: optional
  Allows you to sort the result by one or more fields - fieldName:asc/fieldname:desc.
  There can be several sort parameters (order is important).
  Example: /services/v1/dss/menulevelspecification?sort=Shop.Name:asc
  - Sorts the results by Name ascending.
• from: optional
  Defines the offset from the first result you want to fetch.
  Example: /services/v1/dss/menulevelspecification?from=5
  - Gets results starting from the 5th result
• size: optional
  Allows you to configure the maximum amount of hits to be returned (defaults to 10.000).
  Example:/services/v1/dss/shoplocations?size=10
  - Gets the first 10 results
  /services/v1/dss/shoplocations?from=5&size=10
  - Gets the next 10 results from the 5th result
• source: optional
  Supports searching by defining the request body as JSON. Makes it possible to perform JSON aggregation and use other advanced elasticsearch features. Read more about elasticsearch search requests here.

The Data space API returns results formatted as JSON. If no “size” parameter is set in the request, it returns up to 10.000 results.

Getting data from a Data space table using runtime values

You can query a data space table directly from a content design using runtime values.

The syntax for querying a data space table using runtime values is:
DataSpace:<tablename>[index].<field>.<field>...<field>?<elasticsearch options>

where:

• <tablename> is the data space table name - case insensitive.
• [index] is a required indexer (resulting table is treated as an array with zero or more entries).
• <field> is fields as seen in the JSON result - as with other runtime values, you may dive into the object hierarchy - case sensitive.
• <elasticsearch options> are the same options as supported by the data space API - here you write your query - are inherently case sensitive.

Examples:
<eSeller:Select Value-Of="DataSpace:shoplocations[0].Shop.Name?q=Shop.Address.ZipCode:"5000"" />
- Returns the “Name” value for the first shop with zip code “5000” from the data space table “shoplocations”.

<eSeller:Select Value-Of="DataSpace:shoplocations[0]?q=Shop.Address.ZipCode:"6000"" />
- Returns the first “Shop” object (as JSON) that has zip code “6000” from the data space table “shoplocations”.

<eSeller:Select Value-Of="DataSpace:ShopLocations[0]?q=(Shop.Address.ZipCode:"6000")AND(Shop.Employees:"April")" />
- Returns the first “Shop” object (as JSON) for the shop with zip code “6000” and that has the employee “April”.

Viewing data space tables in the shop administration

In the shop administration you can see a list of all data space tables for an account. The data space overview is located at Integration > Import/Export > Data space.

The overview displays the table name and cache control information about all data space tables in the account.

By clicking “View sample” you can see what kind of information the data space table holds (displays the first 5 entries), and from there you can also click a link to see the response directly in the browser (thus revealing the URL of the data space table).

Data space restriction

Data space tables may be configured to ensure that data returned by the Data Space API is limited server-side.

New data space tables default to “restricted” mode, which means that in order to access the data space table from front-end, some configuration must be made for the data space table in the shop administration.

How does it work?

Restricting data space tables works by forcing a query filter specified for the data space table onto the Elasticsearch query generated by any front-end request to the /services/v1/dss/ or /sessionservices/v1/dss Data Space services.

This entails that the result set that is available to front-end is limited server-side by the query filter specified in the shop administration.

Data space table configuration

In the shop administration at Integration > Import/Export > Data space, you are able to see all data space tables that exist on the account as well as the configuration of them.

You edit the data space table configuration by clicking the name of the data space table.

In the configuration overlay that appears, you are able to configure settings for the data space table. Regardless of the data space table configuration, it is always possible to view a sample of the data space table in the shop administration by clicking “View sample”.

Stateless

If enabled, the data space table is accessible via the service URL /services/v1/dss/

This setting is useful in situations where no state information is necessary for determining who may access data. It may be used for “public” data space tables or data space tables with a query filter that does not require any information regarding state.

Statefull

If enabled, the data space table is accessible via the service URL /sessionservices/v1/dss

This setting is useful in situations that require state information (e.g. who is currently logged in). It may be used for “restricted” data space tables.

HonorQueryFilter

If enabled, requests to the data space table is run through a filter before returning results.

If this setting is enabled, a filter must be specified in the text pane below - otherwise requests to the data space table will fail with the message “QueryFilterDesign cannot be empty for dataspace table [table name].”

In the text pane you must specify an Elasticsearch query string as the filter.

You may use runtime values and eSeller tags (e.g. eSeller:If) in the query filter (e.g. getting the ext. customer ID of the currently logged in customer).

Please mind whether the runtime values used in the query filter require state information (and thus whether the data space table configuration should be set to “Stateless”, “Statefull” or even both). For instance, runtime values from the “Basket” and “Customer” runtime value containers are generally “Statefull” whereas runtime value container “Product” is generally “Stateless”.

LoggedInAsCustomer

If enabled, the data space table is only accessible to logged-in customers (data space table must be “Statefull”).

LoggedInAsSalesPerson

If enabled, the data space table is only accessible to logged-in salespersons (data space table must be “Statefull”).

Cache-Control MaxAge

Allows you to define the value of the Cache-Control header (for how long the resource may be cached). Default is 600.

CacheControlPublic

If enabled, the Cache-Control header is “public”.

If disabled, the Cache-Control header is not “public”.

Enable query logging

Currently only available for internal debugging.

Use cases

Below you see a few examples on how data space table configuration may be applied.

Data space table must be accessible to all users (public)

Recommended settings: Stateless

Data space table must only be accessible to logged in customers (any customer)

Recommended settings: Statefull, LoggedInAsCustomer

Data space table must only be accessible to logged in salesperson (any salesperson)

Recommended settings: Statefull, LoggedInAsSalesPerson

Data space table must be accessible to any logged-in customer OR salesperson

Recommended settings: Statefull, HonorQueryFilter

QueryFilter:

<eSeller:If IsFalse="Settings:IsLoggedIn">user:notauthorized</eSeller:If>
<eSeller:If IsTrue="Settings:IsLoggedIn">*</eSeller:If>

- If no customer/salesperson is logged in, the query will be appended a filter that results in 0 results (user:notauthorized).

- If any customer/salesperson is logged in, the query will not be restricted by any filter.

Documents in a data space table must be filtered by logged-in customer ID

Recommended settings: Statefull, HonorQueryFilter, LoggedInAsCustomer

QueryFilter:

customerid:<eSeller:Select Value-Of=”Customer:ExtCustomerID”/>

This configuration presupposes that the data space table has a column named “customerid” containing the ext. customer ID.

Documents in a data space table must be filtered by currently active country

Recommended settings: Statefull, HonorQueryFilter

QueryFilter:

country:<eSeller:Select Value-Of=”Context:Country.ExtCountryId”/>

This configuration presupposes that the data space table has a column named “country” containing the ext. country ID, e.g. “DK”.