customization assistant user guide

CUSTOMIZATION ASSISTANT USER GUIDE

for version 5.0

Calculation Framework user guide, Basic configuration for version 1.0. 2

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.

© 2012 WaveXtend B.V. All rights reserved.


VERSION

This version of the user guide for the Customization Assistant is valid for WaveXtend Customization

Assistant version 5.0 and can be used for version 4.0 as well. There could be minor differences

between the two versions. Version 4.0 is compatible with Dynamics CRM 4.0 on premise only.

Version 5.0 is compatible with Dynamics CRM 4.0 on premise, Dynamics 2011 on premise, Dynamics

CRM 2011 partner hosted and Dynamics CRM Online.

Reading this guide will give you a profound background to make full use of the Wavextend Customization Assistant and the power to reduce much of time needed to configure the Dynamics CRM entity model.

In case you have remarks, preferably constructive feedback, on this guide. Please send a mail to its authors at [email protected]

The latest version of this guide will be published on our website. People who send feedback will be automatically notified of the availability of new versions until we receive an unsubscription request.

mailto:[email protected]#_blank


TABLE OF CONTENT

COPYRIGHT .............................................................................................................................................. 2

VERSION................................................................................................................................................... 3

TABLE OF CONTENT ................................................................................................................................. 4

INTRODUCTION ....................................................................................................................................... 5

LIcensing .............................................................................................................................................. 5

The basics ................................................................................................................................................ 6

Connecting ........................................................................................................................................... 6

Menu Options ...................................................................................................................................... 7

Bulk Create ............................................................................................................................................ 11

Excel Workbook ................................................................................................................................. 11

Processing the file ............................................................................................................................. 16

The Customization Assistant functions ................................................................................................. 18

Describe ............................................................................................................................................. 18

Delete Attributes ............................................................................................................................... 19

Change Data Type .............................................................................................................................. 19

Mapping ............................................................................................................................................ 22

Convert To/From Relation ................................................................................................................. 22

Rename .............................................................................................................................................. 24

Change Properties ............................................................................................................................. 24

Copy Attributes ................................................................................................................................. 25

Dependency Types ............................................................................................................................ 26

Apply changes to other systems ............................................................................................................ 28

Warning ................................................................................................................................................. 30


INTRODUCTION This guide describes how to use the Wavextend Customization Assistant. The customization assistant can be used with Microsoft Dynamics CRM 4.0, 2011 or Online. Customization Assistant allows you to make changes to the domain model of Dynamics CRM much faster than possible using the regular Customization forms provided by Microsoft. It also allows you to execute some advanced changes that are normally not possible using the Microsoft customization options, like changing the data type of attributes. And last but not least Customization Assistant offers the ability to replay changes on other servers, including attribute deletes, and is therefore a great addition for (vertical) solution developers.

LICENSING

When using the Wavextend Customization Assistant for the first time, the application will request to

input a license key. To obtain a license, contact your Wavextend Partner or go to the Wavextend

