Install the Optimizely integration (version 12)

The integration gives web editors direct access to files and folders from Mediaflow inside the Optimizely 12 interface and allows them to embed images in on-page editing, blocks or the text editor (TinyMCE). It also makes it possible to embed video from Mediaflow using Mediaflow's media player. 

The integration connects directly between the Optimizely 12 web server and the Mediaflow servers, meaning that files do not need to be downloaded locally first when images are mounted.

Good to know

For performance and stability, mounted images are always copied to the web server (under "For this site" or "For all sites" in Optimizely 12). Your website is therefore not dependent on Mediaflow, and the integration does not affect the performance of normal page views. All mounted images remain in Optimizely, and no changes to the website are required if you uninstall the integration.

System requirements

Check that the environment meets the following requirements before installing:

• .NET 8 (net8.0)
• Optimizely CMS 12 – compatible with EPiServer.CMS.UI.Core version 12.17.1 or later (under version 13)
• A Mediaflow account with at least one server key configured
• Permission to add NuGet packages and modify the website's configuration (appsettings.json, Startup.cs or Program.cs)

The integration works both with self-hosted Optimizely CMS 12 and with Optimizely DXP. Sign-in with Opti ID is supported from version 1.2.5; see Opti ID (SSO). For DXP-specific configuration (secrets, environment transformation, deployment), see the Install on Optimizely DXP section below.

The integration is distributed as the Mediaflow.Optimizely NuGet package on Optimizely's NuGet feed.

Settings in Mediaflow

The integration can be used as soon as it has been installed. However, for files to be available and usable in the best possible way, administrators must first prepare the settings in Mediaflow.

Each server key is a Mediaflow OAuth refresh token. You retrieve it in Mediaflow under Settings > Integrations > EPiServer/Optimizely – the key is in the Refresh token field. The key determines which Mediaflow resources the user can access. With virtual role mapping (recommended), you can assign different keys to different editor groups.

You need the appropriate permissions to view the integration settings. If they are not available, you can enter super-admin mode or contact a Mediaflow administrator in your organisation.

Install the integration

Step 1 – Add the NuGet feed and find the package

Mediaflow's integration is installed as a standard NuGet package. Optimizely has its own NuGet feed, which must be added for the package to be found. Instructions are available here: https://nuget.optimizely.com/feed/

Once the feed has been added, you can search for the integration in Visual Studio using Mediaflow.Optimizely. More information and the latest version are available on Optimizely's package page: https://nuget.optimizely.com/packages/mediaflow.optimizely/

Step 2 – Install the NuGet package

Use Optimizely's standard NuGet installation, or install it from the command line:

dotnet add package Mediaflow.Optimizely --version [desired version]

Step 3 – Configure appsettings.json

All configuration is performed in appsettings.json and in Startup.cs (or Program.cs). Add a Mediaflow section to appsettings.json with your server key and the optional settings you want to customise.

{
  "Mediaflow": {
    "EnableMediaLibraryUpload": true,
    "LimitEmbedType": "javascript",
    "ForceAltText": true,
    "SaveLocation": "page",
    "VirtualRoleMapping": [
      {
        "VirtualRole": "*",
        "ServerKey": "<your-mediaflow-server-key>"
      }
    ]
  }
}

Settings reference

Key and ServerKey

The ServerKey value in VirtualRoleMapping is your Mediaflow OAuth refresh token. Mediaflow recommends using VirtualRoleMapping with a "*" row for a shared key, or separate rows per role when you need to segment content (see Segment content with role mapping).

SaveLocation

Controls where images are saved in Optimizely's media section. Note that images are always copied to the web server regardless of the choice.

Step 4 – Register the integration in Startup.cs

Two registration calls are mandatory: AddMediaflow() and UseMediaflow(). The admin page /mediaflow/settings is precompiled and does not require Razor runtime compilation. Add AddMediaflowViews() if the website uses Mediaflow's bundled display templates – this is recommended if you use TinyMCE, as the display template keeps the alt text, description and photographer of images updated on the published page. Add them in Startup.cs or the equivalent in your Program.cs.

ConfigureServices

Choose the option that suits your website.

Minimum registration

using EPiServer.Cms.TinyMce.Core;
using Mediaflow.Optimizely;

public void ConfigureServices(IServiceCollection services)
{
    services
        .AddCms()
        // ... other Optimizely services ...
        .AddMediaflow();

    // Optional: bundled display templates (recommended with TinyMCE)
    // services.AddCms().AddMediaflow().AddMediaflowViews();

    // Optional: enable the Mediaflow button in TinyMCE (see article 2)
}

