INSTALLATION & OPERATIONS GUIDE Wavextend Calculation Framework & List Manager for CRM 4.0
COPYRIGHT Information in this document, including URL and other Internet Web site references, is subject to change without notice. Unless otherwise noted, the companies, organizations, products, domain names, e-mail addresses, logos, people, places, and events depicted in examples herein are fictitious. No association with any real company, organization, product, domain name, e-mail address, logo, person, place, or event is intended or should be inferred. Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Wavextend B.V. As the software licensee, you may make reasonable customizations to the software online help documentation for your internal use only. You are solely responsible for and bear any and all liability relating to any customizations you make. This includes any adverse effect that your customizations have on any functionality of the licensed software, the software documentation itself or otherwise relating to use of your customizations. Please note that installing software upgrades may rewrite customized online help files. Wavextend may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Wavextend, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property. 2011 Wavextend B.V. All rights reserved. Calculation Framework user guide, Basic configuration for version 1.0. 2
VERSION This version of the installation and operations guide for Calculation Framework is valid for Dynamics CRM 4.0 in combination with Wavextend Calculation Framework and/or List Manager 4.0 only. There are different guides per version available on the Wavextend website: www.wavextend.com The target group for this guide consists of implementations consultants and system administrators. In case you have remarks, preferably constructive feedback, on this guide. Please send a mail to its authors at userguide@wavextend.com The latest version of this guide will be published on the Wavextend website. People who send feedback will be automatically notified of the availability of new versions until an unsubscription request is received. Calculation Framework user guide, Basic configuration for version 1.0. 3
TABLE OF CONTENT Copyright... 2 Version... 3 Installation... 6 PreRequisits... 6 Server Topology... 6 Single Server... 6 Multiple CRM Server Topology... 6 Step 1 Package Installation... 7 Running the installer... 7 Installed files... 10 Step 2 Add-On Deployment... 11 Deployment to an organization... 11 Installation Log file... 12 Operations... 13 Licenses... 13 Installing a License... 13 Invalid licenses... 14 Metadata Shadow Copy... 14 Updating the metadata shadow copy... 14 Problem solving... 15 Schedule processing... 15 Security... 15 Logging... 16 Calculation Framework user guide, Basic configuration for version 1.0. 4
INTRODUCTION Thank you for using Calculation Framework and/or List Manager from Wavextend. This user guide provides you with the instructions on how to install the Wavextend add-ons and operations instructions for administration of the add-ons. This guide assumes that you have already installed CRM. Calculation Framework user guide, Basic configuration for version 1.0. 5
INSTALLATION Installing the Wavextend Add-ons consists of two parts: The file system components have to be installed; The components must be deployed to the CRM organisation. The installation package contains both the Calculation Framework and List Manager components. These are packages together because they share components. Depending on your license and CRM privileges you can use one or both add-ons. It is recommended that user access to the system is limited from the start of the installation process until the deployment has been completed. Users may experience slow response and/or errors while the installation process is performing changes to the CRM system. PREREQUISITS Before installing the Wavextend Add-ons it is required that CRM is installed including the latest service pack (roll-up). The CRM organization to which you which to deploy the add-on must be provisioned. There are two versions of the installation package one for 32 and one for 64-bit systems. You must install the version matching your CRM installation. The package can be downloaded from the Customer & Partner Area on the Wavextend website (www.wavextend.com). The installation package will detect if CRM is installed prior to starting. If CRM is not installed or a different version is installed the installation package will give a message and not allow the package to be installed. Make sure you have local system administrator privileges on the CRM server. SERVER TOPOLOGY Single Server When the CRM application is installed to only one server the installation and deployment steps described below must both be performed on the CRM server. In this context the E-mail Router, database and SRS Reporting services are not considered part of the CRM application. Multiple CRM Server Topology When the CRM server environment consists of multiple CRM servers the installation package must be installed on every server which contains one or more of the following roles: Application Server Asynchronous Processing Service SDK Server If role groups are used for the deployment the installation package must be executed on all servers with either or both of the roles. For every server perform the instruction under package installation above. Follow the installation steps as described below on every server. Calculation Framework user guide, Basic configuration for version 1.0. 6
The deployment to the organization must only occur once for every CRM organization and can be run from a single server with the installed package. After installation perform the Add-On Deployment once for every CRM organization by running the deployment manager on the server with the installed components. It is recommended to run the deployment on the server which holds the discovery service role. In the connection dialog specify the server name on the server running the discovery service. The installation will install the Wavextend background service on every server. It is only required to have this service running on one of the servers. The service can be disabled on other servers. This service handles the schedule execution. There are checks in place to prevent multiple executions of schedules by different instances of the background service. It is recommended that the background service is enabled on one or two servers maximum, this will provide redundancy without unneeded resource consumption. STEP 1 PACKAGE INSTALLATION The first step in deployment is to install the latest version of the Wavextend Add-on. To install this package the user must be a system administrator on the server. Access to CRM is not required at this point. Running the installer Start the installation package by double clicking the downloaded setup package. Click Next Calculation Framework user guide, Basic configuration for version 1.0. 7
Read the license agreement, select I Agree and Click Next to continue On this screen you can select if you want to automatically restart the CRM Asynchronous Service and IIS Service after the component have been installed. This is required only in case an update of an existing installation is performed, for new installations restart is optional. Check those services you want to restart and click next. Calculation Framework user guide, Basic configuration for version 1.0. 8
Select the installation location for the installation. Select everyone at the bottom of the screen, this will affect for which users the deployment manager is available in the start menu. Click next The installer is now ready to start click next to start the installation Calculation Framework user guide, Basic configuration for version 1.0. 9
After the installation has completed you can proceed with the deployment. You can launch the deployment manager after clicking close by ensuring the checkbox is selected. Alternatively you can start the deployment manager from the start menu. Click close Installed files During installation files are installed in the following location: <Installation Path>, this is the path you selected during installation Default: C:\Program Files\Wavextend\Wavextend Add-on Pack\ o Deployment Manage.exe o Wavextend.Crm.BackgroundService.exe o Resources folder: several xml files <Crm Web>\ISV\Wavextend, this is the ISV folder under the CRM wwwroot folder. Depending on your installation this can be C:\Program Files\Microsoft Dynamics CRM\CrmWeb, C:\inetpub\wwwroot or a custom location. o ISV\Wavextend\CalculatedAttributes: serveral asp.net pages o Bin Wavextend.Crm.IsvExtension.dll Global Assembly Cache. This is the folder assembly under the windows directory. o Wavextend.Crm.dll o Wavextend.Crm.ListManager.dll o Wavextend.Crm.CalculatedAttributes.dll Calculation Framework user guide, Basic configuration for version 1.0. 10
STEP 2 ADD-ON DEPLOYMENT Deployment to an organization After the system components have been installed to all CRM servers the installed components must be deployed to the appropriate CRM organization(s). Deployment requires CRM System Administrator privileges. The deployment manager must be run on the CRM server. Deployment is done using the Wavextend Deployment Manager you can start this from the start menu under Wavextend. After starting the deployment manager you are asked to provide the connection details for CRM. You can accept the default values and click OK After the connection has been established the available organizations will be listed. Select the organizations to which you want to deploy the Add-ons and click on the Deploy button. The deployment manager will now check the deployment status of each organization. If the add-ons are already deployed this will be detected and displayed. Calculation Framework user guide, Basic configuration for version 1.0. 11
If the add-on is ready to be deployed the following screen will be shown. You can choose add and validate your license now or do it later. To be able to add and validate your license you must have an active internet connection and a logon account for the Wavextend Customer & Partner website. To add your license tick the checkbox and enter the license code, enter your Wavextend username and password. Click Deploy The deployment manager will now start the deployment to the organization. The progress of the deployment is shown in the screen in the progress text box. Deployment will take 10-20 minutes depending on server resources. After deployment has completed a message will be shown with the result. You can now close the deployment manager. If you have not added or validated a license you must proceed with the steps described in the operations section for adding a license. Installation Log file During deployment a log file is created in the user s temp folder. This file is named DeploymentManager-Installation.log, this file contains details on errors during the deployment process. Calculation Framework user guide, Basic configuration for version 1.0. 12
OPERATIONS LICENSES Installing a License To use the Wavextend Add-ons a valid license must be installed in the system. If no valid license is installed the Add-on functionalities will not be available and a message Your server has insufficient licences will be displayed. To add a license through the Dynamics CRM User Interface you must have the CRM role Wavextend: Administrator or System Administrator. To add a license: Open CRM Navigate to the settings area Under Wavextend select Wavextend Licences Click New Copy the license information to the Data field. The license information starts with MYAA and is approximately 9 lines long. Save the license record but do not close it If the license is valid the details on the form will be filled and a validation code will be generated. This code is uniquely generated every time. You have two options to validate your o From within CRM. This requires that the server has an active internet connection. Click on the Validate License button on the toolbar at the top of the form Enter your login credentials for the Wavextend Website (You can request a login at order@wavextend.com). Click on OK If the validation succeeds the window will close and the license will be refreshed. If the validation fails a message will be displayed. You can try validation on the website (see below), if this fails contact Wavextend Support. o On the CRM website. This method can be used if the CRM server does not have an internet connection Go to the Wavextend Website to validate your license (www.wavextend.com/en/extranet/crmvalidation). You will need to login (You can request a login at order@wavextend.com). Copy the information from the Validation Code field on the CRM license form to the form on the Wavextend website and click retrieve to obtain your validation. Note: this validation can only be used with the enter Validation code. Calculation Framework user guide, Basic configuration for version 1.0. 13
Copy the returned Validation to the Validation field in CRM The validation starts with MoAA and is approximately 8 lines long Save the license record. After you have added a license for the first time you must publish all customization this is required to make the entities and attributes available for the Wavextend add-ons. See Updating the metadata shadow copy below. Invalid licenses When a license is present in the system which is (no longer) valid it will be deactivated with a status reason why the license is not valid. Licenses will be validated whenever one of the add-on components is used. For example when a Calculated Attribute is saved or a Marketing List is being processed by the List Manager. Licenses are not considered valid until the validation field has been entered, licenses without a value in this field are ignored. License validation looks at several criteria including the following: Does the CRM unique organization name match that of the license Does the active number of CRM users exceed that of the license (User license only) Is the license expired Is the format of the license, validation code and validation valid and not been tampered. The validation code is linked to the license and the CRM Organization The validation is linked to the validation code METADATA SHADOW COPY The Wavextend add-ons keep a shadow copy of the CRM entity model to for example allow the Calculated Attributes to reference entities. The shadow copy is automatically maintained by the Wavextend Add-ons, updates occur automatically when a publish or publish all is done. Performing a Publish or Publish All is required to make the standard CRM customizations to update therefore updating the shadow copy not a separate action. However under some conditions it may be required to force an update of the Shadow copy. For example after the installation a Publish All is need to fill the shadow copy for the first time. Updating the metadata shadow copy This process will run in the background and will take time to complete depending on the amount of customizations and available system resources. The first time this is an intensive process it is recommended to execute this when the server is not heavily used. Consecutive updates will be less intensive depending on the amount of customizations changes. To update the shadow copy: Open CRM Navigate to the settings area Under Settings select Customizations Select Customize Entities Calculation Framework user guide, Basic configuration for version 1.0. 14
In the more actions menu select Publish All Customizations You can also select entities and click Publish to only update those, this will only update the selected entities. Problem solving The shadow copy and its update process are dependent on several factors. Follow the following guide lines if the shadow copy is incorrect or incomplete: The shadow copy will only be updated if a valid license exists. o Check if a license exists. The shadow copy is updated asynchronously. o Perform a publish all o Wait 15 minutes and check again o Check if the asynchronous service is running If an entity, attribute or relation in the shadow copy is incorrect a method to ensure it is created correctly is removing it from the shadow copy and performing a Publish of the entity or Publish All to refresh the data. You can access the shadow copy using Advanced Find, the shadow copy records are in the Shadow Entity, Shadow Attribute and Shadow Relationship entities. Note that if an entity, attribute or relation is used in a calculated attribute or List Manager sample set it cannot be deleted. In this situation you must first remove the reference. SCHEDULE PROCESSING Scheduling processing is triggered by the Wavextend Background Service. At regular intervals this service checks if there are any schedules which need to be executed. If schedules are found the Process Schedule workflow is triggered. The CRM Asynchronous service will then execute the schedule. The background service uses a default interval off 15 minutes between checks. This interval is controlled by the registry value HKLM\SOFTWARE\Wavextend\Add-on Pack, the value BackgroundServiceInterval contains the number of milliseconds between each check. The default value of 15 minutes is represented as a value of 900.000. SECURITY The Wavextend Add-ons adhere to the CRM security structure for defining calculated attributes and list selection steps. Two default security roles are provided, the default roles allow global access to calculated attributes and list selection step. Depending on your requirements you can include these privileges in different roles. Execution of the Add-on, i.e. refresh of marketing lists or execution of a calculated attribute, occurs under system privileges. This ensures that all relevant records are updated. To share access to advanced find views users must be a member of one of the two team created during deployment. For the Calculation Framework the team is named Wavextend: Calculated Attribute Views Team, for the List Manager the team is named Wavextend: List Manager Views Calculation Framework user guide, Basic configuration for version 1.0. 15
Team. If users are not a member of the correct team they will not be able to access calculated attributes or list selection steps created by other users. LOGGING Wavextend Add-ons use two forms of logging. Operational logging is used to report problems which are typically caused by or can be resolved by configuration. This includes errors such as a calculated attribute attempting to update a field which no longer exists or a marketing list using a view which has been deleted. Operation logging is done in the Wavextend Log entry which is accessible in CRM. Unexpected errors but also problems with licenses are logged in the windows Event Log. Typically if this an error of this type occurs the user will experience problems in the CRM interface or processing of calculated attributes, schedules or marketing lists may have failed. These messages are logged in the Windows Application Event Log under the source Wavextend. Workflows are used to execute various operations for the Wavextend Operations. Workflows to report a status which when completed can be Succeeded or Failed. When operational errors occur the status of the workflow will be succeeded but the Wavextend Log will contain one or more entries with a result Failure. Non-operational errors may cause the workflow to exit with status failed, details on the error can be found in the Windows Event Log. 2011 Wavextend B.V. All rights reserved. Calculation Framework user guide, Basic configuration for version 1.0. 16