website (http://www.wavextend.com/en/Contact/Order).

To use your Wavextend Product the license must be validated. The validation will link the license to

your windows installation. If you want to use the Customization assistant on another desktop you

must repeat the validation procedure. To validate you license follow the instructions presented on

the license registration screen in Customization Assistant.

To obtain a new license, please go to our website http://www.wavextend.com/en/Contact/Order

If you lost your license please send an email to [email protected] and we will respond within

one business day

You need a username and password of the Wavextend partner portal to be able to validate your

license. This username password was send in an email together with your license code.

In case you lost your username and password, please send an email to [email protected] and

we will respond within one business day.

There are two options to validate your license: either directly from the license registration screen in

Customization Assistant or on the Wavextend partner portal:

http://www.wavextend.com/en/Content/Extranet

http://www.wavextend.com/en/Contact/Order

http://www.wavextend.com/en/Contact/Order

mailto:[email protected]


http://www.wavextend.com/en/Content/Extranet


THE BASICS This section describes the basics of the Wavextend Customization Assistant. For details on how to

use a specific option, please refer to the corresponding sections in this guide.

CONNECTING

The Wavextend Customization Assistant must be connected to a CRM organisation to start using it.

When starting the application, the connection dialog is shown.

Enter the connection details of your CRM organization.

o Server: the discovery service host name

For example or crm.mycompany.com depending on the fully qualified domain name

of your server running Dynamics CRM. (don’t use http://)

CRM Online in the US is always dev.crm.dynamics.com, in Europe (EMEA) it is

dev.crm4.dynamics.com and in Asia (APAC) dev.crm5.dynamics.com

o Use SSL: if your server required HTTPS check this box.

o Port number: if your CRM installation is not on the default ports (80 for http or 443

for SSL) you can also enter the port number. 5555 is also a commonly used port for

CRM.

o Credentials: Enter your username, password and domain.

For CRM Online the username is your live ID and the domain is not needed.

o Connection: By default the CRM version and connection mode will be automatically

determined, you can select to override this.

Currently supported: CRM 2011 AD-Authentication, CRM 2011 Federated (AD-

FS/IFD) Authentication, CRM 2011 Online, CRM 4.0 AD-Authentication, CRM 4.0 IFD-

Authentication.

Click on Get organizations.

After the organizations have been retrieved select the organization to connect to and click

OK (if you provided your live id, all CRM Online organizations you have access to will be

displayed)

The customization assistant will now connect to the organization and retrieve the required

information, this may take some time, especially for CRM Online. When the retrieval is

completed you can start using the application.

NOTE : we have not tested support for claims based authentication in CRM 2011. If you run into this

scenario, please contact us at: [email protected] for assistance.



The connection dialog will remember the connection details for all successful connections. When

entering the servername autocomplete will provide remembers servernames when enter the details

are prefilled. The password is never stored.

Depending on the connected system (CRM 4.0 or CRM 2011/Online) different options may be

available.

MENU OPTIONS

The menu of the Wavextend Customization Assistant offers the following options:

File menu

o Change Connection;

Allows you to connect to a different CRM organization or server.


o Load Change File, Save Change File, Replay Changes;

These options allow you to repeat selected changes you made during one session on

a another organization and/or server. For more details see the section on applying

changes to other servers.

Tools menu

o Bulk Create, Bulk Create Template file;

Allows you to quickly create and edit multiple entities, attributes, relations and/or

views using Excel. For more details see the Bulk Create section

o Reload Caches;

Refreshes the metadata cached by the Customization Assistant. This is automatically

done when you connect, change you connection or after you apply changes using the

Customization Assistant. You should do this if changes to the CRM server have been

made outside the Customization Assistant.

o Settings;

Allows you to control certain behaviour of the Customization Assistant.

The context menus also contain various options. You can access these menus by right clicking on a

row in the entity or attribute list. The selected action will be applied to the selected row(s). You can

select multiple rows using the Shift or Control keys.

Some of the options in these menus may be disabled based on the available options for the selected

row(s). Only the options available to all selected rows will be enabled.

Entity menu:

o Describe;

Generates an Excel file containing all entities, attributes, relations and views for the

selected entities. The format is the same format as accepted by the bulk create

feature.

Attribute menu:

o Change Data Type;

Change the data type of one or more fields while retaining the fields on the form and

in views. And optionally keep data in the existing records.

o Change properties;

Allows you to change properties for multiple attributes at once.

o Copy Attribute(s);

Copy an attribute multiple times on the same entity or copies attributes to another

entity.

o Delete attribute(s);

Delete multiple attributes in one action, including deleting the attribute from forms

and views, when selected.

Settings menu

The settings option in the tools menu allows you to control the default behaviour for the Wavextend

Customization Assistant.


o History Replay;

When checked all changes made using the Customization Assistant are saved to the history

file and can be export or reapplied for later use on other servers

Action items will be kept for a maximum of 2 months.

o Step Validation;

When checked, the validation dialog will automatically close and continue to execute the

requested action when no validation warnings or errors were found.

Validation and Operation progress dialog

For each selected action a validation dialog is shown. This dialogs shows the current action to be

executed, steps to be executed and any warnings or errors which might be foreseen.

In the validation dialog you have options to control the display.

o Close when completed;

When checked the dialog will automatically close and continue execution the operation after

the all step have been completed and no warnings or errors have occurred.


This option is only shown while the actions are being executed, when all steps have been

completed this option is no longer available.

o Show;

Allows you to control which steps are shown

o All

Shows all steps, including those completed successfully

o Warnings and Errors

Shows all steps to be executed and any steps with a warning or error

o Errors Only

Shows all steps to be executed and any steps with an error.

o Copy to clipboard;

Allows you to copy all step messages to the clipboard.

o More details link (blue dots behind each step)

If a message with more details is available on a step, a link is shown behind it. Clicking this

will expand the message. For warnings and errors the message is always shown.

The validation dialog will allow you to continue the selected action if only warnings but no error have

occurred. Consider these warning before continuing with the operation. If any errors are foreseen,

the operation cannot be continued.

If warnings occur during the execution this is displayed, but the process will continue. If an error is

encountered during execution, you have the option to retry, ignore or cancel.

The ’Retry’ option will repeat the operations. This can be used when the error was corrected, for

example if the network connection was lost and was restored.

The ‘Ignore’ option will skip the erroneous step; note that this may result in an inconsistent CRM

system state and that steps depending on this may now also fail.

The ‘Cancel’ option stops the entire action allowing you to correct the problem before repeating it or

decide not to further execute the action.


BULK CREATE The bulk create feature allows you to define the CRM Entity model in a Microsoft Excel workbook

which can also be used for documentation purposes. These sheets can be used by the Wavextend

Customization Assistant to provision or update the CRM entity model.

The bulk create feature will create or update you entity model according to the settings in the Excel

sheet. Do note that it is not possible to perform advanced changes using the Excel sheet (such as

changing a field’s data type) that are possible using the Customization Assistant UI.

EXCEL WORKBOOK

The Excel workbook used can be found in the Tools menu (select Bulk Create Template File). Note

that the CRM 4.0 and CRM 2011 versions of these sheets are different. The 2011 version has

additional columns and sheets to support managed properties and global picklists.

If required, the Excel worksheets can be expanded to add additional columns on the right, for the

purpose of change log, data migration mapping or version history. These columns will not be

processed by Customization Assistant. Additional sheets can also be added to the workbook as

needed. The tables on the sheets for processing by the Customization Assistant cannot be modified

(e.g. reorder or remove columns).

Validation rules were added to the tables in the workbook to assist the user when defining the entity

model. If a validation error occurs this must be corrected before using the workbook in the

Wavextend Customization Assistant otherwise the file will not pass validation.

Template File

From the tools menu you can select the option Bulk Create Template File, this will allow you to save a

sample Excel file for use with the Bulk Create Option.

CRM 4.0 and CRM 2011 have different template files. You can use the bulk template file for CRM

2011 file for processing to CRM 4.0. Properties and features not used by CRM 4.0 will be ignored. To

be able to use a template file originally for CRM 4.0 with CRM 2011 you can copy the data from the

CRM 4.0 sheet into an empty CRM 2011 sheet. When doing this select “Paste Values” option from

the “Paste Special” menu item otherwise the validation rules may fail after copy.

Entities sheet

The first sheet in the Excel file defines the entities. The primary attribute and entity system name on

this sheet are only specified for the initial creation action but not for update. However they must

contain a value for update actions even though the attribute already exists. The display name and

length properties of the primary attribute are also for creation only and are not updated from this

sheet during an update action.

All other properties can be used for both create and update actions.


Attributes sheet

The attributes sheet contains the definition of attributes (or fields) and corresponding properties. For

all attributes the properties: entity, name, display name, type and ‘required level’ are mandatory.

The ‘searcheable’ and description properties are optional. The ‘searcheable’ property determines if

the attribute is shown in the column list (for selection criteria or view columns). The mandatory

nature of the remaining properties depend on the attribute data type (see the table below).

Form

at

Len

gth

Min

imu

m

Max

imu

m

Dec

imal

s

Ime

Mo

de

Val

ues

Boolean M

DateTime Default: Date

Values: Date, Date Time

Decimal M M M

Double

Float

M M M

Integer Default: None

Duration, Language, Locale,

Time zone

M M

Memo M

Money M M M

Picklist M

String Default: Text

Values: Email, Phonetic

Guide, Text Area, Ticker

Symbol, Url

M Default: Auto

Values: Auto,

Active, Disabled,

Inactive

System

State M

Status M

M: Mandatory, Empty: not used

For details on how to use the Values field for pick lists, Boolean, state and status fields see the

corresponding section below.

System attributes

Certain system attributes exist such as createdon, statecode and ownerid. These attributes can be

updated using the bulk create sheet in the same way other attributes are. Use the following data

types:

DateTime: Createdon, modifiedon

State: statecode

Status: statuscode


System: Createdby, modifiedby, ownerid, the primary field of the entity and base fields for

money attributes.

Money fields

When CRM creates a money attribute this always creates two fields in the database one for the value

based on currency selected on the entity and the other for the system base currency. This base field

can also be modified using the bulk create feature. However the options are limited to updating the

display name, description and advanced find option. The base field is typically named

<fieldname>_base. If such a field already existed when the money field was created the name could

be different. When including these fields in the bulk create sheet, you must specify them after the

base money field otherwise the process will not be able to process the field.

Option sets (pick list, boolean, state and status fields)

For these field types a list of values should be specified. For picklists and boolean attributes you can

choose to specify the values in the values column or on the option sets sheet.

The easiest way is to specify the values directly in the ‘attributes sheet’. This is useful for simple lists

containing a limited number of values. Using this method you can specify the label, order and

associated numeric values but not a description or use global option sets.

If you have a longer and more complex list you should specify the values in the ‘option sets sheet’

To do so you have to make a reference from the ‘attribute sheet’ to the ‘option set sheet’ This is

done by putting the name of the option from the ‘option set sheet’ into the value column of the

‘attribute sheet’ prefixed with a hash symbol (#). For example if your list was named ‘mylist’ on the

option set page the values column in the ‘attributes sheet’ should contain ‘#mylist’.

The following section explains the rules for option sets and apply to both option set values defined

on the option set sheet and those specified inline on the ‘attribute sheet’.

Each option item is separated by a pipe-symbol (|). For example ‘Item A|Item B|Item C’ specifies a

list with three values. No explicit numeric values are assigned ‘Item A’ will automatically receive

numeric value 1, ‘Item B’ value 2 and ‘Item C’ value 3.

There is also the option to give explicit value numbers to the option set labels. To assign numeric

values add the numeric value followed by a colon in front of the label. For example ‘4:Item A|5:Item

B|200000:Item C’ would create a list containing three items with numeric values 4, 5 and 200.000

labelled Item A, Item B, Item C.

Items are ordered in the order they were typed in the field. The piclists are not are not sorted

numerically or alphabetically by either value or label.

For boolean fields the list must contain exactly two items with numeric values 0 and 1. If no explicit

numeric values are specified the first item is used for the false option and the second for the true

option. For example if the values field contains ‘No|Yes’, the false option will have label ‘No’ and the


true option label ‘Yes’. You could also choose to provide numbers like ‘1:positive|0:negative’ in that

case the order is unimportant.

When updating an existing picklist attribute any values not in the new list will be deleted. The order

of the values will be reset to the ones specified in the bulk create sheet. So be very careful with this

especially if there is data in the database.

Relations sheets (1:N and N:M)

The relation sheets allow you to define one-to-many and many-to-many relationship. Note that a

many to one relationships should be created using a one to many.

The relation name fields are optional. If these are empty, they are automatically filled based

on the prefix and the entity names.

If you select ‘Custom’ for the relationship cascading behaviour you need to use the detail

fields to specify the cascading behaviour. If you select Parental, Referential or Referential

Restrict Delete the individual cascading setting fields are ignored.

The display property should contain either ‘Details’, ‘Sales’, ‘Marketing’ or ‘Service’ no other

custom values are allowed

Views Sheet

The views sheet allows you to create or update views. Only for the normal (public) view types

multiple views can be defined, update of the view occurs based on the name. For the system view

types (lookup view, advanced find view, associated view etc.) only one can be defined per type, these

will always update the existing view of the same type.

Display Name

The display name of the view can be set by typing a full name or by using the following aliases:

{displayname} is equal to the entity display name or {displaycollectionname} is equal to the Plural

name.

Columns

Columns are defined by listing the names of the columns separated by a |-symbol. By default the

columns will be 100 wide. To change this width add a semi-colon follow by the width of the columns.

This width must be one of the following values 25, 50, 75, 100, 125, 150, 200 or 300. If a different

value is specified the first higher (valid) value will be used instead with a maximum of 300.

Example: ‘new_name;200|createdon;100’ is the default view for new custom entities showing the

primary attribute (in this case new_name) and the createdon field.

Search Columns

For the lookup and quick find view you can define one or more columns to add to the search filter.

Add the column names separated by a |-symbol.


Condition Filter

The Condition Filter property is only used by the associated view type. It is possible to specify

additional filters for the view. When adding a filter the fetchXML syntax should be used. Normally in

fetchXML attribute=[attribute name] is supported. In case of a Condition Filter fetchXML not,

‘column’ instead of ‘attribute’ should be used. Note: this only applies to the filter of associated views.

For example the standard filter applied to associated views:

<filter type="and"><condition column="statecode" operator="eq" value="0" /></filter>

Fetch XML

The fetch XML property defines the filter for all other views. If describe was used to prefill the values

for the properties. The fetch XML property contains the full fetchXML statement including the select

columns.

If the filter is specified manually, it is recommend to specify only the filter node in this field. Based on

the filter node Customization Assistant can build the remaining Fetch XML based on the

configuration of columns to show and search columns. This is advised to avoid mistakes in the select

part of the fetchXML.

For example the fetchxml for a standard active view:

<filter type="and"><condition attribute="statecode" operator="eq" value="0" /></filter>

For details on the Fetch Xml or filter node definition please refer to the CRM SDK.

NOTE: in the fetchXML property filter you do not use column instead of attribute like in the Condition

Filter for associated views.

Option Sets and Option Set Values sheets

These two sheets are used in pair. The ‘option sets sheet’ is used to define an option set with its

properties, this is required for all global, state and status option sets. The values sheet is used to add

values to an option sets define on the ‘option sets’ sheet..

An option set has a type (picklist, boolean, state or status). This type must match the type of the

attribute in the ‘attribute sheet’. For example a picklist attribute cannot use a boolean option set.

On the ‘Option Sets’ sheet the following properties values depend on the set type:

Default value is only used by pick lists. This must be a numeric value, which has an item

defined on the values sheet.

Global Option Set can only be set to True for sets of type picklist.

Note: It is not possible to change the global option set setting for existing non global picklists.

The display name field is only required for global option sets.

‘Can be customized’ setting only applies to global option sets

On the values sheet the following rules apply

The set name must exist in the ‘sets sheet’


Value is the numeric value of the item

For Boolean sets 0 is the false value, 1 is the true value. Other values are not valid.

Values for custom pick lists must be 1 or greater.

The values in the list in CRM will be ordered based on the row order in in the sheet and not

by the value or the label.

For state sets the invariant name and default status fields are required. An invariant name is

like an enum name value instead of a numeric value. The invariant name cannot be updated

after initial creation.

For status sets the state field is required and must contain an existing value from the state

list for the same entity.

PROCESSING THE FILE

When information was entered in the excel sheet(s), the file can be processed by customization

assistant.

Select the ‘Bulk Create’ option from the tools menu in the Customization Assistant.

Select the file to process and click ’Load’.

The application will attempt to select the sheets from the Excel work book based on their

name and/or order. Verify the correct sheets were selected.

Ensure that the correct sheets have been selected.

Optionally select the types of items to

process

The auto prefix option will automatically

prefix any new entity, field or relation with

the specified prefix. This will only happen if

the name value of the attribute,

relationship or entity was not provided

with a prefix.

On the existing items option select how to

handle an item that already exist in CRM

o Update; (Limited Properties)

This option will update all

properties that can be updated

with the values from the sheet.

o Skip; Continue with next item

This option will only create items that do not exist, but does not update existing

items. Note: as an exception views are always processed even if they already exist.

o Error; do not continue

When Customization Assistant bulk sheet processor runs into an item that already

exists, the process will be abort during the validation stage and nothing is processed.

If the publish all option is selected then at the end of the processing all items are published

automatically after processing. Note that some updates (specifically when connected to CRM

4.0) require the items to be published before they are updated.


Click OK to start

Processing consist of three phases, first the data from the sheet is read and validated. If the sheet

values are valid, second the data is validated against the CRM data model. If an error occurs during

either of these two stages, the processing will be stopped and all errors are shown in the dialog. If

during this phase warnings only were found, the processes is paused and the user must confirm to

continue before the changes will be applied.

Once processing starts changes shall be applied to the CRM data model. If an error occurs for

example the connection fails, the changes applied before that point will not be rolled back. After the

error condition is resolved, the process can continued or restarted to complete all the steps.

Create or Update

When the Excel sheet is being processed by the Customization Assistant Bulk Sheet Processor, the

system will automatically determine if the item has to be created or updated. Certain field cannot be

updated: for example the attribute type. Depending on the field if the value in the sheet is different

from the current value in CRM the validation checks will either show a warning or error message that

tells if the property can be updated or not.


THE CUSTOMIZATION ASSISTANT FUNCTIONS

DESCRIBE

Related to the bulk create feature is the describe feature, this will allow you to generate an Excel file

from the CRM entity model. This file can be used by the bulk create feature. This is particularly useful

if you need to modify several attributes on an existing system.

To use the describe feature:

Select one or more entities (using the Shift or Control Keys) in the Customization Assistant

Right click on the select entities

Click Describe

Select the location to save the file

Click Save

The resulting describe file can be used to document the CRM system or used as a basis for updating

the system.

NOTE: It is recommended to update the Saved View filters if you are planning to use the Excel sheet

to do modification to the views. The describe function includes the full fetch XML in the Fetch XML

column. For ease of use when modifying a view it is recommended to put only the filter node in this

field. This allows the Customization Assistant to automatically update the display columns as needed.

The full fetch XML is include by the describe function to support any customizations made outside

the scope of the Customization Assistant.


DELETE ATTRIBUTES

With the Customization Assistant you can delete one or more attributes in one action per selected

entity. Also you can remove the attribute from existing views and/or forms with one checkbox: ‘force

delete from forms or views’. When checked the Customization Assistant will first check existing forms

and views and attempt to delete the attribute from them before deleting it from the metadata. For a

full list of dependency types that can be detected and deleted see the section Dependency Types.

Using this method to delete attributes will not delete the attribute from plugin image registrations,

workflow, etc. If these are expecting any of the deletion of the attributes may fail to execute.

CHANGE DATA TYPE

The change data type option allows you to change the data type from an attribute to a different type

for example a decimal attribute can be changed to money. When doing this, the field remains on the

existing forms and views and you have the option to retain the data stored in this fields data records.

For a full list of dependency types that can be detected and restored see the section Dependency

Types.

When making changes to the data type, data may be lost for example when changing a decimal to an

integer any values behind the decimal point will be lost. Some conversions are not possible for

example the change from string to integer will only succeed for the data that contains valid numeric

values. See the table below for possible conversions. These only apply if data type is converted with

the option to keep the data. Conversion of the field type without data can occur between any type.


To:

From: Stri

ng

Mem

o

Bo

ole

an

Op

tio

n S

et

Inte

ger

Dec

imal

Mo

ney

Do

ub

le

Dat

e Ti

me

String Yes Yes Map Map C C C C No

Memo Yes - Map Map C C C C No

Boolean L L - Map V V V V No

Pick list L L Yes - V V V V No

Integer F F Map Map Yes Yes Yes Yes No

Decimal F F Map Map R - Yes D No

Money F F Map Map R Yes - D No

Double (float) F F Map Map R D D - No

Date Time F F Map Map No No No No -

Yes: can be converted without data loss

Map: Existing values are mapped to new pick list items. These can be user defined or

automatically generated based on unique values

C(onversion): This occurs using a conversion. This is only possible if the existing data in the

field conforms to local formatting for the target data type. Invalid value may be lost during

conversion

R(ound): This value will be rounded during conversion

D(ecimal): This conversion will retain the decimals but may lose precision.

F(ormat):During this conversion the value will be formatted according to standard

localization settings based on culture of the system the Customization Assistant is running on

L(abel): Pick list/Boolean conversion to text will use the label of the selected item

V(alue): Pick list/Boolean conversion to numeric will use the value associated with the

selected item.

No: Conversion of data is not possible.

To change the data type:

Select the attribute to change the data type for.

It is possible to select multiple attributes even if they have different types. All selected


attributes will be converted to the same target type.

Select the target data type and enter any additional properties depending on the target data

type.

Select if you want to retain the data for the fields to convert. You can select “keep data”

which will automatically copy the data using the CRM web services and standard conversions

as indicated in the table above.

With the option “copy manually” you can use another application or tool to perform the

conversion of the data. An SQL statement is shown to shown what needs to be converted. Do

note that direct modification of data in the CRM database is not supported.

The last option “Do not keep data” will simply replace the old data type with the new type

and remove any data present.

Click OK to start the process

First the conversion will be validated. If the option to keep data is selected, a check is

performed to see if the data can be converted. This is done on a sample of the data and only

provides an indication whether the conversion is possible.

After the sample validation, the process will start.

It is highly recommended to have a current export of the customization settings and/or a full

backup of the database before you change a data type. If the process fails during the conversion

process it may not be possible to recover without a proper CRM database backup.


MAPPING

If a conversion is made to a picklist, a mapping needs to be specified.

In the options section the new picklist labels and values should be specified.

In the mappings section the mapping between original values and new picklist values can be created.

The auto generate button will try to retrieve all existing options.

CONVERT TO/FROM RELATION

The convert to and from relation operations allow you to change and option set field to a

relationship and a relationship to an option set. During this process the values will be retained and

the fields will remain on the forms and views. For a full list of dependency types that can be detected

and restored see the section Dependency Types.

To change an option set to a relation:

Select the option set attribute to convert


Enter the name of the option set attribute (must be different from the lookup attribute

name)

If the source entity has an integer field you have the option to use that value as the option

set value. Otherwise it will be automatically generated

Select the options if the lookup attribute and the referenced entity should be deleted after

the conversion.


To change a relation to an option set:

Select the lookup attribute to convert

Select the entity the lookup should use.

Select the attribute in which to store the label (default language)

Optionally select an integer attribute in which to store the option set value

Enter the name of the lookup attribute and relation

RENAME

The rename option allows you to change the logical name of a custom attribute. When doing this,

the field remains on the existing forms and views and you have the option to retain the data stored

in this fields data records. For a full list of dependency types that can be detected and restored see

the section Dependency Types.

To rename an attribute:

Select the attribute to rename

Enter a new name for the attribute

Select if data should be retained

CHANGE PROPERTIES

The change properties option allows you to change properties of attributes in bulk. These are the

same properties that can normally be changed using the CRM user interface.

When changing properties for a single attribute the fields will contain the current values for the

properties. The properties enabled, are dependent on the attribute type. For example a string value

does not have a maximum property.


When changing properties for multiple attributes at once, the fields will not contain current value. If

the attributes are of the same type only those properties which can be set will be enabled. If the

attributes are from different types all properties are enabled, for each attribute only those properties

which apply, shall be updated. To change the value for an attribute you need to tick the box in front

of it. Only those properties for which the box has been ticked will be updated. Other properties will

not be changed.

COPY ATTRIBUTES

With copy attributes you can copy one attribute multiple times to the same entity, or copy one or

more attributes to a different entity. Copying includes all the attribute properties such as

requirement level, data type and minimum and maximum value. Data or configuration of forms and

views are not copied of course.

When you select a single attribute you have the option to copy the attribute to the same entity or to

a different entity. You can select to copy it once to a different entity or to the same entity using a

different name. By setting the count property to a value other than 1 you can copy the same

attribute multiple times. Each copy must contain a number to make the name unique. By default the

name is added to the end of the attribute name (“_<number>” for the logical name “ <number>” for


the display name). You can determine the location of the number by using “{0}” for example

“new_{0}_test” with count two and start five will result in two attributes “new_5_test” and

“new_6_test”.

The relation attribute is only available and required if the attribute being copied is a relationship.

When you select multiple attributes at once, you only have the option to copy them to another

entity. They will keep the same name.

NOTE: If you need to copy attributes using a more complex naming scheme you may want to

consider using the describe and bulk create feature. Use describe to export the attribute to excel,

copy and rename it in Excel according to your specifications and use the bulk create feature to

import the changes into CRM.

DEPENDENCY TYPES

For certain operations provided by the Customizations Assistant it is required that fields are deleted

from CRM and restored at a later point typically because of a metadata change. The Customization

Assistant has support for most of the dependencies present in CRM 2011. Depending on the

component type support for different operations may vary according to the listing below

The dependency capabilities listed here only apply when connected to CRM 2011. For CRM 4.0 only

fields used on forms, in views and relation attribute maps are supported. Other dependencies will

not prevent the fields from being deleted. However if a field is deleted or its type is changed then

dependencies such as workflows and plugins may cause errors if they use the changed field.

The listing below only applies to custom, unmanaged attributes. The dependency component must

also be customizable. This can be a custom component or the managed property Is Customizable

must be true.


Dependency types not listed in the table below are not supported for delete and/or restore. During

validation an error including available details of the dependency will be shown. Any dependency

causing a validation error must be manually resolved before the process can be completed

Operation:

Dependency Type: Ren

ame

Del

ete

Ch

ange

Dat

a Ty

pe

Co

nve

rt t

o/f

rom

re

lati

on

Attribute Map Yes Yes D D

View

Fields: columns and filter conditions1)

Yes Yes Yes1) Yes1)

