Skip to main content

EVA Core concepts

The EVA Core (or system) features center around:

  • Configuration
  • Organization units
  • Authentication
  • Users and permissions

Endpoint, configuration and bootstrapping#

To start interacting with EVA using one of our available SDKs you need to know your endpoint Url. The first thing you will want to do is call EVA.Core.GetApplicationConfiguration which will provide additional details about how the EVA environment you are talking to is configured and which features are available. This step is what we call bootstrapping an endpoint. The TypeScript SDK for example can handle this process for you automatically.

The application configuration will contain information such as:

  • Default language and currency
  • Asset (image) base urls
  • Enable EVA plugins
  • Payment provider settings
  • Available SignalR hubs
  • Legal requirement features
  • Application behaviour
  • and much more...

Organization units#

Organization units are as the name implies the means to organize the hierarchy of the client. A top level organization could be a customers main domain and each unique webshop would be a client organization unit. There is a whole breath of topics related to organization units which have no bearing on client application development. For client applications it is important to know that:

  • users belong to an organization unit
  • a physical store is an organization unit
  • hardware stations (cash drawers, printers) belong to an organization unit

For more background information you can checkout the Organization Units documentation in the concepts section.

Choosing which organization unit service calls act on can be done in 3 ways:

  • implicitly from the logged in user
  • explicitly in a request body parameter
  • explicitly through a request header

Authentication#

The EVA backend works with 2 tokens:

  • application tokens
  • user tokens

There used to be a 3rd type of token called the anonymous or default token. This is no longer used and the EVA backend will use the anonymous profile implicitly when calling with a user token.

Application tokens#

The application token is an additional layer of authentication used only for anonymous interactions (calls without a user token). The EVA backend will assign an application token to the client with the EVA-App-Token header in a service response. Any new value for this header should replace the previous token. The JavaScript SDK manages the collection of this token and will apply it to the settings exposed by the @springtree/eva-sdk-core-service package. You are recommended to persist the last known application token to storage to resume your application session.

User tokens#

Once a user is logged in to the system they will have their own authentication token. This token provides access to services to retrieve a users details (order history, profile information, etc). If the logged in user is of type employee they will also gain access to services for interacting with stations and terminals along with user management features. When a user token expires a 401 HTTP code will be returned.

Users and permissions#

A user is a generic entity that based on its type. The user types of interest for client applications are:

  • anonymous (0)
  • an employee (1)
  • a customer (2)

You can retrieve the current users details using the EVA.Core.GetCurrentUser service. The user type can be found in the response at User.Type. This property is a bit-field which means that it can contain multiple values at the same time. So a value of 3 would be both a customer and an employee. You can use a bitwise operator to check for a specific type.

User permissions are available through the ScopedFunctionalities property. Much like other parts of EVA functionalities are fully configurable so the key value will differ per customer. The value of the functionality is a bit-field based on this enum:

  export const enum FunctionalityScope {    None = 0,    Create = 1,    Edit = 2,    Delete = 4,    View = 8,    Manage = 31  }

So if the user is allowed to both View, Create and Edit the value of the functionality will be 11. You can use a bitwise operator to check for a specific permission scope value.

Simplified overview#

Below is a simplified overview of EVA features with a focus on topics of interest for application developers:

flowchart LR subgraph core Configuration Users OrganizationUnits Permissions end subgraph products Catalog Details Searching Prices end subgraph hardware Stations Devices end subgraph crm Customers AddressBook MarketingAndCommunication end subgraph orders Checkout Payments Shipping Discounts Returns end subgraph employees financialPeriods inventoryManagement userTasks end products --> orders Customers --> orders Users --> Permissions OrganizationUnits --> hardware OrganizationUnits --> products OrganizationUnits --> employees OrganizationUnits --> Configuration OrganizationUnits --> Users Payments --> hardware