No, it's not something you do when you don't get the punch line to a joke (that's for you Craig). It is probably a pretty misunderstood exception so I thought I take a few moments to impart some words of wisdom and it wouldn't be my blog without a nifty matrix (because everything is more helpful in a matrix).
As usual, I wouldn't be speaking about this if this one hadn't already bitten me good some time ago. It looked easy, anytime I didn't want to flow something I could just throw this little exception and MIIS would immediately stop processing the flow - so I started using it everywhere, it became my new ELSE directive! I was very pleased with myself because every code path was accounted for, errors were trapped, data was being moved, or the exception was thrown. However, as they say, it works well in PowerPoint...
I started to wonder why data wasn't flowing the way I had anticipated in some cases - especially in my manual precedence rules which I'd spent quite a bit of time on tying up all those loose ELSE conditions. You see, sometimes the right thing to do is to flow nothing at all (leaving the existing value intact) and that's exactly what DeclineMappingException doesn't do. Let's take a look at how this breaks down but first let's set up the situation. The matrix below is comprised of three rows and two columns. The rows are what you choose to do during an attribute flow, so for "contribute" you actually wrote the data to the opposite entity (cs->mv or mv->cs), "no contribution" you didn't write anything, the rule just exits without doing anything and you guessed it with our "Throw" buddy. For the columns we have a special treat - in the first matrix they represent what happens between two different precedence configurations. With "Standard Precedence", the attribute is not configured for "Manual Precedence" and there is more than one source that can contribute the data.
| |
Standard Precedence |
Manual Precedence |
| Contribute |
Value is contributed |
Value is contributed, although it can be overridden by another rule later in the sync |
| No Contribution |
Existing value remains |
Depends on other flows |
| DeclineMappingException |
Next precedent source contributes |
Next precedent source contributes |
The next table contrasts what happens when you contribute a value and the data has either changed or remained the same.
| |
No Change |
Data Changed |
| Contribute |
Engine must evaluate that the data has not changed |
Engine evaluates the change and contributes the new value |
| No Contribution |
Existing value remains |
Changed value is never contributed |
| DeclineMappingException |
Next precedent source contributes |
Changed value is never evaluated, the next precedent source contributes |
So, the real reason for the DeclineMappingException is the last cell here - you threw the exception despite the fact that the data had changed you decided that for whatever reason you want the next precedent source to be able to contribute. Under standard precedence rules the next source in line would contribute and with manual precedence the rule would have a chance to contribute. Let's not even touch what happens if you tell multiple rules to contribute under manual precedence (ok fine, last in wins).
I think in some cases you, like I did, found yourself throwing the exception under one of the No Contribution conditions hoping to save the engine a cycle or two - but it has the wrong effect. I use following rules to help keep this straight:
- If you don't want to contribute a change but you want to leave the existing value (from this MA) in place, then do nothing
- If you want to force the next precedent source to take a crack at this (regardless of precedence settings) and the existing value should not remain then throw the exception
Let me be clear here on the last point, if I throw the exception and none of my other sources have anything to contribute then the value is deleted - you don't get the old value back!
If you came across this because you were searching for code examples of manual precedence then let me at least reward you for reading through this entire post just for this one link. Oh,and one more from Joe's Blog.
