Skip to main content
Documentation & User Guides | FotoWare

Episerver Addon for FotoWare: Installation, Configuration and Use

This Episerver Addon integrates Fotoware DAM with Episerver CMS and Commerce

The addon is available from the Episerver Nuget Feed (download links below)

Before you start

This article is technical in nature and stipulates knowledge of the Episerver ecosystem. We recommend getting the assistance of someone experienced with Episerver integrations to set up and configure the addon.

Example Image Property and selection dialog from FotoWare


Example TinyMce Toolbox button


How it works

When an asset is selected, the asset is imported into the default Episerver asset management repo and used in an image property (of type ContentReference or Url) or the Rich Text editor. There is also an Episerver scheduled job (to be enabled after installation) which ensures that the imported images and metadata are kept up to date in Episerver if they change in FotoWare.

Key features of the integration:

  1. Easy to add to Episerver solutions, both new solutions and existing ones
  2. The integration can be removed without affecting used assets
  3. Used assets from FotoWare are synchronized into Episerver's default asset management, making it easy for developers that know Episerver to get started
  4. It is possible to configure whether media show allows only local assets, assets from FotoWare or both
  5. It is possible for a developer to configure his own media models containing the metadata that should be synchronized with FotoWare
  6. Since downloaded media becomes standard Episerver media items, Episerver will keep track of which media is used where in the solution

**Please note**

Versions 1, 2 and 3 only support imports of static images like "jpgs". PDFs may work but is not meant to. Video, svgs and animated gifs are not currently supported.


Find it on : (external link)

Approximate time to install and configure the addon: less than 1 hour


  • This addon requires at least EPiServer.CMS.UI 11.15.
  • The addon also automatically adds support for Episerver Commerce and should work on version 12 and above
  • Version 2 of EPiServer.CMS.TinyMce is needed for toolbox button in editor

Registering the Selection Widget integration with FotoWare

Before you get started setting up the Episerver integration, you must register the application in the FotoWare Site Configuration: Log in to your FotoWare tenant and open the Tools menu (cogwheel) and choose Site configuration. The integration settings are found in the Integrations node, at Applications.

Click on Add application to set up the integration for the Selection Widget.

Type: Choose Web App / API. Then choose API using the radio button below.

Name: Name the application - for example Episerver integration

Redirect URIs: Here you set the URI that the user should be returned to after authentication is completed. The redirect URI is usually in the form:


Whether or not /episerver is part of the URL depends on how Episerver has been configured. The redirect URI should be set in the Operations Center settings above. Use small caps. In a multisite scenarion, one URL is needed per domain.

User consent: Use markdown syntax to add any custom information that should be displayed when the user uses the plugin for the first time. It's also possible to include a link to a privacy policy.

Access: This is used to control who has access to use the plugin.

Client ID / Client Secret: These values will be auto-generated when you hit the Save button. See screenshot below. Copy both values to a temporary location, such as a text file. You later have to add these to the Web.config file of the EpiServer plug-in, in FotoWare:ClientId and FotoWare:ClientSecret value fields. (See web.config section below.)
Once you have done this, you can delete the text file. If you lose the client secret, you can generate a new one and update the Web.config file.



Registering the Server-to-Server integration the Operations Center

Next, you will need to register a server-to-server authentication to complete the integration. This can be obtained in the FotoWare Site Configuration: Log in to your FotoWare tenant and open the Tools menu (cogwheel) and choose Site configuration. The integration settings are found in the Integrations node, at Applications.

Add a new application and set the Type to Non-interactive/script, as seen in the screenshot below.

Name the integration and click on Save to generate the Client Id and Client secret values. Copy them to a working document and insert them in the Episerver web.config file in the FotoWare:ServerApi:ClientId and FotoWare:ServerApi:ClientSecret value fields. (See below.)

Episerver Configuration

