Umbraco installations that have opted into providing basic or detailed telemetry data will indicate which packages are installed. We use that information to order packages by "Most Active Installs".

Package Popularity

We have two measures that we can use to rank packages by popularity:

• Total Number of NuGet Downloads (obtained from nuget.org)

• Number of Active Installs (obtained from CMS package telemetry over the past 14 days)

Both of these are available for website users to select when filtering the list of packages they are reviewing.

"Number of Active Installs" is used as the measure for "Most popular" packages shown on the Marketplace home page.

How Number of Active Installs is Collected

Umbraco installations that have opted into sending telemetry data will send information periodically to a central collection service. This may include information about packages that are installed.

On a regular basis this information is aggregated and stored in the database that serves the Marketplace API and website.

Package Identification

Packages are identified in the telemetry service based on one of the following:

• The package NuGet ID provided in a package manifest file or manifest filter.

• The package name provided in a package manifest file or manifest filter.

• The name of the folder within /App_Plugins/ that the package creates.

The most reliable way of matching up a package between the Marketplace and the telemetry data is if the package NuGet Id is provided. This can be included in your manifest file or filter if your package depends on Umbraco 12 or above.

Even if the package Id is provided in your package manifest, only installations of Umbraco 12 and up will use it for telemetry reporting. Older versions will use the package name or folder.

If the package name or folder is used, this may not be the same as the NuGet package ID. If not, we need to ensure your package is stored along with the alternate name that is used in the CMS and telemetry data.

It's no longer possible to supply this via the umbraco-marketplace.json file. The field by which this was supplied has been deprecated in the schema and if provided will no be longer imported. This was due to the risks of two package developers providing the same alternate names.

Instead we maintain this list at HQ. You may own a package that appears to not rank as expected via the "most active installs" measure. If you suspect it's due to the telemetry data not being correctly allocated, please let us know. We can make the necessary updates such that it's popularity is properly reflected. You can reach us at packages@umbraco.com and tell us the name used for your package in the package manifest or folder.

What if I don't have a client-side component?

Some packages may not have either a package.manifest.json file nor create a folder in /App_Plugins/. This would normally be the case if the package is providing only server-side functionality, and is written purely in C#.

For these cases there's an option to add and register a manifest filter that ensures the name and Id is set.

An example is shown here:

using System.Collections.Generic;
using Umbraco.Cms.Core.Manifest;

namespace Umbraco.Community.MyPackage
{
    internal sealed class PackageManifestFilter : IManifestFilter
    {
        public void Filter(List<PackageManifest> manifests) =>
            manifests.Add(new PackageManifest
            {
                PackageId = "MyPackage",
                PackageName = "My Package",
            });
    }
}

The class needs to be registered as part of the application startup, via a composer or an extension method as shown here:

using Umbraco.Cms.Core.DependencyInjection;
using Umbraco.Extensions;

namespace Umbraco.Community.MyPackage
{
    public static class UmbracoBuilderExtensions
    {
        public static IUmbracoBuilder AddMyPackage(this IUmbracoBuilder builder)
        {
            builder.ManifestFilters().Append<PackageManifestFilter>();
            return builder;
        }
    }
}

Do you want to be listed on the official Umbraco Marketplace? Follow this guide to get your package or integration listed on the Umbraco Marketplace.

Requirements

Your package needs to live up to the following requirements to be listed on the Umbraco Marketplace:

• The umbraco-marketplace tag is added to your NuGet package.

• It meets the minimum Umbraco version requirement: Umbraco 8

The base package information is then sourced from NuGet, including the package name, icon, authors, description, readme, and project URL.

Additional Package Information

You may choose to add a umbraco-marketplace.json file to provide deeper information about your package.

This file must exist in the folder indicated by the project URL in your NuGet specification.

For example, if your project URL is https://mypackage.com, we will look for the file at https://mypackage.com/umbraco-marketplace.json.

If your project URL is your GitHub repository we will check the root of the default branch, or a deeper link if provided.

It is also possible to use a single website for multiple packages. In this case, create a JSON file for each package, suffixed with the package ID.

For example, if your package ID is My.Package, we will look for https://mypackage.com/umbraco-marketplace-my.package.json.

Custom "README" information

We have implemented an import for a custom "README" file for the Umbraco Marketplace. This can be used if you want to display different information here than on nuget.org.

