data manipulation framework user guide

35
DATA MANIPULATION FRAMEWORK USER GUIDE Basic configuration for version 2011

Upload: others

Post on 02-Oct-2021

1 views

Category:

Documents


0 download

TRANSCRIPT

Page 1: DATA MANIPULATION FRAMEWORK USER GUIDE

DATA MANIPULATION FRAMEWORK USER GUIDE

Basic configuration for version 2011

Page 2: DATA MANIPULATION FRAMEWORK USER GUIDE

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.

© 2011 Wavextend B.V. All rights reserved.

Page 3: DATA MANIPULATION FRAMEWORK USER GUIDE

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

VERSION

This version of the user guide for Data Manipulation Framework is valid for Dynamics CRM 2011 On

Premise in combination with Wavextend Data Manipulation Framework 5.0 on premise only. There

are different user guides per version available on the Wavextend website: www.wavextend.com

The target group for this guide consists of application consultants that are unfamiliar to Wavextend Data Manipulation Framework or power users that will perform simple calculation configuration without assistance of their implementation partner. In either way you are encourage you to take the Microsoft course on Microsoft Dynamics CRM 2011 Customization and Configuration (MB2-866) because it will significantly improve your understanding of the Data Manipulation Framework options.

In addition to this manual there is an ‘Advanced Data Manipulation Framework configuration’ guide which will introduce you in the endless possibilities of complex calculations and automations, dives into deploying calculation configurations on different servers and provides tips for issue tracking.

Reading the two guides will give you a profound background to professionally use Wavextend Data Manipulation Framework and provide the power to reduce much of the .NET and Javascript coding for Dynamics CRM.

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 the Wavextend website. People who send feedback will be automatically notified of the availability of new versions until an unsubscription request is received.

Page 4: DATA MANIPULATION FRAMEWORK USER GUIDE

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

TABLE OF CONTENT

Copyright ................................................................................................................................................. 2

Version ..................................................................................................................................................... 3

Table of content ....................................................................................................................................... 4

Introduction ............................................................................................................................................. 5

How to configure a simple calculated attribute ...................................................................................... 6

A single entity calculation.................................................................................................................... 9

An aggregated calculation ................................................................................................................ 19

A value copy....................................................................................................................................... 24

How to execute a calculated attribute .................................................................................................. 27

Run a calculated attribute manually ................................................................................................. 27

Monitor execution result ................................................................................................................... 28

Execute a schedule ............................................................................................................................ 31

Page 5: DATA MANIPULATION FRAMEWORK USER GUIDE

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

INTRODUCTION Thank you for trying, or better buying, Data Manipulation Framework from Wavextend. This user

guide will lead you through the basics of calculation configuring. After reading this user guide you will

be able to:

1. Configure basic calculated attributes

2. Test your calculated attribute

3. Execute a calculated attribute

4. Schedule a calculated attribute

With these new skills you will be able to perform most common tasks and configurations in Data Manipulation Framework. As a result you will have gained the power to significantly expand the possibilities of Dynamics CRM. Some examples are:

Customer segmentation and customer value calculations

Relation-roles

Customer reports

Performance Management

International address lines and salutation headers

International phone number formatting

Order and or case invoicing

This guide assumes you were able to install Data Manipulation Framework on your Dynamics CRM server, or better, had someone else to do it for you. You can find more information on how to install Data Manipulation Framework on the website: www.wavextend.com. Make sure you have the ‘Wavextend: User’ or ‘Wavextend: Administrator’ role.

In all examples the standard Microsoft “Sample database” is used which is available for installation from within Dynamics CRM 2011 itself. Note: See the installation manual for Dynamics CRM 2011 for further instructions on how to install the sample database.

Some custom attributes were added to this sample database for example purposes.

Page 6: DATA MANIPULATION FRAMEWORK USER GUIDE

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

HOW TO CONFIGURE A SIMPLE CALCULATED ATTRIBUTE The first step in configuring a calculated attribute is to find it in the user interface. To do so you will

need to go to:

Settings -> Wavextend > Calculated attributes

Figure 1: Screenshot of Calculated Attributes in Dynamics CRM.

