Umbraco 7 Sync with Gigya Data Store - DS

Skip to end of metadata
Go to start of metadata

Overview

Synchronization between Umbraco and Gigya's Data Store (DS) is provided through an optional, separate module that can be installed on top of the main Gigya Extension for Umbraco.

The DS Sync module adds the ability to pull data from Gigya's Data Store and map it into the user account database in Umbraco.

Customers who only use Gigya's account storage, and do not use the Gigya Data Store service, do not have to install this additional module.

Prerequisites

  • Umbraco version 7.2 and above
  • Gigya CMS Module for Umbraco version 1.0 and above

Installation and Implementation

To implement DS sync follow these steps:

1. Install Gigya DS Package in Umbraco

  1. Download the package here: Gigya_DS_1.0.0.3.zip
  2. In Umbraco, go to the Developers tab. Open the 'Packages' folder and select 'Install local package'. 
  3. Choose to upload the package.zip file, confirm the warning and click 'Load Package'. 
  4. On the next screen, click 'Accept licence', then 'Install package'. 
  5. The site should refresh automatically, and now includes Gigya DS package. 

To remove the Gigya DS package, see uninstalling.

2. Enable Gigya DS for Selected Umbraco Users

  1. Go to the Users tab in Umbraco. Open the 'Users' folder and select the relevant user. 
  2. Under Sections, check the Gigya DS checkbox. 
  3. Save your changes and refresh the page. The user can now access the Gigya DS tab from the left-hand menu. 

3. Configure DS Settings

Field Mapping

In the Gigya DS Settings tab which is now available on the left-hand menu, map Gigya DS fields to the relevant fields in Umbraco.   

To map fields from Gigya DS to Umbraco: 

  1. Open the Gigya DS Settings tab from the menu on the left-hand side. Select Global Settings
  2. Under Gigya DS Field, specify the DS field to be mapped, in the following format: ds.type.field. Examples include: 
    • ds.userInfo.favouriteColour_s
    • ds.userInfo.extraData.subProperty.value1_s
    • ds.addressInfo.line1_s
    • ds.addressInfo.
  3. Enter the Data Store Object
  4. Select the Umbraco field from the dropdown. 
  5. When you've finished adding fields, click 'Publish'. Note that empty or partially filled mapping definitions will generate an error, so remove unnecessary lines by clicking 'Remove'. 
  6. All sites inherit the global settings by default. To configure a different mapping for a specific site, open that site in the Gigya DS Settings tab and uncheck Inherited from Global Settings

Data Extraction Method

By default, the ds.search method is used for extracting data. To change this to the ds.get method, change the selection under the 'Method' dropdown.

Caching

For performance reasons, the Gigya DS settings are cached in memory for a default of 60 minutes. This can be changed by adding an AppSetting with Gigya.DS.CacheMins as the key. For example: 

<add key="Gigya.DS.CacheMins" value="5" />

When settings are updated through the Umbraco backoffice, the cached settings are cleared from memory.   This is fine in a single server environment but won’t work for a load balanced environment as each server has its own cache.   To clear the cache on the other servers you could republish the settings there or restart the app pool.

Manually Retrieving Gigya DS Data 

DS data can be manually retrieved using the Gigya.Module.DS.Helpers.GigyaDsHelper class. In order to reference the module code you will need to add a reference to these dll's in your project:

  • Gigya.Module.Core
  • Gigya.Module.DS
  • Gigya.Umbraco.Module
  • Gigya.Umbraco.Module.DS