By default, we will import and display the "README" content made available as part of the NuGet package. However, if we find a file by the name of umbraco-marketplace-readme.md in the same location as the umbraco-marketplace.json file, we will import and display that instead.

We will look for an import a file with a package-specific name, e.g. umbraco-marketplace-readme-my.package.md.

JSON Schema

In order for the additional package information to be imported, the file contents need to match the JSON schema we expect.

The schema for the JSON file is available which is illustrated and described as follows. All values are optional and can be empty or omitted.

    {
      "$schema": "https://marketplace.umbraco.com/umbraco-marketplace-schema.json",
      "AddOnPackagesRequiredForUmbracoCloud": [],
      "AlternateCategory": "",
      "AuthorDetails": {
        "Name": "",
        "Description": "",
        "Url": "",
        "ImageUrl": "",
        "Contributors": [
          {
            "Name": "",
            "Url": ""
          }
        ],
        "SyncContributorsFromRepository": true|false
      },
      "Category": "",
      "Description": "",
      "DiscussionForumUrl": "",
      "DocumentationUrl": "",
      "LicenseTypes": [ "" ],
      "IssueTrackerUrl": "",
      "IsSubPackageOf": "",
      "PackageType": "",
      "PackagesByAuthor": [],
      "RelatedPackages": [
        {
          "GroupTitle": "",
          "PackageId": "",
          "Description": ""
        }
      ],
      "Screenshots": [
        {
          "ImageUrl": "",
          "Caption": ""
        }
      ],
      "Tags": [],
      "Title": "",
      "VersionDependencyMode": "",
      "VersionSpecificPackageIds": [
        {
          "UmbracoMajorVersion": 8,
          "PackageId": ""
        }
      ],
      "VideoUrl": ""
    }

Description of each element

Categories

When defining categories for your package, they need to match one of the following:

• Analytics & Insights

• Campaign & Marketing

• Commerce

• Developer Tools

• Editor Tools

• Headless

• PIM & DAM

• Search

• Themes & Starter Kits

• Translations

License Types

When defining the License Type for your package, use one of the following values:

• Free

• Purchase

• Subscription

Package Type

When defining the Package Type for your package, use one of the following values:

• Package

• Integration

An "Integration" provides a connection between Umbraco and a third-party service that a customer has an account with. All other add-ons are considered as a "Package", which is also the default when nothing is specified for this value.

Version Dependency Mode

When defining the Version Dependency Mode for your package, use one of the following values:

• Default

• SemVer

Your Umbraco package will either have a direct or an indirect dependency on Umbraco, which will be reported via NuGet. We use this, across all versions of your package, to determine the minimum and maximum supported versions of Umbraco.

In most cases, we take what we retrieve from NuGet and present that unaltered on the Marketplace.

There is currently one exception though. Many packages are listed with a minimum version of Umbraco as a dependency, but no maximum. Strictly this means the package claims to support not only the minimum selected, but any subsequent major versions of Umbraco too. For major releases with minimal breaking changes, such as Umbraco 9 through 13, this is likely correct. So there is no problem in reporting this compatibility on the website.

With the introduction of Umbraco 14 though, and the significant breaking change of the new backoffice, this is no longer likely to be true. We assume if a package has a minimum version or 13 or less, and an unlimited maximum, that it won't support Umbraco 14. And that's what we'll show on the Marketplace.

For any package that makes backoffice customization, this is almost certainly correct.

Some packages though have no user interface component, and will likely work in Umbraco 14 without modification. If that's the case for you, there are two options:

• Release a new version with a minimum dependency on Umbraco 14, or a maximum exclusive dependency on Umbraco 15.

• Set this option in the umbraco-marketplace.json file to SemVer

  • Via this setting you are indicating that we should take what is defined in NuGet as strictly correct. And as such, we'll import the unlimited maximum and report the package as working on any major version of Umbraco according to the semantic version range.

Related Packages

When providing a list of related packages, you have the option to organize them into separate groups, each with a title.

When a group title is provided, the package, and subsequent ones that don't have a title assigned, will be presented within a group. If a later package has a group title, that will start a new group.

The example below will be rendered as two separate groups, each with two packages:

"RelatedPackages": [
    {
      "PackageId": "Package.One",
      "GroupTitle": "Group One"
    },
    {
      "PackageId": "Package.Two",
    },
    {
      "PackageId": "Package.Three",
      "GroupTitle": "Group Two"
    },
    {
      "PackageId": "Package.Four",
    }
  ],