Of course this works in a similar way in the Outlook client. Depending on your previous activity or

that of your colleagues, you will have none or more preconfigured calculated attributes in the list.

The second step is to hit the ‘New’ button and open up a new calculated attribute form that will look

like the following:

Page 7: DATA MANIPULATION FRAMEWORK USER GUIDE

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

Figure 2: Screenshot of new calculated attribute form

You are recommended to give your calculated attributes descriptive names, so it is easy for you to

find them in the big list you might end up with. Maybe there is a naming convention in your

organization you will need to be aware about, or should be considered.

The description field will provide more room for descriptive info like the purpose or usage of the

calculation.

NOTES:

1. The processing order field could be relevant for scheduling but explanation is left for the

‘scheduling’ chapter.

2. The purpose of the unique identifier field is for usage in on from calculations and plugin

calculations and explanation of the usage is therefor left for the advanced guide. For now,

you need to be aware that this name should be unique. Data Manipulation Framework will

suggest a unique name based on the descriptive name but there is a chance this name is

already used by other calculated attributes. If it is not unique, you will be warned about this

on save. Feel free to change it to any other name you like as long as it is not used by other

calculated attributes.

The third step is to determine the type of calculation. The type will be determined by the expected

use of other attribute values in Dynamics CRM and their relation with the target attribute.

Page 8: DATA MANIPULATION FRAMEWORK USER GUIDE

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

The target attribute is the attribute in the Dynamics CRM domain model where you wish to store the

results of the calculation.

You will have three options:

1. Single Entity Calculation

Use a single entity calculation in case you expect to only use attribute values belonging to the

same entity as the target attribute (the current entity) or if you plan not to use other

attributes values at all (like setting default values).

2. Aggregated Calculation

Use aggregated calculation if you plan to use attributes of ‘downstream’ entities having a

direct 1:N or N:N relationship with the current entity and perform aggregation calculations

on them like averages or summations.

3. Value copy

Use value copy if you plan to use attributes in your calculation from ‘upstream’ entities (or

lookups) in relations to the current entity. The most common use is to copy values like a

phone number from a customer to the opportunity or case. But of course you will have the

option to do more advanced logic as well.

In the following section you will see an example of all three types of calculations and their

steps.

Page 9: DATA MANIPULATION FRAMEWORK USER GUIDE

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

A SINGLE ENTITY CALCULATION

To create a simple calculation please select the type ‘Single Entity Calculation’ and the screen will

show all the relevant fields for this type of calculation looking similar to the following:

Figure 3: Screenshot of a ‘Single Entity Calculation’

In this example two new custom attributes were used that were added to the order entity. One

named cost price and the other called margin. Both attributes were placed on the main form and

margin was made read only as will be the case in most ‘target’ attributes. A couple of records were

created to be sure there are some test results.

TIP: Put something in the description field of an attribute that will say it’s a calculated attribute.

Configuring any calculation will require six steps:

1. Give it a name, description and type (‘Single Entity Calculation’) 2. Specify the target 3. Specify an optional source 4. Specify the calculation 5. Save your configuration

Page 10: DATA MANIPULATION FRAMEWORK USER GUIDE

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

6. Test the calculation

NOTE : If the target entity list is empty, please make sure to run the meta data synchronisation. If

custom added entities and or attributes do not appear in the list, run the meta data synchronisation

again. It will update the lists with entities and attributes. Please refer to the installation and

operations guide for more info on how to run the meta data synchronisation.

The target section allows specification of where the result of the calculation should be stored. Start

with selecting the correct entity. In this example choose ‘Order’.

Figure 4: Selection menu for target entity.

Next, select the target attribute where the result of the calculation will be stored. In this example,

the custom attribute ‘Margin’ was selected.

Page 11: DATA MANIPULATION FRAMEWORK USER GUIDE

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

Figure 5: Selection menu for the target attribute.

NOTE: Only select attributes with a ‘Present’ status reason, because others will fail the calculation.

The following step is optional and allows you to set a limit to the scope for the target records. For

example: only orders with an amount (not null) or only order of this year. To do so you will have to

prepare a ‘saved view’ using the standard advanced find in Dynamics CRM. You can find loads of

