The basic custom-value functions are evaluated on the relevant key-value list of an action. For different types of actions, the relevant key-value list is computed differently. Therefore, make sure you thoroughly understand the computation procedure before creating custom-value statistical types.
String values in the relevant key-value list are converted to numbers in the ordinary way if they are in this format:
- Integer: a sequence of digits possibly preceded by the symbol + or -
- Fixed-point decimal: an integer followed by a dot (.), possibly followed by a sequence of digits
- Floating-point decimal: an integer or fixed-point decimal followed by the letter e or E, possibly followed by a sign, followed by one or two digits
A string that is not in any of these formats is converted to 0.
Evaluation on Momentary Actions
For a momentary action, the relevant key-value list equals the UserData list, which is received with the TEvent that caused the action. The same rule holds for the mediation DN action CallTreatmentCompleted, which is not derived from a durable action, but is formally classified as a retrospective action.
Evaluation on Durable Actions
For a durable action, Stat Server can keep two key-value lists: one relevant to data that is attached at a specific DN during a given interaction (called a local key-value list) and the other one relevant to data that is attached at all DNs during the interaction (called a global key-value list).
The global key-value list equals the UserData list that Stat Server received with the T-Event that triggered the action.
The computation procedure for a local key-value list for a durable action:
- Separates the specific attached data belonging to the DN in which the action occurs from all the data that is attached to the interaction.
- Attaches the data while the action occurs.
Calculating a Local Key-Value List
Stat Server calculates a local key-value list from the global key-value list. The local key-value list is recalculated whenever:
- The action starts.
- The EventAttachedDataChanged TEvent is received while the action goes on (might be repeated any number of times).
- The action ends.
This section describes how the relevant key-value list is updated during an inductive procedure.
These terms are used:
- A key-value list is a finite sequence of ordered pairs of character strings—the first element of a pair is called a key, and the second element a value.
- A marked key-value list is a finite sequence of ordered triples, whose first two elements are strings (key and value), and whose third element is a flag with either a native or a foreign value.
This notation is used:
- Steps are indexed from 1 to N.
- Listk is the UserData key-value list received at Step k.
- Δk is the k-th step value of a marked key-value list defined inductively (referred to as the marked prototype of the relevant key-value list)
These operations are used:
- List Subtraction. Let ListA and ListB be key-value lists. Then ListA\List B is defined as the key-value list obtained from ListA by removing from it:
- The first k occurrences of any key-value pair that occurs k times in ListB and more than k times in ListA.
- All occurrences of any key-value pair that occurs in ListA fewer times than in ListB.
- Marking a List. Let ListA be a key-value list. Then, Native(ListA) is the marked key-value list obtained from ListA by appending native to every pair in the list. Foreign(ListA) is the marked key-value list obtained from ListA by appending foreign to every pair in the list.
- Marked List Union. Let ListA and ListB be marked key-value lists. Then ListA/ListB is the marked key-value list obtained by concatenating ListA and the list obtained from ListB by removing from it:
- The first k occurrences of elements with the same key-value pair occurring k times in ListA and more than k times in ListB, regardless of the flags.
- All occurrences of elements with the same key-value pair occurring in ListB fewer times than in ListA.
Here is the inductive definition of the marked prototype Δk:
- Δ1 = ∅. That is, the marked prototype contains no elements at Step 1.
- If Step k is caused by EventAttachedDataChanged with ThisDN equal to
ThirdPartyDN or at the final step of the action,
Δk = Δk-1/Native(Listk\Listk-1)
- If Step k is caused by EventAttachedDataChanged with ThisDN different from
Δk = Δk-1/Foreign(Listk\Listk-1)
When a custom formula is evaluated on a durable action for use in a current aggregated value, the relevant key-value list is obtained from Δk for the last completed step by removing all pairs flagged by foreign, and removing the flag from the remaining pairs.
When a custom formula is evaluated on a durable action for use in a historical aggregated value, the relevant key-value list is obtained from Δk for the final step of the action by removing all pairs flagged by foreign, and removing the flag from the remaining pairs.
This mechanism is best suited for processing attached data if, once a key-value pair is attached, it never gets removed.
For group actions reflecting an origination DN, custom-formula evaluation is identical to the evaluation of the custom formula for the corresponding mediation DN action.
Evaluation on Retrospective Actions
As a rule, the value of a custom formula for a retrospective action is the same as the final value of the custom formula for the durable action from which the retrospective action is derived.
Note these exceptions:
- Custom formulas are evaluated for the mediation DN action CallTreatmentCompleted in the same way as for instantaneous actions because this retrospective action is not derived from a durable action.
- The retrospective mediation DN actions CallAnswered, CallAbandonedFromRinging, CallReleased, CallMissed, ACWCompleted, and ACWMissed receive the same value as when evaluated on the corresponding regular DN actions.