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

clipboard_ed70c62b16dacf32f318e9976975fa46c.png

Example TinyMce Toolbox button

clipboard_e6317c2270b46b6cc439ed5a486a5e664.png

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

Installation

Find it on Nuget.episerver.com : http://nuget.episerver.com/en/OtherPages/Package/?packageId=FotoWare.PlugIns.Episerver

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

Dependencies

  • 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 integration with FotoWare

Important: The below procedure involves obtaining configuration settings from the Operations Center.
If you are running FotoWare SaaS, you need to get the assistance of your FotoWare Partner or contact FotoWare Support directly 
to obtain these settings.

Before you get started setting up the Episerver integration, you must register the application in the FotoWare Operations Center. You find the settings on the Settings tab, under Services - Applications, as seen in the screenshot below:

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

Name: Name the application - for example Episerver integration

Client ID / Client Secret: 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. 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.

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:

domain.com/*episerver*/FotoWare.PlugIns.Episerver/Authentication/callback

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, and must be included in the Episerver web.config file (see below).

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.

Save the settings and proceed as described below.

Obtaining the FotoWeb API key in the Operations Center

You will also need the FotoWeb API key to successfully set up the integration. This can be obtained in the Operations Center: Go to the Settings tab, expand the Behavior node and choose Authentication, where the API key is shown at the top. This value should be inserted in the Episerver web.config file in the ApiToken key.

Episerver Configuration

1. Web.config Application Settings:

<appSettings>
    <!-- all these data is to be obtained from FotoWare -->
    <add key="FotoWare:ClientId" value="[Enter your FotoWare guid]" />
    <add key="FotoWare:ClientSecret" value="[Enter your client secret string]" />
    <!-- always domain.com/*episerver* + /FotoWare.PlugIns.Episerver/Authentication/callback  where *episerver* is depending your configuration -->
    <add key="FotoWare:RedirectUri"  value="[An URL for your solution that needs to be defined in FotoWare. Can be different for different environments]" />
    <add key="FotoWare:TenantUrl" value="https://my.fotoware.cloud" />
    <add key="FotoWare:ApiToken" value="[Enter your API token string]" />
    <add key="FotoWare:PresetUrl" value="/fotoweb/me/presets/export/5cc307637c958c34d84dd555" />
    <!-- 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]" />

    <!-- these are optional -->
    <!-- EnableOnAllImages default is "true" -->
    <!--<add key="FotoWare:EnableOnAllImages" value="false"/>-->
    <!-- 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="1400" />-->

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">
    <properties>
        <add name="FotoWareData" type="System.String" /> 
           ...
    </properties>
        ...
</profile>

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
{ 
    [Editable(false)]
    public virtual string FotoWareUrl { get; set; } //Link back to Fotoware

    [Editable(false)]
    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
[UIHint(FotoWareUiHint.FotoWareImage)]
public virtual ContentReference ImageAsContentReference { get; set; }

//FotoWareUiHint.FotoWareImageUrl only for Episerver.Url type
[UIHint(FotoWareUiHint.FotoWareImageUrl)]
public virtual Url ImageAsUrl { 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 ui hint to your property:

[UIHint(FotoWareUiHint.DisableDefaultEpiserverMedia)]  //important put last in order

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.

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" />
</logger>

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.1.0.1.0\tools\extras

13. Troubleshooting

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

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.

  • Was this article helpful?