Sync Job Contracts

A sync job contract defines which parts of an ECU configuration ECU Project Synchronization shares. This page describes the format of a contract and how to find the paths of the elements you want to share.

Sync Job Contract Format

A sync job contract is a JSON file with the file name extension .json. It selects the elements of the ECU configuration that dvcfg-b project publish exports and dvcfg-b project sync takes over.

Table 1. Fields of a sync job contract
JSON key	Type	Description
`name`	String	Required. Unique name of the contract. The `--sync-job-name` option selects contracts by this name, and the files of the published data start with it. A file without `name` or with an empty `name` isn’t treated as a contract and is ignored.
`origin`	String	Optional. Owner of the contract, for example the name of the platform team. It’s written to the file `<name>_shortDef.json` of the published data.
`definitions`	Array	Selects all instances of a definition in the active module configurations. Each entry contains: `definition`: Definition path of a module, container, or parameter, for example `/MICROSAR/Com/ComGeneral`. A path without package, for example `Com/ComGeneral`, is also accepted. `includeSubElements`: Optional, default `false`. See the table below.
`instances`	Array	Selects single elements of the configuration. Each entry contains: `instance`: Instance path of a module configuration, container, or parameter, for example `/ActiveEcuC/Com/ComConfig/ComIPdu_001`. See Finding Instance and Definition Paths. `includeSubElements`: Optional, default `false`. See the table below.

A contract needs at least one entry in definitions or instances. Unknown keys are ignored.

Table 2. Effect of `includeSubElements` on a selected container
Value	Selected content
`true`	The container with all parameters, references, and sub-containers, recursively.
`false`	The container with its own parameters and references, but without its sub-containers. Select the sub-containers you need with additional entries.

For a selected parameter, includeSubElements has no effect. The parent containers of a selected element are always added to the published data, so the element can be placed at the same position in the consuming project.

Example

The following contract shares the following parts of the configuration:

All crypto keys and key elements of the hardware security module, selected by their definitions.
The general Com settings, selected by a definition path without package.
One NvM block and the PDU ComIPdu_001, each with all sub-containers.
The PDU ComIPdu_002 without its sub-containers.
The single parameter ComConfigurationId.

{
    "name": "platform-com-hsm",
    "origin": "Platform Team",
    "definitions": [
        {
            "definition": "/MICROSAR/Crypto_30_vHsm/Crypto/CryptoKeyElements",
            "includeSubElements": true
        },
        {
            "definition": "/MICROSAR/Crypto_30_vHsm/Crypto/CryptoKeys",
            "includeSubElements": true
        },
        {
            "definition": "Com/ComGeneral",
            "includeSubElements": true
        }
    ],
    "instances": [
        {
            "instance": "/ActiveEcuC/NvM/DemPrimaryDataBlocks",
            "includeSubElements": true
        },
        {
            "instance": "/ActiveEcuC/Com/ComConfig/ComIPdu_001",
            "includeSubElements": true
        },
        {
            "instance": "/ActiveEcuC/Com/ComConfig/ComIPdu_002",
            "includeSubElements": false
        },
        {
            "instance": "/ActiveEcuC/Com/ComConfig[ComConfigurationId]"
        }
    ]
}

Where Contracts Are Found

dvcfg-b project publish and dvcfg-b project sync search the following folders recursively for files with the extension .json:

The folder Misc/SyncJobContracts of the BSW Package that you pass with -b.
Every folder that you pass with -l (--sync-job-location).

Keep only contracts in these folders. A .json file that isn’t valid JSON stops the command. Use a unique name for each contract.

Finding Instance and Definition Paths

A sync job contract selects elements by their instance path or by their definition path. You don’t have to type these paths: copy them from the GUI client of DaVinci Configurator Classic Version 6.

Table 3. Syntax of instance and definition paths
Element	Instance path, for `instances`	Definition path, for `definitions`
Module configuration	`/ActiveEcuC/Com`	`/MICROSAR/Com`
Container	`/ActiveEcuC/Com/ComConfig/ComIPdu_001`	`/MICROSAR/Com/ComConfig/ComIPdu`
Parameter or reference	`/ActiveEcuC/Com/ComConfig[ComConfigurationId]` Path of the container, followed by the short name of the parameter definition in square brackets.	`/MICROSAR/Com/ComConfig/ComConfigurationId`
Parameter or reference with several values	`/ActiveEcuC/Com/ComConfig/ComIPdu_001[1:ComIPduSignalRef]` Zero-based index of the value, a colon, and the short name of the definition.	`/MICROSAR/Com/ComConfig/ComIPdu/ComIPduSignalRef`

In variant projects, an instance path can end with the variants the element is visible in, for example /ActiveEcuC/Can/CanConfigSet/CanHardwareObject[0:CanControllerRef]{VariantA,VariantB}.

Steps

Open the publishing project in a GUI client and select the element you want to share.
Copy the path:
- In the GUI client Evo 2, open the Properties view. Copy the value of Short Name Path in the Status section for an instance path, or the value of DefinitionRef in the Definition section for a definition path.
- In the GUI client Evo 1, open the context menu of the element and select Copy Short Name Path for an instance path, or Copy Definition for a definition path. If you select several elements, the paths of all elements are copied, one path per line.
Paste the path into the instance or definition field of the contract.

An instance path contains the package of the active ECU configuration, for example /ActiveEcuC. The publishing project and the consuming projects must use the same package, otherwise the instance paths don’t match.