Sana Connector 3.0 - Image Cache

When Sana Requests products, it does so, either because index is being rebuilt or (more often) because some products are flagged by either the ERP-system or Perfion as “have been updated since last update”.

For updated products Sana will do the following

1. Sana will hereafter call “GetProducts” to retrieve product data
2. Sana will call “GetProductImages” to retrieve any images on these products
3. Finally Sana will for each image returned by GetProductImages call GetProductImageFile to retrieve each individual image.

Usually that will work well. Although for installations with many images and/or many changes to products, this way of retrieving images will put too much load on Sana. And often this load would be unnecessary, since usually image data will be rather static while product data is more subject to change. To put it more simple. Let us say you have a product in you ERP, which also is in Perfion. Let us further say it has 8 images. Changing the title of that product will cause the images to be shipped (again) to Sana.

This is where the image cache in the connector comes in. It is really not a cache containing images. Rather it is a cache that remembers which images are sent to Sana (and when) and uses that to decide when a “GetProductImages”-call comes from Sana whether to return the images to Sana or to drop at least some of them, since they have not changed since last time Sana asked.

It basically works like this:

1. When Sana calls GetProductImages first time the cache does nothing (since it is empty)
2. When Sana call GetProductImageFile the cache remembers that this image was sent, for some product/variant combination in some Sana Store.
3. When Sana later calls GetProductImages (for example because the product or one of its variants were modified) the images already sent will not be returned. Only modified or added images (not cached yet) will be returned. Hereby Sana avoids unnecessary calls to GetProductImageFile for images already fetched.

Enabling the Image Cache

This is simply done in settings. Simply toggle the “Enable Image Cache” on as shown in Figure 1 below:

The Image Life Time can be safely set to 0, meaning that an Image will live forever in the cache.

The content in the cache is persisted using the FileSystem-API provided by Sana every 5^th minute meaning that the Image Cache will survive a recycle of IIS or even restart of the server, although content will be up to 5 minutes old.

The Image Cache can be accessed in the Debug Erp-request windows. The connector supports four operations GetPerfionImageCache, ClearPerfionImageCache, PersistPerfionImageCache and GetPerfionImageCacheFile. These four operations can simply be called just like any other “native” Sana-operation as shown in Figure 2:

GetPerfionImageCache

The GetPerfionImageCache simply shows the current contents of the cache. It supports two parameters:

• WebsiteId: Here you must supply the name of a SanaStore or a “*” meaning you are interested in all stores.

• ProductIds: This is optional. If you only are interested in a few products, these may be supplied using this parameter.

A sample query could look like the following:

<Request>
  <Operation>GetPerfionImageCache</Operation>
  <Params>
    <WebsiteId>AllisonNav</WebsiteId>
  </Params>
</Request>

Showing cache content for the WebsiteId “AllisonNav” (all images cached on all products).

If we instead would like to see whether two products numbered “A” and “B” across all websites we would write:

<Request>
  <Operation>GetPerfionImageCache</Operation>
  <Params>
    <WebsiteId>*</WebsiteId>
    <ProductIds>
      <ProductId>A</ProductId>
      <ProductId>B</ProductId>
    </ProductIds>
  </Params>
</Request>

Notice the * supplied as WebsiteId meaning “All channels”.

ClearPerfionImageCache

The ClearPerfionImageCache operation allows you to delete part of the content of the cache or clear it entirely.

It supports the same two parameters as GetPerfionImageCache:

• WebsiteId: Here you must supply the name of a Website/Sana store or a “*” meaning you want to delete content across all stores.

• ProductIds: This is optional. Here you may supply supply one or more Ids of products that should be deleted from cache. If no product ids are supplied the entire cache will be deleted (for all applicable Sana Stores)

The operation returns the deleted image cache entries.

The operation:

<Request>
  <Operation>ClearPerfionImageCache</Operation>
  <Params>
    <WebsiteId>AllisonNav</WebsiteId>
  </Params>
</Request>

Will delete everything cached for AllisonNav. If only one image was cached for that store the result would look like:

<Response>
  <Result>
    <Channel name="AllisonNav">
      <Images>
        <Image>
          <ProductId>1923-16</ProductId>
          <VariantId></VariantId>
          <ImageName>144b5e36-0ba2-4dc8-8e66-b88058ecea29__coffee-beans-lifestyle.jpg</ImageName>
        </Image>
      </Images>
    </Channel>
  </Result>
</Response>

PersistPerfionImageCache

The PersistPerfionImageCache-operation allows you to save the current content of the cache to disc. This is usually not needed since it is done automatically every 5 minutes as part of any request hitting Sana.

The operation does not take any parameters:

<Request>
  <Operation>PersistPerfionImageCache</Operation>
  <Params />
</Request>

Note that an empty Params-element needs to be added, otherwise Sana never responds.

The response will be a simple OK if successful:

<Response>
  <Result>
    <PersistPerfionImageCache>OK</PersistPerfionImageCache>
  </Result>
</Response>

GetPerfionImageCacheFile

This method was added in Sana Connector 3.0.4. The Image Cache file could get corrupted meaning that it contained invalid Xml and would hereby not work. In fact the 3.0.3 connector would stop returning images in GetProductImages.

To avoid this issue three steps were taken:

• If the Connector Failed to load a ImageCache-file it would be backed up and cache was started empty.

• A method named GetPerfionImageCacheFile

This method allows you to check the content of the cached image file. The request here will make a check:

<Request>
  <Operation>GetPerfionImageCacheFile</Operation>
  <Params />
</Request>

 And return the following:

<Response>
  <Result>
    <FileName>ImageCache.xml</FileName>
    <FileExists>1</FileExists>
    <FileSize>3528</FileSize>
    <TimeReadingFile>0,0010023 s</TimeReadingFile>
    <ExceptionReadingFile>(None)</ExceptionReadingFile>
    <TimeParsingFile>0 s</TimeParsingFile>
    <ExceptionParsingFileContentAsXml>(None)</ExceptionParsingFileContentAsXml>
  </Result>
</Response>

Here you get information on the file, whether it exists, its size and whether it could be read (and an exception if not) and interpreted as Xml and how long this takes.

If you supply the parameter “IncludeContentAsCData” as shown below, it will even show you its content (result not shown).

<Request>
  <Operation>GetPerfionImageCacheFile</Operation>
  <Params>
    <IncludeContentAsCData>1</IncludeContentAsCData>
    <RemoveTimeStamps>1</RemoveTimeStamps>
  </Params>
</Request>

Example

Let us take a look at how the Image Cache works. After enabling the cache try the following query (adapted to use an id of a product in your setup):

<Request>
  <Operation>GetProductImages</Operation>
  <Params>
    <WebsiteId>AllisonNav</WebsiteId>
    <Filter>
      <for field="Id">
        <Equal>1923-16</Equal>
      </for>
    </Filter>
  </Params>
</Request>

This results in the following, since product 1923-16 has 3 images.

<Response>
  <Result>
    <ProductImage>
      <field name="ProductId" value="1923-16" />
      <field name="VariantId" value="" />
      <field name="ImageName" value="fa1550bb-4f2d-4757-9eaa-52404dcb95a6__1923-16.jpg" />
    </ProductImage>
    <ProductImage>
      <field name="ProductId" value="1923-16" />
      <field name="VariantId" value="" />
      <field name="ImageName" value="144b5e36-0ba2-4dc8-8e66-b88058ecea29__coffee-beans-lifestyle.jpg" />
    </ProductImage>
    <ProductImage>
      <field name="ProductId" value="1923-16" />
      <field name="VariantId" value="" />
      <field name="ImageName" value="6abf4cec-1a0b-4558-9a2b-04a9f359460c__french-press-lifestyle.jpg" />
    </ProductImage>
  </Result>
</Response>

Remember that GetProductImages does not affect the cache but is only affected by it. Since we started with an empty cache all 3 images are returned to Sana.

In order to add an image to cache, we need to call GetProductImageFile. It looks like this:

<Request>
  <Operation>GetProductImageFile</Operation>
  <Params>
    <WebsiteId>AllisonNav</WebsiteId>
    <ProductId>1923-16</ProductId>
    <VariantId></VariantId>
    <ImageName>144b5e36-0ba2-4dc8-8e66-b88058ecea29__coffee-beans-lifestyle.jpg</ImageName>
  </Params>
</Request>

With an enabled cache this operation will, in addition to return the image, also remember that this image was returned.

Now calling GetProductImages-operation again (in the exact same way as before) we get a different result:

<Response>
  <Result>
    <ProductImage>
      <field name="ProductId" value="1923-16" />
      <field name="VariantId" value="" />
      <field name="ImageName" value="fa1550bb-4f2d-4757-9eaa-52404dcb95a6__1923-16.jpg" />
    </ProductImage>
    <!--Image '144b5e36-0ba2-4dc8-8e66-b88058ecea29__coffee-beans-lifestyle.jpg' removed for ProductId '1923-16' and VariantId '' by Image Cache -->
    <ProductImage>
      <field name="ProductId" value="1923-16" />
      <field name="VariantId" value="" />
      <field name="ImageName" value="6abf4cec-1a0b-4558-9a2b-04a9f359460c__french-press-lifestyle.jpg" />
    </ProductImage>
  </Result>
</Response>

Notice how the cached image will be commented out in the result.

ith an image in the cache you can use GetPerfionImageCache-operation to check that indeed an image is in the cache. It gives the following result:

<Response>
  <Result>
    <!-- ======================== -->
    <!--         Settings         -->
    <!-- ======================== -->
    <!--  - Enabled: Yes          -->
    <!--  - Lifetime: No expiry   -->
    <!-- ======================== -->
    <!--        Statistics        -->
    <!-- ======================== -->
    <!--  - Websites:         1   -->
    <!--  - Products:         1   -->
    <!--  - Images:           1   -->
    <!-- ======================== -->
    <Channel name="AllisonNav">
      <Images>
        <Image datetime="2019-08-13T13:48:51">
          <ProductId>1923-16</ProductId>
          <VariantId></VariantId>
          <ImageName>144b5e36-0ba2-4dc8-8e66-b88058ecea29__coffee-beans-lifestyle.jpg</ImageName>
        </Image>
      </Images>
    </Channel>
  </Result>
</Response>

Troubleshooting

If you for some reason thinks that the Image Cache has forgotten (or lost) it’s content. It may be due to a corrupt ImageCache-file. If you run “on-premise” you can check the folder ..\@data\packages-data\Perfion and see whether there are any backup-files. Usually they will contain invalid xml and have therefore been backed up and a fresh empty cache file has been created in its place.

In case a backup is taken often, please contact Sana Support or Perfion Support.

Final remark regarding disabling the cache

When cache is disabled it first and foremost mean two things:

1. No more images are cached. This means that calls to GetProductImageFile-operations will not add anything to cache.
2. Images will not be removed from GetProductImages due to an image being in cache.

What, however, is not affected is the persisted Image Cache-file. It will, for example, not be emptied or deleted, meaning that you can disable the cache and re-enable it without losing its content. The GetPerfionImage-operation will also still work on a disabled cache showing its now rather static content. Even PersistPerfionImageCache-operation will work.