Service - Transform Units

Overview

Transformations are used to convert any number of inputUnits into any number of outputUnits.

Repository

https://bitbucket.org/izara-supply-units/izara-supply-units-transform-units

Calculating values

combinationEquation and calculateByProperties fields replace out special tags first then parse through an evaluation library, eg:

• https://mathjs.org/
• https://www.npmjs.com/package/string-math
• https://www.npmjs.com/package/exact-math
• https://www.codeproject.com/Articles/12116/JavaScript-Mathematical-Expression-Evaluator

Must make sure equation is validated/sanitized first, be careful/do not use "eval" or "new Function" which can invoke arbritrary commands.

Transform request

• transformConfig is primarily used as a default template, each unitTransform can adjust almost all details such as units inputted and outputted propertyValues
• user can use the transformConfig inputUnits calculatedProperties to recalc inputUnit property values according to the outputUnits numberOfUnits
• user can set to recalculate outputUnits calculatedProperties according to inputUnits property values
• inputUnits array can have multiple elements with the same unitTypeId, this is a guide for frontend to allow multiple units of the same unitType but eg different fabrics to be inputs in the same transformation
• outputUnit calculatedProperties will calculate the same for all outputUnit numberOfUnits, can be adjusted manually
• outputUnits array can have multiple elements with the same unitTypeId for eg calcualting cost for sizes of different clothing)

transformConfigInputOutput

{
	inputUnits: {
		unitTypeId: {
			stageId: "xx", // optional, stage that applies stageAdjustments to input unit
			calculatedProperties:{ // calculates changes to inputUnits unitTrackedProperties
				unitTypeTrackedPropertyId: {
					integerOnly: false, // default false, if true then calculated splits must be integers, will not process transformation if split per outputUnit are not integers. Maybe can remove and use unitTypeTrackedProperty.precision
					quantityReductionSetting: "spread"|"clearPerUnit", // if not all quantityUnitTypeTrackedPropertyId are used up in transformation, do we reduce all numberOfUnits quantity equally, or clear quantity out one unit at a time, frontend uses to calculate initial values
					valueUse: 1, // per transformUnitsObject quantity, maybe allow overwriting on frontend
				},
				// ...
			},
		}, 
		//..
	},
	outputUnits: [
		{
			unitTypeId: "zz",
			stageId: "xx", // optional, stage that applies stageAdjustments to output unit
			numberOfUnits: 1, // default number of outputUnits to create, calculations are based on this and inputUnit numberOfUnits
			calculatedProperties: { // calculates value for unitTypeTrackedProperties added to outputUnits
				unitTypeTrackedPropertyId: {
					calculationType: "calculateValue", // can add other types later
					integerOnly: false, // maybe not needed, in unitTypeTrackedProperty.precision
					combinationEquation: "[calcPropTagA]+[calcPropTagB]", // optional, method of combining multiple calculateByProperties together, defaults to adding/sum
					calculateByProperties: {
						calcPropTag: { // any string, used in combinationEquation
							calculationType: "xx", //"calculationPerInputUnit"|"singleValue"
							
							// if "calculationPerInputUnit"
							inputUnitValueUseCalcs:{ // used by frontend to calculate default values per inputUnit instances
								inputUnitTypeId: {
									unitTypeTrackedPropertyId: "[valueUse]*0.25"
								}
							},
							calculation: "[inputUnitValueUse:{inputUnitTypeId}:{unitTypeTrackedPropertyId}]*[unitTypeTrackedProperty:{inputUnitTypeId}:{unitTypeTrackedPropertyId}]",
							
							// if "singleValue"
							defaultValue: "30", // not calculated, user can overwrite defaultValue
							
							round: "round", //optional: "round"|"ceil"|"floor"|..
							
						},
						// ..
					}
				}, 
				//..
			}
		}, 
		//..
	],

}

objectSchemas

