All content web service requests can be used without specifying a special product license for the users.
For integrations, this is the default. However, at least one EBIS End User license is required for use.

Examples of integrations that already use a special product license:

easy for Exchange
easy DMS
easy BC
These product licenses are activated for the customers who have purchased the above mentioned connections.


However, if special new product licenses are to be used for the web service requests, some things need to be implemented in the clients and integrations.


Preconditions

Three things are necessary to be able to use volume licences in client requests:

  1. a valid easy archive licence
  2. the product GUID representing the client product
  3. a crypted "clic" file

A "clic" file (with .clic file extension) contains configuration information mapping a product GUID to a specific licence part of the easy archive licence file and has to be present in EBIS (or EBIS plugin) configuration directory (configuration/license) at server startup. The easy archive licence file is usually necessary part of the easy archive configuration directory.

How the product GUID is used to actively request the use of a product licence in easy archive via content webservice request parameters is described (for developers) in the following paragraphs.

Requesting a challenge token

Before a Content Webservice request can be authorized to use a product licence, it is necessary to request a challenge response token from the EBIS Webservice by requesting the following URL:

Obtain a challenge response token

GET /apps/ebis/easyi/cr

The response consists only of a simple token string, e.g. 02ce78ad7f3cf43176a307c4133f55fdadea91bf.

Make sure to use the exact URI shown above. As this is not a Content Webservice URI, it does not start with api/content.

Encoding a product code using GUID and challenge token

The GUID is product specific and is provided alongside the "clic" file by EASY SOFTWARE licence management. GUID strings have to be prepared for use once in the following way:

  • remove all special characters like braces and dashes
  • convert uppercase characters to lowercase

A valid GUID string may look like this: c51840c8bd1a4b7797c8e14fb0d8094b and always has a length of 32 characters.

Now that both GUID and challenge are available, the product ID is created as follows:

  1. concatenate challenge token and GUID strings => 02ce78ad7f3cf43176a307c4133f55fdadea91bfc51840c8bd1a4b7797c8e14fb0d8094b
  2. build a SHA1 hash from that string and encode the result hexadecimal => cdb524d2e982b951620fb8e217a0a1f0e83250ab
  3. prepend challenge token and colon => 02ce78ad7f3cf43176a307c4133f55fdadea91bf:cdb524d2e982b951620fb8e217a0a1f0e83250ab

The resulting colon-separated string is used as product code in Content Webservice requests.

Prepare required HTTP header

When the product code is created from GUID and challenge token it has to be sent as HTTP header in the following way:

x-credential-cr-data: 02ce78ad7f3cf43176a307c4133f55fdadea91bf:cdb524d2e982b951620fb8e217a0a1f0e83250ab

That way the server will recognize the request as originating from a specific product and use a licence matching the product's GUID from the "clic" file.

The previously used x-credential-cr.data header is deprecated, but is still supported for backward compatibility.

When using product licenses, all HTTP header parameters of each request must be identical within a user session.

Session timeout

It is not necessary to create a new product code (and use a new challenge) for every new Content Webservice request. The created product code can be used until the session times out. When that happens, the server will respond with HTTP response code 401 (unauthorized). The request has to be sent again with a new product code.