Form

Fields: Field controls, Dependencies

Yes Yes Yes Yes

Form

Fields: Left Navigation, Sub grids

Yes Yes D D

Plugin Step

(SDK Message Processing Step)

Yes Yes Yes Yes

Plugin Step Image

(SDK Message Processing Step Image)

Yes Yes Yes Yes

Chart2) Yes Yes Yes3) D

Workflow No No No No

Yes: Can be deleted and restored if applicable

No: Cannot be deleted, this will cause an error during validation the operation cannot be

executed.

D: Can be deleted but not restored, this will generate a warning during validation

Yes/D: For charts restore is supported for the aggregated attribute only 1) Depending on the filter and data type change views may no longer function following a data

type change. 2) For Charts the existing record is deleted and a new chart created with the updated details,

the solution reference may be lost 3) For Charts the aggregate operation on the attribute being changed will be changed to count

if the new attribute type is not numeric and the existing operator is sum, avg, min or max.

Besides the dependencies registered by CRM there are other dependencies to consider. These

include JavaScript used on forms, application using the CRM web services, Ribbon definitions and

others. These dependencies are not updated because there is no reliable method of achieving this.

As these dependencies are not registered in CRM the validation will not be able to report these, such

dependencies must be checked and corrected manually.


APPLY CHANGES TO OTHER SYSTEMS I you need to repeat changes made using the Customization Assistant on other systems such as when