Below is an example of how you could retrieve DS data manually. If you want to use your own settings this can be done by passing your own settings models into the GigyaDsHelper constructor.

  private void ManuallyRetrieveDsData()
        {
            // Create a new Umbraco logger
            var logger = new Logger(new UmbracoLogger());

            // Create a new Gigya Umbraco DS Settings helper for retrieving DS settings from the database (these are managed through Umbraco)
            var settingsHelper = new GigyaUmbracoDsSettingsHelper(logger);
            
            // Gets the DS settings for the current site (this is done by finding the homepage from the current Umbraco page) 
            var dsSettings = settingsHelper.GetForCurrentSite();

            // Create a new Gigya Settings helper for getting core module settings
            var coreSettingsHelper = new GigyaSettingsHelper();

            // Get core settings for the current site (this is done by finding the homepage from the current Umbraco page) 
            var coreSettings = coreSettingsHelper.GetForCurrentSite(true);

            // Create a new helper (GigyaDsHelper) to retrieve DS data from Gigya
            var dsHelper = new GigyaDsHelper(coreSettings, logger, dsSettings);

			// Create a new DS helper with the specified home page ID
			var dsHelper = GigyaDsHelperFactory.Instance(siteId);
 
			// When calling GigyaDsHelperFactory within the context of an Umbraco page rather than an AJAX request, there's no need to pass the site ID: 
			var dsHelperForCurrentSite = GigyaDsHelperFactory.Instance();
            // Retrieve DS data for a user whose UID is userIdValue
			var dsData = dsHelper.GetOrSearch("userIdValue");

			// Retrieve DS data for the current user (no need to pass the UID) 
			var dsData2 = dsHelper.GetOrSearchForCurrentUser();
        }

Using Hooks to Manipulate Data Before Mapping into Umbraco

After the DS fields have been retrieved, an event is fired which can be subscribed to in order to manipulate the account info object before the fields are mapped to Umbraco. The following code sample demonstrates how to do this. Usually this code would be added to Global.asax.cs.

protected override void OnApplicationStarted(object sender, EventArgs e)
        {
            base.OnApplicationStarted(sender, e);

            // Register event to be called after Gigya DS data has been merged with 
            GigyaEventHub.Instance.AccountInfoMergeCompleted += Instance_AccountInfoMergeCompleted;
        }

        private void Instance_AccountInfoMergeCompleted(object sender, AccountInfoMergeCompletedEventArgs e)
        {
            // Model representing Gigya DS data that has been merged with the getAccountInfo model
            dynamic gigyaAccountInfoWithDsDataMerged = e.GigyaModel;

            try
            {
                // Assuming I have a DS field called ds.addressInfo.line1_s then I would use this code to change the value
                gigyaAccountInfoWithDsDataMerged.ds.addressInfo.line1_s = "first line of address";
            }
            catch(Exception ex)
            {
                e.Logger.Error("Error in Instance_AccountInfoMergeCompleted.", ex);
            }
        }

The events described in the core Gigya module for Umbraco can also be used to manipulate data. See Field Mapping 

Logs

The logger used is GigyaUmbracoLogger, so it's possible to enable debug mode just for Gigya. To log debug messages in Umbraco:

  1. Open the <project root>/Config/log4net.config file. 
  2. Add the following piece of code: 

    <logger name="GigyaUmbracoLogger">
    	<level value="Debug" />
    </logger>
  3. In the Umbraco admin module, go to Settings > Gigya
  4. Make sure the Debug Mode box is checked.

Troubleshooting

  • If logs appear empty, make sure that debug mode is enabled for the log4net file either at the global level or for GigyaUmbracoLogger.
  • If a Gigya field is not being saved to Umbraco, check the field mappings on the DS Settings page. Make sure the names are correct and they are the same type (for example, don’t try to map a Gigya field that’s a string to an Umbraco numeric. Note that incorrect field mappings should appear in the log when debug mode is enabled.

Uninstalling

To remove the Gigya DS package (still retaining the core Gigya package):

  1. Click the Developer tab on the left. 
  2. Open the Packages folder and expand Installed Packages
  3. Select 'Gigya DS'. In the Uninstall package tab make sure you uncheck “/bin/Gigya.Module.Core.dll”, as this file is used by the core Gigya module. All other files can be removed.
  4. Click Confirm uninstall

 

 

  • No labels