Package the Model

You can deploy a digital twin model either to the ScaleOut Digital Twins™ service or to an on-premises deployment running ScaleOut StreamServer. This section explains how to deploy a Java model using the UI either in the Azure cloud or on-premises. The topic explains how to use the APIs to deploy a Java model without the UI to ScaleOut StreamServer on-premises.

Model.json Specification File

ScaleOut Digital Twins requires a model-specification file in JSON format which tells the service about the Java type names defined when creating the model. This file is called “model.json” and for deployment it is placed in the same directory as the model’s JARs. It contains three required fields: modelType, messageProcessorType, and messageType. See the below table for all available configuration options and default values.

Property	Description	Default
modelType	The fully qualified type name of the digital twin’s state object class	NULL
messageProcessorType	The fully qualified type name of the message processor class	NULL
messageType	The fully qualified type name of the message class	NULL
simulationProcessorType	(optional) The fully qualified type name of the simulation processor class for simulation digital twins	NULL
azureDigitalTwinModelName	(optional) The Azure Digital Twins Digital Twin Model Identifier (DTMI) as specified by the Digital Twin Data Language (DTDL). Automatically updates model.json if using the Model Generator	NULL
enablePersistence	(optional) Enable persistence. True if models should persist state for RealTime DigitalTwin instances; false otherwise	false
persistenceProvider	(optional) The persistence provider type. Supported values: “SQLServer”, “SQLite”, “AzureDigitalTwinsService”, or “Default”. “Default” uses the configured default provider	NULL
alertProviders	(optional) An array of alert provider configurations. See Configuring Your Alert Provider for details	NULL
enableSimulationSupport	(optional) Enable simulation events. Must be true to allow the simulation processor to receive simulation events. Requires a model with a SimulationProcessor	false
enableMessageRecording	(optional) Enable message recording. Must be true to record incoming messages from data sources	false

The Thermostat model would have the following model.json model-specification file (also called a schema file):

{
  "modelType": "com.digitaltwin.example.RealTimeThermostat",
  "messageProcessorType": "com.digitaltwin.example.RealTimeThermostatMessageProcessor",
  "messageType": "com.digitaltwin.example.TemperatureChangeMessage",
}

The Heater model would have the following model.json model-specification file (also called a schema file):

{
  "modelType": "com.digitaltwin.example.SimulatedHeater",
  "messageProcessorType": "com.digitaltwin.example.HeaterMessageProcessor",
  "simulationProcessorType": "com.digitaltwin.example.HeaterSimulationProcessor",
  "messageType": "com.digitaltwin.example.TemperatureChangeMessage",
  "enableSimulationSupport": true
}

Automatic Packaging with Maven Archetype

Projects generated from any of the available DigitalTwin Maven Archetypes have packaging steps built into the Maven project.

mvn package

This command will build the package, run all unit tests, and produce a deployable Thermostat.zip ZIP archive in the Maven project’s target directory. The ZIP archive will contain your build output, project dependencies, and pre-configured model.json.

Alternatively, from your IDE of choice (IntelliJ, Eclipse, VS Code) you can run the package command.

Adding Model Packaging to Maven Projects

The following package plugins will allow your Maven project to generate a ZIP archive for deployment. This task relies on the model.json configuration file to be created/configured and then placed in the src/main/resources directory.

Begin by creating deployment.xml in the src\assembly directory (create the assembly directory if it does not already exist) with the following contents:

<assembly xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3 https://maven.apache.org/xsd/assembly-1.1.3.xsd">
    <id>deployment</id>
    <formats>
        <format>zip</format>
    </formats>
    <includeBaseDirectory>false</includeBaseDirectory>
    <fileSets>
        <!-- Compiled JAR -->
        <fileSet>
            <directory>${project.build.directory}</directory>
            <includes>
                <include>${project.build.finalName}.jar</include>
            </includes>
        </fileSet>

        <!-- Dependencies -->
        <fileSet>
            <directory>${project.build.directory}/dependency-jars</directory>
            <includes>
                <include>*.jar</include>
            </includes>
        </fileSet>

        <!-- model.json -->
        <fileSet>
            <directory>src/main/resources</directory>
            <includes>
                <include>model.json</include>
            </includes>
        </fileSet>
    </fileSets>
</assembly>

Next, add the following plugins to the projects pom.xml under the <build><plugins> tag:

<!-- other plugins above... -->
<plugin>
  <artifactId>maven-assembly-plugin</artifactId>
  <version>3.6.0</version>
  <executions>
    <execution>
      <id>make-zip</id>
      <phase>package</phase>
      <goals>
        <goal>single</goal>
      </goals>
      <configuration>
        <finalName>${project.artifactId}</finalName>
        <appendAssemblyId>false</appendAssemblyId>
        <descriptors>
          <descriptor>src/assembly/deployment.xml</descriptor>
        </descriptors>
      </configuration>
    </execution>
  </executions>
</plugin>
<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-dependency-plugin</artifactId>
  <version>3.6.0</version>
  <executions>
    <execution>
      <id>copy-dependencies</id>
      <phase>package</phase>
      <goals>
        <goal>copy-dependencies</goal>
      </goals>
      <configuration>
        <outputDirectory>${project.build.directory}/dependency-jars</outputDirectory>
        <includeScope>runtime</includeScope>
      </configuration>
    </execution>
  </executions>
</plugin>
<!-- other plugins below... -->

Now run the following:

mvn package

This command will build the package, run all unit tests, and produce a deployable Thermostat.zip ZIP archive in the Maven project’s target directory. The ZIP archive will contain your build output, project dependencies, and pre-configured model.json.

Adding Model Packaging to Gradle Projects

The following packageForDeployment ZIP task will generate a package for Gradle projects. This task relies on the model.json configuration file to be created/configured and then placed in the src/main/resources directory. Add the following to your Gradle build:

tasks.register('packageForDeployment', Zip) {
    group = 'distribution'
    description = 'Packages build output, dependencies, and model.json into a deployable ZIP'

    // The output zip will be named like: project-name.zip
    archiveFileName = "${project.name}.zip"
    destinationDirectory = layout.buildDirectory.dir("deployment")

    // Include the compiled JAR
    from(jar) {
        into('')
    }

    // Include all runtime dependencies (flattened)
    from(configurations.runtimeClasspath) {
        into('')
        // Optional: filter to include only JARs
        include '*.jar'
    }

    // Include model.json from resources
    from('src/main/resources') {
        include 'model.json'
        into('')
    }

    // Fail the build if model.json is missing
    doFirst {
        def modelFile = file('src/main/resources/model.json')
        if (!modelFile.exists()) {
            throw new GradleException("Missing required file: src/main/resources/model.json")
        }
    }
}

tasks.register<Zip>("packageForDeployment") {
    group = "distribution"
    description = "Packages build output, dependencies, and model.json into a deployable ZIP"

    archiveFileName.set("${project.name}.zip")
    destinationDirectory.set(layout.buildDirectory.dir("deployment"))

    // Include compiled JAR
    from(tasks.named("jar")) {
        into("")
    }

    // Include runtime dependencies
    from(configurations.runtimeClasspath) {
        into("")
        include("*.jar")
    }

    // Include model.json from resources
    from("src/main/resources") {
        include("model.json")
        into("")
    }

    // Fail if model.json is missing
    doFirst {
        val modelFile = file("src/main/resources/model.json")
        if (!modelFile.exists()) {
            throw GradleException("Missing required file: src/main/resources/model.json")
        }
    }
}

Then run the following to generate the YourProjectName.zip ZIP package in the projects build/deployment/ directory.

./gradlew clean build packageForDeployment

.\gradlew.bat clean build packageForDeployment

Manual Model Packaging

You can generate the deployable ZIP archive manually or if using a different java build tool. To do this, collect the java projects build output as a JAR, the dependency JARs, the model.json configuration file, and compress them into a ZIP archive.

Continuing with the Thermostat.java example, the sequence for creating the Thermostat ZIP archive is as follows:

Compile Digital Twin classes
JAR digital twin classes
Copy build output into a directory named _Thermostat_
Copy all dependencies of Digital Twin classes into Thermostat directory
Copy model.json into Thermostat directory

The directory structure should now appear as follows:

    Thermostat
|
 \
  model.json
  thermostat-1.0.jar
  core-3.2.2.jar
  common-3.2.10.jar
  hosting-3.2.10.jar
  ... more dependencies ...

From inside the Thermostat directory, select all of the files and archive them into a zip file. You can now use this zip file to deploy the model to the cloud service.