Skip to content

Commit 0b6551a

Browse files
MrHinshMrHinsh
committed
Enhance field mapping documentation with detailed descriptions, examples, and best practices
- Updated descriptions for Field To Field Multi Map, Field To Tag Field Map, Field Value Map, Multi Value Conditional Map, Regex Field Map, and Tree To Tag Field Map to provide clearer insights into their functionalities and use cases. - Added comprehensive overviews and how-it-works sections for each field map to explain their processes and applications. - Included multiple configuration examples for each field map to illustrate practical usage scenarios. - Expanded sections on best practices, performance considerations, and troubleshooting tips to aid users in effective implementation. - Improved formatting and organization of content for better readability and understanding. - Made minor adjustments to the sample shortcode layout for consistency.
1 parent 82cad58 commit 0b6551a

File tree

13 files changed

+2355
-141
lines changed

13 files changed

+2355
-141
lines changed

‎docs/content/docs/reference/field-maps/field-calculation-map/index.md‎

Lines changed: 148 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,7 @@
11
---
22
title: Field Calculation Map
33
description: |
4-
The Field Calculation Map is a specialised field map used in the Azure DevOps Migration Tools. It allows you to compute values dynamically during migration by applying mathematical or logical operations on numeric fields. Calculations are defined using NCalc expressions and can reference one or more source fields using named parameters.
5-
6-
This is especially useful for scenarios where derived values need to be migrated, such as calculating cost based on effort and rate, or generating summary fields that are not explicitly stored in the source system.
4+
The Field Calculation Map performs mathematical calculations on numeric fields using NCalc expressions during work item migration. It allows you to compute values dynamically by applying mathematical or logical operations on source fields and storing the result in a target field.
75
dataFile: reference.fieldmaps.fieldcalculationmap.yaml
86
slug: field-calculation-map
97
aliases:
@@ -17,19 +15,159 @@ discussionId: 2756
1715

1816
{{< class-description >}}
1917

20-
## Purpose and Use Cases
18+
The Field Calculation Map is a specialised field map used in the Azure DevOps Migration Tools. It allows you to compute values dynamically during migration by applying mathematical or logical operations on numeric fields. Calculations are defined using NCalc expressions and can reference one or more source fields using named parameters.
19+
20+
This is especially useful for scenarios where derived values need to be migrated, such as calculating cost based on effort and rate, or generating summary fields that are not explicitly stored in the source system.
21+
22+
## How It Works
23+
24+
During work item processing, the Field Calculation Map:
2125

22-
This map is typically used when:
26+
1. **Validates Configuration**: Ensures the expression, target field, and parameter mappings are properly configured
27+
2. **Collects Source Values**: Retrieves values from all source fields specified in the parameters dictionary
28+
3. **Validates Field Values**: Confirms that all source fields exist and contain numeric values
29+
4. **Evaluates Expression**: Executes the NCalc expression using the collected field values as parameters
30+
5. **Converts Result**: Automatically converts the calculation result to match the target field's data type
31+
6. **Sets Target Field**: Assigns the calculated value to the specified target field
2332

24-
- You want to calculate **Custom.EstimatedCost** as `EstimatedHours × HourlyRate`
25-
- You need to **convert days to hours** or apply rounding
26-
- You wish to **assign weights** to different numeric fields and store a computed score
27-
- Your source project uses **different naming or units**, and you want to normalise during migration
33+
## Use Cases
2834

29-
## Options
35+
This field map is commonly used for:
36+
37+
- **Cost Calculations**: Computing `Custom.EstimatedCost` as `EstimatedHours × HourlyRate`
38+
- **Unit Conversions**: Converting days to hours, points to hours, or other unit transformations
39+
- **Weighted Scoring**: Applying weights to different numeric fields and storing computed scores
40+
- **Mathematical Transformations**: Applying formulas, rounding, or mathematical functions to field values
41+
- **Derived Metrics**: Creating calculated fields that combine multiple source values
42+
43+
## Configuration Structure
3044

3145
{{< class-options >}}
3246

