|
| 1 | +**NOTICE:** This software (or technical data) was produced for the U.S. Government under contract, |
| 2 | +and is subject to the Rights in Data-General Clause 52.227-14, Alt. IV (DEC 2007). Copyright 2023 |
| 3 | +The MITRE Corporation. All Rights Reserved. |
| 4 | + |
| 5 | + |
| 6 | +# Roll Up Overview |
| 7 | + |
| 8 | +The Workflow Manager can be configured to replace the values of track and detection properties after |
| 9 | +receiving tracks and detections from a component. This feature is commonly used to replace specific |
| 10 | +terms with a more general category. For example, the "CLASSIFICATION" property may be set to "car", |
| 11 | +"bus", and "truck". Those are all a kind of "vehicle". To use this feature, a JSON file in the |
| 12 | +format described below must be created. Then, the `ROLL_UP_FILE` job property must be set to the |
| 13 | +file path where that file is located. |
| 14 | + |
| 15 | + |
| 16 | +# Roll Up File |
| 17 | + |
| 18 | +The JSON below is an example of a roll up file. |
| 19 | + |
| 20 | +```json |
| 21 | +[ |
| 22 | + { |
| 23 | + "propertyToProcess": "CLASSIFICATION", |
| 24 | + "originalPropertyCopy": "ORIGINAL CLASSIFICATION", |
| 25 | + "groups": [ |
| 26 | + { |
| 27 | + "rollUp": "vehicle", |
| 28 | + "members": [ |
| 29 | + "truck", |
| 30 | + "car", |
| 31 | + "bus" |
| 32 | + ] |
| 33 | + }, |
| 34 | + { |
| 35 | + "rollUp": "sandwich", |
| 36 | + "members": [ |
| 37 | + "grilled cheese", |
| 38 | + "reuben", |
| 39 | + "hamburger", |
| 40 | + "hot dog" |
| 41 | + ] |
| 42 | + } |
| 43 | + ] |
| 44 | + }, |
| 45 | + { |
| 46 | + "propertyToProcess": "COLOR", |
| 47 | + "groups": [ |
| 48 | + { |
| 49 | + "rollUp": "purple", |
| 50 | + "members": [ |
| 51 | + "indigo" |
| 52 | + ] |
| 53 | + } |
| 54 | + ] |
| 55 | + }, |
| 56 | + { |
| 57 | + "propertyToProcess": "PROP3", |
| 58 | + "groups": [ |
| 59 | + { |
| 60 | + "rollUp": "new name", |
| 61 | + "members": [ |
| 62 | + "old name" |
| 63 | + ] |
| 64 | + } |
| 65 | + ] |
| 66 | + } |
| 67 | +] |
| 68 | +``` |
| 69 | + |
| 70 | +At the top level, the roll up file contains an array where each element defines a detection property |
| 71 | +that should be modified. In this example, there is one element for "CLASSIFICATION", one for |
| 72 | +"COLOR", and one for "PROP3". Each element contains the following fields: |
| 73 | + |
| 74 | +- `propertyToProcess`: (Required) A detection property key. The value will be modified according to |
| 75 | + the `groups` key. |
| 76 | +- `originalPropertyCopy`: (Optional) Copies the value of `propertyToProcess` prior to roll up to |
| 77 | + another property. The copy is made even if the property is not modified. |
| 78 | +- `groups`: (Optional) Array containing an element for each roll up name. If the value of the |
| 79 | + detection property specified by `propertyToProcess` matches a string listed in `members`, it |
| 80 | + will be replaced by the content of the `rollUp` property. |
| 81 | + |
| 82 | +In the example above, the value of the "CLASSIFICATION" detection property will be copied to |
| 83 | +"ORIGINAL CLASSIFICATION" before the roll up is performed. If the "CLASSIFICATION" detection |
| 84 | +property is set to "truck", "car", or "bus", the value of the detection property will be replaced |
| 85 | +by "vehicle". |
| 86 | + |
| 87 | +In a real use case there will generally be multiple roll up groups for a single detection property. |
| 88 | +The "sandwich" group shows how to include an additional mapping for the same "CLASSIFICATION" |
| 89 | +property. The "COLOR" and "PROP3" sections show examples of how to apply roll up to different |
| 90 | +detection properties with different configurations. |
| 91 | + |
| 92 | +If the roll up above was applied to these detection properties: |
| 93 | + |
| 94 | +```json |
| 95 | +{ |
| 96 | + "CLASSIFICATION": "truck", |
| 97 | + "COLOR": "red", |
| 98 | + "PROP3": "truck", |
| 99 | + "PROP4": "other" |
| 100 | +} |
| 101 | +``` |
| 102 | + |
| 103 | +it would result in: |
| 104 | + |
| 105 | +```json |
| 106 | +{ |
| 107 | + "CLASSIFICATION": "vehicle", |
| 108 | + "ORIGINAL CLASSIFICATION": "truck", |
| 109 | + "COLOR": "red", |
| 110 | + "PROP3": "truck", |
| 111 | + "PROP4": "other" |
| 112 | +} |
| 113 | +``` |
| 114 | + |
| 115 | +"COLOR" was not modified since it does not define a roll up group with "red" as a member. "PROP3" |
| 116 | +was not modified because only the "CLASSIFICATION" property has a roll up group with "truck" as a |
| 117 | +member. "PROP4" was not modified because it is not in the roll up file. |
0 commit comments