An Adxstudio Portal application caches results from CRM to improve performance. In order for the portal to get fresh data from CRM, we have to configure the cache invalidation in CRM to notify the portal of CRM data changes. This is done by adding a Web Notification URL in CRM. A Web Notification Plugin registered with the Adxstudio Portals solution in CRM is triggered on all entity create, update, delete, disassociate, associate, publish, and publishall messages and notifies the Web Notification URLs defined in the CRM to invalidate the cache so the users visiting the portal get the recent data changes.

There is no set scheduled time interval for notifying the portal to invalidate its cache. For each event that is processed in the CRM event execution pipeline, such as a create, update, or delete, a new system job for the appropriately registered Web Notification plugin step is created and run that sends an HTTP POST web request to each Web Notification URL to inform the portal cache should be refreshed. These requests usually complete within seconds of the event execution and the portal cache is virtually maintained in realtime, merely seconds behind the actual data change in CRM. Any data operations performed directly by the Portal immediately invalidate its cache without the need for web notifications.

Managing Web Notification URLs in CRM

The Web Notification URLs can be created, edited and deleted within Microsoft Dynamics CRM

  • Login to CRM
  • Navigate to Settings
  • Click Web Notification URLs

To create a new web notification URL

  • Click New

To edit and existing web notification URL

  • Double-click on the existing Web Notification URL listed in the grid

Web Notification URLs

  • Specify a Name of the Portal
  • Specify the URL to your portal and add /Cache.axd to the end of the URL
  • Click Save & Close

Web Notification URL

Attributes & Relationships

The table below explains the Web Notification URL attributes used by Adxstudio Portals.

Name Description
Name  The descriptive name of the record. This field has no impact on Web Notifications and is purely for reference within CRM.
URL 

The URL to your portal's cache invalidation handler.

Example: http://website.com/cache.axd

Example: http://website.com/searchindex.axd

The Web Notification plugin runs in a sandbox, which has an additional restriction on what URLs can be used. IP addresses and localhost URLs are NOT allowed as outbound HTTP calls from the CRM sandbox service. Therefore the URL must consist of a domain name. Therefore URLs such as http://10.100.1.2/Cache.axd or http://localhost/Cache.axd are not valid.

Web Notification Plugin

The plugin included in the installation must be activated in order for the cache invalidation to be triggered by a web notification.

  • Login to CRM
  • Navigate to Settings
  • Click Customizations
  • Click Customize the System

Customize the System

  • Click Sdk Message Processing Steps in the left hand navigation menu
  • Ensure that the 7 Web Notification Plugin steps are Enabled by checking the Status column listed in the grid. 
  • If any of the following plugin steps are not enabled, select the steps and click Activate on the grid's toolbar.
    1. Adxstudio.Xrm.Plugins.WebNotificationPlugin: Associate of any Entity
    2. Adxstudio.Xrm.Plugins.WebNotificationPlugin: Create of any Entity
    3. Adxstudio.Xrm.Plugins.WebNotificationPlugin: Update of any Entity
    4. Adxstudio.Xrm.Plugins.WebNotificationPlugin: Delete of any Entity
    5. Adxstudio.Xrm.Plugins.WebNotificationPlugin: Disassociate of any Entity
    6. Adxstudio.Xrm.Plugins.WebNotificationPlugin: Publish of any Entity
    7. Adxstudio.Xrm.Plugins.WebNotificationPlugin: PublishAll of any Entity

Activate steps

If you have any plugin steps from an old Microsoft.Xrm.Portal.Plugins.WebNotificationPlugin assemply, you should deactivate and delete them.

Portal Configuration

The following handler declaration should exist in the portal's web.config file in order for the website to process the HTTP POST request made by the web notifications. This will already exist in the web.config we distribute in the MasterPortal project. If your web.config does not include this handler declaration, you will need to add it.

<configuration>
  <system.webServer>
    <handlers>
      <add name="CacheInvalidation" verb="*" path="Cache.axd" preCondition="integratedMode" type="Adxstudio.Xrm.Web.Handlers.CacheInvalidationHandler, Adxstudio.Xrm"/>
    </handlers>
  </system.webServer>
</configuration>

Validate Web Notifications

To verify that the web notifications have been configured correctly and that the portal's cache is being refreshed when changes are made to entities within CRM, complete the following steps.

If tracing is enabled in the website, you can verify that web notifications are configured correctly by viewing the portal's trace.axd handler. See ASP.Net Tracing.

  • Login to CRM
  • Open any entity record
  • Make a change to a field.
  • Click Save & Close
  • Wait momentarily for the asynchronous plugin may take a minute to process.
  • Open a web browser and navigate to the website's URL and append /trace.axd to view the trace
  • If there is a POST to the cache.axd then web notifications are working.

Trace

  • If there are no POSTs to the cache.axd then web notification are not working.
    • Login to CRM
    • Navigate to Settings
    • Click System Jobs
    • Review the jobs listed and determine if the various Adxstudio.Xrm.Plugins.WebNotificationPlugin jobs have Succeeded or Failed.
    • If there are no WebNotificationPlugin jobs listed
      • This may indicate that the plugins are not enabled. See Web Notification Plugin above.
    • If the jobs are marked Succeeded
      • This may indicate that the portal is not responding to the notifications or the CRM server is unable to communicate with the portal's web server.
    • If there are jobs that have failed
      • Double-click on the job and view the error details. The details should indicate the reason for the failed job and should help troubleshoot the problem.

