Topics

All topics

Development

Create Sitefinity connectors using service hooks

This article contains
NEW TO SITEFINITY?

Overview

The service hooks in Sitefinity provide a powerful and easy mechanism for creating custom connectors that can update external systems when an event occurs in Sitefinity. For example, you can create a HubSpot contact when a user logs in Sitefinity. To do that you need to create custom triggers and custom actions for the service hooks.

Create custom triggers

You can register your own triggers and actions. They should be registered in custom Sitefinity modules as shown in the sample below. For more information, see Custom modules. 

To register a trigger, you need to implement IServiceHookTriggerProvider interface in your module. You also need to create a new trigger class that inherits from ServiceHookTriggerSettingsBase. 

When defining trigger settings, you need to add this data in constructor: 

  • key - unique key for the trigger (can be any string) 
  • triggerTitle - title to be displayed in the UI. 
  • eventType – EventHub event that you want to track 
  • module - name of the module to be displayed in the UI

    Also, you can add additional event filter in the IsMatch function. 
using Telerik.Sitefinity.ServiceHooks;
namespace SitefinityWebApp
{
public class HubSpotConnectivityTriggerSettings : ServiceHookTriggerSettingsBase
{
public HubSpotConnectivityTriggerSettings() : base("SomeRandomValue", "User is logged in", typeof(Telerik.Sitefinity.Web.Events.ILoginCompletedEvent), "HubSpotConnectivity")
{
}
}
}
view raw customservicehooktrigger.cs hosted with ❤ by GitHub

Create custom actions 

To register custom actions, you must implement IServiceHookActionProvider interface in your module. In addition, you need to create new action setting class that inherits from IServiceHookActionSettings or the built-in WebhookActionSettings 

When defining action setting you need to

  • Define unique Key
  • Define action Title that is displayed in UI
  • Define ParametersType property (Can be left null if no parameters are needed for the action). The properties of the provided type will be rendered in the Create screen of the Service hooks page and the configured values will be available later during the execution of the action. How the properties are rendered in the UI depends on their type and provided attributes. For more information, see Create widget designers. The properties values will be stored in Advanced settings. If you’d like to encrypt the data in the configurations you can decorate the property with [Sitefinity.Configuration.SecretData] attribute. And if you’d like to hide the field’s value in the UI you can decorate it with the [DataType(customDataType: KnownFieldTypes.Password)] attribute.

To complete the action, you must implement the ExecuteActionAsync method as shown in the sample

using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Linq;
using System.Net.Http;
using System.Text;
using System.Threading;
using System.Threading.Tasks;
using Progress.Sitefinity.Renderer.Designers.Attributes;
using SitefinityWebApp;
using Telerik.Sitefinity.Configuration;
using Telerik.Sitefinity.Data.Linq.Dynamic;
using Telerik.Sitefinity.HubSpotConnector.Configuration;
using Telerik.Sitefinity.Security;
using Telerik.Sitefinity.Security.Model;
using Telerik.Sitefinity.ServiceHooks;
using Telerik.Sitefinity.ServiceHooks.Model;
using Telerik.Sitefinity.Services;
[assembly: SitefinityModule(HubSpotConnectivityModule.ModuleName, typeof(HubSpotConnectivityModule), "HubSpot connectivity", "", StartupType.OnApplicationStart)]
namespace SitefinityWebApp
{
public class HubSpotContactCreationActionSettings : IServiceHookActionSettings
{
/// <inheritdoc />
public virtual string Title
{
get
{
return ActionTitle;
}
}
/// <inheritdoc />
public virtual string Key
{
get
{
return Name;
}
}
/// <inheritdoc />
public virtual Type ParametersType
{
get
{
return typeof(HubSpotContactCreationActionParameters);
}
}
/// <inheritdoc />
public virtual async Task<ServiceHookActionResult> ExecuteActionAsync(ITriggerData triggerData, object parameters, CancellationToken cancellationToken)
{
if (triggerData == null)
throw new ArgumentNullException(nameof(triggerData));
if (parameters == null)
throw new ArgumentNullException(nameof(parameters));
if (triggerData.OriginalEvent != null && triggerData.OriginalEvent.UserId != null)
{
var userId = Guid.Parse(triggerData.OriginalEvent.UserId.ToString());
if (userId != Guid.Empty)
{
var actionParameters = parameters as HubSpotContactCreationActionParameters;
if (actionParameters != null)
{
var apiKey = this.GetApiKey(actionParameters.ApiKey);
if (!string.IsNullOrEmpty(apiKey))
{
var url = $"https://api.hubapi.com/crm/v3/objects/contacts?hapikey={apiKey}";
UserManager userManager = UserManager.GetManager();
User user = userManager.GetUser(userId);
if (user != null)
{
UserProfileManager profileManager = UserProfileManager.GetManager();
var profile = profileManager.GetUserProfile<SitefinityProfile>(user);
var requestContent = new StringContent(
"{{\"properties\":{{\"company\":\"{0}\",\"email\":\"{1}\",\"firstname\":\"{2}\",\"lastname\":\"{3}\",\"phone\":\"{4}\",\"website\":\"{5}\"}}}}"
.Arrange("mycompany", user.Email, profile.FirstName, profile.LastName, "1113334444222", "www.mycompanysite.com"),
Encoding.UTF8,
"application/json");
if (this.CanSendRequest(actionParameters.RoleType, userId))
{
var request = new HttpRequestMessage(HttpMethod.Post, url);
request.Content = requestContent;
// If a hubspot contact does not exist, sending will create new
// If it exists, in HubSpot, in the api key logs for request response, you will see "Contact already exists" message.
using (HttpClient httpClient = new HttpClient())
{
HttpResponseMessage httpResponseMessage = null;
try
{
httpResponseMessage = await httpClient.SendAsync(request);
httpResponseMessage.EnsureSuccessStatusCode();
}
catch (HttpRequestException exc)
{
if (httpResponseMessage != null && httpResponseMessage.StatusCode != System.Net.HttpStatusCode.Conflict)
{
throw exc;
}
}
}
}
}
}
}
}
}
return new ServiceHookActionResult(null, true);
}
private string GetApiKey(string paramaterApiKey)
{
var apiKey = paramaterApiKey;
if (string.IsNullOrEmpty(apiKey))
{
var configManager = ConfigManager.GetManager();
var hubSpotConnectorConfig = configManager.GetSection<HubSpotConnectorConfig>();
apiKey = hubSpotConnectorConfig.HubSpotApiKey;
}
return apiKey;
}
private bool CanSendRequest(RoleType roleType, Guid userId)
{
IList<Role> roles = RoleManager.FindRolesForUser(userId);
var canSendRequest = true;
switch (roleType)
{
case RoleType.NonAdminstrators:
canSendRequest = roles.Any(role => !SecurityManager.IsAdministrativeRole(role.Id));
break;
case RoleType.Administrators:
canSendRequest = roles.Any(role => SecurityManager.IsAdministrativeRole(role.Id));
break;
case RoleType.All:
default:
break;
}
return canSendRequest;
}
private const string Name = "HubSpotContactCreation";
private const string ActionTitle = "HubSpot Contact Creation";
public enum RoleType
{
NonAdminstrators,
Administrators,
All
}
public class HubSpotContactCreationActionParameters
{
[DisplayName("Role type")]
[DefaultValue(RoleType.NonAdminstrators)]
[Choice("[{\"Title\":\"Non adminstrators\",\"Name\":\"NonAdminstrators\",\"Value\":\"NonAdminstrators\",\"Icon\":null},{\"Title\":\"Administrators\",\"Name\":\"Administrators\",\"Value\":\"Administrators\",\"Icon\":null},{\"Title\":\"All\",\"Name\":\"All\",\"Value\":\"All\",\"Icon\":null}]", NotResponsive = true)]
public RoleType RoleType { get; set; }
[DisplayName("Api Key")]
[DefaultValue("")]
public string ApiKey { get; set; }
}
}
}
view raw customservicehookaction.cs hosted with ❤ by GitHub