1. Web.config Application Settings:

    <!-- all this data to be obtained from FotoWare -->
    <!-- Documentation ClientId and Secret for Selection widget -->
        <add key="FotoWare:ClientId" value="[Enter your Fotoware guid]" />
        <add key="FotoWare:ClientSecret" value="[Enter your client secret string]" />
    <!-- Documentation for ServerApi ClientID and Secret -->
        <add key="FotoWare:ServerApi:ClientId" value="[Enter your Fotoware guid]" />
        <add key="FotoWare:ServerApi:ClientSecret" value="[Enter your client secret string]" />
    <!-- always*episerver* + /fotoware.plugins.episerver/authentication/callback  where *episerver* is depending on your configuration. CASE SENSITIVE, so use lower case  -->
        <add key="FotoWare:RedirectUri"  value="[A URL for your solution that needs to be defined in FotoWare. Can be different for different environments]" />
        <add key="FotoWare:TenantUrl" value="" />
    <!-- presets is used to predefine a width of an image to download, can be used with FotoWare:PreferredDownloadWidth. Presets are defined in FotoWare -->
        <add key="FotoWare:PresetUrl" value="/fotoweb/me/presets/export/[your preset's id]" />
    <!-- which asset folder to import images to -->
        <add key="FotoWare:RootFolderId" value="[Enter an id to a media folder in Episerver where you want downloaded assets, for instance 218]" />
    <!-- FotoWare:ApiToken has been removed, pls use ServerApi ClientID and Secret
        <add key="FotoWare:ApiToken" value="[Enter your API token string]" />-->
    <!-- these are optional -->
        <!-- EnableOnAllImages default is "true" -->
            <!--<add key="FotoWare:EnableOnAllImages" value="false"/>-->
        <!-- ExportWidgetEnableOnAllImages default is "true" -->
            <!--<add key="FotoWare:ExportWidgetEnableOnAllImages" value="false"/>-->
         <!-- Leave empty or remove unless you hav been told otherwise. Domain is not required in Episerver multisite solution,
            or /episserver/fotoware.plugins.episerver/authentication/callback
            where *episerver* is depending on your configuration. CASE SENSITIVE, so use LOWER CASE  -->

            <add key="FotoWare:RedirectUri"  value="[A URL for your solution that needs to be defined in FotoWare. Can be different for different environments]" />

         <!-- Optional: how often users need to login to FotoWare, in days. Default value is 14 days -->
            <add key="FotoWare:RefreshToken:ValidDays" value="14" />

        <!-- DisableEpiserverDefaultMediaSelector default is "false" -->
            <!--<add key="FotoWare:DisableEpiserverDefaultMediaSelector" value="true"/>-->

        <!-- <add key="FotoWare:AllowedTypes" value=".jpg,.jpeg,.jpe,.gif,.bmp,.png" />
            <add key="FotoWare:ArchiveUrlsToSynchronize" value="/fotoware/archives/5000-Archive,/fotoware/archives/5000-Archive-2" />
            <add key="FotoWare:PreferredDownloadWidth" value="0" /> --><-- PreferredDownloadWidth is important to be same or less than the preset's width to work, zero is default and will  take the default preset's width -->

It is also possible to implement and register an instance of the IFotoWareSettings (or extended IFotoWareCommerceSettings) interface to take full control of all settings, for instance configuring which metadata to synchronize.

Also in web.config

Upon installation, the profile store needs to add "FotoWareData", used for storing user specific FotoWare data. Be sure it is there.

<profile defaultProvider="x">
        <add name="FotoWareData" type="System.String" /> 

2. Configuring additional settings

You need to implement the IFotoWareMedia interface on a content type that inherits from Episerver's ImageData class in your solution. This will enable some additional fields which is used by the addon to keep the assets in sync with the original in FotoWare.

public class ImageFile : ImageData,  IFotoWareMedia
    public virtual string FotoWareUrl { get; set; } //Link back to Fotoware

    public virtual DateTime FotoWareModifiedDate { get; set; } //for sync job to work

The FotoWareModifiedDate property is used to keep track of when the asset was last changed in FotoWare. It should be noted that an update to an asset's metadata in FotoWare adds 2 seconds to the modified date, and therefore we need to keep track of this date and time.

3. Add to your Tiny MCE configuration toolbar

The button should be plugged into Tiny MCE automatically. If it doesn't show up, you probably already have a custom config. Search for TinyMceInitialization in your solution and add: **fotoware-insert-media** to your toolbar, you may need to put a module dependency to [ModuleDependency(typeof(FotoWare.plugins.Episerver.Tinymce.TinyMceModule))] so that your custom config runs last.

4. Decorate your Episerver Property with the FotoWare UIHint