Option B – the website already enables Razor runtime compilation

Keep your existing call and add Mediaflow's view support after it (only applies if you use the display templates):

using EPiServer.Cms.TinyMce.Core;
using Mediaflow.Optimizely;

public void ConfigureServices(IServiceCollection services)
{
    services
        .AddCms()
        // ... other Optimizely services ...
        .AddMediaflow();

    services.AddControllersWithViews().AddRazorRuntimeCompilation();

    // Mediaflow support for display templates – after runtime compilation!
    services.AddMediaflowViews();
}

Configure (request pipeline)

Add UseMediaflow() after UseAuthorization() and before UseEndpoints():

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    app.UseStaticFiles();
    app.UseRouting();
    app.UseAuthentication();
    app.UseAuthorization();

    app.UseMediaflow();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapContent();
    });
}

What each call does

Step 5 – Set permissions

Mediaflow is not open to all groups in Optimizely, in order to limit access and prevent unauthorised use of Mediaflow.

Permitted groups are CmsEditors, CmsAdmins, WebEditors, WebAdmins, Administrators and the Mediaflow group, which you can create and add members to in order to grant them access.

The add-on looks up a Mediaflow server key for the current user via VirtualRoleMapping. If no mapping matches, the fallback key Key is used for users in the roles above. If neither a mapping nor Key exists, the user cannot authenticate with Mediaflow. The user must always be signed in to the CMS – even with a "*" row.

If the website uses Opti ID: map to CmsEditors and CmsAdmins (or "*") instead of the older WebAdmins/WebEditors roles. Custom roles in VirtualRoleMapping must exist in Opti ID Admin Center (or your IdP) and be synchronised to the CMS at sign-in. If you map CMS virtual roles, set SupportsClaims: true for them in appsettings.json.

Make sure that editors who are to use the selector belong to a role with a matching VirtualRoleMapping row, or add them to the Mediaflow group and configure a suitable key.

Segment content with role mapping (optional)

By default, all users in Optimizely 12 have access to the same shared content when images are mounted – unless virtual role mapping is configured. If you have several editor groups working with different parts of the website, you can segment the content so that groups have access to different Mediaflow folders. This is done using Optimizely's Virtual Role and VirtualRoleMapping in appsettings.json.

Note: Segmentation in this way requires a unique server key in Mediaflow for each group. This may involve a cost depending on your agreement.

"Mediaflow": {
  "VirtualRoleMapping": [
    { "VirtualRole": "CmsAdmins",  "ServerKey": "ZZXXCCVVBB" },
    { "VirtualRole": "CmsEditors", "ServerKey": "AABBCCDDEE" },
    { "VirtualRole": "*",          "ServerKey": "QQWWEERRTT" }
  ]
}

The add-on checks role membership in list order and uses the first matching row. Place specific roles before the wildcard "*".

Opti ID (SSO)

From version 1.2.5, the integration works on websites that sign editors in with Opti ID. AddMediaflow() detects the Opti ID scheme and adds it to Mediaflow's authorisation policies. The order of AddMediaflow() and AddOptimizelyIdentity() does not matter, and no additional Mediaflow configuration is required.

services.AddOptimizelyIdentity(useAsDefault: false);
services.AddMediaflow();

With useAsDefault: false, the policies accept both an Opti ID session and a session from the website's standard sign-in (for example ASP.NET Identity).

Custom policies (optional). If you want to control roles or schemes yourself, you can provide custom policies. Policies under Constants.AdminPolicy and Constants.EditorsPolicy are not overwritten. Specify all schemes that should be accepted – if you specify only one, the others are ignored.

services.AddMediaflow(authorization =>
{
    authorization.AddPolicy(Constants.AdminPolicy, policy =>
    {
        policy.AddAuthenticationSchemes(OptimizelyIdentityDefaults.SchemeName);
        policy.RequireRole("CmsAdmins");
    });
});

Cookies. Opti ID cookies (prefix oid-) require SameSite=None and Secure. A site-wide cookie policy with Lax or Strict causes Mediaflow to see the user as signed out and respond with 401. Adjust the cookie policy on the website (see Troubleshooting).

Install on Optimizely DXP

If your Optimizely CMS 12 website runs on Optimizely DXP, the add-on itself is the same NuGet package and uses the same code registration as a self-hosted website. Follow steps 1–4 above. The differences concern how you configure secrets per environment, deploy the code package and ensure outbound network access.

Include the package in the code package

Add Mediaflow.Optimizely as a standard NuGet reference in your CMS project. When you build and publish a DXP code package (.cms.app.*.nupkg), the add-on is included automatically. Deploy via your normal DXP flow (Integration → Preproduction → Production). No separate DXP-specific package or module upload is required.