information on how to use the advanced find in materials from Microsoft or on the web so this topic

is not further discussed in this guide.

Page 12: DATA MANIPULATION FRAMEWORK USER GUIDE

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

Figure 6: example of a saved advanced find query

You can create or select this view as a filter under the ‘Target Filter’ lookup button.

To do so:

1. Click on ‘target filter’

2. Click on ‘New’

3. Give the filter a descriptive name (you might reuse it later for other calculated attributes)

4. Make sure to choose type ‘User Query’

5. Select the Saved advanced find view as an ‘existing view’ that contains your filter criteria

6. Click ok

7. Make sure to select the earlier created filter, or create a new advanced find view from here

8. Click ok

Page 13: DATA MANIPULATION FRAMEWORK USER GUIDE

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

Figure 7: Creation of a target filter using a shadow view

You will only be able to see your own saved views or those shared with you.

The custom target filter is not further discussed in this guide but saved for the advanced guide.

The third step is to define a source for those calculations that will use other attribute values in the

calculation. This applies to most every calculation except for those where you have the intention to

set the target attribute with a static default value. How to set a static default value is demonstrated

in the last part of this chapter.

The source section contains those attribute you would like to use as variables in your calculation

expression. A single entity calculation is configured, so you should choose attributes coming from the

current entity (same as target attribute entity). In this example ‘Order’. The calculation used to

calculate margin in this example is:

Margin = Total Amount – Cost price

So in the source section two source attributes are chosen, being Total Amount and Cost price, both

belonging to the Order entity. Your calculation should now look similar to this:

Page 14: DATA MANIPULATION FRAMEWORK USER GUIDE

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

Figure 8: Source section

The final step in calculation configuration is to set the calculation operator in the calculation section.

In this example it is set to: ‘Subtract’

Wavextend Data Manipulation Framework supports the following calculation operators for Single

Entity Calculations:

1. Add (only numeric data)

2. Subtract (only numeric data)

3. Multiply (only numeric data)

4. Divide (only numeric data)

5. Custom SQL (all data types)

6. Expression (all data types)

And hit ‘Save’ to store your calculation configuration to be able to test it and run it.

The result of this calculation configuration is as follows:

[Target Entity].[Target attribute] = [Target Entity].[Source Attribute 1] – [Target Entity].[Source Attribute 2]

And it will only do this for the target records that are returned from the [Target Filter] view.

To see the result of the calculation (without updating data in the Dynamics CRM database) you hit

the ‘Execute Test‘ button in the calculation test section.(only appears after saving of your

calculation).

Page 15: DATA MANIPULATION FRAMEWORK USER GUIDE

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

As result you can now see a pro forma calculation for your configuration. The result section allows

you to open records directly from the test list by clicking on the names of the result records. The

‘Changes Only ‘checkbox will filter the results changed results where Old Value and New Value is

different. Make sure to hit the ‘Execute Test’ again after ticking the ‘Changes Only’ checkbox.

Figure 9: Test result

The test result will only display records that were selected as result of the ‘Target Filter’ and shows

the changes that would be made to the database in case you would execute the calculated attribute.

The first column shows the primary attribute of the ‘Target Entity’, the second column contains the

value of the ‘Target Attribute’ before update and the third columns contains the value of the ‘Target

Attribute’ after update.

The ‘View Statement’ button is an advanced topic and not further discussed in this guide. Please

refer to the ‘Advanced Guide’ for more info.

Congratulations, you have now configured your first calculated attribute. Before you execute it (look

in the execution chapter) here are some important things to remember:

NOTES:

1. When a value changes as a result of the execution the text in the calculation test

window will be black, otherwise grey.

2. In case the result of the calculation fall out of boundary, (min, max or size property

of the target attribute) the ‘New Value’ will turn red.

3. If you choose incompatible source attributes data types (like subtracting string values

to return a money attribute) you will receive an error messaging saying the ‘Operand

data type ……. is invalid for subtract operator.’ or ‘Specified cast is not valid.’

Page 16: DATA MANIPULATION FRAMEWORK USER GUIDE

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

In addition to configure a calculation you can also use Single Entity Calculation to set a static default

