Provisioning

Provisioning is the method of which data entered into Unity configuration pages transfers to applications within the HCC2.

There are two provisoning methods, Simple and Complex. If an application is set as complex provisoing it will be to watching for new provsioning data to validate and then return a validation result to the HCC2 Rest Server.

For both Simple and Complex provisioning the latest approved config values are stored within the PostValidConfig thread safe data class found in [provisioning.py]. This class will only ever contain validated, post deployment HCC2 configuration data; therfore it should be the only source of configuration data for your application.

All configuration values can be accessed though the class level value method.

Configure values in Unity and Deploy. If the application is running the provisoning thread will notice new config data and load this in the PostValidConfig class.

Local Image

[0][2025-03-12T23:17:30.124746Z][samplePythonApp][INFO] ---------------------------------------------
[0][2025-03-12T23:17:30.138488Z][samplePythonApp][INFO] Provisioning : Simple
[0][2025-03-12T23:17:30.144915Z][samplePythonApp][INFO] ---------------------------------------------
[0][2025-03-12T23:17:30.196002Z][samplePythonApp][INFO] Provisioning complete. Result Pass
[0][2025-03-12T23:17:30.198964Z][samplePythonApp][INFO] Reading All Post Valid Config Values.
[0][2025-03-12T23:17:31.284260Z][samplePythonApp][INFO] Current Post Valid Config:
[0][2025-03-12T23:17:31.285388Z][samplePythonApp][INFO]  - sampleConfigInt : 444
[0][2025-03-12T23:17:31.287436Z][samplePythonApp][INFO]  - sampleConfigFloat : 675.255
[0][2025-03-12T23:17:31.288282Z][samplePythonApp][INFO]  - sampleConfigString : my sample string

Access this data by importing the PostValidConfig class and calling the value method with a configuration register's topic.

NOTE The name used to reference the config register is the topic name, with all . replace with _.

from services import PostValidConfig

print(PostValidConfig.value("sampleConfigInt"))
print(PostValidConfig.value("sampleConfigFloat"))
print(PostValidConfig.value("sampleConfigString"))

>> 444
>> 675.255
>> my sample string

Simple Provisioning

Simple provisioning is the easiest way for REST applications to register with the HCC2. It works if the config only includes safe, passive settings. Without harmful parameters, validation is minimal since improper values won’t cause critical issues.

Set complex as false within [config.json].

  "provisioning": {
    "complex": false
  },

Your application will not have to reply durring HCC2 deployments; new config data is automatically accepted. The PostValidConfig class within [services\provisioning.py] will be updated with the new configuration values shortly after.

Complex Provisioning

Complex provisioning is for applications requiring stricter validation to prevent harmful configurations. For example, a voltage output level setting is best handled through complex provisioning, where values outside safe bounds can be rejected.

Set complex as true within [config.json].

  "provisioning": {
    "complex": true
  },

Your application MUST parse the prevalid configuration configuration data and return a validation result. This pre-valid data is read in from a json file, parameters.this.0.json, found within the provisioning TAR.GZ file.

Example pre-valid configuration data.

{
    "enabledVoltOut": true,
    "voltageSet": 24,
    "enabledCurrIn": true,
    "currentLimit": 1,
    "cyclePeriodSec": 3,
    "dutyCycle": 50,
    "offset": -18,
    "smsNumber": "+1 555-123-4567",
    "appSettings": "{\"settings\": [{\"settingName\": \"PressureThreshold\", \"value\": 3500}]}",
    "hash": "5a11bcbf7acfed636c42b6f2684128dfaaf53278723fb9aec0a85ee94bb58156"
}

Add validations to the complex_provisioning_validation function within [app.py]. If the pre-vaid config is valid this function should return True and the HCC2 deployment should succeed. If the config is invalid return False; this will prevent the HCC2 deployment from occuring and show your application as the cause.

Once fully deployed, the Provisioning class will update the thread safe PostValidConfig class found within [services\provisioning.py].

NOTE This function will have to execute and return in under 15 seconds or the HCC2 deployment will fail due to this application PENDING.

def complex_provisioning_validation(self : Provisioning) -> bool:
    """Custom provisioning validation logic if complex provisioning is enabled.

    Add your validation logic for the values of CONFIG DATAPOINTS ONLY.

    If simple provisioning is enabled this function will be skipped and any incoming 
    pre-valid configuration values will be automatically accepted."""

    # Read in pre-valid configuration file (parameters_this_0.json) from provisioning TAR.GZ file.
    pvc = self.pre_valid_config

    # Set Voltage must be less than 24 volts
    if pvc['voltageSet'] > 24.0:
        hcc2_logger.error(f"Validation Error: Set voltage ({pvc['voltageSet']} V) must be less than or equal to 24 Volts.")
        return False

    # Current limit must be between 0.5 and 2 Amps
    if not (0.5 <= pvc['currentLimit'] <= 2.0):
        hcc2_logger.error(f"Validation Error: Current limit ({pvc['currentLimit']} A) must be between 0.5 and 2 Amps.")
        return False

    # Polling period must be greater than or equal 1 second
    if pvc['cyclePeriodSec'] < 1:
        hcc2_logger.error(f"Validation Error: Polling period ({pvc['cyclePeriodSec']} s) must be greater than or equal 1 Seconds.")
        return False

    # Either voltage out or current in must be true
    if not (pvc['enabledVoltOut'] or pvc['enabledCurrIn']):
        hcc2_logger.error(f"Validation Error: Either voltage out or current in must be True.")
        return False

    hcc2_logger.info("Provisioning Validation Successful")
    return True