The below code should be added to the Model object in the types of pages where you plan to use the FotoWare Addon. 

//FotoWareUiHint.FotoWareImage only for ContentReference type
public virtual ContentReference ImageAsContentReference { get; set; }

//FotoWareUiHint.FotoWareImageUrl only for Episerver.Url type
public virtual Url ImageAsUrl { get; set; }

[UIHint(FotoWareUiHint.FotoWareXhtmlString)] //Introduced in version 3.5, it is not mandatory, but needed in some solutions
public virtual XhtmlString MainBody { get; set; }

This will replace Episerver's built in Image editor with an extended one that supports selecting images from FotoWare as well as local Episerver images.

To disable being able to select local images in Episerver you can add another attribute to your property:

*** NOTE: FotowareConfigurationAttribute** is introduced in version 2. ***
`[FotowareConfiguration(DisableDefaultEpiserverMedia = true, ExportWidgetEnabled = WidgetStatus.Disabled, /* only with XhtmlString, will use the export url from fotoware direct, instead of downloading the asset to Episerver */ UseExportUrlOnly = false, QueryParameters = "crop=false&enhance=false&caption=false&action=false&publication=false&behaviour=false")]`

This attribute should be used in combination with FotoWareUiHint. Parameters documented here: Using the widgets

** NOTE: Below parameter is removed in version 2:**
`[UIHint(FotoWareUiHint.DisableDefaultEpiserverMedia)]  //please use FotoWareConfigurationAttribute`

If your solution uses custom **XhtmlStringEditorDescriptor**, please inherit of FotowareXhtmlStringEditorDescriptor instead and always start with base.ModifyMetadata(metadata, attributes);

5. Scheduled jobs

There are 2 jobs:

Fotoware - Synchronize assets
Normally enabled if you want to sync updates from FotoWare to Episerver. This job will only update assets if it's been updated in FotoWare.

Fotoware - Synchronize assets - Force
Same as above but will always download the latest image and metadata. Only to be run manually if needed.

You may turn on/off scheduled jobs or run them manually in in Admin/config tab/module management/Fotoware.EpiserverAddon/overview in Episerver.

6. Synchronizing metadata from FotoWare to Episerver

The addon supports synchronizing metadata between FotoWare and Episerver through a mapping schema that is defined in your implementation of the IFotoWareSettings interface. Implement your own IFotoWareSettings and define the mapping schema for metadata that you want to get into the Episerver assets. It should be noted that there is a number of default metadata in FotoWare but this can be extended for each client.

Note: The export widget will work without a Server API License but will then not synchronize metadata; instead the image will only be download to Episerver.

The default mapping schema is set up as follows:

MetadataConfiguration = new NameValueCollection
    {"5", "Name"},
    {"25", "Keywords"},
    {"80", "Photographers"},
    {"116", "Copyright"},
    {"120", "Description"}

The mapping schema has keys that match the metadata name in FotoWare and the value is the property name in Episerver. Notice that the types need to be the same when changing the configuration; for instance Photographers is a list of strings.

The following example shows how to add a custom metadata to the synchronization:

MetadataConfiguration = new NameValueCollection
    {"5", "Name"},
    {"25", "Keywords"},
    {"80", "Photographers"},
    {"116", "Copyright"},
    {"120", "Description"},
    {"998", "EpiserverCustomProp"} // set on imagetype


7. Controlling the structure of downloaded assets in Episerver [Optional]


Since FotoWare stores assets in a flat list and Episerver uses a hierarchical structure, assets imported to Episerver is put in a folder structure to help browsing through the imported assets as well as avoiding long list of assets in the same folder which Episerver does not handle in a good way. It is possible to control how the folder structure for assets in Episerver is done. By default, folders are created based on the year and month that the asset was imported into Episerver, but you could use other structures, for instance based on metadata in the solution.

This is done by implementing the IFolderResolver interface.

8. Customize Tiny MCE html template [Optional]

You have the possibility to implement your own input html when inserting in Tiny Mce, for example filling the alt-text or adding some css classes.

This is done by implementing and registering an implementation of IFotoWareTinyMceTemplateResolver where you override GetHtml(ContentReference contentReference, string insertingToContentReference=null)

9. Event handling with FotoWare events