value. There are two scenarios where you should consider this. The first is when you create a custom

new attribute with a default value in a database that already contains data. Dynamics CRM will fill

the default value for all new records but existing records will have empty values. In that case a

calculated attribute with a corresponding static default value, executed once, will help you. The

second scenario is when you want to set conditional values. Such a case is shown in the next

example.

In this example the purpose is to set the ‘relation type’ attribute of an account to ‘customer’ in case

an account has an order submitted in the past with a positive amount.

The first step in doing so is to prepare an advanced find view that filters all accounts that have an

order submitted in the past with a positive amount.

Figure 10: Advanced find view preparation query

You save this view with a descriptive name like ‘Accounts with order’. This view is selected in the

configuration as the ‘Target Filter’ using a shadow view as explained in the previous paragraph

Now configure a calculated attribute like in the following screenshot:

Page 17: DATA MANIPULATION FRAMEWORK USER GUIDE

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

Figure 10: Example configuration of a conditional default value.

As you will see in the screenshot, no source attributes were used and as a ‘Calculation Operator’

‘Expression’ is selected. The ‘Custom Calculation’ field will contain the default value. In this case

which corresponds with the value of the picklist of relationship type ‘customer’.

NOTE: You can either choose ‘Expression’ or ‘Custom SQL’ as Calculation Operator. Custom SQL was

the only option in Data Manipulation Framework 4.0 and was then just called ‘Custom’. For single

Page 18: DATA MANIPULATION FRAMEWORK USER GUIDE

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

entity calculations Data Manipulation Framework 2011 on premise supports both Custom SQL as well

as Expressions, which is similar to Microsoft Excel® formulas and supports the same syntax (in

English). In Dynamics CRM Online the only option is Expressions. So, for compatibility reasons this

option is preferred above Custom SQL.

The test result window now looks as follows:

Figure 11: Test result window of conditional default value

Page 19: DATA MANIPULATION FRAMEWORK USER GUIDE

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

NOTES:

1. All the available expression formulas are explained in help file which can be found by

clicking the ‘Expression Help’ button on the ribbon.

2. To set an unconditional default value, just leave out the ‘Target Filter’

3. Hierarchical conditions can be accomplished using two different calculated attributes

in the right order which is show in the Scheduling chapter. For example: An account

with opportunities is a prospect unless the account also has an order which makes it

into a customer.

4. Notice you are not limited to calculate set numeric or money fields, but also picklists,

dates, string values and even lookups.

5. To set the default value of strings enclose the string with single quotes like ‘default

value’

AN AGGREGATED CALCULATION

The second type of calculation configuration to show is an aggregated calculation. An aggregated

calculation comes in handy for all those scenarios where you:

1. Want to see a total on a form, like number of complaints for this customer on the

account form.

2. Want to filter on a total in an advanced find, like select all customers that spend

more than x this year or select all customers that had no orders this year.

3. Want to export a total for book keeping for instance, like: export the total amount to

be invoiced for this case based on the hours spend on the service activities multiplied

by the rate of the resource.

4. Set a conditional branch in workflow based on a total like ‘if the total amount for this

customer this year is more than x and the customer puts in a complaint, please call

the customer right away otherwise send an excuse letter’.

All these and many more scenarios are made possible in Dynamics CRM exclusively using

Wavextend Data Manipulation Framework.

To configure an aggregated calculation you need to perform the six following steps:

1. Give it a name, description and type (‘Aggregated Calculation’) 2. Specify the target 3. Specify a source 4. Specify the aggregation calculation 5. Save your configuration

Page 20: DATA MANIPULATION FRAMEWORK USER GUIDE

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

6. Test the calculation

One and two are skipped because, except for to the type, they are exactly the same as the

previous chapter. The difference starts with the source.

In the source section, you need configure the following in corresponding order:

1. The ‘Source Entity’. This is the entity where the data used in the aggregation

calculation will come from. For example order.

2. The ‘Relationship’. You will need to specify which relationship (1:N or N:N) will

apply to the ‘Source Entity’ and ‘Target Entity’. Most of the time there is only

one valid relationship like the order_customer_accounts relationship for

example. In some cases there will be more than one relationship available and