47+
### Sample
48+
49+
{{< class-sample sample="sample" >}}
50+
51+
### Defaults
52+
53+
{{< class-sample sample="defaults" >}}
54+
55+
### Basic Example
56+
57+
```json
58+
{
59+
"FieldMapType": "FieldCalculationMap",
60+
"ApplyTo": ["Bug", "Task"],
61+
"expression": "[effort] * [rate]",
62+
"parameters": {
63+
"effort": "Custom.EstimatedHours",
64+
"rate": "Custom.HourlyRate"
65+
},
66+
"targetField": "Custom.EstimatedCost"
67+
}
68+
```
69+
70+
### Advanced Example
71+
72+
```json
73+
{
74+
"FieldMapType": "FieldCalculationMap",
75+
"ApplyTo": ["User Story"],
76+
"expression": "if([priority] <= 2, [points] * 1.5, [points])",
77+
"parameters": {
78+
"priority": "Microsoft.VSTS.Common.Priority",
79+
"points": "Microsoft.VSTS.Scheduling.StoryPoints"
80+
},
81+
"targetField": "Custom.WeightedPoints"
82+
}
83+
```
84+
85+
## Supported Expression Features
86+
87+
The [NCalc engine](https://github.com/ncalc/ncalc) supports a wide range of mathematical operations:
88+
89+
### Arithmetic Operations
90+
91+
- Basic operations: `+`, `-`, `*`, `/`, `%`
92+
- Parentheses for order of operations: `([a] + [b]) * [c]`
93+
94+
### Logical Operations
95+
96+
- Comparison: `==`, `!=`, `<`, `>`, `<=`, `>=`
97+
- Boolean logic: `&&`, `||`, `!`
98+
99+
### Mathematical Functions
100+
101+
- `Abs(x)` - Absolute value
102+
- `Round(x, decimals)` - Round to specified decimal places
103+
- `Pow(x, y)` - Power function
104+
- `Min(a, b)` - Minimum value
105+
- `Max(a, b)` - Maximum value
106+
- `Sqrt(x)` - Square root
107+
108+
### Conditional Logic
109+
110+
- `if(condition, trueValue, falseValue)` - Conditional evaluation
111+
112+
## Data Type Handling
113+
114+
The Field Calculation Map automatically handles data type conversions:
115+
116+
### Source Field Types
117+
118+
- Accepts any numeric field types (integer, double, decimal)
119+
- Automatically converts string representations of numbers
120+
- Validates that all source fields contain numeric values
121+
122+
### Target Field Types
123+
124+
- **Integer fields**: Results are rounded to nearest integer
125+
- **Double fields**: Results maintain decimal precision
126+
- **String fields**: Results are converted to string representation
127+
- **Other types**: Direct assignment attempted
128+
129+
## Error Handling and Validation
130+
131+
The field map includes comprehensive error handling:
132+
133+
### Pre-Execution Validation
134+
135+
- Verifies that the target field exists on the work item
136+
- Ensures all source fields specified in parameters exist
137+
- Validates that source field values are numeric
138+
139+
### Expression Evaluation
140+
141+
- Catches and logs NCalc expression errors
142+
- Reports detailed error messages for debugging
143+
- Gracefully skips calculation if validation fails
144+
145+
### Type Conversion
146+
147+
- Handles automatic type conversion between numeric types
148+
- Logs warnings for conversion failures
149+
- Preserves data integrity during type conversions
150+
151+
## Best Practices
152+
153+
### Expression Design
154+
155+
- Use descriptive parameter names that match your field purpose
156+
- Test expressions with sample data before migration
157+
- Consider edge cases like null or zero values
158+
159+
### Performance Considerations
160+
161+
- Complex expressions may impact migration performance
162+
- Use simple expressions when possible
163+
- Consider the frequency of execution for your work item types
164+
165+
### Field Validation
166+
167+
- Ensure source fields contain numeric data
168+
- Validate target field types support calculated results
169+
- Test with various data scenarios
170+
33171
## How NCalc Expressions Work
34172

35173
The [NCalc](https://github.com/ncalc/ncalc) engine supports:
@@ -73,24 +211,6 @@ This multiplies the values of the two fields `Custom.EstimatedHours` and `Custom
73211
- Errors during evaluation are **not recoverable** mid-run unless caught at validation.
74212
- Does **not support cross-work-item calculations**.
75213

76-
## Samples
77-
78-
### Sample
79-
80-
{{< class-sample sample="sample" >}}
81-
82-
### Defaults
83-
84-
{{< class-sample sample="defaults" >}}
85-
86-
### Classic
87-
88-
{{< class-sample sample="classic" >}}
89-
90-
## Metadata
91-
92-
{{< class-metadata >}}
93-
94214
## Schema
95215

96216
{{< class-schema >}}

0 commit comments

Comments
 (0)