Otherwise, if tracing is not enabled

  • Login to CRM
  • Navigate to Portals
  • Click Web Pages
  • Double-click on the Home web page listed in the grid
  • Modify the Copy field by adding some arbitrary text.
  • Click Save & Close
  • Open the website's URL to the home page in your web browser
  • Verify that the arbitrary text added in a previous step is showing up on the page. 
  • If the text is appearing on the page, this indicates the cache is being refreshed and you are done. Don't forget to edit the page and remove the arbitrary text. 
  • If the page does not display the newly added text then something is not configured correctly.
    • This may indicate that the plugins are not enabled. See Web Notification Plugin above.
    • This may indicate that the portal is not responding to the notifications or the CRM server is unable to communicate with the portal's web server.
    • Double-click on the job and view the error details. The details should indicate the reason for the failed job and should help troubleshoot the problem.
    • Login to CRM
    • Navigate to Settings
    • Click System Jobs
    • Review the jobs listed and determine if the various Adxstudio.Xrm.Plugins.WebNotificationPlugin jobs have Succeeded or Failed.
    • If there are no WebNotificationPlugin jobs listed
    • If the jobs are marked Succeeded
    • If there are jobs that have failed

Plugin Configuration

By default, the web notification plugin is set up to run for all entities. There may be times when certain entities do not require notifications to be sent, one can configure the plugin steps to exclude specific entities by a comma delimited list of entity names.

This exclusion list only prevents the plugin jobs from sending actual notifications to the portal, reducing load on the portal. It does not reduce the number of plugin jobs that are actually run -- it just turns some of them into no-ops that don't do anything and exit quickly.

This configuration must be done from the Plugin Registration Tool that is distributed with the Microsoft Dynamics CRM SDK.

  • In the Plugin Registration Tool, connect to the CRM organization with Adxstudio Portals installed.
  • Open the WebNotificationPlugin Step to configure. It will be in the assembly Adxstudio.Xrm.Plugins.
  • In the Unsecure Configuration of the Step, place the following XML:
    <Settings>
    <setting name="entitiesToExclude">
    <value>adx_webnotificationurl,cm_settings</value>
    </setting>
    </Settings>
  • Adjust the value node to contain a comma separated list of entity logical names that should not send notifications.
The CRM user assigned to the "Run in User's Context" of the plugin step will need to have Read privilege on Web Notification URL (adx_webnotificationurl) entity in order for the plugin to read the records to post notifications.

Explicit Plugin Registration

If the set of entities that your portal deals with is relatively small and/or you want to reduce the number of plugin executions for entities that are not used in the portal, you may elect to explicitly register the WebNotificationPlugin steps with only those entities. This will ensure that only messages triggered for those specific entities result in executing this Web Notification plugin. Each entity will require a step for Create, Update, and Delete. Note: The messages Associate, Disassociate, Publish, and PublishAll cannot be registered against a specific primary entity.

To remove the steps that are declared for Create, Update, and Delete of any entity, you must unregister them.

  1. Run the CRM Plugin Registration Tool and connect to the CRM organization you wish to modify. 
  2. Expand the Assembly named Adxstudio.Xrm.Plugins
  3. Expand the Plugin named Adxstudio.Xrm.Plugins.WebNotificationPlugin
  4. Unregister Adxstudio.Xrm.Plugins.WebNotificationPlugin: Create of any Entity
    Unregister Create
  5. Unregister Adxstudio.Xrm.Plugins.WebNotificationPlugin: Update of any Entity
    Unregister Update
  6. Unregister Adxstudio.Xrm.Plugins.WebNotificationPlugin: Delete of any Entity
    Unregister Delete

For each entity register the following new plugin steps

  1. Register new step for Create
    1. Select the Plugin named Adxstudio.Xrm.Plugins.WebNotificationPlugin
      Right-click, click Register New Step
      Register new step
    2. Set Message to Create
      Set Primary Entity to one of the entities in the set the portal references
      Click Asynchronous
      Check Delete AsyncOperation if StatusCode = Successful
      Register Create
  2. Register new step for Update
    1. Select the Plugin named Adxstudio.Xrm.Plugins.WebNotificationPlugin
      Right-click, click Register New Step
      Register new step
    2. Set Message to Update
      Set Primary Entity to one of the entities in the set the portal references
      Click Asynchronous
      Check Delete AsyncOperation if StatusCode = Successful
      Register Create
  3. Register new step for Delete
    1. Select the Plugin named Adxstudio.Xrm.Plugins.WebNotificationPlugin
      Right-click, click Register New Step
      Register new step
    2. Set Message to Delete
      Set Primary Entity to one of the entities in the set the portal references
      Click Asynchronous
      Check Delete AsyncOperation if StatusCode = Successful
      Register Create

Batch Data Operations

If large-scale data operations such as a bulk data import occur, the volume of system jobs running WebNotificationPlugin steps may impact the execution of other system jobs or negatively affect the performance of the portal. If your environment is experiencing this, it may be best to disable the plugin steps for the WebNotificationPlugin temporarily and then enable them once these large-scale data operations have completed. While the plugin steps are disabled, the portal cache will become stale and you will need to invalidate the cache once your large-scale data operations are complete and you have re-enabled the plugin steps. You can force the portal cache to be invalidated/refreshed either by making a web request to the portal's cache handler URL including ?Message=InvalidateAll, or by recycling the IIS website's application pool.