Skip to main content

External user search

While EVA boasts an extensive range of functionalities and services for storing and searching users, there may be some situations where you want to store your users outside of EVA - either momentarily or not. For this kind of situation, we offer the following integration flow.

Configuration & settings

To be able to make use of "Search in external database" (for example) action buttons in our front ends, you first have to link your external database to EVA. This requires configuration of several services and settings.

How EVA Handles External User Searches​

EVA processes external user searches as follows:

Initial Search Within EVA:

  • EVA first searches for the user within its own records.
  • If no result is found, EVA automatically searches the external system.

Creating an External User:

  • From the search results, create an external user by pressing the + Create button.
  • EVA populates the create modal with values from the external system to record the user within EVA.

Adding to Basket:

  • After successfully creating a user, you can immediately add them to a basket.

Configuration Requirements​

To enable external user searches, use the following services and settings:

Services​

The following services and properties are relevant.

  • SearchUsers contains the property Source, which must be set to External
    • This SearchUsers call has a default limit of 5 seconds, but it can be configured otherwise with the setting ExternalUserProvider:Timeout.
  • CheckEmailAddressAvailability
  • CheckNicknameAvailability
    • These two Check services have a hardcoded timeout of 500ms
  • GetApplicationConfiguration service exposes if external user search is available, by displaying it as a ExternalUserProvider:Enabled property.
    • This property will return true if the setting ExternalUserProvider:BaseUrl has been configured.

The different endpoints in practice​

{
 "Nickname": "<value>"
}

Settings​

All of the above POST requests are made to your configured endpoints based on the following setting:

  • ExternalUserProvider:BaseUrl
  • ExternalUserProvider:Username
  • ExternalUserProvider:Password
  • ExternalUserProvider:Timeout - Usage is as described in the Services section above

Calling the endpoint​

The BaseURL included in the settings here above needs to be exposed to EVA in the following way:

Exists​

When checking for availability, EVA will need to be able to call the BaseURL endpoint to see if it (be it the email address or nickname) already exists. Hence, the endpoint needs to be exposed.

Example:

  • ExternalUserProvider:BaseUrl = customer-api.io
  • Endpoint: customer-api.io/exists

The same goes for when EVA needs to check the external database to find a user.

  • ExternalUserProvider:BaseUrl = customer-api.io
  • Endpoint: customer-api.io/search

Get​

Once the search has been done and an Identifier retrieved, EVA can fetch the details of the user.

To that end, EVA invokes the following endpoint with the Identifier:

  • Endpoint customer-api.io/get/{identifier}

EVA expects the following response from the endpoint:

Sample
{
  "Identifier": "12345",
  "BackendRelationID": "rel-67890",
  "EmailAddress": "example@example.com",
  "Initials": "J.D.",
  "FirstName": "John",
  "LastName": "Doe",
  "DateOfBirth": "1985-06-15",
  "Gender": "M",
  "LanguageID": "en",
  "CountryID": "US",
  "Nickname": "Johnny",
  "PhoneNumber": "+1234567890",
  "TimeZone": "Europe/Amsterdam",
  "Title": "Mr.",
  "Salutation": "Dear",
  "CustomID": "cust-001",
  "ShippingAddress": {
    "HouseNumber": "123",
    "Address1": "456 Elm Street",
    "Address2": "Apt 789",
    "ZipCode": "90210",
    "Subdistrict": "Central",
    "District": "Downtown",
    "City": "Metropolis",
    "State": "NY",
    "Region": "Northeast",
    "CountryID": "US"
  },
  "BillingAddress": {
    "HouseNumber": "123",
    "Address1": "456 Elm Street",
    "Address2": "Apt 789",
    "ZipCode": "90210",
    "Subdistrict": "Central",
    "District": "Downtown",
    "City": "Metropolis",
    "State": "NY",
    "Region": "Northeast",
    "CountryID": "US"
  },
  "CustomFields": [
    {
      "BackendID": "cf-001",
      "Value": "CustomValue1"
    },
    {
      "BackendID": "cf-002",
      "Value": 42
    }
  ]
}
Additional information on the Get method
  • Identifier is what EVA will map to what is known as the BackendID within EVA
  • BackendRelationID is like the BackendID, but with the intention of being used as a link to a financial system
  • Gender has no input validation, this is just a string
  • LanguageID ISO 639-1 (for example: en)
  • CountryID ISO 3166-1 alpha-2 (for example: US)
  • TimeZone IANA Time Zone - for example: Europe/Amsterdam or America/New_York
  • CustomFields array of object containing a BackendID ("string") and a Value ("any")
    • Note that for these to map correctly, there needs to be a [custom field(/documentation/documentation/other/custom-fields)] in EVA as well with the corresponding BackendID
  • BillingAddress, ShippingAddress and the CountryID are also ISO 3166-1 alpha-2