Package.One and Package.Two will be part of Group One, while Package.Three and Package.Four will be part of Group Two.

Video URL

When defining the Video URL for your package, use one of the following formats:

• https://www.youtube.com/embed/{videoId}

• https://www.youtube.com/watch?v={videoId}

• https://player.vimeo.com/video/{videoId}

Validation

Want to check how the Umbraco Marketplace parses your package? Try the validation tools.

Synchronization With NuGet and Package Owner Data

The schedule for retrieving the latest information from NuGet and any further information provided by the package owners is as follows:

If you can't wait, it's possible to trigger the process for a single package by making an HTTP POST request to https://functions.marketplace.umbraco.com/api/InitiateSinglePackageSyncFunction.

The request should include a Content-Type header of application/json and a body of:

{
  "PackageId": "MyPackage"
}

This endpoint is throttled such that only one request a minute can be made per package ID.

Feedback

If you run into any issues with listing your package, please file an issue on the Issue Tracker.

We will periodically send details of updates made to registered package developers.

If you aren't currently receiving these updates from Umbraco you can sign up for this newsletter.

Umbraco Authorized Services is an Umbraco package designed to reduce the effort needed to integrate third-party services into Umbraco solutions. Many Software as a Service (SaaS) offerings require an OAuth or API key based flow for authentication and authorization. Working with them requires a fair bit of plumbing code to handle creating an authorized connection. This is necessary before the developer working with the service can get to using the provided API to implement the business requirements.

There are similarities to the flow that needs to be implemented for different services. Steps include:

• Redirecting to an authentication endpoint.

• Handling the response including an authentication code and exchanging it for an access token.

• Securely storing the token.

• Including the token in API requests.

• Serializing requests and deserializing the API responses.

• Handling cases where the token has expired and obtaining a new one via a refresh token.

With API key based flows, the process is a little simpler. But you still have to consider secure storage of the key, providing it correctly in API calls and handling serialization tasks.

There are also differences across the request and response structures and variations in the details of the flow itself.

The package tries to implement a single, best practice implementation of working with OAuth. For particular providers the specific flow required can be customized via configuration or code.

The primary use case for this package is when working with services that offer an OAuth2/OAuth1 default authentication and authorization flow against an "app". The developer will need to create this "app" with the service. By doing this, for OAuth1 information such as "client ID"/"consumer key" and "client secret"/"consumer secret" can be applied to the configuration.

When creating the app it is usually necessary to configure a call-back URL. You should use the following:

• For OAuth2: /api/AuthorizedServiceResponse/HandleOAuth2IdentityResponse

• For OAuth1: /api/AuthorizedServiceResponse/HandleOAuth1IdentityResponse

In addition, the package supports integration with OAuth1 or Api key based authentication and authorization services.

Features

For the solution developer, the Umbraco Authorized Services offers two primary features.

Authorized Services in the backoffice

Firstly there's a tree available in the Settings section of the backoffice, called Authorized Services. The tree shows the list of services based on the details provided in configuration.

Each tree entry has a management screen where an administrator can authenticate with an app that has been setup with the service. The status of each service is shown on this screen. When authorized, the authentication and authorization flow has been completed and an access token stored.

A service can be configured to allow the manual entry of access tokens/API keys manually using the CanManuallyProvideToken or CanManuallyProvideApiKey settings. If this is set to true, a new section will be available for providing them.

IAuthorizedServiceCaller interface

Secondly, the developer has access to an interface - IAuthorizedServiceCaller - that they can inject instances of and use to make authorized requests to the service's API.

Using a settings screen the administrator can review the service configuration.

Depending on the authentication method of the service,

• OAuth1

• OAuth2AuthorizationCode (default)

• OAuth2ClientCredentials

• ApiKey

The interface provides methods for retrieving the value of the access tokens or API key - GetOAuth1Token(), GetOAuth2Token() and GetApiKey(). These will return null if the token or key is not found. They will also return null if the service is not configured to use the authorization method related to these objects.

Usage

Below you can learn more about how to use the Umbraco Authorized Services package.

Installation

App Creation

Services supported by the package will often offer an OAuth authentication and authorization flow against an "app" that the developer will need to create. This will make available information, including for example a "client ID" and "client secret", that will need to be applied in configuration.

When creating the app it will usually be necessary to configure a call back URL. You should use the following:

• For OAuth2: /umbraco/api/AuthorizedServiceResponse/HandleOAuth2IdentityResponse

• For OAuth1: /umbraco/api/AuthorizedServiceResponse/HandleOAuth1IdentityResponse

Configuring a Service

Details of services available need to be applied to the Umbraco web application's configuration.

An example of doing this through the appSettings.json file is shown below. Other sources such as environment variables can also be used, as per standard .NET configuration.

TokenEncryptionKey is a setting for an optional key used for token encryption when they are saved and retrieved from storage. It's only necessary and advisable when using the non-default AesSecretEncryptor implementation.

Services contains the a collection of details for all the configured services structured as a dictionary.

The dictionary key is the alias of the service, which must be unique across the service collection.

The following table describes each of the service elements. Where appropriate, an example is provided for one service provider, GitHub.

Not all values are required for all services. Those that are required are indicated below.

Version 14.0.0 and up

• The JsonSerializer configuration option was removed, as we will now use the CMS default based only on System.Text.Json.

  • Types related to this feature are also removed: JsonSerializerOption and JsonSerializerFactory.

Up to version 14.0.0

The options for JsonSerializer are:

• Default - uses the Umbraco CMS default IJsonSerializer.

• JsonNet - uses the JSON.Net serializer.

• SystemTextJson - uses the System.Text.Json serializer.

With UseProofKeyForCodeExchange set to true, a random code will be generated on the client and stored under the name code_verifier. Using the SHA-256 algorithm it will be hashed under the name code_challenge. When the authorization URL is generated, the code_challenge will be sent to the OAuth Server, which will store it. The next request for access token will pass the code_verifier as a header key. The OAuth Server will compare it with the previously sent code_challenge.

Authorizing a Service

With one or more service configured, it will be available from the items within a tree in the Settings section.

Selecting an item will show some details about the configured service, and it's authentication status.

If the service is not yet authorized, click the Authorize Service button to trigger the authentication and authorization flow. You will be directed to the service to login, and optionally choose an account. You will then be asked to agree to the permissions requested by the app. Finally you will be redirected back to the Umbraco backoffice. You should see confirmation that an access token has been retrieved and stored such that the service is now authorized. If provided, you can click the Verify Sample Request button to ensure that service's API can be called.

Calling an Service

To make a call to an authorized service, you first need to obtain an instance of IAuthorizedServiceCaller. This is registered with the dependency injection framework. As such it can be injected into a controller, view or service class where it needs to be used.

When making a request where all information is provided via the path and querystring, such as GET requests, the following method will be invoked:

The parameters for the request are as follows:

• serviceAlias - the alias of the service being invoked (e.g. github).

• path - the path to the API method being invoked (e.g. /repos/Umbraco/Umbraco-CMS/contributors).

• httpMethod - the HTTP method to use for the request (e.g. HttpMethod.Get).

There is also a type parameter:

• TResponse - defines the strongly typed representation of the service method's response, that the raw response content will be deserialized into.

If you need to provide data in the request an overload is available. This can be used for POST or PUT requests that trigger the creation or update of a resource:

The additional parameter is:

• requestContent - the strongly typed request content, which will be serialized and provided in the request.

And additional type parameter:

• TRequest - defines the strongly typed representation of the requested content.

If you need to work with the raw JSON response, there are equivalent methods for both of these that omit the deserialization step:

Finally, there are convenience extension methods available for each of the common HTTP verbs. These allow you to simplify the requests and omit the HttpMethod parameter, e.g.

Depending on the configured authentication method, there are some methods that can be used to retrieve the access token or the API key:

Verified Providers

The following service providers have been tested against the package implementation. For each one the necessary configuration is listed.

As integrations with more providers are successfully completed, we plan to maintain the details for each here. Pull requests updating this list with verified integrations are welcome.

Contributing

The Authorized Services package is open-source and we welcome Issues, suggestions for improvement, and PRs.

The readme file there contains further information, expanding on the documentation you have read here. This will help anyone interested in understanding how it has been developed and how to contribute to the solution.

Within this Umbraco DXP (Digital Experience Platform) area of the Umbraco documentation, you'll find topics related to extending Umbraco CMS via packages and integrations.