{
	objectType: "transformConfig",
		addOnDataStructure: [
			{
				type:"versionedData",
				versionedDataLabel: "transformConfigInputOutput",
				storageResourceTag : "xx",
				fieldNames: [
					{ 
						fieldName: "inputUnits",
					},
					{ 
						fieldName: "outputUnits",
					},
				]
			},
		],
		storageResources:{
		"xxx":{
			storageType: "graph",
			graphServerTag: "xx",
		}
	},
	fieldNames: {
		transformConfigId: {
			type: "string",
            randomOnCreate: true
		},
		{ 
			fieldName: "inputUnits",
			type: "arrayMixed",
			requiredOnCreate: true
			validation: {
			  itemValidation:{} // for validate item in array
			},
		},
		{ 
			fieldName: "outputUnits",
			type: "arrayMixed",
			requiredOnCreate: true
			validation: {
			  itemValidation:{} // for validate item in array
			},
		},
		timingSetting: {
			type: "string", // "immediate"|"fixed"|"variable"
		},
		fixedSeconds: {
			type: "numeric", // if timingSetting="fixed" this is the fixed number of seconds the action takes
		},
		defaultSeconds: {
			type: "numeric", // if timingSetting="variable" this is the default number of seconds the action takes
		}
	},
	identifiers: [
		{
			fieldName: "transformConfigId"
		},
	]
},

{
	objectType: "unitTransform",
	storageResources:{
		"xxx":{
			storageType: "graph",
			graphServerTag: "xx",
		}
	},
	fieldNames: {
		unitTransformId: {
			type: "string",
            randomOnCreate: true
		},
		fromTime: {
			type: "timestamp",
		},		
		toTime: {
			type: "timestamp",
		},		
	},
	identifiers: [
		{
			fieldName: "unitTransformId"
		},
	]
},

• Is created each time a transformUnit action is applied to units

{
	objectType: "transformUnitChangeLocation",
	storageResources:{
		"xxx":{
			storageType: "graph",
			graphServerTag: "xx",
		}
	},
	fieldNames: {
		transformUnitchangeLocationId: {
			type: "string",
            randomOnCreate: true
		},
	},
	identifiers: [
		{
			fieldName: "transformUnitchangeLocationId"
		},
	]
},

• links a unitTransform to a from and to location, if a majority of input units are in a matching from location when the transformUnit action is performed the output units will be placed by default in the transformUnitChangeLocation's to location
• If none match then the location that has the majority of inputUnit's will set the default to location
• Each transformUnit action can overwrite the location of the outputUnits

relationshipSchemas

[
  {
    "oldTransformUnitTrackedProperty": {
      storageResources:{
		"xxx":{
			storageType: "graph",
			graphServerTag: "xx",
		}
      },
      links: [
        {
          storageResourceTags: ["xxx"],
          from: {
            objType: {
              serviceTag: "transformUnits",
              objectType: "unitTransform"
            },
            linkType: "one",
          },
          to: {
            objType: {
              serviceTag: "unitType",
              objectType: "unitTrackedProperty"
            },
            linkType: "many",
          }
        }
      ]
    }
  }
]

[
  {
    "newTransformUnitTrackedProperty": {
      storageResources:{
		"xxx":{
			storageType: "graph",
			graphServerTag: "xx",
		}
      },
		fieldNames: {
			adjustmentValue: {
				type: "string", // so can adjust any type of property, will need cast type in logic
				requiredOnCreate: true,
			},
		},         
      links: [
        {
          storageResourceTags: ["xxx"],
          from: {
            objType: {
              serviceTag: "transformUnits",
              objectType: "unitTransform"
            },
            linkType: "one",
          },
          to: {
            objType: {
              serviceTag: "unitType",
              objectType: "unitTrackedProperty"
            },
            linkType: "many",
          }
        }
      ]
    }
  }
]

• links unitTransform event to all before and after unitTrackedProperties that are adjusted by this transformation

