Principle of interfacing between eCOS and DATAKISS

DATAKISS is a SaaS solution designed to help clients prepare for the future territorialization of their sales force. This solution requires data related to stores, users, homes, and the organization. It allows users to create new territories or regions, delete existing ones, and modify territories by adding or removing stores. Multiple scenarios can be created, but only one can be validated by the client.

As part of the partnership between EXTERNIS and DATAKISS, we decided to interface our solutions to simplify processes for administrators. This integration virtually eliminates the need for processing via Excel files. Now, all interactions take place through API calls, without any file exchange between applications.

DATAKISS retrieves the following information from eCOS :

• Current organizational structure
• Current users
• Current delivery locations + geolocation + visit frequency
• Users' Homes
• Attachment Delivery location / Current user
• Theoretical information provided by DATAKISS during the previous sectorization:
  • Theoretical visit frequency
  • Average visit time
  • Theoretical number of kilometers
  • Number of days on the field
  • Number of weeks worked
  • Number of hours worked per day

As the eCOS solution is a field-based solution, it uses current data. DATAKISS, on the other hand, processes future data. The two solutions operate independently in terms of their databases.

Once the future sectorization developed in DATAKISS is validated, the EXTERNIS teams take charge of the reorganization requested by the client. After the new users and organizations are created in eCOS , the validated sectorization from DATAKISS is retrieved, thus establishing the link between delivery locations and users.

eCOS retrieves the following information from DATAKISS:

• New users
• New delivery locations
• Linking delivery locations - users
• Theoretical information entered in DATAKISS:
  • Theoretical visit frequency
  • Average visit time
  • Theoretical number of kilometers
  • Number of days on the field
  • Number of weeks worked
  • Number of hours worked per day

Managing a new user created in DATAKISS: When importing the sectorization, it is necessary to establish a link with an existing user in the eCOS ® database.

Managing a new delivery location: If the location reference in DATAKISS matches the one in eCOS , the matching is performed automatically. Otherwise, the location will be ignored.

New customer onboarding

EXTERNIS and DATAKISS define a correspondence for their respective clients. Each must provide a unique code to identify the client within their system.

Example :

Setting up the "DEMOCLIENT" client

DEMOCLIENT	Customer ID

EXTERNIS creates a specific user on the client platform (username: datakiss ) and communicates the username and password to DATAKISS.
EXTERNIS also provides a unique API key to use for the connection.

DATAKISS, for its part, creates a specific user on the client platform (username: externis ) and provides EXTERNIS with the username and password. DATAKISS must also activate the necessary permissions for the client in question.

Authentication principle

The eCOS APIs are available in 2 environments:

• Test environment (QA)
• Production environment (PROD)

Each environment has a root URL, represented in the documentation by <root> ( example: <root>/Auth/Logon )

All APIs are protected by a Token, except for the authentication API (logon) which can be called anonymously.

DATAKISS must first call the logon API to obtain this token. It must then be passed in the header of all HTTPS requests for calls to other APIs.

An EXTERNIS configuration file exists that allows the correct DATAKISS environments and APIs to be used depending on the environment. It is essential to fill it in correctly before implementation.

DATAKISS connection → eCOS ®

To connect to eCOS ®, DATAKISS must complete 2 steps:

• Log in to our system: to retrieve a User entity representing the user "DATAKISS"
• Log in to the client platform: to retrieve a completed version of the User, with the information needed to consume the rest of the APIs.

APIs :

• <root>/Auth/Logon
• <root>/Auth/LogonApplication

POST API:

<root>/Auth/Logon (username, password, customer, apiKey)
@username = xxx
@password = xxx
@customer = xxx
@apiKey = xxx

For the Customer, it is the name of the eCOS ® platform that is expected.

eCOS ® connection → DATAKISS

To connect to DATAKISS, eCOS will need an API key provided by DATAKISS.

Each method called must contain the API key + the Client Name which corresponds to our eCOS client name or matching via a possible mapping configuration.

DATAKISS must grant permission for the relevant client before an API call, otherwise the call will be rejected.

Technical information

• Authentication: creation of a DATAKISS user on eCOS specific to each client platform
• Data exchange is done exclusively via API; no file exchanges are involved.
• The reference and eCOS ID of a location will be sent as keys and must be returned.
• A user's identifier and eCOS ID will be sent as keys and must be returned.
• For the frequency of visits to the site, we will export the parameterized value on the eCOS ® side calculated over 1 year (52 weeks – 365 days)
• Multi-organization management (CS-Promoter for the same location): We duplicate the locations as many times as there are organizations attached to the location (same eCOS reference).
• When sending data from eCOS to Datakiss, eCOS will receive the ID_Scenario and must retain it. This ID may change, and eCOS must be able to update it.

Future developments

In the near future, DATAKISS theoretical data will be used in eCOS reports to compare theoretical and actual figures. We will keep you informed of any developments via release notes.