making changes on a development environment and then move them to UAT and production. Or

provision an update of your vertical solution to your customers. You can do this using the replay

option in the Customization Assistant.

The replay option automatically tracks changes you make using the Customization Assistant and

stores the into memory such as which action and which attributes. The action can then be repeated

in the same order and with the same settings. All validations and the execution will be repeated.

If needed you can save these changes to a file and then import and execute them using a

Customization Assistant running on a different system.

Note: changes are version specific it is not possible to replay CRM 4.0 changes on a CRM 2011

system. The automatic change history stores these changes in separate files.

Saving changes:

Perform the changes as described in the sections above using the customization assistant

functions or bulk create option.

From the start menu select Save Change file

Select the changes you wish to save

Click save

Name the file

Click ok

Load changes from file

Note: changes executed on the same system are saved in and loaded automatically. Changes are kept

for 2 months.

From the file menu select load change file

Select the file

Click open


Changes have been loaded

Replay Changes

From the file menu select replay changes

From the list select the changes you wish to replay

Click replay

The system will automatically perform all the validations and unless any errors occur,

execute the selected steps.


WARNING Customization Assistant gives the ability to execute and deploy customizations to Dynamics CRM

much faster and advanced, than possible in the customization options provided by the standard

options in Dynamics CRM. That great power comes with the responsibility to think carefully before

usage. Please, make a proper Dynamics CRM database backup before the execution of any changes

to your Dynamics CRM installation using Customization Assistant.

Wavextend does not hold responsibility for damages done to your CRM implementations using

Customization Assistant nor does it provide any warranties.

© 2012 WaveXtend B.V. All rights reserved.

customization assistant user guide

Documents