[
  {
    "hasChangeLocation": {
      storageResources:{
		"xxx":{
			storageType: "graph",
			graphServerTag: "xx",
		}
      },
      links: [
        {
          storageResourceTags: ["xxx"],
          from: {
            objType: {
              serviceTag: "stageManager",
              objectType: "stage"
            },
            linkType: "one",
          },
          to: {
            objType: {
              serviceTag: "stageManager",
              objectType: "stageChangeLocation"
            },
            linkType: "many",
          }
        }
      ]
    }
  }
]

• links transformConfig to a pair of from/to locations
• multiple pairs per transformConfig allows for a transformConfig to change the location according to the units current location

[
  {
    "changeFromLocation": {
      storageResources:{
		"xxx":{
			storageType: "graph",
			graphServerTag: "xx",
		}
      },
      links: [
        {
          storageResourceTags: ["xxx"],
          from: {
            objType: {
              serviceTag: "transformUnits",
              objectType: "transformConfig"
            },
            linkType: "one",
          },
          to: {
            objType: {
              serviceTag: "supplyLocationManager",
              objectType: "supplyLocation"
            },
            linkType: "one",
          }
        }
      ]
    }
  }
]

[
  {
    "changeToLocation": {
      storageResources:{
		"xxx":{
			storageType: "graph",
			graphServerTag: "xx",
		}
      },
      links: [
        {
          storageResourceTags: ["xxx"],
          from: {
            objType: {
              serviceTag: "transformUnits",
              objectType: "transformConfig"
            },
            linkType: "one",
          },
          to: {
            objType: {
              serviceTag: "supplyLocationManager",
              objectType: "supplyLocation"
            },
            linkType: "one",
          }
        }
      ]
    }
  }
]

• When this action is applied if the units location matches a transformConfigChangeLocation's changeFromLocation, change to the changeToLocation

[
  {
    "hasMonitorMarker": {
      storageResources:{
		"xxx":{
			storageType: "graph",
			graphServerTag: "xx",
		}
      },
      links: [
        {
          storageResourceTags: ["xxx"],
          from: {
            objType: {
              serviceTag: "transformUnits",
              objectType: "transformConfig"
            },
            linkType: "one",
          },
          to: {
            objType: {
              serviceTag: "monitorManager",
              objectType: "monitorMarker"
            },
            linkType: "many",
          }
        }
      ]
    }
  }
]

[
  {
    "disabledMonitorMarker": {
      storageResources:{
		"xxx":{
			storageType: "graph",
			graphServerTag: "xx",
		}
      },
      links: [
        {
          storageResourceTags: ["xxx"],
          from: {
            objType: {
              serviceTag: "transformUnits",
              objectType: "transformConfig"
            },
            linkType: "one",
          },
          to: {
            objType: {
              serviceTag: "monitorManager",
              objectType: "monitorMarker"
            },
            linkType: "many",
          }
        }
      ]
    }
  }
]

• During the period of the transformUnit, this marker allows the monitor project to offer more granular monitoring, eg when stitching a clothing item the transformUnit could focus on a subset of the video feed group's feeds (eg the table where the shirt is sewed)
• A monitorMarker can be disabled and re-enabled

[
  {
    "appliedMonitorMarker": {
      storageResources:{
		"xxx":{
			storageType: "graph",
			graphServerTag: "xx",
		}
      },
      links: [
        {
          storageResourceTags: ["xxx"],
          from: {
            objType: {
              serviceTag: "transformUnits",
              objectType: "unitTransform"
            },
            linkType: "many",
          },
          to: {
            objType: {
              serviceTag: "monitorManager",
              objectType: "monitorMarker"
            },
            linkType: "many",
          }
        }
      ]
    }
  }
]

• Each time a unitTransform is applied an appliedMonitorMarker relationship is created between the unitTransform object and all of the transformConfig's active monitorMarkers
• the monitorMarker then links to the monitor object that the market applies to

Working documents

Transform Units