Available events are

  • OnImageDownloading: Raised before downloading an asset with the possibility to cancel the action.
  • OnImageDownloaded: Raised after the asset has been downloaded.
  • OnImageDeleted: Raised in the synchronization job when an asset is deleted or revoked in FotoWare.

Example of how to register event handlers for these events in an IInitializableModule:

public void Initialize(InitializationEngine context)
   var events = context.Locate.Advanced.GetInstance<FotoWareEvents>();
   events.OnImageDownloaded += FotoWareHttpClientOnImageDownloaded;
   events.OnImageDownloading += EventsOnOnImageDownloading;
   events.OnImageDeleted += FotoWareHttpClient_FotoWareImageDeleted;

10. Disabling FotoWare plugin in Episerver Commerce Asset list

Implement and register IFotoWareCommerceSettings.PreventCommerceEditorIntegration
By default it is enabled.

11. Logging FotoWare.plugins.Episerver

The addon has a number of logging information that can be used for information and debugging the integration. Add this to EpiserverLog.config or your log4net config:

<logger name="FotoWare.plugins.Episerver" additivity="true">
  <level value="Info" />

12. Extras: Code Samples

In the nuget package under tools, you'll find some code samples of IFolderResolver, IFotoWareSettings and IFotoWareTinyMceTemplateResolver implementations as well as additional scheduled jobs for synchronization of entire archives from FotoWare.

The additional code is available under this folder after you install the Nuget package:
[Your site root]\packages\FotoWare.plugins.Episerver.\tools\extras

13. Troubleshooting

Make sure you enable logging (see point 11 above) to troubleshoot the plugin.

14. Multi-site Configuration

Starting with version 3.5 you can have different FotoWare instances for different sites in Episerver. Please implement the IFotoWareConfig interface.

Example: Foreach site

    public class ExampleFotoWareSite1Config : IFotoWareConfig
        public IFotoWareSettings Settings => new ExampleSiteOneFotoWareSettings();//implement a contrate IFotoWareSettings with all settings

        public Guid SiteId => new Guid("b1c98de6-afbd-433c-bbde-97f873edbb12");//Change this from Episerver / admin / config / websites

A fallback will be made to the default IFotoWareSettings set globally if not siteid is found.

An example can also be found in Extras / Code Samples above

15. Known issues

  • Error message: "An error occurred when sending the request "

This is probably due to the handshake with the endpoint not working. Try to add 'ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12;' in Global appstart.

  • Important: Callback url is case sensitive. Please check your url. Best practice, use lower case. 

16. Change log

## - may 2021

#3799 Use Export Url direct in WYSIWYG, without downloading the asset in Episerver


## - apr 2021

#3632 Multisite configuration - you can now have different FotoWare instances per site in Episerver

#2985 FotoWare login token expiry (default 14 days)


## - mar 2021

#3634 [BUG] Cookie is set as httpOnly from web.config <httpCookies httpOnlyCookies="true" requireSSL="true" />,
javascript cant read, popup opens and closes several times

## - nov 2020

[Breaking] FotoWare:ApiToken in appsetting is now removed and replaced with FotoWare:ServerApi:ClientId and FotoWare:ServerApi:ClientSecret.

#1749 Use Oauth server to server api authentication

#2926 You can now run the plugin with Export Widget without Server APi License, then the asset is transferred but not the metadata.

## - nov 06, 2020

Last version with FotoWare:ApiToken configuration. Version 3 introduces Oauth server to server authentication

#392 [BUG] Image property is not updated in Episerver. Change the window dialog popup against Episerver javascript modal window.

#2967 [BUG] Server error not showing if custom errorpage is enabled on server

### - June 07, 2020
[BUG] Images like PSD, is saved with psd in name, but should save as export format (jpg)
[BUG] Tinymce is always opening ExportWidget diregarding config
[BUG] TemplateResolver for TinyMce was not triggered

### - June 01, 2020

Images like PSD are saved with psd in name, but should save as export format (jpg)

### - May 15, 2020

Accesstoken not fetched caused loop
Images with åäö not working
cookie login user specific

### - Jan 10, 2020

Support for Export Widget
New - FotowareConfigurationAttribute

### - Oct 20, 2019

Bug fixes and better logging

### - Jun 10, 2019

Initial release

  • Was this article helpful?