eWay-CRM Gate Introduction

eWay-CRM Gate is IIS web application that allows you to let users out of eWay-CRM have access to eWay-CRM data in HTML form (e.g. you can share invoice with a customer). The installation of eWay-CRM server component does not have eWay-CRM Gate turned on by default.

Installation and Configuration

IIS application eWay-CRM Gate is in the Gate folder of the base folder of eWay-CRM server component. This location is important because eWay-CRM Gate is loading it's connection string to database from the Web.config file (configuration file of the eWay-CRM Web Service) that is in the base folder of the server component. Although, in IIS, application running in this folder may run under different WebSite or different URL than eWay-CRM Web Service.

To run eWay-CRM Gate, you need to configure it correctly. You need to define what SQL procedures will be called - you set mapping. Configuration is done in Web.config file that is in the Gate folder. The default configuration file is provided with new installation of eWay-CRM server component.

Mapping is set in the configuration section mappedContent. Each mapping must contain name and name of the SQL procedure. It also can contain optional alias of parameters so the name of the parameter in URL may be different than its name in SQL procedure. You do not need to set all SQL procedure parameters in the file. Those that are not set will have same name in URL and in SQL (at sign is not used).

The example of the mapping is:

  <mappedContent>
    <mappings>
      <mapping name="username" procedureName="eWaySP_UnitTests_GetHtmlUsername">
        <renamedParameters>
          <renamedParameter name="id" procedureParameterName="UserItemGUID" />
        </renamedParameters>
      </mapping>
    </mappings>
  </mappedContent>

The example shows mapping of eWaySP_UnitTests_GetHtmlUsername procedure that has two parameters: (@UserItemGUID a @Color). This procedure will be called using eWay-CRM Gate under name username with parameters id and Color.

Call the Procedure

One HTTP call means one call of SQL procedure. There are some limits and specifics. The call can be done in this form:

https://{address of Gate application}/{mapping name}/{parameters in base64}

Parameters of HTTP URL are transferred as base64 encrypted string. Specifically, it is a string of standard URI parameters (Query String in percent encoding - see https://en.wikipedia.org/wiki/Query_string) whose UTF8 byte representation is coded as base64 string.

You can use eWay-CRM procedure called dbo.EncodeToBase64 to code parameters into base64.

All calls must contain parameter with id. The value of this parameter must be GUID/UUID (128-bit number in hexadecimal form with 4 dashes). Null GUID is not permitted for id parameter.

The example of a call as described is:

http://server/eWay/Gate/username/aWQ9NzE0RUVCQkMtQkI3MC00MTJELTgzOEMtRTlFOTg2QzYxMEE0JmNvbG9yPXB1cnBsZQ==

This is call with those encrypted parameters:

id=714EEBBC-BB70-412D-838C-E9E986C610A4&color=purple

Color parameter can be specified as color or Color, because SQL ignore size of letters.

Mapped SQL procedure must return at least one row and one column. Text value of first row and first column (0 and 0 indexes) is returned as HTML contain. The rest is ignored.

Create Link to Document on Server

The requirement for creating functional links is that documents are stored on the SQL Server database and and not in the disk - see save documents.

Then you can use this command on server database:

SELECT 'https://web_service_address/Gate/doc/' + dbo.EncodeToBase64('id=0C803C29-3F12-11E9-BB42-001C4232EF18&revision=1')

 You need to change "web_service_address" to your web service address and value next to id= must be GUID of document you want to create link to. The revision parameter allows you to set on what revision of document the link will be created. The result of this command is:

https://web_service_address/Gate/doc/aWQ9MEM4MDNDMjktM0YxMi0xMUU5LUJCNDItMDAxQzQyMzJFRjE4JnJldmlzaW9uPTE=

Incorrect Calls

If the call does not contain all mandatory values or SQL runs with error or is using non-existing mapping, application returns error with 404 code. Diagnostics of the true cause must be done by calling the application from localhost. Call must go through loopback IP address. This can be helpful when you try to configure mapping correctly.

If the incorrect call is repeated, IP address will be temporarily blocked. For this period, the displayed error has 503 code. The list of blocked IP addresses can be flushed by restarting eWay-CRM Gate IIS application.

Security Warning

eWay-CRM Gate application is useful in combination with custom SQL procedures so different needs for public outputs can be realized. But there are some risks when you are using these outputs. If you set mapping in eWay-CRM Gate, the server database (the core of whole system) is opened to calls made by almost anyone, anytime. You still need to have this on your mind! Because of it, we do not recommend you to use eWay-CRM Gate to:

  • return information about more than one item in eWay-CRM (e.g. lists, reports, summarizations),
  • return values about fields and items that are restricted by some permissions in eWay-CRM,
  • return personal and sensitive data that are covered by GDPR,
  • change or erase data in eWay-CRM,
  • call procedures that uses transactions,
  • sent emails.

Important: eWay System s.r.o. does not and cannot take any responsibility for damages and data leaks that will be caused by incorrect use and configuration of eWay-CRM Gate application. User/customer bears responsibility for given eWay-CRM installation.