Configure settings per environment

DXP applies environment-specific configuration via transform files (appsettings.Integration.json, appsettings.Preproduction.json, appsettings.Production.json) that override values in appsettings.json during deployment.

Put non-secret Mediaflow settings in the appropriate transform file – for example, SaveLocation, ForceAltText, LimitEmbedType and the structure for VirtualRoleMapping (role names without keys):

{
  "Mediaflow": {
    "EnableMediaLibraryUpload": true,
    "LimitEmbedType": "javascript",
    "ForceAltText": true,
    "SaveLocation": "page",
    "VirtualRoleMapping": [
      { "VirtualRole": "*", "ServerKey": "" }
    ]
  }
}

Leave ServerKey empty in version control and fill in the actual values via DXP App Settings (see below). See Configuring environments in Optimizely DXP.

Store server keys as secrets

Mediaflow's server keys are OAuth refresh tokens and must be treated as secrets. If you use version control, exclude this information.

On DXP, add them via PaaS portal → App Settings for each environment. The settings are applied at the next deployment. See Manage app settings in Optimizely DXP.

Simplest – one server key:

Role mapping – override individual keys:

Define the VirtualRole names in the transform file; override only the ServerKey values in the PaaS portal. App Settings take precedence over appsettings.json and transform files.

Startup registration on DXP

Use the same registration as for any CMS 12 website. If your DXP solution already calls AddCmsCloudPlatformSupport(), keep it – it does not replace the Mediaflow registration. Both are required:

services
    .AddCms()
    // ... other Optimizely services ...
    .AddMediaflow();   // + .AddMediaflowViews() if needed, see step 4

if (!env.IsDevelopment())
{
    services.AddCmsCloudPlatformSupport(configuration);
}

Also add app.UseMediaflow() to the request pipeline as in step 4. Many DXP projects already have Razor runtime compilation – in that case, use Option B in step 4 if you add the display templates. If the DXP solution uses Opti ID, see Opti ID (SSO).

Outbound network access

The CMS application server must reach Mediaflow over HTTPS for authentication and file operations:

• accounts.mediaflow.com – OAuth token calls
• api.mediaflow.com – Mediaflow API

Editors' browsers also load the selector's resources from mfstatic.com and may retrieve thumbnails from m.mediaflow.com. These are client requests and are not blocked by DXP's server network, but ad blockers or corporate proxies on client computers may interfere.

If the selector does not load or uploads fail with authentication errors on DXP but work locally: confirm with Optimizely Support or your network team that outbound traffic to the endpoints above is permitted from the CMS App Service.

Admin settings and databases

The built-in admin interface at /mediaflow/settings stores overrides in Optimizely's Dynamic Data Store, which is located in the environment's SQL database. Settings changed in Integration are not transferred to Production – configure each environment separately, or use App Settings and transform files for a consistent baseline per environment.

Verify the installation

After restarting the website:

1. Open the browser's developer console while signed in to the CMS. Confirm that there are no 404 errors for paths under /EPiServer/Mediaflow.Optimizely/.
2. Sign in as a CMS editor and open a page with a Mediaflow property or a TinyMCE field. Confirm that the Mediaflow selector or button is displayed.
3. As an administrator (CmsAdmins, WebAdmins or Administrators – also via Opti ID), open /mediaflow/settings and confirm that the admin page loads. Here you can override ForceAltText, VirtualRoleMapping and FileTypeFilter at runtime; saved values take precedence over appsettings.json.
4. Opti ID: sign in via Opti ID and open the Mediaflow selector. If /api/mediaflow/settings responds with 401 for a signed-in user, see Troubleshooting.

Upgrade from an older version

When upgrading from 1.1.x to 1.2.x: rebuild Optimizely's link database or resave content that uses Mediaflow properties after the upgrade. Version 1.2.x tracks content references (soft links) for Mediaflow properties, which powers Optimizely's References view. Existing content is not indexed automatically until the link database has been rebuilt or the affected pages and blocks have been resaved.

For 1.2.5: If you added AddMediaflowViews() solely for the admin page, it can be removed. Keep it if you use TinyMCE, so that metadata for inserted images follows the media object. If the website has its own Views/Shared/DisplayTemplates/XhtmlString.cshtml, render via the Mediaflow extension:

@using Mediaflow.Optimizely.Utility
@model EPiServer.Core.XhtmlString
@{ Html.RenderXhtmlString(Model.WithMediaflowMetadata()); }

Troubleshooting (installation and operation)