you will need to choose the right one. Look in the customizations configuration

and the descriptions for more info on which relationship to choose.

3. The ‘Source Attribute 1’ to specify which attribute should be used in the

aggregation and belongs to the ‘Source Entity’

4. Optionally a ‘Source Filter’ like only orders submitted this year to ensure only

year to date orders are aggregated.

Figure 12: Source configuration for aggregated calculation

‘Custom Source Filter’ is skipped for explanation until the advanced guide.

In the calculation section you can specify which type of aggregation has to be performed on the

‘Source Attribute 1’. To do so, select the appropriate aggregation option in the ‘Aggregation

Operator’ list of options.

Page 21: DATA MANIPULATION FRAMEWORK USER GUIDE

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

Figure 13: Aggregation Operator selection

Here is an explanation of the different options:

1. Sum, will add up all found values of the ‘Source Attribute 1’ belonging to the

same ‘Target Entity’ records in relation to ‘Relationship’ optionally filtered by

‘Source Filter’

2. Average, will add up all found values of the ‘Source Attribute 1’ belonging to the

same ‘Target Entity’ records in relation to ‘Relationship’ optionally filtered by

‘Source Filter’ and divide it by the number of found values.

3. Maximum, will pick the largest value out of all found values of the ‘Source

Attribute 1’ belonging to the same ‘Target Entity’ records in relation to

‘Relationship’ optionally filtered by ‘Source Filter’

4. Minimum, will pick the smallest value out of all found values of the ‘Source

Attribute 1’ belonging to the same ‘Target Entity’ records in relation to

‘Relationship’ optionally filtered by ‘Source Filter’

5. Count, will count the number of records found belonging to the same ‘Target

Entity’ records in relation to ‘Relationship’ optionally filtered by ‘Source Filter’

6. Count distinct, will count the number of unique values found of the ‘Source

Attribute 1’ belonging to the same ‘Target Entity’ records in relation to

‘Relationship’ optionally filtered by ‘Source Filter’

7. StdDev, will first add up all found values of the ‘Source Attribute 1’ belonging to

the same ‘Target Entity’ records in relation to ‘Relationship’ optionally filtered

by ‘Source Filter’ and divide it by the number of found values and second adds

up the difference of all found values of the ‘Source Attribute 1’ with the result of

the first step and divide it by the number of found values. In other words a

standard deviation or average difference calculation.

8. Custom SQL (called Custom in 4.0), will allow you to use default values or

advanced TSQL statements that are discussed further in the advanced guide.

Page 22: DATA MANIPULATION FRAMEWORK USER GUIDE

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

NOTE: Not every aggregation calculation is applicable to all data types. The following table shows

which aggregation is dependent on the used data type:

Sum only numeric data types and money data types

Average only numeric data types and money data types

Minimum all data types

Maximum all data types

Count all data types

Count distinct all data types

StDev only numeric data types and money data types

Custom SQL all data types

Page 23: DATA MANIPULATION FRAMEWORK USER GUIDE

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

Now let’s have a look at a typical example of an aggregated calculation configuration:

Figure 14: Example of aggregated calculation configuration.

In this example the following is calculated:

[Account].[Annual Revenue] = SUM([Order].[Total Amount]) where [Order].[Date Submitted] equals

‘This year’ and [Account] is related to [Order] through the[order_customer_account] relationship.

NOTES:

1. You are permitted to combine ‘Target Filter’ and ‘Source Filter’. The first will

determine the scope of the records to be updated and the second will determine

the scope of the values used in the calculation.

Page 24: DATA MANIPULATION FRAMEWORK USER GUIDE

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

2. More complex aggregation calculations are possible of course but leave two

options. Either choose to read and learn from the ‘Advanced Guide’ and use

Custom SQL, or break up the calculation into multiple separate simple

calculations and execute them in the right order as discussed in chapter

‘Scheduling’.

A VALUE COPY

A ‘Value copy (N:1)’ type of calculation is used when attributes coming from an ‘upstream entity’ (or

Lookup as they are called in Dynamics CRM) are used in the calculation. In most cases this is used to

copy values from an upstream entity, similar to a mapping in the relationship configuration of