Umbraco is used in solutions in both a "platform" and "composable" DXP context. With the former, Umbraco has responsibility for both content management and delivery, with extensions added as NuGet packages. In a composable DXP, Umbraco is often a stand-alone service that takes part in an overall architecture. In these cases, Umbraco CMS is focused on the management of content exposed via APIs for delivery.

Umbraco is also used in a hybrid DXP context. Here, some features are added directly to the Umbraco platform, like Umbraco Forms or Umbraco Commerce. However, Umbraco still acts as a component in a wider architecture.

In all situations, backoffice integrations with third-party services are an important part of providing an intuitive, unified editor experience.

Our aim is to support the different ways of using Umbraco in a DXP context and provide resources for building integrations with Umbraco.

Packages and integrations

Packages for Umbraco are installed as Nuget packages.

Integrations provide functionality via a third-party service's API, whereas packages extend the functionality of the CMS (management or delivery).

Umbraco Commercial Products

Umbraco makes available four licensed add-ons that are available for purchase. They each have their dedicated documentation area:

We aim to make all commercial products available as new major versions in alignment with the releases of Umbraco CMS. A new major version of Umbraco, running on the latest version of .NET, is expected every six months. At or around the same time, compatible Forms, Deploy, Workflow and Commerce releases will also be made available, along with the additional, dependent packages.

We align version numbers across the products. So when running for example Umbraco CMS 12, the same major version of the commercial products should be used.

Umbraco Marketplace

The Umbraco Marketplace is a public website used to showcase Umbraco packages. These are commercial and open-source extensions available for use in Umbraco solutions. On the marketplace, you can browse and search for packages, understand their usage, and review their suitability for your project.

The marketplace is available at marketplace.umbraco.com.

Within the Marketplace section of the documentation, you'll find details aimed at package developers looking to list their Umbraco CMS extensions and integrations.

Umbraco Packages

We create and support open-source packages designed to improve the experience of creating integrations and developing Umbraco solutions as a DXP.

Within the packages section of the documentation you'll find information on using a component called Authorized Services. This package is designed for the purpose of simplifying custom integrations with third-party services that use a OAuth flow for authentication and authorization.

Umbraco Integrations

Finally, Umbraco HQ develops and makes available open-source integrations. These add functionality to the Umbraco CMS to support working with third-party services.

These integrations are helpful starting points for anyone looking to integrate such services into their Umbraco solution.

When we have released an integration for a particular provider and use case that matches your needs, they are available for use directly. If we don't meet your particular requirement, we welcome feedback at the Issue Trackers. As all are open-source, they can be used as references for building similar integrations with related services.

Source code and issue trackers are found in the following GitHub repositories:

• Umbraco CMS Integrations

• Umbraco Forms Integrations

Within the Integrations section of the documentation, you'll find details on installing and working with the integration packages developed by Umbraco HQ.

Umbraco HQ has developed and made available integrations with different SaaS (Software as a Service) providers. These are all open-source and add functionality to Umbraco CMS to support working with third-party services.

Analytics

Automation

Commerce

Customer Relationship Management (CRM)

Digital Asset Management (DAM)

Product Information Management (PIM)

Search

This integration provides a form picker and rendering component for forms managed within an ActiveCampaign CRM: Customer Relationship Management account.

Package Links

• NuGet install

• Source code

• Umbraco marketplace listing

Minimum version requirements

Umbraco CMS

Authentication

All requests to the ActiveCampaign API are authenticated by providing an API key. The API key is included as an HTTP header called Api_Token.

If the configuration is incomplete, the user will receive an error message.

Configuration

To connect to your ActiveCampaign account, the following configuration is required:

"Umbraco": {
  "CMS": {
    "Integrations": {
        "Crm": {
          "ActiveCampaign": {
            "Settings": {
              "BaseUrl": "https://[YOUR_ACCOUNT_NAME].api-us1.com",
              "ApiKey": "[YOUR_API_KEY]"
            }
          }
        }
      }

Backoffice usage

To use the form picker, a new Data Type needs to be created based on the ActiveCampaign Form Picker property editor.

The settings in appsettings.json will be used for sending the required HTTP header for authorization, and for retrieving the account name used for rendering the form.

Front-end rendering

A strongly typed model will be generated by the property value converter. An HTML helper is available, to render the form on the front end.

Ensure that your template has a reference to the following using statement:

@using Umbraco.Cms.Integrations.Crm.ActiveCampaign.Core.Helpers;

Assuming a property based on the created Data Type with the alias activeCampaignForm has been created, render the form using:

@Html.RenderActiveCampaignForm(Model.ActiveCampaignForm)

This integration provides a custom workflow, allowing form entries to be mapped to an ActiveCampaign contact record. The record can be used to create a new contact or to associate a contact with an existing Customer Relationship Management (CRM) account.

Package Links

Minimum version requirements

Umbraco CMS

Umbraco Forms

Authentication

All requests to the ActiveCampaign API are authenticated by providing an API key. The API key is included as an HTTP header called Api-Token.

If the configuration is incomplete, the user will receive an error message.

Configuration

An ActiveCampaign contact has four main properties: email, first name, last name, and phone.

To connect to your ActiveCampaign account, the following configuration is required:

The email property is mandatory by default through ActiveCampaign API rules. The required rule can be extended to the other properties, by explicitly specifying that in the required property of each ContactFields node.

Working with the integration

To use it, follow these steps:

1. Attach the ActiveCampaign Contacts Workflow to a form.

2. Configure the mappings between the contact properties and the form fields.

3. Select an account if you want to associate the contacts, and/or map any contact custom fields.

When a form is submitted on the website, the workflow will execute. Based on the provided email it will create or update an ActiveCampaign account. If custom fields mappings have been provided, the contact payload will contain custom fields values.

If an account has been provided in the workflow setup, then an association with the account will be created.

This integration provides a custom dashboard and indexing component for managing search indices in Algolia.

Package Links

Minimum version requirements

Umbraco CMS

Authentication

The communication with Algolia is handled through their , which requires an Application ID and an API key.

They are used to initialize the which handles indexing and searching operations.

Configuration

The following configuration is required for working with the Algolia API:

Algolia comes with a set of predefined API keys:

Working with the integration

The following details how you can work with the Algolia integration.

1. Go to the Settings section in the Umbraco CMS backoffice.

2. Locate the Algolia Search Management dashboard.

In this view, you will be able to create definitions for indices in Algolia.

1. Provide a name for the index for each indices.

2. Select the Document Types to be indexed.

3. Select the fields you want to include for each Document Type.

After creating an index, only the content definition is saved into the algoliaIndices table in Umbraco, and an empty index is created in Algolia.

The actual content payload is pushed to Algolia for indices created in Umbraco in two scenarios:

• From the list of indices, the Build action is triggered, resulting in all content of specific Document Types being sent as JSON to Algolia.

From the dashboard, you can also perform a search over one selected index, or remove it.

Each Umbraco content item indexed in Algolia is referenced by the content entity's GUID Key field.

Algolia record structure

An indexed Algolia record matching an Umbraco content item contains a default set of properties. It is augmented by the list of properties defined within the Umbraco dashboard.

Properties that can vary by culture will have a record property correspondent with this naming convention: [property]-[culture].

The list of default properties consists of:

• ObjectID - GUIDfrom the content item'sKey` property

• Name - with culture variants if any

• CreateDate

• CreatorName

• UpdateDate

• WriterName

• TemplateId

• Level

• Path

• ContentTypeAlias

• Url - with culture variants if any

• Any registered properties on the Document Type

Extending the Algolia indexing

Indexing the content for Algolia is based on the IDataEditor.PropertyIndexValueFactory property from Umbraco CMS, the indexed value of the property being retrieved using the GetIndexValues method.

The integration uses the same conversion process as Umbraco CMS uses for Examine, and apply a custom converter afterwards.

To customize the returned value from Umbraco CMS you would need to use a custom converter specific to the particular indexed Umbraco property editor.

To extend the behavior, there are available options:

Version 2.3.0/3.1.0 and up

By default the integration comes with a NULL return value provider, but you can add your own by implementing the IAlgoliaGeolocationProvider interface, and register it as singleton:

Version 2.1.5 and up

A custom converter will look like this, allowing developers to add their implementation based on the content property:

Version 2.0.0 to 2.1.5

Starting with version 2.0.0, we provide a collection of converters for the following Umbraco property editors:

• Umbraco.TrueFalse

• Umbraco.Decimal

• Umbraco.Integer

• Umbraco.MediaPicker3

• Umbraco.Tags

To create a new converter one should implement the IAlgoliaIndexValueConverter interface. Then specify the name of the property editor and add the new implementation. The new converter will then need to be added to the Algolia Converters collection.

To do so, follow these steps:

1. Create the new converter

1. Replace the default converter (if one exists) with the new one

1. Inject custom converters

Up to version 1.5.0

These implementations contain a custom converter for the Umbraco.MediaPicker3 property editor.

If a different implementation is required, you will need to follow these steps:

1. Inherit from AlgoliaSearchPropertyIndexValueFactory

2. Override the GetValue method

4. Register your implementation in the composer

The following code sample demonstrates this approach:

Extension registration

The following diagram shows the Umbraco commercial products, their dependencies and the relations between them. Depending on your setup, you may need one or more of the additional packages shown here when working with them.

Explanatory notes:

• Umbraco.Licensing supports the older licensing mechanism for Umbraco's products, including Forms, and Deploy when used on Umbraco Cloud.

• Umbraco.Licenses is the newer component supporting subscription licensing, used for Workflow, Commerce and Deploy 12+ when used on-premise.

This integration provides a custom Media Picker for digital assets managed in an Aprimo workspace. It can be used as a property editor for content. A value converter providing a strongly typed model for rendering is available, along with a sample rendering component.

Package Links

Minimum version requirements

Umbraco CMS

Configuration

The following configuration is required to connect to the Aprimo Digital Asset Management (DAM) workspace:

The configuration is split into two components:

• A generic one that holds your tenant's name, and

• One for OAuth settings.

Using the offline_access scope, the response from Aprimo API will contain a refresh token, with an expiration period of 10 days. This will keep the API access available for the front-end rendering of the images.

Backoffice usage

To use the Media Picker, a new Data Type should be created based on the Aprimo Media Picker property editor.

If the configuration is not valid, an error-tag will be displayed in the right upper corner of the configuration box.

Otherwise, you will be able to select one of the two available options for picking assets:

• Aprimo API - items are retrieved using the API and an overlay of the property editor will display the list of available items in the Digital Asset Management (DAM) workspace.

• Aprimo Content Selector - rich UI tool hosted on Aprimo Cloud where you can pick items using a familiar Aprimo interface.

Browser information

Before using the integration with Aprimo, please make sure to use a browser that is supported by Aprimo Cloud. Without one you will not be able to authenticate, nor use the Content Selector.

• Chrome for Windows and Macintosh

• Edge (Windows 10 only)

• Internet Explorer 9, 10, and 11

• Safari 6, 6.1, 6.2, and 7.0 (Macintosh only)

Front-end rendering

A strongly-typed model will be generated by the property value converter. An HTML helper is available to render the asset on the front end.

Make sure your template has a reference to the following using statement:

Assuming a property based on the created Data Type with the alias aprimoMediaPicker has been created, render the media asset:

Properties available from the strongly-typed model:

• Title

• Thumbnail

• Crops

• Asset fields

Working with Crops

For the selected media asset you can retrieve the details of the crops using the MediaWithCrops object.

It contains:

• Details of the original asset,

• The list of available crops, and

• A method to retrieve the crop URL based on name and width/height.

For example:

• To get the URL for crop item with the name Social: @Model.MediaWithCrops.GetCropUrl("Social")

• To get the URL for crop item with height 1080: @Model.MediaWithCrops.GetCropUrl(null, 1080)

Working with fields

The asset's fields are grouped in an object containing their label and a dictionary of values based on the available cultures for that asset.

For example, to get values for a field with the label Display Title:

The Umbraco Marketplace is a public website used to showcase Umbraco packages. These commercial and open-source extensions to the Umbraco CMS are available for use in Umbraco solutions. On the website, you can browse and search for packages, read details about their installation and usage, and review their suitability for your project.

The website is available at .

Website Features

The Marketplace website is a read-only display of packages available to extend Umbraco. The information displayed combines what is available at nuget.org, augmented with additional details provided by the package owners.

Each package is listed within a category, grouping together packages meeting needs within a particular area. Information such as version number, Umbraco compatibility, description, screenshots, and video are available. A keyword search is also available as well as browsing and filtering packages within each category or list.

We provide links for each package to the NuGet details, and other locations if available, such as the source code, documentation, and issue tracker.

Listing Your Package

If you are a package developer wanting to make your work available for Umbraco website developers, please review the article.

Package Telemetry Data

Umbraco installations that have opted into providing basic or detailed telemetry data will indicate which packages are installed. We use that information to order packages by "Most Active Installs".

To understand how to ensure your package is ranking correctly by this measure, please consider the details provided about .