Back to top image

Episerver 12 Connector Installation and Configuration (.NET 5 Core)

Episerver is now known as Optimizely. For the consistency, the documentation and Smartling interface refers to this software as Episerver. 

This article will guide you through installing and configuring Episerver 12 (.NET Core 5).
If you are working with Episerver 11 (.NET Framework 4.x.x), read this documentation.

Please note that this Connector is a paid product. For pricing information, please reach out to your Smartling Customer Success Manager.

Prerequisites 

  1. Create an ASP.NET site project for building your site and running on your Episerver instance
    • ASP.NET site project is managed by your developer. The project is a set of code repositories and resources that can be compiled, combined and deployed to an Episerver instance.
  2. Your Episerver instance, or site, should have Internet access, with no firewalls in place.
  3. Smartling Episerver plugin requires the following dependencies:
     
    EPiServer.CMS.UI.Core [12.2.1, 13.0.0)

 

STEP ONE: Initialize Smartling API in Startup.cs.

  1. Enable EPiServer.ContentDeliveryApi.OAuth. on your ASP.NET site project
    • Smartling relies on a package for authentication and authorization of the  EPiServer.OpenIDConnect.UI. The package must be included in your solution. The Smartling integration creates a POST request to URL, e.g.: 
      https://your.episerver.domain/api/episerver/connect/token
    • Find more information on how ContentDeliveryAPI OAuth should be configured in Startup.cs from Episerver documentation
  2. Generate ClientId and ClientSecret for Smartling OpenID Connect application and add the application in your Startup.cs file.
    • Ensure to include the special Smartling scope: SmartlingApiOptionsDefaults.Scope

Example

Screenshot_2022-03-22_at_15.20.58.png

Copy and modify this example code

1

// Smartling API
services.AddSmartlingApi(OpenIDConnectOptionsDefaults.AuthenticationScheme);

2

services.AddOpenIDConnect<SiteUser>(options =>
{
    var application = new OpenIDConnectApplication()
    {
        ClientId = "<smartling_client_id>",
        ClientSecret = "<smartling_client_secret>",
        Scopes =
        {
            SmartlingApiOptionsDefaults.Scope
        }
    };

    options.Applications.Add(application);
});

services.AddOpenIDConnectUI();

 

STEP TWO: Install the package

  1. Make sure you have Nuget source for your project.
  2. Install the v1. version of `Smartling.Translation` (Smartling EPiServer AddOn) package from the source
  3. Configure database logging for Smartling.Translation namespace into a separate file
    • For support purposes, Smartling strongly recommended having Smartling database logs separate from other .NET Core 5 logs.
  4. Build website solution, i.e. build ASP.NET site project
  5. Ensure that there is a Smartling.Translation.Core.dll assembly in the bin folder after site deployment
    • This package should have bin folder where all the compiled and dependent code is resided.
  6. Make the following request to your EPiServer instance:
    curl --location --request POST '<schema>://<epi-server-host>:<port>/api/episerver/connect/token'
    \ --data-urlencode 'grant_type=client_credentials' \ --data-urlencode 'client_id=<smartling_client_id>'
    \ --data-urlencode 'client_secret=<smartling_client_secret>' \ --data-urlencode
      'scope=smartling_api'
  7. Take `access_token` from the response and use it in the next request:
    curl --location --request GET '<schema>://<epi-server-host>:<port>/api/smartling.translation/dictionary/content-types'
      \ --header 'Authorization: Bearer <access_token>'
    • You should see the page, block and catalog content types used in your EPiServer instance.
  8. When the installation is complete, simply provide your Smartling Solutions Architect with the following information so Smartling can complete the configuration of the Smartling Episerver Connector:
    • API URL (<schema>://<epi-server-host>:<port>).
    • Client ID and Client Secret that you created above

If you get an error flag, contact Technical Support or your Solution Architect, with the logs.

 

IP Whitelisting

In case you would like to limit access to Smartling API or provide access to your dev\sandbox environment you can whitelist the following IPs:

  • 52.200.226.107
  • 52.200.205.55
  • 52.86.212.212
  • 52.87.14.187
  • 54.243.240.47

Smartling integration will access to the following endpoints:

  • <schema>://<epi-server-host>:<port>/api/episerver/connect/token
  • <schema>://<epi-server-host>:<port>/<protectedVirtualPath>/smartling.translation/*

 

Connecting Episerver to Smartling

  1. Create an Episerver Connector project type in your Smartling Account.
  2. From within this project, click Settings > Episerver Settings
  3. Click Connect to Episerver.
  4. Choose to connect by OAuth login (Client ID and secret)

    1. The following are some URL settings that the connector uses for Authentication:

      • apiUrl (mandatory): This URL is used to get access to EPiServer in general. Usually, it is just a host, e.g. http://172.30.21.102/`
      • authApiUrl (optional): This setting is a path to Auth endpoint. It should be a path without a host. Default value is /api/episerver/auth/token. The connector concatenates apiUrl with authApiUrl to get the full endpoint for Authentication
      • apiVirtualPath (optional): EPiServer uses /episerver virtual path by default. So, the hosted connector may use something like http://172.30.21.102/episerver/smartling.translation/pages/13` for getting content. If you want to change this setting, you should give Smartling a new value, eg /api thus connector will build a content URL with another segment, e.g. `http://172.30.21.102/api/smartling.translation/pages/13`.
      • Important note: Smartling EPiServer .NET Core installation uses /api virtual path by default. It can be changed via plugin API in EPiServer customer development project.
      • basePreviewUrl(optional): The preview is taken by the connector, and it makes HTTP request to take preview HTML. The URL of your Epi instance is unknown for the connector - the apiUrl is used by default. The Epi site can be configured in EPiServer with a public site URL. It does work for simple site infrastructure, but your site may have separated Author and Publish EPiServer instances. The connector needs the Author instance of the EPiServer, not Publish.
      • sslVerificationMode (optional): In case of a site has separated Author and Publish EPiServer instances, Author instance may have an invalid SSL certificate. Access to the Author instance can be restricted via IP-whitelist. In this case, sslVerificationMode can be set to DISABLED - hosted connector will not check SSL certificate of the EPiServer.
  5. Click Connect to Episerver to save your subdomain, or cancel to exit the menu.
  6. Click Allow to authorize the Smartling Episerver Connector.

Your Episerver instance will now be connected to your Smartling project. Now you're ready to configure your Episerver Connector.

Table of Contents