Dynamics CRM. The big difference between a standard Dynamics CRM mapping and a value copy is

that it can be used after initial creation of the record and it does not matter if the relationship was

created from 1 to N or from N to 1.

Some examples of scenarios:

1. Copy the customer’s phone number on every running opportunity every time the

customer contact data is updated.

2. Copy the type of support contract from a customer to the case every time a new case

is created or on running cases when the type of contract on the customer is updated.

These examples and many more mappings are made possible in Dynamics CRM exclusively using

Wavextend Data Manipulation Framework.

The explanation on how to create custom aggregations with value copy calculations is saved for the

‘Advanced Guide’. If you leave the ‘Custom Aggregation’ field blank, the value copy will just copy the

selected 'Source Attribute 1’ into the ‘Target attribute’

Here’s an example of a valid ‘Value copy (N:1)’ calculation:

Page 25: DATA MANIPULATION FRAMEWORK USER GUIDE

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

Figure 15: Example of value copy calculation

This example will copy the value of the [Account].[Address Phone] into the

[Opportunity].[Description] field where [Account] is the customer lookup for [Opportunity]

NOTES:

1. The data types of ‘Target attribute’ and ‘Source Attribute 1’ will need to be

compatible.

2. These value copies look similar to relationship mappings in Dynamics CRM but are

very different. A mapping in Dynamics CRM is only called on creation of a related

Page 26: DATA MANIPULATION FRAMEWORK USER GUIDE

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

entity. (like create opportunity from account). This makes it a static mapping and is

limited to creation from the account form. It will not be updated after initial creation

of the related entity and is not updated upon change of the lookup. These things can

be accomplished with a value copy calculation which makes it a dynamic mapping.

Page 27: DATA MANIPULATION FRAMEWORK USER GUIDE

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

HOW TO EXECUTE A CALCULATED ATTRIBUTE In the previous chapters you learned how configure calculated attributes using Wavextend Data

Manipulation Framework. It’s now time to put you calculations to action.

To execute a calculated attribute configuration you have many different options depending on your

specific requirements or situation:

1. Execute it manually. This is for ad hoc purposes. Like setting an initial value or a

default value or for manual maintenance jobs

2. Execute it as part of a schedule. This will update a number of calculated attributes in

a batch. You will have two options:

a. Run the batch manually. b. Run the batch periodically in a predefined schedule

3. Execute the calculated attribute as part of a custom workflow. Use this option if

‘near real time’ information is important for your business. You can trigger the

calculation in two ways:

a. Run the calculated attribute for all applicable records. b. Run the calculated attribute only for a record related to the workflow record.

4. Execute the calculated attribute as a result of an onLoad, onChange or onSave event

on the entity Form.

5. Execute the calculated attribute as a result of a web service call from a custom plugin.

Manual execution is discussed in this chapter. Scheduled batch execution is clarified in the next

chapter. OnForm execution, SDK and Execution as part of workflow is not further explained in this

guide but as part of the ‘Advanced Guide’.

RUN A CALCULATED ATTRIBUTE MANUALLY

To manually run a calculated attribute you need to use a workflow.

Navigate to your list of calculated attributes and select the attributes you would like to execute. Hit

the workflow button and select the ‘Wavextend: Process Calculated Attribute” workflow.

Page 28: DATA MANIPULATION FRAMEWORK USER GUIDE

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

Figure 16: Manual execution through workflow

NOTES:

1. Running the workflow is also accessible from the calculated attribute list

2. From the list it is possible to run multiple selected calculated attributes but the order

will not comply with the order field, which is discussed in next chapter.

MONITOR EXECUTION RESULT

You have the ability to view the progress and success or failure of your execution. To do so, open up

the form of your calculated attribute and navigate to the workflow side menu.

To check if the calculation was executed properly, navigate to the log side menu, after successful

workflow execution to see the following:

Page 29: DATA MANIPULATION FRAMEWORK USER GUIDE

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

Figure 17: Logging

In this example the Customer type calculated attribute was executed three times of which the first

two times were successful and the last execution completed with error.

To find more information on the problem, open up the log record with the ‘Completed with