Finally, you need to register the trigger and the action in a Sitefinity module: 

using System;
using System.Collections.Generic;
using SitefinityWebApp;
using Telerik.Sitefinity;
using Telerik.Sitefinity.Abstractions;
using Telerik.Sitefinity.Configuration;
using Telerik.Sitefinity.ServiceHooks;
using Telerik.Sitefinity.Services;
[assembly: SitefinityModule(HubSpotConnectivityModule.ModuleName, typeof(HubSpotConnectivityModule), "HubSpot connectivity", "", StartupType.OnApplicationStart)]
namespace SitefinityWebApp
{
public class HubSpotConnectivityModule : ModuleBase, IServiceHookTriggerProvider, IServiceHookActionProvider
{
public override Guid LandingPageId
{
get { return Guid.Empty; }
}
public override void Initialize(ModuleSettings settings)
{
base.Initialize(settings);
App.WorkWith().Module(Name)
.Initialize();
}
public override void Install(SiteInitializer initializer)
{
}
protected override ConfigSection GetModuleConfig()
{
return null;
}
public override Type[] Managers
{
get { return null; }
}
IDictionary<string, IServiceHookTriggerSettings> IServiceHookTriggerProvider.GetServiceHookTriggersSettings()
{
var triggerSettings = new Dictionary<string, IServiceHookTriggerSettings>();
var loginCompletedTriggerSettings = new HubSpotConnectivityTriggerSettings();
triggerSettings.Add(loginCompletedTriggerSettings.Key, loginCompletedTriggerSettings);
return triggerSettings;
}
IDictionary<string, IServiceHookActionSettings> IServiceHookActionProvider.GetServiceHookActionsSettings()
{
var actionSettings = new Dictionary<string, IServiceHookActionSettings>();
actionSettings.Add("HubSpotContactCreation", new HubSpotContactCreationActionSettings());
return actionSettings;
}
internal const string ModuleName = "HubSpotConnectivity";
}
}
view raw registercustomactionandtrigger.cs hosted with ❤ by GitHub

After you have implemented and registered your custom action and trigger you are ready to configure your first service hook using the new connector.

  1. Navigate to Administration » Servicehooks
  2. Click Create.
  3. Select your newly created trigger and action using the selectors. 

Customize UI fields 

By providing a value for the ParemtersType in the trigger and in the action you can easily build custom UI for your connectors. But if the built-in functionalities are not enough you can customize the fields in the create/edit screen using the Admin App extensions. Learn more about custom fields in GitHub.  

 

Want to learn more?

Increase your Sitefinity skills by signing up for our free trainings. Get Sitefinity-certified at Progress Education Community to boost your credentials.

Get started with Integration Hub | Sitefinity Cloud | Sitefinity SaaS

This free lesson teaches administrators, marketers, and other business professionals how to use the Integration hub service to create automated workflows between Sitefinity and other business systems.

Web Security for Sitefinity Administrators

This free lesson teaches administrators the basics about protecting yor Sitefinity instance and its sites from external threats. Configure HTTPS, SSL, allow lists for trusted sites, and cookie security, among others.

Foundations of Sitefinity ASP.NET Core Development

The free on-demand video course teaches developers how to use Sitefinity .NET Core and leverage its decoupled architecture and new way of coding against the platform.

Was this article helpful?