rejections’ or even worse ‘Errors occured’ result .

Figure 18: Log details

Page 30: DATA MANIPULATION FRAMEWORK USER GUIDE

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

CONFIGURE A SCHEDULE

The Wavextend addons for Dynamics CRM ship with a build in scheduler you can use to periodically

schedule the services provided by Wavextend addons or allows you to run a couple of dependent or

independent calculated attributes

Data Manipulation Framework is connected to the Wavextend scheduler and this allows you to

configure predefined schedules to run your calculated attributes in a batch.

This is where the ‘Processing order’ field on your calculated attribute starts playing a role. You can

give the order field any numeric value you like. The processing order field will determine in which

order calculated attributes belonging to a schedule batch will be executed. The execution process

will start at the lowest possible order value and work its way up to the highest one. This is important

if one calculated attribute is dependent on the value of another calculated attribute. Attributes

without a processing order number will be processes first.

A calculated attribute can be a member of more than one schedule, so make sure you leave enough

room between your order numbers to fit others in afterwards. The math for doing sophisticated

execution order planning is left entirely up to you. To configure a schedule you go to:

Settings -> Wavextend > Wavextend Schedules

To create a new schedule, hit the new button, configure the desired schedule and hit save.

Figure 19: Schedule example every night

Page 31: DATA MANIPULATION FRAMEWORK USER GUIDE

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

In the side tab Calculated Attributes you have the ability to add calculated attributes to your

schedule. The other way around, from the calculated attribute form, also works.

NOTES:

1. The scheduling options will be different per predefined ‘pattern’.

2. The time needs to be entered in military format.

3. The ‘Interval’ field will tell you in combination with the pattern what the time is

between execution. For example an interval of 1 means every day and an interval of

2 means every other day. As a check the next scheduled run field is provided (after

saving the schedule).

If you do not to intent to periodically execute the schedule but use it as a batch to run manually, you

can select the pattern ‘On Demand’.

EXECUTE A SCHEDULE

You have two options to execute a schedule batch:

1. Execute it manually. You do this to set initial or default values on a group of

calculated attributes at the same time ensuring the execution is in the desired order.

2. Execute it periodically. Do this for a scheduled batch run. Like automatically

executing a couple of calculated attributes every night.

Manual execution of a schedule batch is performed by running the ‘Wavextend: Execute Now’

workflow on the selected schedule.

Page 32: DATA MANIPULATION FRAMEWORK USER GUIDE

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

Figure 20: Manually run a schedule

Automatic running requires to have a valid schedule pattern with calculated attributes. The rest will

go automatically.

Execution as part of workflow is described in the ‘Advanced Guide’

NOTES:

1. Having the same ‘Processing order’ number is not a problem for calculated

attributes as long as there is no dependency between them.

2. Manual execution can take a couple of minutes depending on how busy the Async

service is on the application server

Page 33: DATA MANIPULATION FRAMEWORK USER GUIDE

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

A schedule provides logging in the logging side menu of the schedule as well as execution

information:

Figure 21: Execution information

Figure 22: Execution information

In this example you will see that both calculations were performed successfully. These log entries are

connected to the calculated attribute as well of course for further investigation (see chapter Monitor

Execution Result).

Page 34: DATA MANIPULATION FRAMEWORK USER GUIDE

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

A

Advanced Calculation Framework configuration, 3

Aggregated Calculation, 19

Aggregation Operator, 20

C

Calculation Operator, 14, 17

Custom, 17

Custom Calculation, 17

Custom Filter, 20

I

Interval, 31

O

Outlook client, 6

P

pattern, 31

Processing order, 30, 32

R

relation type, 16

Relationship, 20, 21

S

Single Entity Calculation, 9

Source Attribute 1, 20, 21, 24

Source Attribute 1’, 20

Source Entity, 20

Source Filter, 20, 21

Substract, 14

T

Target attribute, 24

Target Entity, 15, 21

Target Entity’, 20

Target Filter, 12, 15, 16, 19

Test, 14

V

Value copy, 24

View Query, 15

Page 35: DATA MANIPULATION FRAMEWORK USER GUIDE

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

© 2011 Wavextend B.V. All rights reserved.