BSW/
  ├── Nm/         # AUTOSAR Network Management (Nm.c)
  ├── CanNm/      # CAN Network Management (CanNm.h)
  ├── CanSM/      # CAN State Manager (CanSM.h)
  ├── Os/         # OS abstraction types and error handling
  ├── Csm/        # Crypto Service Manager makefiles
Generators/
  ├── Rte/        # RTE datatype definitions and XSLT utilities
  ├── Diag_A2lGen/# Diagnostic generator and licensing

1.2.17 - DVCfg_AutomationInterfaceDocumentations

DaVinci Configurator AutomationInterface
Development Documentation of the AutomationInterface (AI)
DaVinci Configurator Team
July 19, 2017
© 2017
Vector Informatik GmbH
Ingersheimerstr. 24
70499 Stuttgart

---

Contents
1
Introduction
9
1.1
General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9
1.2
Facts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9
2
Getting started with Script Development
10
2.1
General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10
2.2
Automation Script Development Types . . . . . . . . . . . . . . . . . . . . . . . .
10
2.3
Script File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10
2.4
Script Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
12
2.4.1
Script Project Development . . . . . . . . . . . . . . . . . . . . . . . . . .
14
2.4.2
Java JDK Setup
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
14
2.4.3
IntelliJ IDEA Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15
2.4.4
Gradle Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15
3
AutomationInterface Architecture
17
3.1
Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
17
3.2
Languages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
18
3.2.1
Why Groovy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
18
3.3
Script Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
19
3.3.1
Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
19
3.3.2
Script Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
20
3.3.3
Script Locations
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
20
3.4
Script loading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
20
3.4.1
Internal Script Reload Behavior . . . . . . . . . . . . . . . . . . . . . . . .
20
3.5
Script editing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
21
3.6
Licensing
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
21
3.7
Script Coding Conventions and Constraints . . . . . . . . . . . . . . . . . . . . .
21
3.7.1
Usage of static fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
22
3.7.2
Usage of Outer Closure Scope Variables . . . . . . . . . . . . . . . . . . .
23
3.7.3
States over script task execution . . . . . . . . . . . . . . . . . . . . . . .
23
3.7.4
Usage of Threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
23
3.7.5
Usage of DaVinci Configurator private Classes Methods or Fields . . . . .
23
4
AutomationInterface API Reference
24
4.1
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
24
4.2
Script Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
25
4.2.1
Script Task Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
25
4.2.1.1
Script Creation with IDE Code Completion Support . . . . . . .
26
4.2.1.2
Script Task isExecutableIf . . . . . . . . . . . . . . . . . . . . . .
27
4.2.2
Description and Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
27
4.3
Script Task Types
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
29
4.3.1
Available Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
29
4.3.1.1
Application Types . . . . . . . . . . . . . . . . . . . . . . . . . .
29
4.3.1.2
Project Types
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
30
4.3.1.3
UI Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
31
4.3.1.4
Generation Types . . . . . . . . . . . . . . . . . . . . . . . . . .
31
4.4
Script Task Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
33
© 2017, Vector Informatik GmbH
2 of 250

---

Contents
4.4.1
Execution Context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
33
4.4.1.1
Code Block Arguments . . . . . . . . . . . . . . . . . . . . . . .
34
4.4.2
Task Execution Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . .
34
4.4.3
Script Path API during Execution . . . . . . . . . . . . . . . . . . . . . .
35
4.4.3.1
Path Resolution by Parent Folder
. . . . . . . . . . . . . . . . .
36
4.4.3.2
Path Resolution . . . . . . . . . . . . . . . . . . . . . . . . . . .
36
4.4.3.3
Script Folder Path Resolution
. . . . . . . . . . . . . . . . . . .
37
4.4.3.4
Project Folder Path Resolution . . . . . . . . . . . . . . . . . . .
37
4.4.3.5
SIP Folder Path Resolution . . . . . . . . . . . . . . . . . . . . .
38
4.4.3.6
Temp Folder Path Resolution . . . . . . . . . . . . . . . . . . . .
38
4.4.3.7
Other Project and Application Paths
. . . . . . . . . . . . . . .
39
4.4.4
Script logging API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
39
4.4.5
User Interactions and Inputs
. . . . . . . . . . . . . . . . . . . . . . . . .
40
4.4.5.1
UserInteraction . . . . . . . . . . . . . . . . . . . . . . . . . . . .
40
4.4.6
Script Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
42
4.4.6.1
Script Exceptions
. . . . . . . . . . . . . . . . . . . . . . . . . .
42
4.4.6.2
Script Task Abortion by Exception . . . . . . . . . . . . . . . . .
42
4.4.6.3
Unhandled Exceptions from Tasks . . . . . . . . . . . . . . . . .
43
4.4.7
User defined Classes and Methods
. . . . . . . . . . . . . . . . . . . . . .
44
4.4.8
Usage of Automation API in own defined Classes and Methods . . . . . .
45
4.4.8.1
Access the Automation API like the Script code{} Block
. . . .
45
4.4.8.2
Access the Project API of the current active Project . . . . . . .
45
4.4.9
User defined Script Task Arguments in Commandline
. . . . . . . . . . .
46
4.4.9.1
User defined Argument Validators . . . . . . . . . . . . . . . . .
47
4.4.9.2
Call Script Task with Task Arguments . . . . . . . . . . . . . . .
49
4.4.10 Stateful Script Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
50
4.5
Project Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
52
4.5.1
Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
52
4.5.2
Accessing the active Project . . . . . . . . . . . . . . . . . . . . . . . . . .
52
4.5.3
Creating a new Project
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
54
4.5.3.1
Mandatory Settings . . . . . . . . . . . . . . . . . . . . . . . . .
55
4.5.3.2
General Settings . . . . . . . . . . . . . . . . . . . . . . . . . . .
55
4.5.3.3
Target Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . .
56
4.5.3.4
Post Build Settings
. . . . . . . . . . . . . . . . . . . . . . . . .
57
4.5.3.5
Folders Settings
. . . . . . . . . . . . . . . . . . . . . . . . . . .
57
4.5.3.6
DaVinci Developer Settings . . . . . . . . . . . . . . . . . . . . .
59
4.5.3.7
vVIRTUALtarget Settings
. . . . . . . . . . . . . . . . . . . . .
60
4.5.4
Opening an existing Project . . . . . . . . . . . . . . . . . . . . . . . . . .
62
4.5.4.1
Parameterized Project Load
. . . . . . . . . . . . . . . . . . . .
62
4.5.4.2
Open Project Details
. . . . . . . . . . . . . . . . . . . . . . . .
63
4.5.5
Saving a Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
63
4.5.6
Opening AUTOSAR Files as Project . . . . . . . . . . . . . . . . . . . . .
64
4.5.6.1
Raw AUTOSAR models as Project . . . . . . . . . . . . . . . . .
65
4.6
Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
66
4.6.1
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
66
4.6.2
Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
66
4.6.2.1
Read the ActiveEcuc
. . . . . . . . . . . . . . . . . . . . . . . .
66
4.6.2.2
Write the ActiveEcuc . . . . . . . . . . . . . . . . . . . . . . . .
69
4.6.2.3
Read the SystemDescription
. . . . . . . . . . . . . . . . . . . .
72
4.6.2.4
Write the SystemDescription . . . . . . . . . . . . . . . . . . . .
73
4.6.3
BswmdModel in AutomationInterface
. . . . . . . . . . . . . . . . . . . .
75
© 2017, Vector Informatik GmbH
3 of 250

---

Contents
4.6.3.1
BswmdModel Package and Class Names . . . . . . . . . . . . . .
75
4.6.3.2
Reading with BswmdModel . . . . . . . . . . . . . . . . . . . . .
75
4.6.3.3
Writing with BswmdModel . . . . . . . . . . . . . . . . . . . . .
76
4.6.3.4
Sip DefRefs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
77
4.6.3.5
BswmdModel DefRefs . . . . . . . . . . . . . . . . . . . . . . . .
77
4.6.3.6
Switching from Domain Models to BswmdModel . . . . . . . . .
78
4.6.4
MDF Model in AutomationInterface . . . . . . . . . . . . . . . . . . . . .
78
4.6.4.1
Reading the MDF Model . . . . . . . . . . . . . . . . . . . . . .
79
4.6.4.2
Reading the MDF Model by String . . . . . . . . . . . . . . . . .
81
4.6.4.3
Writing the MDF Model
. . . . . . . . . . . . . . . . . . . . . .
82
4.6.4.4
Simple Property Changes . . . . . . . . . . . . . . . . . . . . . .
83
4.6.4.5
Creating single Child Members (0:1) . . . . . . . . . . . . . . . .
83
4.6.4.6
Creating and adding Child List Members (0:*) . . . . . . . . . .
84
4.6.4.7
Updating existing Elements . . . . . . . . . . . . . . . . . . . . .
86
4.6.4.8
Deleting Model Objects . . . . . . . . . . . . . . . . . . . . . . .
87
4.6.4.9
Duplicating Model Objects . . . . . . . . . . . . . . . . . . . . .
87
4.6.4.10 Special properties and extensions . . . . . . . . . . . . . . . . . .
88
4.6.4.11 Reverse Reference Resolution - ReferencesPointingToMe . . . . .
90
4.6.4.12 AUTOSAR Root Object
. . . . . . . . . . . . . . . . . . . . . .
90
4.6.4.13 ActiveEcuC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
90
4.6.4.14 DefRef based Access to Containers and Parameters
. . . . . . .
91
4.6.4.15 Ecuc Parameter and Reference Value Access . . . . . . . . . . .
92
4.6.5
SystemDescription Access . . . . . . . . . . . . . . . . . . . . . . . . . . .
94
4.6.6
Transactions
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
95
4.6.6.1
Transactions API
. . . . . . . . . . . . . . . . . . . . . . . . . .
95
4.6.6.2
Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
97
4.6.7
Model Synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
98
4.6.8
Post-build selectable Variance . . . . . . . . . . . . . . . . . . . . . . . . .
99
4.6.8.1
Investigate Project Variance
. . . . . . . . . . . . . . . . . . . .
99
4.6.8.2
Variant Model Objects
. . . . . . . . . . . . . . . . . . . . . . . 100
4.6.9
Additional Model API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
4.6.9.1
User Annotations
. . . . . . . . . . . . . . . . . . . . . . . . . . 102
4.7
Generation
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
4.7.1
Code Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
4.7.1.1
Generation Settings . . . . . . . . . . . . . . . . . . . . . . . . . 104
4.7.1.2
Generation of External Generation Step . . . . . . . . . . . . . . 107
4.7.1.3
Evaluate generation or validation results
. . . . . . . . . . . . . 107
4.7.2
Generation Task Types
. . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
4.7.3
Software Component Templates and Contract Phase Headers Generation 111
4.7.3.1
Swct Generation Settings . . . . . . . . . . . . . . . . . . . . . . 111
4.7.3.2
Generation with default Project Settings
. . . . . . . . . . . . . 111
4.7.3.3
Generation of all Software Components . . . . . . . . . . . . . . 111
4.7.3.4
Generation of one Software Component . . . . . . . . . . . . . . 112
4.7.3.5
Generation of multiple Software Components . . . . . . . . . . . 113
4.7.3.6
Evaluate generation results . . . . . . . . . . . . . . . . . . . . . 113
4.8
Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
4.8.1
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
4.8.2
Access Validation-Results . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
4.8.3
Model Transaction and Validation-Result Invalidation . . . . . . . . . . . 115
4.8.4
Solve Validation-Results with Solving-Actions . . . . . . . . . . . . . . . . 115
4.8.4.1
Solver API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
© 2017, Vector Informatik GmbH
4 of 250

---

Contents
4.8.5
Advanced Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
4.8.5.1
Access Validation-Results of a Model Object . . . . . . . . . . . 118
4.8.5.2
Access Validation-Results of a DefRef . . . . . . . . . . . . . . . 118
4.8.5.3
Filter Validation-Results using an ID Constant . . . . . . . . . . 119
4.8.5.4
Identification of a Particular Solving-Action . . . . . . . . . . . . 119
4.8.5.5
Validation-Result Description as MixedText . . . . . . . . . . . . 120
4.8.5.6
Further IValidationResultUI Methods . . . . . . . . . . . . . . . 120
4.8.5.7
IValidationResultUI in a variant (Post Build Selectable) Project 121
4.8.5.8
Erroneous CEs of a Validation-Result . . . . . . . . . . . . . . . 121
4.8.5.9
Examine Solving-Action Execution . . . . . . . . . . . . . . . . . 123
4.8.5.10 Create a Validation-Result in a Script Task . . . . . . . . . . . . 124
4.8.5.11 Turn off auto-solving-action execution . . . . . . . . . . . . . . . 126
4.9
Update Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
4.9.1
Method Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
4.9.2
Example: Content of Input Files has changed. . . . . . . . . . . . . . . . . 127
4.9.3
Example: List of Input Files shall be changed . . . . . . . . . . . . . . . . 128
4.9.4
Prerequisites
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
4.10 Domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
4.10.1 Communication Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
4.10.1.1 CanControllers . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
4.10.1.2 CanFilterMasks
. . . . . . . . . . . . . . . . . . . . . . . . . . . 133
4.10.2 Diagnostics Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
4.10.2.1 DemEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
4.10.3 Mode Management Domain . . . . . . . . . . . . . . . . . . . . . . . . . . 137
4.10.3.1 BswM Auto Configuration
. . . . . . . . . . . . . . . . . . . . . 137
4.10.4 Runtime System Domain
. . . . . . . . . . . . . . . . . . . . . . . . . . . 140
4.10.4.1 Component Port Connection . . . . . . . . . . . . . . . . . . . . 140
4.10.4.2 Data Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
4.11 Persistency
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
4.11.1 Model Export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
4.11.1.1 Export ActiveEcuc . . . . . . . . . . . . . . . . . . . . . . . . . . 162
4.11.1.2 Export Post-build selectable Variants . . . . . . . . . . . . . . . 162
4.11.1.3 Advanced Export
. . . . . . . . . . . . . . . . . . . . . . . . . . 163
4.11.2 Model Import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
4.12 Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
4.12.1 Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
4.12.2 Converters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
4.13 Advanced Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
4.13.1 Java Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
4.13.1.1 Script Task Creation in Java Code . . . . . . . . . . . . . . . . . 168
4.13.1.2 Java Code accessing Groovy API . . . . . . . . . . . . . . . . . . 168
4.13.1.3 Java Code in dvgroovy Scripts . . . . . . . . . . . . . . . . . . . 169
4.13.2 Unit testing API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
4.13.2.1 JUnit4 Integration . . . . . . . . . . . . . . . . . . . . . . . . . . 170
4.13.2.2 Execution of Spock Tests . . . . . . . . . . . . . . . . . . . . . . 171
4.13.2.3 Registration of Unit Tests in Scripts . . . . . . . . . . . . . . . . 171
5
Data models in detail
173
5.1
MDF model - the raw AUTOSAR data
. . . . . . . . . . . . . . . . . . . . . . . 173
5.1.1
Naming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
5.1.2
The models inheritance hiearchy . . . . . . . . . . . . . . . . . . . . . . . 173
5.1.2.1
MIObject and MDFObject . . . . . . . . . . . . . . . . . . . . . 174
© 2017, Vector Informatik GmbH
5 of 250

---

Contents
5.1.3
The models containment tree . . . . . . . . . . . . . . . . . . . . . . . . . 174
5.1.4
The ECUC model
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
5.1.5
Order of child objects
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
5.1.6
AUTOSAR references . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
5.1.7
Model changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
5.1.7.1
Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
5.1.7.2
Undo/redo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
5.1.7.3
Event handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
5.1.7.4
Deleting model objects
. . . . . . . . . . . . . . . . . . . . . . . 178
5.1.7.5
Access to deleted objects . . . . . . . . . . . . . . . . . . . . . . 178
5.1.7.6
Set-methods
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
5.1.7.7
Changing child list content . . . . . . . . . . . . . . . . . . . . . 178
5.1.7.8
Change restrictions
. . . . . . . . . . . . . . . . . . . . . . . . . 178
5.2
Post-build selectable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
5.2.1
Model views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
5.2.1.1
What model views are . . . . . . . . . . . . . . . . . . . . . . . . 179
5.2.1.2
The IModelViewManager project service
. . . . . . . . . . . . . 179
5.2.1.3
Variant siblings . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
5.2.1.4
The Invariant model views . . . . . . . . . . . . . . . . . . . . . 182
5.2.1.5
Accessing invisible objects . . . . . . . . . . . . . . . . . . . . . . 184
5.2.1.6
IViewedModelObject
. . . . . . . . . . . . . . . . . . . . . . . . 185
5.2.2
Variant specific model changes
. . . . . . . . . . . . . . . . . . . . . . . . 185
5.2.3
Variant common model changes . . . . . . . . . . . . . . . . . . . . . . . . 186
5.3
BswmdModel details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
5.3.1
BswmdModel - DefinitionModel . . . . . . . . . . . . . . . . . . . . . . . . 187
5.3.1.1
Types of DefinitionModels
. . . . . . . . . . . . . . . . . . . . . 188
5.3.1.2
DefRef Getter methods of Untyped Model . . . . . . . . . . . . . 189
5.3.1.3
References
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
5.3.1.4
Post-build selectable with BswmdModel . . . . . . . . . . . . . . 192
5.3.1.5
Creation ModelView of the BswmdModel . . . . . . . . . . . . . 193
5.3.1.6
Lazy Instantiating . . . . . . . . . . . . . . . . . . . . . . . . . . 194
5.3.1.7
Optional Elements . . . . . . . . . . . . . . . . . . . . . . . . . . 194
5.3.1.8
Class and Interface Structure of the BswmdModel . . . . . . . . 194
5.3.1.9
BswmdModel write access
. . . . . . . . . . . . . . . . . . . . . 195
5.3.2
BswmdModel generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
5.3.2.1
DerivativeMapping . . . . . . . . . . . . . . . . . . . . . . . . . . 199
5.4
Model Utility Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
5.4.1
AutosarUtil . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
5.4.2
AsrPath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
5.4.3
AsrObjectLink . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
5.4.3.1
Object links depend on the MDF object type . . . . . . . . . . . 200
5.4.3.2
Restrictions of object links . . . . . . . . . . . . . . . . . . . . . 200
5.4.3.3
Examples for object link strings
. . . . . . . . . . . . . . . . . . 200
5.4.4
DefRefs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
5.4.4.1
TypedDefRefs
. . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
5.4.4.2
DefRef Wildcards
. . . . . . . . . . . . . . . . . . . . . . . . . . 202
5.4.5
CeState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
5.4.5.1
Getting a CeState object . . . . . . . . . . . . . . . . . . . . . . 204
5.4.5.2
IParameterStatePublished . . . . . . . . . . . . . . . . . . . . . . 204
5.4.5.3
IContainerStatePublished . . . . . . . . . . . . . . . . . . . . . . 205
5.5
Model Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
© 2017, Vector Informatik GmbH
6 of 250

---

Contents
5.5.1
EcucDefinitionAccess . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
5.5.1.1
Post-build loadable
. . . . . . . . . . . . . . . . . . . . . . . . . 206
5.5.1.2
Post-build selectable . . . . . . . . . . . . . . . . . . . . . . . . . 209
5.5.2
EcuConfigurationAccess . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
5.5.2.1
Post-build loadable
. . . . . . . . . . . . . . . . . . . . . . . . . 211
5.5.2.2
Post-build selectable . . . . . . . . . . . . . . . . . . . . . . . . . 213
6
AutomationInterface Content
215
6.1
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
6.2
Folder Structure
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
6.3
Script Development Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
6.3.1
DVCfg_AutomationInterfaceDocumentation.pdf . . . . . . . . . . . . . . 215
6.3.2
Javadoc HTML Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
6.3.3
Script Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
6.4
Libs and BuildLibs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
7
Automation Script Project
217
7.1
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
7.2
Automation Script Project Creation
. . . . . . . . . . . . . . . . . . . . . . . . . 217
7.3
Project File Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
7.4
IntelliJ IDEA Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
7.4.1
Supported versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
7.4.2
Building Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
7.4.3
Debugging with IntelliJ . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
7.4.4
Troubleshooting
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
7.5
Project Migration to newer DaVinci Configurator Version . . . . . . . . . . . . . 221
7.6
Debugging Script Project
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
7.7
Build System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
7.7.1
Jar Creation and Output Location . . . . . . . . . . . . . . . . . . . . . . 222
7.7.2
Gradle File Structure
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
7.7.2.1
projectConfig.gradle File settings . . . . . . . . . . . . . . . . . . 222
7.7.3
Advanced Build Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
7.7.3.1
Usage of external Libraries (Jars) in the AutomationProject
. . 223
7.7.3.2
Static Compilation of Groovy Code . . . . . . . . . . . . . . . . 224
7.7.3.3
Gradle dvCfgAutomation API Reference
. . . . . . . . . . . . . 225
8
AutomationInterface Changes between Versions
227
8.1
Currently Supported Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
8.2
Changes in MICROSAR AR4-R18 - Cfg5.15 . . . . . . . . . . . . . . . . . . . . . 230
8.2.1
General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
8.2.2
Automation Script Project . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
8.2.2.1
Supported IntelliJ IDEA Version . . . . . . . . . . . . . . . . . . 230
8.2.2.2
BuildSystem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
8.2.3
Script Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
8.2.3.1
User defined arguments . . . . . . . . . . . . . . . . . . . . . . . 230
8.2.4
Project Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
8.2.5
Project Creation vVIRTUALtarget settings . . . . . . . . . . . . . . . . . 230
8.2.6
Model changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
8.2.7
Model Automation API . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
8.2.7.1
IVarianceApi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
8.2.7.2
Access methods
. . . . . . . . . . . . . . . . . . . . . . . . . . . 232
8.2.7.3
Reverse Reference Resolution - ReferencesPointingToMe . . . . . 232
© 2017, Vector Informatik GmbH
7 of 250

---

Contents
8.2.7.4
Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
8.2.7.5
User Annotations
. . . . . . . . . . . . . . . . . . . . . . . . . . 232
8.2.7.6
Variance
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
8.2.7.7
Model Synchronization
. . . . . . . . . . . . . . . . . . . . . . . 232
8.2.8
Persistency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
8.2.9
Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
8.2.10 Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
8.2.10.1 Validation-Result Access Methods . . . . . . . . . . . . . . . . . 233
8.2.11 Generation
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
8.2.11.1 SWC Templates and Contract Headers Generation . . . . . . . . 233
8.2.12 BswmdModel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
8.2.12.1 BswmdModel Groovy . . . . . . . . . . . . . . . . . . . . . . . . 233
8.2.12.2 DerivativeMapping . . . . . . . . . . . . . . . . . . . . . . . . . . 234
8.2.13 Mode Management Domain . . . . . . . . . . . . . . . . . . . . . . . . . . 234
8.2.14 Runtime System Domain
. . . . . . . . . . . . . . . . . . . . . . . . . . . 234
8.2.14.1 Data Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
8.3
Changes in MICROSAR AR4-R17 - Cfg5.14 . . . . . . . . . . . . . . . . . . . . . 235
8.3.1
General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
8.3.2
Script Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
8.3.2.1
Stateful Script Tasks . . . . . . . . . . . . . . . . . . . . . . . . . 235
8.3.3
Automation Script Project . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
8.3.3.1
Groovy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
8.3.3.2
Supported IntelliJ IDEA Version . . . . . . . . . . . . . . . . . . 235
8.3.3.3
BuildSystem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
8.3.4
Converter Refactoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
8.3.5
UserInteraction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
8.3.6
Project Load . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
8.3.6.1
AUTOSAR Arxml Files . . . . . . . . . . . . . . . . . . . . . . . 236
8.3.7
Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
8.3.7.1
Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
8.3.7.2
MDF Model Read and Write . . . . . . . . . . . . . . . . . . . . 236
8.3.7.3
SystemDescription Access . . . . . . . . . . . . . . . . . . . . . . 237
8.3.7.4
ActiveEcuc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
8.3.8
Persistency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
8.3.9
Generation
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
8.3.10 BswmdModel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
8.3.10.1 Writing with BswmdModel . . . . . . . . . . . . . . . . . . . . . 237
8.3.11 BswmdModel Groovy
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
8.3.12 Diagnostics Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
8.3.13 Communication Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
8.3.14 Runtime System Domain
. . . . . . . . . . . . . . . . . . . . . . . . . . . 238
8.4
Changes in MICROSAR AR4-R16 - Cfg5.13 . . . . . . . . . . . . . . . . . . . . . 239
8.4.1
General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
8.4.2
API Stability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
8.4.3
Beta Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
9
Appendix
240
Nomenclature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
Figures
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
Listings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
ToDos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
© 2017, Vector Informatik GmbH
8 of 250

---

1 Introduction
1.1 General
The user of the DaVinci Configurator Pro can create scripts, which will be executed inside of
the Configurator to:
• Create projects
• Update projects
• Manipulate the data model with an access to the whole AUTOSAR model
• Generate code
• Executed repetitive tasks with code, without user interaction
• More
The scripts are written by the user with the DaVinci Configurator AutomationInterface.
1.2 Facts
Installation
The DaVinci Configurator Pro can execute customer defined scripts out of the
box. No additional scripting language installation is required by the customer.
Languages
The scripts are written in Groovy or Java. See 3.2 on page 18 for details.
Debugging Support
The scripts can be debugged via IntelliJ IDEA. See 7.6 on page 221.
Documentation
The AutomationInterface provides a comprehensive documentation:
• This document
• Javadoc HTML pages as class reference
• Script samples and templates
– ScriptProject creation assistant in the DaVinci Configurator
• API documentation inside of an IDE
• Integrated Definition (BSWMD) description for all modules in the SIP
Code Completion
You have code completion for Groovy and Java for the DaVinci Configu-
rator AutomationInterface. You have to use IntelliJ IDEA for code completion.1
There is also a SIP based code completion for contained Module, Container and Parameter
definitions. This eases the traversal through the AUTOSAR model.
1See chapter 7 on page 217 for details.
© 2017, Vector Informatik GmbH
9 of 250

---

2 Getting started with Script Development
2.1 General
This chapter gives a short introduction of how to get started with script file or script project
creation.
Attention: You need at least one of the License Options .WF or .MD to develop scripts.
The script project creation assistant will not be available otherwise.
2.2 Automation Script Development Types
The DaVinci Configurator supports two types of automation scripts:
• Script files (.dvgroovy files)
• Script projects (.jar files)
Script File
The script file provides the simplest way to implement an automation script.
When the script gets bigger you should migrate to a script project.
To create a script file proceed with chapter 2.3.
Script Project
The script project is more effort to create and maintain, but provides IDE
support for:
• Code completion
• Syntax highlighting
• API Documentation
• Debug support
• Build support
It is the recommended way to develop scripts, containing more tasks or multiple clas-
ses.
To create a script project proceed with chapter 2.4 on page 12.
2.3 Script File
The script file is the simplest way to implement an automation script. It could be sufficient
for small tasks and if the developer does not need support by the tool during implementing the
script and if debugging is not required.
Prerequisites
Before you start, please make sure that you have a SIP containing a DaVinci
Configurator 5 available on your system.
© 2017, Vector Informatik GmbH
10 of 250

---

Chapter 2.
Getting started with Script Development
Creation
Inside your SIP you find examples of automation script files.
Create your own
script folder and copy an example, e.g. ...ScriptSamples/SimpleScript.dvgroovy to your
folder.
Rename the script file and open it in any text editor. In case of SimpleScript.dvgroovy
it consists of several tasks.
One of the tasks will print a "HelloApplication" string to the
console.
Figure 2.1: Script Samples location
Open the DaVinci Configurator inside your SIP. If not yet visible open the Views
• Script Locations
• Script Tasks
via the View menu.
In the Script Locations View select the location folder User@Machine. On its context menu
you can Add a script location. Select your own script folder.
Figure 2.2: Script Locations View
Alternatively you could add the script location to the Session folder. In this case the script
location would only be stored in the current session.
Switch to the Script Tasks View. It provides an overview over the tasks contained in your
script.
Figure 2.3: Script Tasks View
© 2017, Vector Informatik GmbH
11 of 250

---

Chapter 2.
Getting started with Script Development
Execute the SimpleAppTask by double-click or by the Execute Command contained in its
context menu or by the Execute Button of the Task View and check that "HelloApplication" is
printed in the console.
You can modify the implementation according to your needs. For the AutomationInterface
API Reference see chapter 4 on page 24. It is sufficient to edit and save the modifications in
your editor. The file is automatically reloaded by the DaVinci Configurator then and can be
executed immediately.
Debugging
It is not possible to debug a script file, if you want to debug, please migrate to a
script project, see chapter 2.4.
2.4 Script Project
The script project is the preferred way to develop an automation script, if the content is more
than one simple task.
A script project is a normal IDE project (IntelliJ IDEA recommended), with compile bindings
to the DaVinci Configurator AutomationInterface.
The DaVinci Configurator will load a script project as a single .jar file. So the script project
must be built and packaged into a .jar file before it can be executed.
Prerequisites
Before you start, please make sure that the following items are available on
your system:
• SIP containing a DaVinci Configurator 5
• Java JDK: For the development with the IntelliJ IDEA a "Java SE Development Kit 8"
(JDK 8) is required. Please install the JDK 8 as described in chapter 2.4.2 on page 14.
• IDE: For the script project development the recommended IDE is IntelliJ IDEA. Please
install IntelliJ IDEA as described in chapter 2.4.3 on page 15.
• Build system: To build the script project the build system Gradle is required. See
chapter 2.4.4 on page 15 for installation instructions.
Project Creation
Open the DaVinci Configurator inside your SIP. If not yet visible open the
following Views via the View menu:
• Script Locations
• Script Tasks
Switch to the View Script Tasks and select the Button Create New Script Project....
Figure 2.4: Create New Script Project... Button
Note: If the button is not available, please make sure you have least one of the License
Options .WF or .MD to develop scripts.
© 2017, Vector Informatik GmbH
12 of 250

---

Chapter 2.
Getting started with Script Development
The New Automation Script Project dialogs is opened. Click Next because you are reading
the document.
On the second page first you have to select a Script template on which the new project shall be
based on. Please select Default Automation Project and click Next.
On the third page Project Settings, please specify the following items:
• Script Project Name
– Define a name for your new project.
• Project Location
– Select a parent folder in which your project shall be created in.
Note: A new folder with the project name is created in this folder.
• Gradle Distribution URL
– Select one option:
∗ Gradle Default
· This will download the required Gradle build system. To use this option you
need internet access.
∗ Custom URL
· Specify an URL to your own Gradle distribution.
New settings are displayed to specify the path. To setup your own Gradle
build system see 2.4.4 on page 15.
• Open IntelliJ IDEA
– Select this option if the project shall automatically be opened in IntelliJ IDEA after
creation. In case IntelliJ IDEA is not installed on your system a warning will be
issued.
Figure 2.5: Project Settings
Proceed until the dialog is finished.
© 2017, Vector Informatik GmbH
13 of 250

---

Chapter 2.
Getting started with Script Development
A new project will be created. Necessary tasks as setting up the IntelliJ IDEA and building the
project are automatically initiated. At the end IntelliJ IDEA will be started with the created
project.
You can now modify the implementation according to your needs. For the AutomationInterface
API Reference see chapter 4 on page 24. To edit and rebuild the project use IntelliJ IDEA.
After each build the project is automatically reloaded by the DaVinci Configurator and can be
executed there.
IntelliJ IDEA Usage
Ensure that the Gradle JVM and the Project SDK are set in the IntelliJ
IDEA Settings. For details see 2.4.3 on the following page.
Having modified and saved MyScript.groovy in the IntelliJ IDEA editor you can build the
project by pressing the Run Button provided in the toolbar. The functionality of this Run
Button is determined by the option selected in the Menu beneath this button. In this menu
<ProjectName> [build] shall be selected.
Figure 2.6: Project Build
For more information to IntelliJ IDEA usage please see chapter 7.4 on page 218. If you have
trouble with IntelliJ, see 7.4.4 on page 220.
Debugging
To debug the script project follow the instructions in chapter 7.6 on page 221.
DaVinci Configurator views
The View Script Tasks provides an overview over the scripts
and tasks contained in the project. The newly created project already contains a sample script
file MyScript.groovy.
The Default Automation Project sample script file contains one task that prints a "Hello-
Application" string to the console. Run and check it as already described in 2.3 on page 10.
If you have selected a different Script Sample the MyScript.groovy will contain the sample
code.
The View Script Locations contains the path to the script project build folder containing the
built .jar file.
2.4.1 Script Project Development
For more details to the development of a script project see chapter 7 on page 217.
2.4.2 Java JDK Setup
Install a JDK 8 on your system. The Java JDK website provides download versions for different
systems. Download an appropriate version.
The architecture is not relevant, both x86 and x64 are valid.
The JDK is needed for the Java Compiler for IntelliJ IDEA and Gradle.
© 2017, Vector Informatik GmbH
14 of 250

---

Chapter 2.
Getting started with Script Development
2.4.3 IntelliJ IDEA Setup
Install IntelliJ IDEA on your system. The IntelliJ IDEA website provides download versions
for different applications. Download1 a version that supports Java and Groovy and that is in
the list of supported versions (see list 7.4.1 on page 218).
Code completion and compilation additionally require that the Project SDK is set. Therefore
open the File -> Project Structure Dialog in IntelliJ IDEA and switch to the settings dialog
for Project. If not already available set an appropriate option for the Project SDK. Please
set the value to a valid Java JDK ( see 2.4.2 on the previous page). Do not select a JRE.
Figure 2.7: Project SDK Setting
To enable building of projects ensure that the Gradle JVM is set. Therefore open the File
-> Settings Dialog in IntelliJ IDEA and find the settings dialog for Gradle. If not already
available set an appropriate option for the Gradle JVM. Please set the value to the same Java
JDK as the Project SDK above. Do not select a JRE.
If you do not have the Gradle settings, please make sure that the Gradle plugin inside of
IntelliJ IDEA is installed. Open the File -> Settings Dialog then Plugins and select the
Gradle plugin.
Figure 2.8: Gradle JVM Setting
2.4.4 Gradle Setup
If your system has internet access you can use the default Gradle Build System provided by
the DaVinci Configurator. In this case you do not have to install Gradle. If you are a Vector
internal user you could also skip the Gradle installation.
1 Vector-Internal:
If
you
are
inside
of
the
Vector
intranet,
you
could
download
it
from:
file:////vistrpesfs1/project2/DaVinci/Eclipse/Platform/CFG5/BuildComponents/IntelliJ
© 2017, Vector Informatik GmbH
15 of 250

---

Chapter 2.
Getting started with Script Development
If you want to use your own Gradle Build System install it on your system. The Gradle website
provides the required download version for the Gradle Build System. Please download the
version 3.0. See chapter 7.7 on page 221 for more details to the Build System.
© 2017, Vector Informatik GmbH
16 of 250

---

3 AutomationInterface Architecture
3.1 Components
The DaVinci Configurator consists of three components:
• Core components
• AutomationInterface (AI) - also called Automation API
• Scripting engine
The other part is the script provided by the user.
The Scripting engine will load the script, and the script uses the AutomationInterface to perform
tasks. The AutomationInterface will translate the requests from the script into Core components
calls.
Figure 3.1: DaVinci Configurator components and interaction with scripts
The separation of the AutomationInterface and the Core components has multiple benefits:
• Stable API for script writters
– Including checks, that the API will not break in following releases
• Well defined and documented API
• Abstraction from the internal heavy lifting
– This ease the usage for the user, because the automation interfaces are tailored to
the use cases.
PublishedApi
All AutomationInterface classes are marked with a special annotation to high-
light the fact that it is part of the published API. The annotation is called @Publishe-
dApi.
So every class marked with @PublishedApi can be used by the client code. But if a class is
not marked with @PublishedApi or is marked with @Deprecated it should not be used by any
client code, nor shall a client call methods via reflection or other runtime techniques.
© 2017, Vector Informatik GmbH
17 of 250

---

Chapter 3.
AutomationInterface Architecture
You should not access DaVinci Configurator private or package private classes, methods or
fields.
3.2 Languages
The DaVinci Configurator provides out of the box language support for:
• Java1
• Groovy2
The recommended scripting language is Groovy which shall be preferred by all users.
3.2.1 Why Groovy
Flat Learning Curve
Groovy is concise, readable with an expressive syntax and is easy to
learn for Java developers3.
• Groovy syntax is 95%-compatible with Java4
• Any Java developer will be able to code in Groovy without having to know nor understand
the subtleties of this language
This is very important for teams where there’s not much time for learning a new language.
Domain-Specific Languages (DSL)
Groovy has a flexible and malleable syntax, advanced
integration and customization mechanisms, to integrate readable business rules in your appli-
cations.
The DSL features of Groovy are extensively used in DaVinci Automation API to provide simple
and expressive syntax.
Powerful Features
The Groovy language supports Closures, builders, runtime & compile-time
meta-programming, functional programming, type inference, and static compilation.
Website
The website of Groovy is http://groovy-lang.org. It provides a good documentation
and starting guides for the Groovy language.
Groovy Book
The book "Groovy in Action, Second Edition"5 provides a comprehensive
guide to Groovy programming language. It is written by the developers of Groovy.
1http://http://www.java.com [2016-05-09]
2http://groovy-lang.org [2016-05-09]
3Copied from http://groovy-lang.org [2016-05-09]
4Copied from http://melix.github.io/blog/2010/07/27/experience_feedback_on_groovy.html [2016-05-09]
5Groovy in Action, Second Edition by Dierk König, Paul King, Guillaume Laforge, Hamlet D’Arcy, Cédric
Champeau, Erik Pragt, and Jon Skeet June 2015 ISBN 9781935182443
https://www.manning.com/books/groovy-in-action-second-edition [2016-05-09]
© 2017, Vector Informatik GmbH
18 of 250

---

Chapter 3.
AutomationInterface Architecture
3.3 Script Structure
A script always contains one or more script tasks. A script is represented by an instance of
IScript, the contained tasks are instances of IScriptTask.
Figure 3.2: Structure of scripts and script tasks
You create the IScript and IScriptTask instance with the API described in chapter 4.2 on
page 25.
The script task type (IScriptTaskType) defines where the task could be executed. It also
defines the signature of the task’s code {} block. See chapter 4.3 on page 29 for the available
script task types.
3.3.1 Scripts
Script contain the tasks to execute and are loaded from the script locations specified in the
DaVinci Configurator.
The DaVinci Configurator supports two types of automation scripts:
• Script files (.dvgroovy files)
• Script projects (.jar files)
For details to the script project, see chapter 7 on page 217.
© 2017, Vector Informatik GmbH
19 of 250

---

Chapter 3.
AutomationInterface Architecture
3.3.2 Script Tasks
Script tasks are the executable units of scripts, which are executed at certain points in the
DaVinci Configurator (specified by the IScriptTaskType). Every script task has a code {}
block, which contains the logic to execute.
3.3.3 Script Locations
Script locations define where script files are loaded from. These locations are edited in the
DaVinci Configurator Script Locations view. You can also start the Configurator with the
option –scriptLocations to specify additional locations.
The DaVinci Configurator could load scripts from different script locations:
• SIP
• Project
• User-defined directories
• More
3.4 Script loading
All scripts contained in the script locations are automatically loaded by the DaVinci Configu-
rator. If new scripts are added to script locations these scripts are automatically loaded.
If a script changes during runtime of the DaVinci Configurator the whole script is reloaded and
then executable, without a restart of the tool or a reload of the project.
This enables script development during the runtime of the DaVinci Configurator
• No project reload
• No tool restart
• Faster feedback loops
Note: A jar file of a script project should be updated by the Gradle build system, not by hand.
Because the Java VM is holding a lock to the file. If you try to replace the file in the explorer
you will get an error message.
3.4.1 Internal Script Reload Behavior
Your script can be loaded and unloaded automatically multiple times during the execution of
the DaVinci Configurator. More precise, when a script is currently not used and there are
memory constraints your script will be automatically unloaded.
If the script will be executed again, it is automatically reloaded and then executed. So it is
possible that the script initialization code is called multiple times in the DaVinci Configurator
lifecycle. But this is no issue, because the script and the tasks shall not have any internal
state during initialization.
© 2017, Vector Informatik GmbH
20 of 250

---

Chapter 3.
AutomationInterface Architecture
Memory Leak Prevention
The feature above is implemented to prevent leaking memory from
an automation script into the DaVinci Configurator memory. So when the memory run low, all
unused scripts are unloaded, which will also free leaked memory of scripts.
But this does not mean that is impossible to construct memory leaks from an automation
script. E.g. Open file handles without closing them will still cause a memory leak.
3.5 Script editing
The DaVinci Configurator does not contain any editing support for scripts, like:
• Script editor
• Debugger
• REPL (Read-Eval-Print-Loop)
These tasks are delegated to other development tools:
• IntelliJ IDEA (recommended)
• EclipseIDE
• Notepad++
See chapter 7 on page 217 for script development and debugging with IntelliJ IDEA.
3.6 Licensing
The DaVinci Configurator requires certain license options to develop and/or execute script
tasks.
The required license options differ between development and execution time. Normally you
need more license options to develop scripts than you need to execute them.
The default license options are:
• .PRO option for execution
• .WF option for development and debugging
The license option .MD includes the option .WF for automation scripts. So you can also use
.MD as replacement of .WF.
Some script task may require different options during development or execution. It is also
possible that the execution does not require any license option. See chapter 4.3 on page 29 for
details, which script task type requires which license.
3.7 Script Coding Conventions and Constraints
This section describes conventions, which you are advised to apply.
© 2017, Vector Informatik GmbH
21 of 250

---

Chapter 3.
AutomationInterface Architecture
Requirement Levels - Wording
• Shall: This word, or the terms "Mandatory", "Required" or "Must", mean that the rule or
convention is an absolute requirement.
• Shall not: This word, or the terms "Must not" mean that the rule or convention is an
absolute prohibition.
• Should: This word, or the adjective "Recommended", mean that there may exist valid
reasons in particular circumstances to ignore a particular item, but the full implications
must be understood and carefully weighed before choosing a different course.
• Should not: This phrase, or the phrase "Not recommended" mean that there may exist
valid reasons in particular circumstances when the particular behavior is acceptable or
even useful, but the full implications should be understood and the case carefully weighed
before implementing any behavior described with this label.
• May: This word, or the adjective "Optional", mean that an item is truly optional.
See also "RFC 2119: Key words for use in RFCs to Indicate Requirement Levels"6.
3.7.1 Usage of static fields
You shall not use any static fields in your script code or other written classes inside of your
project. Except static final constants of simple immutable types like (normally compile time
constants):
• int
• boolean
• double
• String
• ...
Static fields will cause memory leaks, because the fields are not garbage collected. Exam-
ple:
scriptTask (" Name "){
code {
MyClass . leakVariable . add (" Leaked Memory ")
}
}
c l a s s MyClass {
s t a t i c List l e a k V a r i a b l e = []
}
Listing 3.1: Static field memory leak
The use of static fields of the AutomationInterface is allowed.
6https://www.ietf.org/rfc/rfc2119.txt
© 2017, Vector Informatik GmbH
22 of 250

---

Chapter 3.
AutomationInterface Architecture
3.7.2 Usage of Outer Closure Scope Variables
The same static field rule applies to variables passed from outer Closure scopes into a script
task code{} block. You shall not cache/save data into such variables.
Example:
scriptTask (" Name "){
def i n v a l i d V a r i a b l e = [] // List
code {
invalidVariable . add (" Leaked Memory ")
}
}
Listing 3.2: Memory leak with closure variable
3.7.3 States over script task execution
You shall not hold or save any states over multiple script task executions in your classes.
The script task should be state less. All states are provided by the Automation API or the data
models.
If you need to cache data over multiple executions, see chapter 4.4.10 on page 50 for a solu-
tion.
3.7.4 Usage of Threads
A script task shall not create any Thread, Executor, ThreadPool or ForkJoinPool in-
stances. If multithreading is required, the Automation API provides the corresponding met-
hods.
A different thread will not provide any Automation APIs and will cause IllegalStateExcepti-
ons.
3.7.5 Usage of DaVinci Configurator private Classes Methods or Fields
A script task should not call or rely on any non published API or private (also package private)
classes, methods or fields. You also should not use any reflection techniques to reflect about
Configurator internal APIs. Otherwise it is not guaranteed that your script will work with other
DaVinci Configurator versions. See 3.1 on page 17 for details about PublishedApi.
But it is valid to use reflection for your own script code.
© 2017, Vector Informatik GmbH
23 of 250

---

4 AutomationInterface API Reference
4.1 Introduction
This chapter contains the description of the DaVinci Configurator AutomationInterface. The
figure 4.1 shows the APIs and the containment structure of the different APIs.
Figure 4.1: The API overview and containment structure
The components have an hierarchical order, where and when the components are usable. When a
component is contained in another the component is only usable, when the other is active.
© 2017, Vector Informatik GmbH
24 of 250

---

Chapter 4.
AutomationInterface API Reference
Usage examples:
• The Generation API is only usable inside of a loaded Project
• The Workflow Update API is only usable outside of a loaded Project
4.2 Script Creation
This section lists the APIs to create, execute and query information for script tasks. The
sections document the following aspects:
• Script task creation
• Description and help texts
• Task executable query
4.2.1 Script Task Creation
To create a script task you have to call one of the scriptTask() methods. The last parameter
of the scriptTask methods can be used to set additional options of the task. Every script task
needs one IScriptTaskType. See chapter 4.3 on page 29 for all available task types.
The code{ } block is required for every IScriptTask. The block contains the code, which is
executed when the task is executed.
Script Task with default Type
The method scriptTask() will create an script task for the
default IScriptTaskType DV_PROJECT.
scriptTask (" TaskName "){
code {// Task execution code here
}
}
Listing 4.1: Task creation with default type
Script Task with Task Type
You could also define the used IScriptTaskType at the script-
Task() methods.
The methods
• scriptTask(String, IApplicationScriptTaskType, Closure)
• scriptTask(String, IProjectScriptTaskType, Closure)
will create an script task for passed IScriptTaskType. The two methods differentiate, if a
project is required or not. See chapter for all available task types 4.3 on page 29
© 2017, Vector Informatik GmbH
25 of 250

---

Chapter 4.
AutomationInterface API Reference
scriptTask (" TaskName ", DV_APPLICATION ){
code {// Task execution code here
}
}
Listing 4.2: Task creation with TaskType Application
scriptTask (" TaskName ", DV_PROJECT ){
code {// Task execution code here
}
}
Listing 4.3: Task creation with TaskType Project
Multiple Tasks in one Script
It is also possible to define multiple tasks in one script.
scriptTask (" TaskName "){
code { }
}
scriptTask (" SecondTask "){
code { }
}
Listing 4.4: Define two tasks is one script
4.2.1.1 Script Creation with IDE Code Completion Support
The IDE could not know which API is available inside of a script file. So a glue code is needed
to tell the IDE, what API is callable inside of a script file.
The ScriptApi.daVinci() method enables the IDE code completion support in a script file.
You have to write the daVinci{ } block and inside of the block the code completion is available.
The following sample shows the glue code for the IDE:
i m p o r t s t a t i c com . vector . cfg . a u t o m a t i o n . api . Sc ri pt Api .*
// daVinci enables the IDE code completion support
daVinci {
// Normal script code here
scriptTask (" TaskName "){
code {// Script task execution code here
}
}
}
Listing 4.5: Script creation with IDE support
The daVinci{} block is only required for code completion support in the IDE. It has no effect
during runtime, so the daVinci{} is optional in script files (.dvgroovy)
© 2017, Vector Informatik GmbH
26 of 250

---

Chapter 4.
AutomationInterface API Reference
4.2.1.2 Script Task isExecutableIf
You can set an isExecutableIf handler, which is called before the IScriptTask is executed.
The code can evaluate, if the IScriptTask shall be executable. If the handler returns true, the
code of the IScriptTask is executable, otherwise false. See class IExecutableTaskEvaluator
for details.
The Closure isExecutable has to return a boolean. The passed arguments to the closure are
the same as the code{ } block arguments.
Inside of the Closure a property notExecutableReasons is available to set reasons why it is not
executable. It is highly recommended to set reasons, when the Closure returns false.
scriptTask (" TaskName "){
isExecutableIf { taskArgument ->
// Decide , if the task shall be executable
if ( t a s k A r g u m e n t == " C o r r e c t A r g u m e n t " ) {
r e t u r n t r u e
}notExecutableReasons.addReason "The argument is not 'CorrectArgument'"
r e t u r n f a l s e
}
code { taskArgument ->
// Task execution code here
}
}
Listing 4.6: Task with isExecutableIf
4.2.2 Description and Help
Script Description
The script can have an optional description text. The description shall
list what this script contains. The method scriptDescription(String) sets the description
of the script.
The description shall be a short overview. The String can be multiline.
// You can set a description for the whole script
scriptDescription " The Script has a description "
scriptTask (" Task "){
code {}
}
Listing 4.7: Script with description
Task Description
A script task can have an optional description text. The description shall
help the user of the script task to understand what the task does. The method taskDescrip-
tion(String) sets the description of the script task.
The description shall be a short overview. The String can be multiline.
© 2017, Vector Informatik GmbH
27 of 250

---

Chapter 4.
AutomationInterface API Reference
scriptTask (" TaskName "){
taskDescription " The description of the task "
code { }
}
Listing 4.8: Task with description
Task Help
A script task can also have an optional help text. The help text shall describe in
detail what the task does and when it could be executed. The method taskHelp(String) sets
the help of the script task.
The help shall be elaborate text about what the task does and how to use it. The String can
be multiline.
The help text is automatically expanded with the help for user defined script task arguments,
see IScriptTaskBuilder.newUserDefinedArgument(String, Class, String).
scriptTask (" TaskName "){
taskDescription " The short description of the task "
taskHelp """
The long help text
of the script with multiple lines
And paragraphs ...
""". stripIndent ()
// stripIndent () will strip the indentation of multiline strings
// The three """ are needed , if you want to write a multiline string
code { }
}
Listing 4.9: Task with description and help text
© 2017, Vector Informatik GmbH
28 of 250

---

Chapter 4.
AutomationInterface API Reference
4.3 Script Task Types
The IScriptTaskType instances define where a script task is executed in the DaVinci Configu-
rator. The types also define the arguments passed to the script task execution and what return
type an execution has.
Every script task needs an IScriptTaskType. The type is set during creation of the script
tasks.
License Options
For the common explanation of the required license options, see chapter 3.6
on page 21.
Interfaces
All task types implement the interface IScriptTaskType. The following figure
show the type and the defined sub types:
Figure 4.2: IScriptTaskType interfaces
4.3.1 Available Types
The class IScriptTaskTypeApi defines all available IScriptTaskTypes in the DaVinci Confi-
gurator. All task types start with the prefix DV_.
None at parameters and return types mean, that any arguments could be passed and return to
or from the task. Normally it will be nothing. The arguments are used, when the task is called
in unit tests for example.
4.3.1.1 Application Types
Application
The type DV_APPLICATION is for application wide script tasks. A task could
create/open/close/update projects. Use this type, if you need full control over the project
handling, or you want to handle multiple project at once.
© 2017, Vector Informatik GmbH
29 of 250

---

Chapter 4.
AutomationInterface API Reference
Name
Application
Code identifier
DV_APPLICATION
Task type interface
IApplicationScriptTaskType
Parameters
None
Return type
None
Execution
Standalone
Required license option
Development: .WF Execution: .PRO
4.3.1.2 Project Types
Project
The type DV_PROJECT is for project script tasks. A task could access the currently
loaded project. Manipulate the data, generate and save the project. This is the default type, if
no other type is specified.
Name
Project
Code identifier
DV_PROJECT
Task type interface
IProjectScriptTaskType
Parameters
None
Return type
None
Execution
Standalone
Required license option
Development: .WF Execution: .PRO
Module activation
The type DV_ON_MODULE_ACTIVATION allows the script to hook any Mo-
dule Activation in a loaded project. Every DV_ON_MODULE_ACTIVATION task is automatically
executed, when an "Activate Module" operation is executed. The script task is called after the
module was created.
Name
Module activation
Code identifier
DV_ON_MODULE_ACTIVATION
Task type interface
IProjectScriptTaskType
Parameters
MIModuleConfiguration moduleConfiguration
Return type
Void
Execution
Automatically during module activation
Required license option
Development: .WF Execution: .PRO
Module deactivation
The type DV_ON_MODULE_DEACTIVATION allows the script to hook any
Module Deactivation in a loaded project. Every DV_ON_MODULE_DEACTIVATION task is automa-
tically executed, when an "Deactivate Module" operation is executed. The script task is called
before the module is deleted.
Name
Module deactivation
Code identifier
DV_ON_MODULE_DEACTIVATION
Task type interface
IProjectScriptTaskType
Parameters
MIModuleConfiguration moduleConfiguration
Return type
Void
Execution
Automatically during module deactivation
Required license option
Development: .WF Execution: .PRO
© 2017, Vector Informatik GmbH
30 of 250

---

Chapter 4.
AutomationInterface API Reference
4.3.1.3 UI Types
Editor selection
The type DV_EDITOR_SELECTION allows the script task to access the currently
selected element of an editor. The task is executed in context of the selection and is not callable
by the user without an active selection.
Name
Editor selection
Code identifier
DV_EDITOR_SELECTION
Task type interface
IProjectScriptTaskType
Parameters
MIObject selectedElement
Return type
Void
Execution
In context menu of an editor selection
Required license option
Development: .WF Execution: .PRO
Editor multiple selections
The type DV_EDITOR_MULTI_SELECTION allows the script task to
access the currently selected elements of an editor. The task is executed in context of the
selection and is not callable by the user without an active selection. The type is also usable
when the DV_EDITOR_SELECTION apply.
Name
Editor multiple selections
Code identifier
DV_EDITOR_MULTI_SELECTION
Task type interface
IProjectScriptTaskType
Parameters
List<MIObject> selectedElements
Return type
Void
Execution
In context menu of an editor selection
Required license option
Development: .WF Execution: .PRO
4.3.1.4 Generation Types
Generation Step
The type DV_GENERATION_STEP defines that the script task is executable as
a GenerationStep during generation. The user has to explicitly create an GenerationStep in the
Project Settings Editor, which references the script task.
Name
Generation Step
Code identifier
DV_GENERATION_STEP
Task type interface
IProjectScriptTaskType
Parameters
EGenerationPhaseType phase
EGenerationProcessType processType
IValidationResultSink resultSink
Return type
Void
Execution
Selected as GenerationStep in GenerationProcess
Required license option
Development: .MD Execution: None
See chapter 4.7.2 on page 109 for usage samples.
Custom Workflow Step
The type DV_CUSTOM_WORKFLOW_STEP defines that the script task
is executable as a CustomWorkflow step in the CustomWorkflow process. The user has to
explicitly create an CustomWorkflow step in the Project Settings Editor, which references the
script task.
© 2017, Vector Informatik GmbH
31 of 250

---

Chapter 4.
AutomationInterface API Reference
Name
Custom Workflow Step
Code identifier
DV_CUSTOM_WORKFLOW_STEP
Task type interface
IProjectScriptTaskType
Parameters
None
Return type
Void
Execution
Selected as Custom Workflow Step in the Project Settings
Required license option
Development: .WF Execution: .PRO
See chapter 4.7.2 on page 109 for usage samples.
Generation Process Start
The type DV_ON_GENERATION_START defines that the script task is
automatically executed when the generation is started.
Name
Generation Process Start
Task type interface
IProjectScriptTaskType
Code identifier
DV_ON_GENERATION_START
Parameters
List<EGenerationPhaseType> generationPhases
List<IGenerator> executedGenerators
Return type
Void
Execution
Automatically before GenerationProcess
Required license option
Development: .MD Execution: None
See chapter 4.7.2 on page 109 for usage samples.
Generation Process End
The type DV_ON_GENERATION_END defines that the script task is
automatically executed when the generation has finished.
Name
Generation Process End
Code identifier
DV_ON_GENERATION_END
Task type interface
IProjectScriptTaskType
Parameters
EGenerationProcessResult processResult
List<IGenerator> executedGenerators
Return type
Void
Execution
Automatically after GenerationProcess
Required license option
Development: .MD Execution: None
See chapter 4.7.2 on page 109 for usage samples.
© 2017, Vector Informatik GmbH
32 of 250

---

Chapter 4.
AutomationInterface API Reference
4.4 Script Task Execution
This section lists the APIs to execute and query information for script tasks. The sections
document the following aspects:
• Script task execution
• Logging API
• Path resolution
• Error handling
• User defined classes and methods
• User defined script task arguments
4.4.1 Execution Context
Every IScriptTask could be be executed, and retrieve passed arguments and other context
information. This execution information of a script task is tracked by the IScriptExecution-
Context.
The IScriptExecutionContext holds the context of the execution:
• The script task arguments
• The current running script task
• The current active script logger
• The active project, if existing
• The script temp folder
• The script task user defined arguments
The IScriptExecutionContext is also the entry point into every automation API, and pro-
vide access to the different API classes. The classes are describes in their own chapters like
IProjectHandlingApiEntryPoint or IWorkflowApiEntryPoint.
The context is immediately active, when the code block of an IScriptTask is called.
Groovy Code
The client sample illustrates the seamless usage of the IScriptExecutionCon-
text class in Groovy:
scriptTask (" taskName ", DV_APPLICATION ){
code {
// The IScriptExecutionContext is automatically active here
// Call methods of the IScriptExecutionContext
def logger = s c r i p t L o g g e r
def temp = paths . t e m p F o l d e r
// Use an automation API
workflow {
// Now the Workflow API is active
}
}
}
Listing 4.10: Access automation API in Groovy clients by the IScriptExecutionContext
© 2017, Vector Informatik GmbH
33 of 250

---

Chapter 4.
AutomationInterface API Reference
In Groovy the IScriptExecutionContext is automatically activated inside of the code{}
block.
Java Code
For java clients the method IScriptExecutionContext.getInstance(Class)
provides access to the API classes, which are seamlessly available for the groovy clients:
// Java code
// Passed from the script task :
IScriptExecutionContext scriptContext = ...;
// Retrieve automation API in Java
IWorkflowApi workflow = scriptContext . getInstance ( IWorkflowApiEntryPoint . class )
. getWorkflow ();
IWorkflowContext workflowCtx = workflow . getWorkflow ();
// In groovy code it would be:
workflow {
}
Listing 4.11: Access to automation API in Java clients by the IScriptExecutionContext
In Java code the context is always the first parameter passed to every task code (see IScript-
TaskCode).
4.4.1.1 Code Block Arguments
The code block can have arguments passed into the script task execution. The arguments passed
into the code{ } block are defined by the IScriptTaskType of the script task. See chapter 4.3
on page 29 for the list of arguments (including types) passed by each individual task type.
scriptTask (" Task "){
code { arg1 , arg2 , ... -> // arguments here defined by the IScriptTaskType
}
}
scriptTask (" Task2 "){
// Or you could specify the type of the arguments for code completion
code { String arg1 , List < Double > arg2 ->
}
}
Listing 4.12: Script task code block arguments
The arguments can also retrieved with IScriptExecutionContext.getScriptTaskArguments().
4.4.2 Task Execution Sequence
The figure 4.3 on the next page shows the overview sequence when a script task gets executed
by the user and the interaction with the IScriptExecutionContext. Note that the context
gets created each time the task is executed.
© 2017, Vector Informatik GmbH
34 of 250

---

Chapter 4.
AutomationInterface API Reference
Figure 4.3: Script Task Execution Sequence
4.4.3 Script Path API during Execution
Script tasks could resolve relative and absolute file system paths with the IAutomationPat-
hsApi.
As entry point call paths in a code{ } block (see IScriptExecutionContext.getPaths()).
There are multiple ways to resolve relative paths:
• by Script folder
• by Temp folder
• by SIP folder
• by Project folder
• by any parent folder
© 2017, Vector Informatik GmbH
35 of 250

---

Chapter 4.
AutomationInterface API Reference
4.4.3.1 Path Resolution by Parent Folder
The resolvePath(Path parent, Object path) method resolves a file path relative to supplied
parent folder.
This method converts the supplied path based on its type:
• A CharSequence, including String or GString. Interpreted relative to the parent direc-
tory. A string that starts with file: is treated as a file URL.
• A File: If the file is an absolute file, it is returned as is. Otherwise, the file’s path is
interpreted relative to the parent directory.
• A Path: If the path is an absolute path, it is returned as is. Otherwise, the path is
interpreted relative to the parent directory.
• A URI or URL: The URL’s path is interpreted as the file path. Currently, only file: URLs
are supported.
• A IHasURI: The returned URI is interpreted as defined above.
• A Closure: The closure’s return value is resolved recursively.
• A Callable: The callable’s return value is resolved recursively.
• A Supplier: The supplier’s return value is resolved recursively.
• A Provider: The provider’s return value is resolved recursively.
The return type is java.nio.file.Path.
scriptTask (" TaskName "){
code {
// Method resolvePath (Path , Object ) resolves a path relative to the
supplied folder
Path parentFolder = Paths . get ('.')
Path p = paths . resolvePath ( parentFolder , " MyFile . txt ")
/* The resolvePath (Path , Object ) method will resolve
* relative and absolute paths to a java . nio . file . Path object .
*/
}
}
Listing 4.13: Resolves a path with the resolvePath() method
4.4.3.2 Path Resolution
The resolvePath(Object) method resolves the Object to a file path. Relative paths are
preserved, so relative paths are not converted into absolute paths.
This method converts the supplied path same as the resolvePath(Path, Object) method.
The return type is java.nio.file.Path. See 4.4.3.1. But it does NOT convert relative paths
into absolute.
© 2017, Vector Informatik GmbH
36 of 250

---

Chapter 4.
AutomationInterface API Reference
scriptTask (" TaskName "){
code {
// Method resolvePath () resolves a path and preserve relative paths
Path p = paths . resolvePath (" MyFile . txt ")
/* The resolvePath () method will resolve
* relative and absolute paths to a java . nio . file . Path object .
* Is also preserves relative paths .
*/
}
}
Listing 4.14: Resolves a path with the resolvePath() method
4.4.3.3 Script Folder Path Resolution
The resolveScriptPath(Object) method resolves a file path relative to the script directory
of the executed IScript.
This method converts the supplied path same as the resolvePath(Path, Object) method.
The return type is java.nio.file.Path. See 4.4.3.1 on the previous page.
scriptTask (" TaskName "){
code {
// Method resolveScriptPath () resolves a path relative to the script
folder
Path p = paths . resolveScriptPath (" MyFile . txt ")
/* The resolveScriptPath () method will resolve
* relative and absolute paths to a java . nio . file . Path object .
*/
}
}
Listing 4.15: Resolves a path with the resolveScriptPath() method
4.4.3.4 Project Folder Path Resolution
The resolveProjectPath(Object) method resolves a file path relative to the project directory
(see getDpaProjectFolder()) of the current active project.
This method converts the supplied path same as the resolvePath(Path, Object) method.
The return type is java.nio.file.Path. See 4.4.3.1 on the preceding page.
There must be an active project to use this method. See chapter 4.5.2 on page 52 for details
about active projects.
© 2017, Vector Informatik GmbH
37 of 250

---

Chapter 4.
AutomationInterface API Reference
scriptTask (" TaskName "){
code {
// Method resolveProjectPath () resolves a path relative active project
folder
Path p = paths . resolveProjectPath (" MyFile . txt ")
/* The resolveProjectPath () method will resolve
* relative and absolute paths to a java . nio . file . Path object .
*/
}
}
Listing 4.16: Resolves a path with the resolveProjectPath() method
4.4.3.5 SIP Folder Path Resolution
The resolveSipPath(Object) method resolves a file path relative to the SIP directory (see
getSipRootFolder()).
This method converts the supplied path same as the resolvePath(Path, Object) method.
The return type is java.nio.file.Path. See 4.4.3.1 on page 36.
scriptTask (" TaskName "){
code {
// Method resolveSipPath () resolves a path relative SIP folder
Path p = paths . resolveSipPath (" MyFile . txt ")
/* The resolveSipPath () method will resolve
* relative and absolute paths to a java . nio . file . Path object .
*/
}
}
Listing 4.17: Resolves a path with the resolveSipPath() method
4.4.3.6 Temp Folder Path Resolution
The resolveTempPath(Object) method resolves a file path relative to the script temp di-
rectory of the executed IScript. A new temporary folder is created for each IScriptTask
execution.
This method converts the supplied path same as the resolvePath(Path, Object) method.
The return type is java.nio.file.Path. See 4.4.3.1 on page 36.
scriptTask (" TaskName "){
code {
// Method resolveTempPath () resolves a path relative to the temp folder
Path p = paths . resolveTempPath (" MyFile . txt ")
/* The resolveTempPath () method will resolve
* relative and absolute paths to a java . nio . file . Path object .
*/
}
}
Listing 4.18: Resolves a path with the resolveTempPath() method
© 2017, Vector Informatik GmbH
38 of 250

---

Chapter 4.
AutomationInterface API Reference
4.4.3.7 Other Project and Application Paths
The IAutomationPathsApi will also resolve any other Vector provided path variable like $(Ecu-
cFile). The call would be paths.ecucFile, add the variable to resolve as a Groovy pro-
perty.
Short list of available variables (not complete, please see DaVinci Configurator help for more
details):
• EcucFile
• OutputFolder
• SystemFolder
• AutosarFolder
• more ...
scriptTask (" TaskName ", DV_PROJECT ){
code {
// The property OutputFolder is the folder of the generated artifacts
Path folder = paths . outputFolder
}
}
Listing 4.19: Get the project output folder path
scriptTask (" TaskName "){
code {
// The property sipRootFolder is the folder of the used SIP
Path folder = paths . sipRootFolder
}
}
Listing 4.20: Get the SIP folder path
4.4.4 Script logging API
The script task execution (IScriptExecutionContext) provides a script logger to log events
during an execution. The method getScriptLogger() returns the logger. The logger can be
used to log:
• Errors
• Warnings
• Debug messages
• More...
You shall always prefer the usage of the logger before using the println() of stdout or
stderr.
In any code block without direct access to the script API, you can write the following code to
access the logger: ScriptApi.scriptLogger
© 2017, Vector Informatik GmbH
39 of 250

---

Chapter 4.
AutomationInterface API Reference
scriptTask (" TaskName "){
code {// Use the scriptLogger to log messages
scriptLogger . info
"My script is running "
scriptLogger . warn
"My Warning "
scriptLogger . error "My Error "
scriptLogger . debug "My debug message "
scriptLogger . trace "My trace message "
// Also log an Exception as second argument
scriptLogger . error ("My Error ", new RuntimeException (" MyException "))
}
}
Listing 4.21: Usage of the script logger
The ILogger also provides a formatting syntax for the format String. The syntax is {Index-
Number} and the index of arguments after the format String.
It is also possible to use the Groovy GString syntax for formatting.
scriptTask (" TaskName "){
code { argument ->
// Use the format methods to insert data
scriptLogger . infoFormat ("My script {0} with :{1} ", scriptTask , argument )
}
}
Listing 4.22: Usage of the script logger with message formatting
scriptTask (" TaskName "){
code { argument ->
// Use the Groovy GString syntax to insert data
scriptLogger . info "My script $scriptTask with : $argument "
}
}
Listing 4.23: Usage of the script logger with Groovy GString message formatting
4.4.5 User Interactions and Inputs
The UserInteraction and UserInput API provides methods to directly communicate with the
user, via MessageBoxes or Input dialogs.
You should use the API only if you want do communicate directly with the user, because some
API calls may block and wait for user interaction. So you should not use the API for batch
jobs.
4.4.5.1 UserInteraction
The UserInteraction API provides methods to display messages to the user directly. In UI
mode the DaVinci Configurator will prompt a message box an will block until the user has
acknowledged the message. In console (non UI) mode, the message is logged to the console in
a user logger.
© 2017, Vector Informatik GmbH
40 of 250

---

Chapter 4.
AutomationInterface API Reference
The user logger will display error, warnings and infos by default. The logger name will not be
displayed.
The user interaction is good to display information where the user has to respond to immediately.
Please use the feature sparingly, because users do not like to acknowledge multiple messages for
a single script task execution.
The code block userInteractions{} provides the API inside of the block. The following
methods can be used:
• errorToUser()
• warnToUser()
• infoToUser()
• messageToUser(ELogLevel, Object)
The severity (error, warning, info) will change the display (icons, text) of the message box. No
other semantic is applied by the severity.
scriptTask (" TaskName ", DV_APPLICATION ){
code {
userInteractions {
warnToUser (" Warning displayed to the user as message box ")
}
// You could also write
userInteractions . errorToUser (" Error message for the user ")
}
}
Listing 4.24: UserInteraction from a script
© 2017, Vector Informatik GmbH
41 of 250

---

Chapter 4.
AutomationInterface API Reference
4.4.6 Script Error Handling
4.4.6.1 Script Exceptions
All exceptions thrown by any script task execution are sub types of ScriptingException.
Figure 4.4: ScriptingException and sub types
4.4.6.2 Script Task Abortion by Exception
The script task can throw an ScriptClientExecutionException to abort the execution of an
IScriptTask, and display a meaningful message to the user.
scriptTask (" TaskName "){
code {// Stop the execution and display a message to the user
t h r o w new S c r i p t C l i e n t E x e c u t i o n E x c e p t i o n ( " Message to the User " )
}
}
Listing 4.25: Stop script task execution by throwing an ScriptClientExecutionException
Exception with Console Return Code
An ScriptClientExecutionException with an return
code of type Integer will also abort the execution of the IScriptTask.
© 2017, Vector Informatik GmbH
42 of 250

---

Chapter 4.
AutomationInterface API Reference
But it also changes the return code of the console application, if the IScriptTask was executed
in the console application. This could be used when the console application of the DaVinci
Configurator is called for other scripts or batch files.
scriptTask (" TaskName "){
code {// The return code will be returned by the DvCmd.exe process
def r e t u r n C o d e = 50
t h r o w new S c r i p t C l i e n t E x e c u t i o n E x c e p t i o n ( returnCode , " Message to the
User ")
}
}
Listing 4.26: Changing
the
return
code
of
the
console
application
by
throwing
an
ScriptClientExecutionException
Reserved Return Codes
The returns codes 0-20 are reversed for internal use of the DaVinci
Configurator, and are not allowed to be used by a client script. Also negative returns codes are
not permitted.
4.4.6.3 Unhandled Exceptions from Tasks
When a script task execution throws any type of Exception (more precise Throwable) the
script task is marked as failed and the Exception is reported to the user.
© 2017, Vector Informatik GmbH
43 of 250

---

Chapter 4.
AutomationInterface API Reference
4.4.7 User defined Classes and Methods
You can define your own methods and classes in a script file. The methods a called like any
other method.
scriptTask (" Task "){
code {userMethod()
}
}
def u s e r M e t h o d () {
r e t u r n " U s e r S t ri n g "
}
Listing 4.27: Using your own defined method
Classes can be used like any other class. It is also possible to define multiple classes in the
script file.
scriptTask (" Task "){
code {
new Us er Cl as s () . u s e r M e t h o d ()
}
}
c l a s s U se rC la ss {
def u s e r M e t h o d () {
r e t u r n " R e t u r n V a l u e "
}
}
Listing 4.28: Using your own defined class
You can also create classes in different files, but then you have to write imports in your script
like in normal Groovy or Java code.
The script should be structured as any other development project, so if the script file gets too
big, please refactor the parts into multiple classes and so on.
daVinci Block
The classes and methods must be outside of the daVinci{ } block.
i m p o r t s t a t i c com . vector . cfg . a u t o m a t i o n . api . Sc ri pt Api .*
daVinci {
scriptTask (" Task "){
code {}
}
}
def u s e r M e t h o d () {}
c l a s s U serC lass {}
Listing 4.29: Using your own defined method with a daVinci block
Code Completion
Note that the code completion for the Automation API will not work auto-
matically in own defined classes and methods. You have to open for example a scriptCode{}
© 2017, Vector Informatik GmbH
44 of 250

---

Chapter 4.
AutomationInterface API Reference
block. The chapter 4.4.8 describes how to use the Automation API for your own defined classes
and methods.
4.4.8 Usage of Automation API in own defined Classes and Methods
In your own methods and classes the automation API is not automatically available differently
as inside of the script task code{} block. But it is often the case, that methods need access to
the automation API.
The class ScriptApi provides static methods as entry points into the automation API.
The static methods either return the API objects, or you could pass a Closure, which will
activate the API inside of the Closure.
4.4.8.1 Access the Automation API like the Script code{} Block
The ScriptApi.scriptCode(Closure) method provides access to all automation APIs the
same way as inside of the normal script code{} block.
This is useful, when you want to call script code API inside of your own methods and clas-
ses.
def yourMethod (){
// Needs access to an automation API
ScriptApi . scriptCode {
// API is now available
workflow . update ()
}
}
Listing 4.30: ScriptApi.scriptCode{} usage in own method
The ScriptApi.scriptCode() method can be used to call API in Java style.
def yourMethod (){
// Needs access to an automation API
ScriptApi . scriptCode (). workflow . update ()
}
Listing 4.31: ScriptApi.scriptCode() usage in own method
Java note: The ScriptApi.scriptCode() returns the IScriptExecutionContext.
4.4.8.2 Access the Project API of the current active Project
The ScriptApi.activeProject() method provides access to the project automation API of
the currently active project. This is useful, when you want to call project API inside of your
own methods and classes.
© 2017, Vector Informatik GmbH
45 of 250

---

Chapter 4.
AutomationInterface API Reference
def yourMethod (){
// Needs access to an automation API
ScriptApi . activeProject {
// Project API is now available
transaction {
// Now model modifications are allowed
}
}
}
Listing 4.32: ScriptApi.activeProject{} usage in own method
The ScriptApi.activeProject() method returns the current active IProject.
def yourMethod (){
// Needs access to an automation API
IProject theActiveProject = ScriptApi . activeProject ()
}
Listing 4.33: ScriptApi.activeProject() usage in own method
4.4.9 User defined Script Task Arguments in Commandline
A script task can create IScriptTaskUserDefinedArgument, which can be set by the user
(e.g. from the commandline) to pass user defined arguments to the script task execution. An
argument can be optional or required. The arguments are type safe and checked before the task
is executed.
Possible valueTypes are:
• String
• Boolean
• Void: For parameter where only the existence is relevant.
• File: The existence of the file is not checked by default. See argument validators.
• Path: Same as File
• Integer
• Long
• Double
The help text is automatically expanded with the help for user defined script task argu-
ments.
scriptTask (" TaskName "){
//
newUserDefinedArgument ( String argName , Class <T> valueType , String help )
def procArg = n e w U s e r D e f i n e d A r g u m e n t ( " p " , Void , " Enables the pr o c es sin g of
... ")
code {
if ( procArg . hasValue ) {
scriptLogger . info
" The argument -p was defined "
}
}
}
Listing 4.34: Script task UserDefined argument with no value
© 2017, Vector Informatik GmbH
46 of 250

---

Chapter 4.
AutomationInterface API Reference
scriptTask (" TaskName "){
/** newUserDefinedArgument(String argName, Class<T> valueType, String help)
*/
def countArg = n e w U s e r D e f i n e d A r g u m e n t ( " count " , Integer ,
" The amount of elements to create ")
def nameArg = n e w U s e r D e f i n e d A r g u m e n t ( " name " , String ,
" The element name to create ")
code {
int count = countArg . value
String name = nameArg . value
scriptLogger . info
" The arguments --name and -- count were $name , $count "
}
}
Listing 4.35: Define and use script task user defined arguments from commandline
scriptTask (" TaskName "){
/** newUserDefinedArgument(String argName, Class<T> valueType,
*
T defaultValue , String help )
*/
def procArg = n e w U s e r D e f i n e d A r g u m e n t ( " p " , Double , 25.0 , // The Default value
" Help text ... ")
code {
d o u b l e value = procArg . value
scriptLogger . info
" The argument -p was $value "
}
}
Listing 4.36: Script task UserDefined argument with default value
scriptTask (" TaskName "){
/** newUserDefinedArgument(String argName, Class<T> valueType, String help)
*/
def multiArg = n e w U s e r D e f i n e d A r g u m e n t ( " multiArg " , String , " Help text ... " )
/** The client calls the task with arguments:
*
-- multiArg " ArgOne " -- multiArg " ArgTwo "
*/
code {
List < String > values = multiArg . values
// Call values instead of value
scriptLogger . info
" The argument -- multiArg
had values : $values "
}
}
Listing 4.37: Script task UserDefined argument with multiple values
4.4.9.1 User defined Argument Validators
You could also specify a validator for the argument to check for special conditions, like the
file must exist. This is helpful to provide a quick feedback to the user, if the task would be
executable. Simply add the validator at the end of the newUserDefinedArgument() call. The
validator code is called when the input is checked.
© 2017, Vector Informatik GmbH
47 of 250

---

Chapter 4.
AutomationInterface API Reference
There are also default validators available, like:
• Constraints.IS_EXISTING_FOLDER
• Constraints.IS_EXISTING_FILE
• Constraints.IS_VALID_AUTOSAR_SHORT_NAME
Please see chapter 4.12.1 on page 165 for more available validators.
i m p o r t com . vector . cfg . business . C o n s t r a i n t s
scriptTask (" TaskName "){
/** newUserDefinedArgument(String argName, Class<T> valueType,
*
T defaultValue , String help , Consumer <T> validator )
*/
def contArg = n e w U s e r D e f i n e d A r g u m e n t ( " p " , String ,
" Help text ... ",
Constraints .
IS_VALID_AUTOSAR_SHORT_NAME_PATH )
code {
String value = contArg . value
scriptLogger . info
" The argument -p was $value "
}
}
Listing 4.38: Script task UserDefined argument with predefined validator
Or you implement your own validation logic, by passing a Closure, which throws an exception,
if the value is invalid.
scriptTask (" TaskName "){
/** newUserDefinedArgument(String argName, Class<T> valueType,
*
T defaultValue , String help , Consumer <T> validator )
*/
def procArg = n e w U s e r D e f i n e d A r g u m e n t ( " p " , Integer , 20 ,
" Help text ... ",
// The validator code
{ value ->
if ( value % 2) {
t h r o w new I l l e g a l A r g u m e n t E x c e p t i o n ( " The value has to be
even .")
}
})
code {
}
}
Listing 4.39: Script task UserDefined argument with own validator
© 2017, Vector Informatik GmbH
48 of 250

---

Chapter 4.
AutomationInterface API Reference
4.4.9.2 Call Script Task with Task Arguments
The commandline option taskArgs is used to specify the arguments passed to a script task to
execute:
--taskArgs <TASK_ARGS>
Passes arguments to the specified script tasks.
The arguments have the following syntax:
Syntax: --taskArgs "<TaskName>" "<Arguments to Task>"
E.g. --taskArgs "MyTask" "-s --projectCfg MyFile.cfg"
If only one task is executed, the "<TaskName>" can be omitted.
For multiple task arguments the following syntax apply:
Syntax: --taskArgs "<TaskName>" "<Arguments to Task>"
"<TaskName2>" "<Arguments to Task2>"
E.g. --taskArgs "MyTask" "-s --projectCfg MyFile.cfg"
"Task2" "-d --saveTo saveFile.txt"
Note: The newlines in the listing are only for visualization.
If the task name is not unique, your can specify the full qualified name with script name
--taskArgs "MyScript:MyTask" "-s --projectCfg MyFile.cfg"
Arguments with spaces inside the script task argument could be quoted with ""
--taskArgs "MyScript:MyTask" "-s --projectCfg \"Path to File\MyFile.cfg\" -d"
The task help of a task will print the possible arguments of a script task.
--scriptTaskHelp taskName
© 2017, Vector Informatik GmbH
49 of 250

---

Chapter 4.
AutomationInterface API Reference
4.4.10 Stateful Script Tasks
Script tasks normally have no state or cached data, but it can be useful to cache data during
an execution, or over multiple task executions. The IScriptExecutionContext provides two
methods to save and restore data for that purpose:
• getExecutionData() - caches data during one task execution
• getSessionData() - caches data over multiple task executions
Execution Data
Caches data during a single script task execution, which allows to save cal-
culated values or services needed in multiple parts of the task, without recalculating or creating
it. Note: When the task is executed again the executionData will be empty.
scriptTask (" TaskName "){
code {// Cache a value for the execution
executionData . myCacheValue = 500
def val = e x e c u t i o n D a t a . m y C a c h e V a l u e // Retrieve the value anywhere
scriptLogger . info
" The cached value is $val "
// Or access it from any place with ScriptApi . scriptCode like :
def sa m eV al ue = S cr ip tA pi . s c r i p t C o d e . e x e c u t i o n D a t a . m y C a c h e V a l u e
}
}
Listing 4.40: executionData - Cache and retrieve data during one script task execution
Session Data
Caches data over multiple task executions, which allows to implement a stateful
task, by saving and retrieving any data calculated by the task itself.
Caution: The data is saved globally so the usage of the sessionData can lead to memory
leaks or OutOfMemoryErrors. You have to take care not to store too much memory in the
sessionData.
The DaVinci Configurator will also free the sessionData, when the system run low on free
memory. So you have to deal with the fact, that the sessionData was freed, when the script
task getting executed again. But the data is not deallocated during a running execution.
scriptTask (" TaskName "){
// Setup - set the value the first time , this is only executed once ( during
initialization )
sessionData . myExecutionCount = 1
code {// Retrieve the value
def e x e c u t i o n C o u n t = s e s s i o n D a t a . m y E x e c u t i o n C o u n t
scriptLogger . info
" The task was executed $executionCount times "
// Update the value
sessionData . myExecutionCount = executionCount + 1
}
}
Listing 4.41: sessionData - Cache and retrieve data over multiple script task executions
© 2017, Vector Informatik GmbH
50 of 250

---

Chapter 4.
AutomationInterface API Reference
API usage
Both methods executionData and sessionData return the same API of type
IScriptTaskUserData.
The IScriptTaskUserData provides methods to retrieve and store properties by a key (like a
Map). The retrieval and store methods are Object based, so any Object can be a key. The
exception are Class instances (like String.class, which required that the value is an instance
of the Class).
On retrieval if a property does not exist an UnknownPropertyException is thrown. Properties
can be set multiple times and will override the old value. The keys of the properties used to
retrieve and store data are compared with Object.equals(Object) for equality.
The listing below describes the usage of the API:
scriptTask (" TaskName "){
code {
def val
// The sessionData and executionData have the same API
// You have multiple ways to set a value
executionData . myCacheId = " VALUE "
executionData . set (" myCacheId ", " VALUE ")
executionData [" myCacheId "] =
" VALUE "
// Or with classes for a service locator pattern
executionData . set ( Integer .class , 50)
// Possible for any Class
executionData [ Integer ] = 50
// There are the same ways to retrieve the values
val = executionData . myCacheId
val = executionData . get (" myCacheId ")
val = executionData [" myCacheId "]
// Or with classes for a service locator pattern
val
= executionData . get ( Integer . class )
val
= executionData [ Integer ]
// You can also ask if the property exists
b o o l e a n exists = e x e c u t i o n D a t a . has ( " my Ca ch eId " )
}
}
Listing 4.42: sessionData and executionData syntax samples
© 2017, Vector Informatik GmbH
51 of 250

---

Chapter 4.
AutomationInterface API Reference
4.5 Project Handling
Project handling comprises creating new projects, opening existing projects or accessing the
currently active project.
IProjectHandlingApi provides methods to access to the active project, for creating new pro-
jects and for opening existing projects.
getProjects() allows accessing the IProjectHandlingApi like a property.
scriptTask ('taskName ') {
code {
// IProjectHandlingApi is available as " projects " property
def p r o j e c t H a n d l i n g A p i = projects
}
}
Listing 4.43: Accessing IProjectHandlingApi as a property
projects(Closure) allows accessing the IProjectHandlingApi in a scope-like way.
scriptTask ('taskName ') {
code {
projects {
// IProjectHandlingApi is available inside this Closure
}
}
}
Listing 4.44: Accessing IProjectHandlingApi in a scope-like way
4.5.1 Projects
Projects in the AutomationInterface are represented by IProject instances. These instances
can be created by:
• Creating a new project
• Loading an existing project
You can only access IProject instances by using a Closure block at IProjectHandlingApi or
IProjectRef class. This shall prevent memory leaks, by not closing open projects.
4.5.2 Accessing the active Project
The IProjectHandlingApi provides access to the active project. The active project is either
(in descending order):
• The last IProject instance activated with a Closure block
– Stack-based - so multiple opened projects are possible and the last (inner) Closure
block is used.
• The passed project to a project task
• Or the loaded project in the current DaVinci Configurator in an application task
© 2017, Vector Informatik GmbH
52 of 250

---

Chapter 4.
AutomationInterface API Reference
The figure 4.5 describes the behavior to search for the active project of a script task.
Figure 4.5: Search for active project in getActiveProject()
It is possible that there is no active project, e.g. no project was loaded.
You can switch the active project, by calling the with(Closure) method on an IProject
instance.
// Retrieve theProject from other API like load a project
IProject theProject = ...;
theProject . with {
// Now theProject is the new active project inside of this closure
}
Listing 4.45: Switch the active project
To access the active project you can use the activeProject(Closure) and getActivePro-
ject() methods.
© 2017, Vector Informatik GmbH
53 of 250

---

Chapter 4.
AutomationInterface API Reference
scriptTask ('taskName ') {
code {
if ( projects . p r o j e c t A c t i v e ) {
// active IProject is available as " activeProject " property
scriptLogger . info " Active project : ${ projects . activeProject . projectName }"
projects . activeProject {
// active IProject is available inside this Closure
scriptLogger . info " Active project : ${ projectName }"
}
} else {
scriptLogger . info 'No project active '
}
}
}
Listing 4.46: Accessing the active IProject
isProjectActive() returns true if and only if there is an active IProject. If isProjec-
tActive() returns true it is safe to call getActiveProject().
getActiveProject() allows accessing the active IProject like a property.
activeProject(Closure) allows accessing the active IProject in a scope-like way. This will
enable the project specific API inside of the Closure.
4.5.3 Creating a new Project
The method createProject(Closure) creates a new project as specified by the given Closure.
Inside the closure the ICreateProjectApi is available.
The new project is not opened and usable until IProjectRef.openProject(Closure) is called
on the returned IProjectRef.
scriptTask ('taskName ', DV_APPLICATION ) {
code {
def n e w P r o j e c t = projects . c r e a t e P r o j e c t {
projectName ' NewProject '
projectFolder paths . resolveTempPath (' projectFolder ')
}
scriptLogger . info (" Project created and saved to: $newProject ")
// Now open the project
newProject . openProject {
// Inside here the project can be used
}
}
}
Listing 4.47: Creating a new project (mandatory parameters only)
The next is a more sophisticated example of creating a project with multiple settings:
© 2017, Vector Informatik GmbH
54 of 250

---

Chapter 4.
AutomationInterface API Reference
scriptTask ('taskName ', DV_APPLICATION ) {
code {
def n e w P r o j e c t = projects . c r e a t e P r o j e c t {
projectName ' NewProject '
projectFolder paths . resolveTempPath (' projectFolder ')
general {
author ' projectAuthor '
version '0.9 '
}
postBuild {
loadable true
selectable true
}
folders . ecucFileStructure = ONE_FILE_PER_MODULE
folders . moduleFilesFolder = 'Appl / GenData '
folders . templatesFolder = 'Appl / Source '
target . vVIRTUALtargetSupport = false
daVinciDeveloper . createDaVinciDeveloperWorkspace = false
}
}
}
Listing 4.48: Creating a new project (with some optional parameters)
The ICreateProjectApi contains the methods to parameterize the creation of a new pro-
ject.
4.5.3.1 Mandatory Settings
Project Name
Specify the name newly created project with setProjectName(String). The
name given here is postfixed with ".dpa" for the new project’s .dpa file.
The following constraints apply:
• Constraints.IS_VALID_PROJECT_NAME 4.12.1 on page 165
Project Folder
Specify the folder in which to create the new project in with setProjectFol-
der(Object). The value given here is converted to Path using the converter ScriptConver-
ters.TO_SCRIPT_PATH 4.12.2 on page 166.
The following constraints apply:
• Constraints.IS_CREATABLE_FOLDER 4.12.1 on page 165
4.5.3.2 General Settings
Use getGeneral() or general(Closure) to specify the new project’s general settings. The
provided settings are defined in ICreateProjectGeneralApi.
© 2017, Vector Informatik GmbH
55 of 250

---

Chapter 4.
AutomationInterface API Reference
Author
The author for the new project can be specified with setAuthor(String). This is an
optional parameter defaulting to the name of the currently logged in user if the parameter is
not provided explicitly.
The following constraints apply:
• Constraints.IS_NON_EMPTY_STRING 4.12.1 on page 165
Version
The version for the new project can be specified with setVersion(Object). This
is an optional parameter defaulting to "1.0" if the parameter is not provided explicitly. The
value given here is converted to IVersion using ScriptConverters.TO_VERSION 4.12.2 on
page 166.
The following constraints apply:
• Constraints.IS_NOT_NULL 4.12.1 on page 165
Description
The description for the new project can be specified with setDescription(String).
This is an optional parameter defaulting to "" if the parameter is not provided explicitly.
The following constraints apply:
• Constraints.IS_NOT_NULL 4.12.1 on page 165
Start Menu Entries
setCreateStartMenuEntries(boolean) defines whether or not to create
start menu entries for the new project. This is an optional parameter defaulting to false if the
parameter is not provided explicitly.
4.5.3.3 Target Settings
Use getTarget() or target(Closure) to specify the new project’s target settings for compiler,
derivatives and pin layouts.
ICreateProjectTargetApi contains the API to specify the new project’s target settings.
Available Derivatives
getAvailableDerivatives() returns all possible input values for set-
Derivative(DerivativeInfo).
Derivative
Set the derivative for the new project with setDerivative(DerivativeInfo).
This is an optional parameter defaulting to the first element in the collection returned by
getAvailableDerivatives() (or null if the collection is empty). The value given here must
be one of the values returned by getAvailableDerivatives().
Available Compilers
getAvailableCompilers() returns all possible input values for set-
Compiler(ImplementationProperty). Note: the available compilers depend on the currently
configured derivative. This method will return the empty collection if no derivative has been
configured at the time it is called.
© 2017, Vector Informatik GmbH
56 of 250

---

Chapter 4.
AutomationInterface API Reference
Compiler
Set the compiler for the new project with setCompiler(ImplementationProperty).
This is an optional parameter defaulting to the first element in the collection returned by ge-
tAvailableCompilers() (or null if the collection is empty). The value given here must be
one of the values returned by getAvailableCompilers().
Available Pin Layouts
getAvailablePinLayouts() returns all possible input values for set-
PinLayout(ImplementationProperty). Note: the available pin layouts depend on the cur-
rently configured derivative. This method will return the empty collection if no derivative has
been configured at the time it is called.
Pin Layout
Set the pin layout of the selected derivative for the new project with setPinLa-
yout(ImplementationProperty). This is an optional parameter defaulting to the first element
in the collection returned by getAvailablePinLayouts() (or null if the collection is empty).
The value given here must be one of the values returned by getAvailablePinLayouts().
vVIRTUALtarget Support
setvVIRTUALtargetSupport(boolean) specifies whether or not
to support the vVIRTUALtarget for the new project. This is an optional parameter defaulting to
false if the parameter is not provided explicitly. See also ICreateProjectApi.getVirtualTarget()
and ICreateProjectVirtualTargetApi for specifying further details (path to vVIRTUALtar-
get project, ...).
The following constraints apply:
• vVIRTUALtarget support may not be available depending on the purchased license
4.5.3.4 Post Build Settings
Use getPostBuild() or postBuild(Closure) to specify the new project’s post build settings
for Post-build selectable and or loadable projects.
ICreateProjectPostBuildApi contains the API to specify the new project’s post build set-
tings.
Post-build Loadable Support
setLoadable(boolean) sets whether or not to support Post-
build loadable for the new project. This is an optional parameter defaulting to false if the
parameter is not provided explicitly.
Post-Build Selectable Support
setSelectable(boolean) sets whether or not to support
Post-build selectable for the new project. This is an optional parameter defaulting to false if
the parameter is not provided explicitly.
4.5.3.5 Folders Settings
Use getFolders() or folders(Closure) to specify the new project’s folders settings.
ICreateProjectFolderApi contains the methods to specify the new project’s folders set-
tings.
© 2017, Vector Informatik GmbH
57 of 250

---

Chapter 4.
AutomationInterface API Reference
Module Files Folder
Set the module files folder for the new project with setModuleFilesFol-
der(Object). This is an optional parameter defaulting to ".\Appl\GenData" if the parameter
is not provided explicitly. The value given here is converted to Path using ScriptConver-
ters.TO_PATH 4.12.2 on page 166. Normally a relative path (to be interpreted relative to the
project folder) should be given here.
The following constraints apply:
• Constraints.IS_CREATABLE_FOLDER 4.12.1 on page 165
Templates Folder
Set the templates folder for the new project with setTemplatesFolder(Object).
This is an optional parameter defaulting to ".\Appl\Source" if the parameter is not provided
explicitly.
The value given here is converted to Path using ScriptConverters.TO_PATH 4.12.2 on page 166.
Normally a relative path (to be interpreted relative to the project folder) should be given
here.
The following constraints apply:
• Constraints.IS_CREATABLE_FOLDER 4.12.1 on page 165
Service Components Folder
Set the service component files folder for the new project with
setServiceComponentFilesFolder(Object).
This is an optional parameter defaulting to
".\Config\ServiceComponents" if the parameter is not provided explicitly.
The value given here is converted to Path using ScriptConverters.TO_PATH 4.12.2 on page 166.
Normally a relative path (to be interpreted relative to the project folder) should be given
here.
The following constraints apply:
• Constraints.IS_CREATABLE_FOLDER 4.12.1 on page 165
Application Components Folder
Set the application component files folder for the new project
with setApplicationComponentFilesFolder(Object). This is an optional parameter defaul-
ting to ".\Config\ApplicationComponents" if the parameter is not provided explicitly.
The value given here is converted to Path using ScriptConverters.TO_PATH 4.12.2 on page 166.
Normally a relative path (to be interpreted relative to the project folder) should be given
here.
The following constraints apply:
• Constraints.IS_CREATABLE_FOLDER 4.12.1 on page 165
Log Files Folder
Set the log files folder for the new project with setLogFilesFolder(Object).
This is an optional parameter defaulting to ".\Config\Log" if the parameter is not provided
explicitly.
The value given here is converted to Path using ScriptConverters.TO_PATH 4.12.2 on page 166.
Normally a relative path (to be interpreted relative to the project folder) should be given
here.
The following constraints apply:
© 2017, Vector Informatik GmbH
58 of 250

---

Chapter 4.
AutomationInterface API Reference
• Constraints.IS_CREATABLE_FOLDER 4.12.1 on page 165
Measurement And Calibration Files Folder
Set the measurement and calibration files folder
for the new project with setMeasurementAndCalibrationFilesFolder(Object). This is an
optional parameter defaulting to ".\Config\McData" if the parameter is not provided expli-
citly.
The folder object passed to the method is converted to Path using ScriptConverters.TO_PATH 4.12.2
on page 166. Normally a relative path (to be interpreted relative to the project folder) should
be given here.
The following constraints apply:
• Constraints.IS_CREATABLE_FOLDER 4.12.1 on page 165
AUTOSAR Files Folder
Set the AUTOSAR files folder for the new project with setAuto-
sarFilesFolder(Object). This is an optional parameter defaulting to ".\Config\AUTOSAR"
if the parameter is not provided explicitly.
The value given here is converted to Path using ScriptConverters.TO_PATH 4.12.2 on page 166.
Normally a relative path (to be interpreted relative to the project folder) should be given
here.
The following constraints apply:
• Constraints.IS_CREATABLE_FOLDER 4.12.1 on page 165
ECUC File Structure
The literals of EEcucFileStructure define the alternative ECUC file
structures supported by the new project. The following alternatives are supported:
SINGLE_FILE results in a single ECUC file containing all module configurations.
ONE_FILE_PER_MODULE results in a separate ECUC file for each module configuration all located
in a common folder.
ONE_FILE_IN_SEPARATE_FOLDER_PER_MODULE results in a separate ECUC file for each module
configuration each located in its separate folder.
Set the ECUC file structure to use for the new project with the method setEcucFileStruc-
ture(EEcucFileStructure). This is an optional parameter defaulting to EEcucFileStruc-
ture.SINGLE_FILE if the parameter is not provided explicitly.
4.5.3.6 DaVinci Developer Settings
Use getDaVinciDeveloper() to specify the new project’s DaVinci Developer settings.
ICreateProjectDaVinciDeveloperApi contians the methods for specifying the new project’s
DaVinci Developer settings.
Create DEV Workspace
setCreateDaVinciDeveloperWorkspace(boolean) specifies whet-
her or not to create a DaVinci Developer workspace for the new project. This is an optional
parameter defaulting to true if and only if a compatible DaVinci Developer installation can be
detected and the parameter is not provided explicitly.
© 2017, Vector Informatik GmbH
59 of 250

---

Chapter 4.
AutomationInterface API Reference
DEV Executable
Set the DaVinci Developer executable for the new project with setDaVin-
ciDeveloperExecutable(Object). This is an optional parameter defaulting to the location of
a compatible DaVinci Developer installation (if there is any) if the parameter is not provided
explicitly.
The value given here is converted to Path using ScriptConverters.TO_SCRIPT_PATH 4.12.2 on
page 166.
The following constraints apply:
• Constraints.IS_COMPATIBLE_DA_VINCI_DEV_EXECUTABLE 4.12.1 on page 166
DEV Workspace
Set the DaVinci Developer workspace for the new project with setDaVin-
ciDeveloperWorkspace(Object). This is an optional parameter defaulting to
".\Config\Developer\<ProjectName>.dcf" if the parameter is not provided explicitly.
The value given here is converted to Path using ScriptConverters.TO_PATH 4.12.2 on page 166.
Normally a relative path (to be interpreted relative to the project folder) should be given
here.
The following constraints apply:
• Constraints.IS_DCF_FILE 4.12.1 on page 166
• Constraints.IS_CREATABLE_FOLDER 4.12.1 on page 165 (applies to the parent Path of
the given Path to the DaVinci Developer executable)
Import Mode Preset
setUseImportModePreset(boolean) specifies whether or not to use the
import mode preset for the new project. This is an optional parameter defaulting to true if
the parameter is not provided explicitly.
Object Locking
setLockCreatedObjects(boolean) specifies whether or not to lock created
objects for the new project. This is an optional parameter defaulting to true if the parameter
is not provided explicitly.
Selective Import
The literals of ESelectiveImport define the alternative modes for the se-
lective import into the DaVinci Developer workspace during project updates. The following
alternatives are supported:
ALL results in selective import for all elements.
COMMUNICATION_ONLY results in selective import for communication elements only.
Set the selective import mode for the new project with setSelectiveImport(ESelectiveImport).
This is an optional parameter defaulting to ESelectiveImport.ALL if the parameter is not pro-
vided explicitly.
4.5.3.7 vVIRTUALtarget Settings
Use getVirtualTarget() to specify the new project’s vVIRTUALtarget settings. The vVIR-
TUALtarget support may not be available depending on the purchased license.
© 2017, Vector Informatik GmbH
60 of 250

---

Chapter 4.
AutomationInterface API Reference
scriptTask (' ProjectCreation ', DV_APPLICATION ) {
code {
def p rj Fo ld er = paths . r e s o l v e T e m p P a t h ( ' p r o j e c t F o l d e r ')
def n e w P r o j e c t = projects . c r e a t e P r o j e c t {
projectName ' tpVttFullyCustom '
projectFolder prjFolder
target {
vVIRTUALtargetSupport = true
}
virtualTarget {
createVirtualTargetProjectFile = true
virtualTargetExecutable = getCustomVttExe ()
virtualTargetProject = new File ( prjFolder . toFile () , "/ MyVtt / custom .
vttproj ")
}
}
scriptLogger . info (" Project created and saved ")
}
}
Listing 4.49: Creating a new project with custom VTT settings
Create vVIRTUALtarget project file
setCreateVirtualTargetProjectFile(boolean) spe-
cifies whether or not to create a vVIRTUALtarget project file for the new project.
This
is an optional parameter defaulting to true. However the vVIRTUALtarget project file is
only created when ICreateProjectTargetApi.vVIRTUALtargetSupport(boolean) evaluates
to true.
vVIRTUALtarget Project
Set the path to the vVIRTUALtarget project (*.vttproj) for the
new project with setVirtualTargetProject(Object). This is an optional parameter defaul-
ting to ’.\Config\VTT\ProjectName.vttproj’ if the parameter is not provided explicitly. See also
ICreateProjectTargetApi.setvVIRTUALtargetSupport(boolean) and ICreateProjectVir-
tualTargetApi.setCreateVirtualTargetProjectFile(boolean) at which both have to be
true to force the creation of the vVIRTUALtarget project.
The value given here is converted to Path using ScriptConverters.TO_SCRIPT_PATH 4.12.2 on
page 166.
vVIRTUALtarget Executable
Set the vVIRTUALtarget executable (VttCmd.exe) for the new
project with setVirtualTargetExecutable(Object). This is an optional parameter defaulting
to the location of the currently registered installation (if there is any) if the parameter is not
provided explicitly.
The value given here is converted to Path using ScriptConverters.TO_SCRIPT_PATH 4.12.2 on
page 166.
© 2017, Vector Informatik GmbH
61 of 250

---

Chapter 4.
AutomationInterface API Reference
4.5.4 Opening an existing Project
You can open an existing DaVinci Configurator Dpa project with the automation interface.
The method openProject(Object, Closure) opens the project at the given .dpa file location,
delegates the given code to the opened IProject.
The project is automatically closed after leaving the Closure code of the openProject(Object,
Closure) method.
The Object given as .dpa file is converted to Path using ScriptConverters.TO_SCRIPT_PATH 4.12.2
on page 166
scriptTask ('taskName ', DV_APPLICATION ) {
code {
// replace getDpaFileToLoad () with the path to the . dpa file to be loaded
projects . openProject ( getDpaFileToLoad ()) {
// the opened IProject is available inside this Closure
scriptLogger . info 'Project loaded and ready '
}
}
}
Listing 4.50: Opening a project from .dpa file
4.5.4.1 Parameterized Project Load
You can also configure how a Dpa project is loaded, e.g. by disabling the generators.
The method parameterizeProjectLoad(Closure) returns a handle on the project specified by
the given Closure. Using the IOpenDpaProjectApi, the Closure may further customize the
project’s opening procedure.
The project is not opened until openProject() is called on the returned IProjectRef.
scriptTask ('taskName ', DV_APPLICATION ) {
code {
def project = projects . p a r a m e t e r i z e P r o j e c t L o a d {
// replace getDpaFileToLoad () with the path to the . dpa file to be loaded
dpaFile getDpaFileToLoad ()
// prevent activation of generators and validation
loadGenerators false
enableValidation false
}
project . openProject {
// the opened IProject is available inside this Closure
scriptLogger . info 'Project loaded and ready '
}
}
}
Listing 4.51: Parameterizing the project open procedure
IOpenProjectApi contains the methods for parameterizing the process of opening a project.
© 2017, Vector Informatik GmbH
62 of 250

---

Chapter 4.
AutomationInterface API Reference
DPA File
The method setDpaFile(Object) sets the .dpa file of the project to be opened.
The value given here is converted to Path using ScriptConverters.TO_SCRIPT_PATH 4.12.2 on
page 166.
Generators
Using setLoadGenerators(boolean) specifies whether or not to activate genera-
tors (including their validations) for the opened project.
Validation
setEnableValidation(boolean) specifies whether or not to activate validation
for the opened project.
4.5.4.2 Open Project Details
IProjectRef is a handle on a project not yet loaded but ready to be opened. This could be
used to open the project.
IProjectRef instances can be obtained from form the following methods:
• IProjectHandlingApi.createProject(Closure) 4.5.3 on page 54
• IProjectHandlingApi.parameterizeProjectLoad(Closure) 4.5.4 on the preceding page
The IProject is not really opened until IProjectRef.openProject(Closure) is called. Here,
the project is opened and the given Closure is executed on the opened project. When IPro-
jectRef.openProject(Closure) returns the project has already been closed.
4.5.5 Saving a Project
IProject.saveProject() saves the current state including all model changes of the project to
disc.
scriptTask ('taskName ', DV_APPLICATION ) {
code {
// replace getDpaFileToLoad () with the path to the . dpa file to be loaded
def project = projects . o p e n P r o j e c t ( g e t D p a F i l e T o L o a d () ) {
// modify the opened project
transaction {
operations . activateModuleConfiguration ( sipDefRef . EcuC )
}
// save the modified project
saveProject ()
}
}
}
Listing 4.52: Opening, modifying and saving a project
© 2017, Vector Informatik GmbH
63 of 250

---

Chapter 4.
AutomationInterface API Reference
4.5.6 Opening AUTOSAR Files as Project
Sometimes it could be helpful to load AUTOSAR arxml files instead of a full-fledged DaVinci
Configurator project.
For example to modify the content of a file for test cases with the
AutomationInterface, instead of using an XML editor.
You could load multiple arxml files into a temporary project, which allowed to read and write
the loaded file content with the normal model APIs.
The following elements are loaded by default, without specifying the AUTOSAR files:
• ModuleDefinitions from the SIP: To allow the usage of the BswmdModel
• AUTOSAR standard definition: Refinement resolution of definitions
Caution: Some APIs and services may not be available for this type of project, like:
• Update workflow: You can’t update a non existing project
• Validation: The validation is disabled by default
• Generation: The generators are not loaded by default
The method parameterizeArxmlFileLoad(Closure) allows to load multiple arxml files into a
temporary project. The given Closure is used to customize the project’s opening procedure by
the IOpenArxmlFilesProjectApi.
The arxml file project is not opened until openProject() is called on the returned IPro-
jectRef.
scriptTask ('taskName ', DV_APPLICATION ) {
code {
def project = projects . p a r a m e t e r i z e A r x m l F i l e L o a d {
// Add here your arxml files to load
arxmlFiles ( arxmlFilesToLoad )
rawAutosarDataMode = true
}project.openProject {
scriptLogger . info 'Project loaded and ready '
}
}
}
Listing 4.53: Opening Arxml files as project
Arxml Files
Add arxml files to load with the method arxmlFiles(Collection). Multiple
files and method calls are allowed. The given values are converted to Path instances using
ScriptConverters.TO_SCRIPT_PATH 4.12.2 on page 166.
Raw AUTOSAR Data Mode
the method setRawAutosarDataMode(boolean) specifies whet-
her or not to use the raw ATUOSAR data model.
Currently only this mode is supported! You have to set rawAutosarDataMode = true.
Note: In raw mode most of the provided services and APIs will disabled, see below for de-
tails.
© 2017, Vector Informatik GmbH
64 of 250

---

Chapter 4.
AutomationInterface API Reference
4.5.6.1 Raw AUTOSAR models as Project
Sometimes it could be helpful to create an empty AUTOSAR model or load single ARXML
file. This is called raw mode (IProjectHandlingRawApi).
You could for example create an empty AUTOSAR model add elements and then export the
snippet as an ARXML file.
In raw mode most of the provided services and APIs will disabled, like:
• Ecuc access
• BswmdModel support
• Generation
• Validation
• Workflow
• Domain API
• ChangeInspector
• and more
Empty AUTOSAR model
The emptyAutosarModel(String, Closure) method creates a
new empty AUTOSAR model, only containing one MIARPackage created by this method with
the path AsrPath.
The passed AUTOSAR version defines the version of the AUTOSAR model, the version is
specified in the format "4.2.1" or "4.0.3", ...
scriptTask (" taskName ", DV_APPLICATION ) {
code {
def a s r P k g T o C r e a t e = AsrPath . create ( " / MyPkg " )
def a u t o s a r V e r s i o n = " 4.2.1 "
projects . raw . emptyAutosarModel ( autosarVersion , asrPkgToCreate ) {
modelProject , myPkg ->
// modelProject is the created IProject
// myPkg is the MIARPackage specified above with asrPkgToCreate
// Now you could use the model like any other project :
transaction {
// For example create a new sub package :
def mySubPkg = myPkg . s u b P a c k a g e . b y N a m e O r C r e a t e ( " MySubPkg " )
}
// Then export the package content
def e x p o r t F o l d e r = paths . g e t T e m p F o l d e r ()
persistency . modelExport . exportModelTree ( exportFolder , myPkg )
}
}
}
Listing 4.54: Create an empty AUTOSAR model
© 2017, Vector Informatik GmbH
65 of 250

---

Chapter 4.
AutomationInterface API Reference
4.6 Model
4.6.1 Introduction
The model API provides means to retrieve AUTOSAR model content and to modify AUTO-
SAR data. This comprises Ecuc data (module configurations and their content) and System
Description data.
In this chapter you’ll first find a brief introduction into the model handling. Here you also find
some simple cut-and-paste examples which allow starting easily with low effort. Subsequent
sections describe more and more details which you can read if required.
Chapter 5 on page 173 may additionally be useful to understand detailed concepts and as a
reference to handle special use cases.
4.6.2 Getting Started
The model API basically provides two different approaches:
• The MDF model is the low level AUTOSAR model. It stores all data read from AUTO-
SAR XML files. Its structure is base on the AUTOSAR MetaModel. In 5.1 on page 173
you find detailed information about this model.
• The BswmdModel is a model which wraps the MDF model to provide convenient and
type-safe access to the Ecuc data. It contains, definition based classes for module con-
figurations, containers, parameters and references. The class CanGeneral for example
as type-safe implementation in contrast to the generic AUTOSAR class MIContainer in
MDF.
It is strongly recommended to use the BswmdModel model to deal with Ecuc data
because it simplifies scripting a lot.
4.6.2.1 Read the ActiveEcuc
This section provides some typical examples as a brief introduction for reading the Ecuc by
means of the BswmdModel. See chapter 4.6.3.2 on page 75 for more details.
The following example specifies no types for the local variables. It therefore requires no import
statements. A drawback on the other hand is that the type is only known at runtime and you
have no type support in the IDE:
© 2017, Vector Informatik GmbH
66 of 250

---

Chapter 4.
AutomationInterface API Reference
scriptTask (" TaskName "){
code {
// Gets the module DefRef searching all definitions of this SIP
def m o d u l e D e f R e f = si pD ef Re f . EcuC
// Creates all BswmdModel instances with this definition . A List <EcuC >
in this case .
def e c u c M o d u l e s = b s w m d M o d e l ( m o d u l e D e f R e f )
// Gets the EcucGeneral container of the first found module instance
def ecuc = e c u c M o d u l e s . single
def e c u c G e n e r a l = ecuc . e c u c G e n e r a l
// Gets an ( enum ) parameter of this container
def cpuType = e c u c G e n e r a l . CPUType
}
}
Listing 4.55: Read with BswmdModel objects starting with a module DefRef (no type
declaration)
In contrast to the listing above the next one implements the same behavior but specifies all
types:
// Required imports
i m p o r t com . vector . cfg . a u t o m a t i o n . model . ecuc . microsar . ecuc . EcuC
i m p o r t com . vector . cfg . a u t o m a t i o n . model . ecuc . microsar . ecuc . e c u c g e n e r a l .
EcucGeneral
i m p o r t com . vector . cfg . a u t o m a t i o n . model . ecuc . microsar . ecuc . e c u c g e n e r a l . cputype .
CPUType
i m p o r t com . vector . cfg . a u t o m a t i o n . model . ecuc . microsar . ecuc . e c u c g e n e r a l . cputype .
ECPUType
scriptTask (" TaskName "){
code {
// Gets the ecuc module configuration
EcuC ecuc = bswmdModel ( EcuC ). single
// Gets the EcucGeneral container
EcucGeneral ecucGeneral = ecuc . ecucGeneral
// Gets an enum parameter of this container
CPUType cpuType = ecucGeneral . CPUType
if ( cpuType . value == ECPUType . CPU32Bit ) {
"Do something ... "
}
}
}
Listing 4.56: Read with BswmdModel objects starting with a module class (strong typing)
© 2017, Vector Informatik GmbH
67 of 250

---

Chapter 4.
AutomationInterface API Reference
The bswmdModel() API takes an optional closure argument which is being called for each
created BswmdModel object. This object is used as parameter of the closure:
// Required imports
i m p o r t com . vector . cfg . a u t o m a t i o n . model . ecuc . microsar . ecuc . EcuC
i m p o r t com . vector . cfg . a u t o m a t i o n . model . ecuc . microsar . ecuc . e c u c g e n e r a l . cputype .
ECPUType
scriptTask (" TaskName "){
code {
// Executes the closure with all instances of this definition
bswmdModel ( EcuC ) {
// The related BswmdModel instance is parameter of this closure
ecuc ->
if ( ecuc . e c u c G e n e r a l . CPUType . value == ECPUType . CPU32Bit ) {
"Do something ... "
}
}
}
}
Listing 4.57: Read with BswmdModel objects with closure argument
Additionally to the DefRef, an already available MDF model object can be specified to create
the related BswmdModel object for it:
// Required imports
i m p o r t com . vector . cfg . a u t o m a t i o n . model . ecuc . microsar . ecuc . e c u c g e n e r a l .
EcucGeneral
i m p o r t com . vector . cfg . a u t o m a t i o n . model . ecuc . microsar . ecuc . e c u c g e n e r a l . cputype .
ECPUType
scriptTask (" TaskName "){
code {
// Gets the MDF model instance of the Ecuc General container
def co nt ai ne r = mdfModel ( E c u c G e n e r a l . DefRef ) . single
// Executes the closure with this MDF object instance
bswmdModel ( container , EcucGeneral . DefRef ) {
// The related BswmdModel instance is parameter of this closure
ecucGeneral ->
if ( e c u c G e n e r a l . CPUType . value == ECPUType . CPU32Bit ) {
"Do something ... "
}
}
}
}
Listing 4.58: Read with BswmdModel object for an MDF model object
© 2017, Vector Informatik GmbH
68 of 250

---

Chapter 4.
AutomationInterface API Reference
4.6.2.2 Write the ActiveEcuc
This section provides some typical examples as a brief introduction for writing the Ecuc by
means of the BswmdModel. See chapter 4.6.3.3 on page 76 for more details.
For the most cases the entry point for writing the ActiveEcuc is a (existing) module configuration
object which can be retrieved with the bswmdModel() API. Because the model is in read-only
state by default, every call to an API which creates or deletes elements has to be executed in
a transaction() block.
// Required imports
i m p o r t com . vector . cfg . a u t o m a t i o n . model . ecuc . microsar . ecuc . EcuC
i m p o r t com . vector . cfg . a u t o m a t i o n . model . ecuc . microsar . ecuc . e c u c g e n e r a l .
EcucGeneral
scriptTask (" TaskName "){
code {
transaction {
// Gets the first found ecuc module instance
EcuC ecuc = bswmdModel ( EcuC ). single
// Gets the EcucGeneral container or create one if it is missing
EcucGeneral ecucGeneral = ecuc . ecucGeneralOrCreate
// Gets an boolean parameter of this container or create one if it
is missing
def e c u C S a f e B s w C h e c k s = e c u c G e n e r a l . e c u C S a f e B s w C h e c k s O r C r e a t e
// Sets the parameter value to true
ecuCSafeBswChecks . value = true
}}}
Listing 4.59: Write with BswmdModel required/optional objects
© 2017, Vector Informatik GmbH
69 of 250

---

Chapter 4.
AutomationInterface API Reference
// Required imports
i m p o r t com . vector . cfg . a u t o m a t i o n . model . ecuc . microsar . ecuc . EcuC
i m p o r t com . vector . cfg . a u t o m a t i o n . model . ecuc . microsar . ecuc . e c u c h a r d w a r e .
ecuccoredefinition . EcucCoreDefinition
scriptTask (" TaskName "){
code {
transaction {
// Gets the first found ecuc module instance
EcuC ecuc = bswmdModel ( EcuC ). single
// Gets the EcucCoreDefinition list ( creates ecucHardware if it is
missing )
def e c u c C o r e D e f i n i t i o n s = ecuc . e c u c H a r d w a r e O r C r e a t e .
ecucCoreDefinition
// Adds two EcucCores
EcucCoreDefinition core0 = ecucCoreDefinitions . createAndAdd ("
EcucCore0 ")
EcucCoreDefinition core1 = ecucCoreDefinitions . createAndAdd ("
EcucCore1 ")
if ( e c u c C o r e D e f i n i t i o n s . exists ( " E cu cC ore0 " ) ) {
// Sets EcucCoreId to 0
ecucCoreDefinitions . byName (" EcucCore0 "). ecucCoreId . setValue (0) ;
}
// Creates a new EcucCore by method ' byNameOrCreate '
EcucCoreDefinition core2 = ecucCoreDefinitions . byNameOrCreate ("
EcucCore2 ");
}}}
Listing 4.60: Write with BswmdModel multiple objects
// Required imports
i m p o r t com . vector . cfg . a u t o m a t i o n . model . ecuc . microsar . ecuc . EcuC
i m p o r t com . vector . cfg . a u t o m a t i o n . model . ecuc . microsar . ecuc . e c u c g e n e r a l .
EcucGeneral
scriptTask (" TaskName "){
code {
transaction {
// Gets the first found ecuc module instance
EcuC ecuc = bswmdModel ( EcuC ). single
// Duplicates container ' EcucGeneral ' and all its children
EcucGeneral ecucGeneral_Dup = ecuc . ecucGeneral . duplicate ()
}
}
}
Listing 4.61: Write with BswmdModel - Duplicate a container
© 2017, Vector Informatik GmbH
70 of 250

---

Chapter 4.
AutomationInterface API Reference
// Required imports
i m p o r t com . vector . cfg . a u t o m a t i o n . model . ecuc . microsar . ecuc . e c u c g e n e r a l .
EcucGeneral
scriptTask (" TaskName "){
code {
transaction {
// Gets the first found ecuc module instance
EcucGeneral ecucGeneral = bswmdModel ( EcucGeneral ). single
// Deletes ' ecucGeneral ' from model
ecucGeneral . moRemove ()
// Checks if the container ' ecucGeneral ' was removed from repository
if ( e c u c G e n e r a l . m o I s R e m o v e d () ) {
"Do something ... "
}
}
}
}
Listing 4.62: Write with BswmdModel - Delete elements
© 2017, Vector Informatik GmbH
71 of 250

---

Chapter 4.
AutomationInterface API Reference
4.6.2.3 Read the SystemDescription
This section contains only one example for reading the SystemDescription by means of the MDF
model. See chapter 4.6.4.1 on page 79 for more details.
// Required imports
i m p o r t com . vector . cfg . model . mdf . ar4x . s w c o m p o n e n t t e m p l a t e . datatype .
dataprototypes .*
i m p o r t com . vector . cfg . model . mdf . ar4x . c o m m o n s t r u c t u r e . d a t a d e f p r o p e r t i e s .*
scriptTask (" mdfModel ", DV_PROJECT ){
code {
// Create a type - safe AUTOSAR path
def asrPath =
AsrPath . create ("/ PortInterfaces / PiSignal_Dummy / DeSignal_Dummy ",
MIVariableDataPrototype )
// Enter the MDF model tree starting at the object with this path
mdfModel ( asrPath ) { MIVariableDataPrototype prototype ->
// Traverse down to the swDataDefProps
prototype . swDataDefProps { MISwDataDefProps swDataDefPropsParam ->
// swDataDefPropsVariant is a List < MISwDataDefPropsConditional >
// Execute the following for ALL elements of this List
swDataDefPropsParam . swDataDefPropsVariant {
MISwDataDefPropsConditional swDataDefPropsCondParam ->
// Resolve the dataConstr reference ( type MIDataConstr )
def target = s w D a t a D e f P r o p s C o n d P a r a m . dat aC o n st r . refTarget
// Get the swCalibrationAccess enum value
def access = s w D a t a D e f P r o p s C o n d P a r a m . s w C a l i b r a t i o n A c c e s s
a s s e r t access == M I S w C a l i b r a t i o n A c c e s s E n u m . N O T _ A C C E S S I B L E
}
}
}
}
}
Listing 4.63: Read system description starting with an AUTOSAR path in closure
The same sample as above, but in property access style instead of closures:
© 2017, Vector Informatik GmbH
72 of 250

---

Chapter 4.
AutomationInterface API Reference
// Create a type - safe AUTOSAR path
def asrPath =
AsrPath . create ("/ PortInterfaces / PiSignal_Dummy / DeSignal_Dummy ",
MIVariableDataPrototype )
def pr ot ot yp e = mdfModel ( asrPath )
def s w D a t a D e f P r o p s P a r a m = pr ot ot yp e . s w D a t a D e f P r o p s
// Execute the following for ALL swDataDefPropsVariant
swDataDefPropsParam . swDataDefPropsVariant . each { swDataDefPropsCondParam ->
//
Resolve the dataConstr reference ( type MIDataConstr )
def target = s w D a t a D e f P r o p s C o n d P a r a m . d a t a C o n s t r . refTarget
// Get the swCalibrationAccess enum value
def access = s w D a t a D e f P r o p s C o n d P a r a m . s w C a l i b r a t i o n A c c e s s
a s s e r t access == M I S w C a l i b r a t i o n A c c e s s E n u m . N O T _ A C C E S S I B L E
}
Listing 4.64: Read system description starting with an AUTOSAR path in property style
4.6.2.4 Write the SystemDescription
Writing the system description looks quite similar to the reading, but you have to use methods
like (see chapter 4.6.4.3 on page 82 for more details):
• get<Element>OrCreate() or <element>OrCreate
• createAndAdd()
• byNameOrCreate()
You have to open a transaction before you can modify the MDF model, see chapter 4.6.6 on
page 95 for details.
The following samples show the different types of write API:
transaction {
// The asrPath points to an MIVariableDataPrototype
mdfModel ( asrPath ) { dataPrototype ->
dataPrototype . category = " NewCategory "
}
}
Listing 4.65: Changing a simple property of an MIVariableDataPrototype
transaction {
// The asrPath points to an MIVariableDataPrototype
mdfModel ( asrPath ) {
int count = 0
a s s e r t a dm in Da ta == null
adminDataOrCreate {
count ++
}
a s s e r t count == 1
a s s e r t adminData != null
}
}
Listing 4.66: Creating non-existing member by navigating into its content with OrCreate()
© 2017, Vector Informatik GmbH
73 of 250

---

Chapter 4.
AutomationInterface API Reference
transaction {
// The asrPath points to an MIVariableDataPrototype
mdfModel ( asrPath ) {
a s s e r t a dm in Da ta . sdg . empty
adminData {
sdg . createAndAdd ( MISdg ) {
gid = " NewGidValue "
}
}
a s s e r t a dm in Da ta . sdg . first . gid == " N e w G i d V a l u e "
}
}
Listing 4.67: Creating new members of child lists with createAndAdd() by type
transaction {
// The path points to an MISenderReceiverInterface
mdfModel ( asrPath ) { sendRecIf ->
def dataList = s en dR ec If . d a t a E l e m e n t
def d a t a E l e m e n t = dataList . b y N a m e O r C r e a t e ( " M y D a t a E l e m e n t " )
dataElement . name = " NewName "
def d a t a E l e m e n t 2 = dataList . b y N a m e O r C r e a t e ( " NewName " )
a s s e r t d a t a E l e m e n t == d a t a E l e m e n t 2
}
}
Listing 4.68: Updating existing members of child lists with byNameOrCreate() by type
© 2017, Vector Informatik GmbH
74 of 250

---

Chapter 4.
AutomationInterface API Reference
4.6.3 BswmdModel in AutomationInterface
The AutomationInterface contains a generated BswmdModel. The BswmdModel provides clas-
ses for all Ecuc elements of the AUTOSAR model (ModuleConfigurations, Containers, Para-
meter, References). The BswmdModel is automatically generated from the SIP of the DaVinci
Configurator.
You should use the BswmdModel whenever possible to access Ecuc elements of the AUTOSAR
model. For accessing the Ecuc elements with the BswmdModel, see chapter 4.6.3.2.
For a detailed description of the BswmdModel, see chapter 5.3.1 on page 187.
4.6.3.1 BswmdModel Package and Class Names
The generated model is contained in the Java package com.vector.cfg.automation.model.ecuc.
Every Module has its own sub packages with the name:
• com.vector.cfg.automation.model.ecuc.<AUTOSAR-PKG>.<SHORTNAME>
– e.g. com.vector.cfg.automation.model.ecuc.microsar.dio
– e.g. com.vector.cfg.automation.model.ecuc.autosar.ecucdefs.can
The packages then contain the class of the element like Dio for the module. The full path would
be com.vector.cfg.automation.model.ecuc.microsar.dio.Dio.
For the container DioGeneral it would be:
• com.vector.cfg.automation.model.ecuc.microsar.dio.diogeneral.DioGeneral
To use the BswmdModel in script files, you have to write an import, when accessing the
class:
// The required BswmdModel import of the class Dio
i m p o r t com . vector . cfg . a u t o m a t i o n . model . ecuc . microsar . dio . Dio
scriptTask (" TaskName "){
code {Dio.DefRef //Usage of the class Dio
}
}
Listing 4.69: BswmdModel usage with import
4.6.3.2 Reading with BswmdModel
The bswmdModel() methods provide entry points to start navigation through the ActiveEcuc.
Client code can use the Closure overloads to navigate into the content of the found bswmd ob-
jects. Inside the called closure the related bswmd object is available as closure parameter.
The following types of entry points are provided here:
• bswmdModel(WrappedTypedDefRef) searches all objects with the specified definition and
returns the BswmdModel instances.
• bswmdModel(Class) searches all objects with the specified class and returns the Bswmd-
Model instances. Finds the same elements as above.
© 2017, Vector Informatik GmbH
75 of 250

---

Chapter 4.
AutomationInterface API Reference
• bswmdModel(MIHasDefinition, WrappedTypedDefRef) returns the BswmdModel instance
for the provided MDF model instance.
• bswmdModel(Class, String) searches all objects with the specified class and the mat-
ching path, see IMdfModelApi.mdfModel(String) or chapter 4.6.4.2 on page 81 for de-
tails.
When a closure is being used, the object found by bswmdModel() is provided as parameter when
the closure is called.
The bswmdModel() method itself returns the found objects too. Retrieving the objects member
and children (Container, Parameter) as properties or methods are then possible directly using
the returned object.
Examples:
code {
// Gets the ecuc module configuration
EcuC ecuc = bswmdModel ( EcuC ). single
}
Listing 4.70: Read with BswmdModel the EcuC module configuration
Or the same with a DefRef instead of a Class:
code {
// Gets the ecuc module configuration
EcuC ecuc = bswmdModel ( EcuC . DefRef ). single
}
Listing 4.71: Read with BswmdModel the EcuC module configuration with DefRef
For more usage samples please see chapter 4.6.2.1 on page 66.
4.6.3.3 Writing with BswmdModel
As well as for reading with BswmdModel the entry points for writing with BswmdModel are also
the bswmdModel() methods. There has to be at least one existing element in the ActiveEcuc
from which the navigation can be started. For the most cases the entry point for writing the
ActiveEcuc is the module configuration.
Example:
code {
transaction {
// Gets the ecuc module configuration
EcuC ecuc = bswmdModel ( EcuC ). single
// Gets the EcucGeneral container or create one if it is missing
EcucGeneral ecucGeneral = ecuc . ecucGeneralOrCreate
}
}
Listing 4.72: Write with BswmdModel the EcucGeneral container
For more usage samples please see chapter 4.6.2.2 on page 69.
The model is in read-only state by default, so no objects could be created. For this reason all
calls which creates or deletes elements has to be executed within a transaction() block.
© 2017, Vector Informatik GmbH
76 of 250

---

Chapter 4.
AutomationInterface API Reference
See 5.3.1.9 on page 195 for more details to the BswmdModel write API.
4.6.3.4 Sip DefRefs
The sipDefRef API provides access to retrieve generated DefRef instances from the SIP without
knowing the correct Java/Groovy imports. This is mainly useful in script files, where no IDE
helps with the imports.
If you are using an Automation Script Project you can ignore this API and use the
DefRefs provided by the generated classes, which is superior to this API, because they are
typesafe and compile time checked. See 4.6.3.5 for details.
The listing show the usage of the sipDefRef API with short names and definition paths.
code {
def t he De fR ef
// You can call sipDefRef .< ShortName >
theDefRef = sipDefRef . EcucGeneral
theDefRef = sipDefRef . Dio
theDefRef = sipDefRef . DioPort
// Or you can use the [] notation
theDefRef = sipDefRef [" Dio "]
theDefRef = sipDefRef [" DioChannelGroup "]
// If the DefRef is not unique you have to specify the full definition
theDefRef = sipDefRef ["/ MICROSAR / EcuC / EcucGeneral "]
theDefRef = sipDefRef ["/ MICROSAR / Dio "]
theDefRef = sipDefRef ["/ MICROSAR / Dio / DioConfig / DioPort "]
}
Listing 4.73: Usage of the sipDefRef API to retrieve DefRefs in script files
4.6.3.5 BswmdModel DefRefs
The generated BswmdModel classes contain DefRef instances for each definition element (Mo-
dules, Containers, Parameters). You should always prefer this API over the Sip DefRefs, because
this is type safe and checked during compile time.
You can use the DefRefs by calling <ModelClassName>.DefRef. The literal DefRef is a static
constant in the generated classes.
For simple parameters like Strings, Integer there is no generated class, so you have to call the
method on its parent container like <ParentContainerClass>.<ParameterShortName>DefRef.
There exist generated classes for Parameters of type Enumeration and References to Container
and therefore you have both ways to access the DefRef:
• <ModelClassName>.DefRef or
• <ParentContainerClass>.<ParameterShortName>DefRef
To use the DefRefs of the classes you have to add imports in script files, see chapter 4.6.3.1 on
page 75 for required import names.
© 2017, Vector Informatik GmbH
77 of 250

---

Chapter 4.
AutomationInterface API Reference
// Required imports
i m p o r t com . vector . cfg . a u t o m a t i o n . model . ecuc . microsar . ecuc . e c u c g e n e r a l .
EcucGeneral
i m p o r t com . vector . cfg . a u t o m a t i o n . model . ecuc . microsar . ecuc . e c u c g e n e r a l . cputype .
CPUType
scriptTask (" TaskName "){
code {
def t he De fR ef
// DefRef from EcucGeneral container
theDefRef = EcucGeneral . DefRef
// DefRef from generated parameter
theDefRef = CPUType . DefRef
// Or the same
theDefRef = EcucGeneral . CPUTypeDefRef
// DefRef from simple parameter
theDefRef = EcucGeneral . AtomicBitAccessInBitfieldDefRef
theDefRef = EcucGeneral . DummyFunctionDefRef
}
}
Listing 4.74: Usage of generated DefRefs form the bswmd model
4.6.3.6 Switching from Domain Models to BswmdModel
You can switch from domain models to the BswmdModel, if the domain model is backed by Acti-
veEcuC elements. Please read the documentation of the different domain models, for whether
this is possible for a certain domain model.
To switch from a domain model to the BswmdModel, you can call one of the methods for IHas-
ModelObjects like, bswmdModel(IHasModelObject, WrappedTypedDefRef). But you need a
DefRef to get the type safe BswmdModel object. The domain model documents, which DefRef
must be used for the certain domain model object.
// Domain model object of the communication domain
ICanController canDomainModel = ...
def c a n C o n t r o l l e r B s w m d = c a n D o m a i n M o d e l . b s w m d M o d e l ( C a n C o n t r o l l e r . DefRef )
// Or use a closure
canDomainModel . bswmdModel ( CanController . DefRef ){ canControllerBswmd ->
// Use the bswmd object
}
Listing 4.75: Switch from a domain model object to the corresponding BswmdModel object
4.6.4 MDF Model in AutomationInterface
Access to the MDF model is required in all areas which are not covered by the BswmdModel.
This is the SystemDescription (non-Ecuc data) and details of the Ecuc model which are not
covered by the BswmdModel.
The MDF model implements the raw AUTOSAR data model and is based on the AUTOSAR
meta-model. For details about the MDF model, see chapter 5.1 on page 173.
© 2017, Vector Informatik GmbH
78 of 250

---

Chapter 4.
AutomationInterface API Reference
For more details concerning the methods mentioned in this chapter, you should also read the
JavaDoc sections in the described interfaces and classes.
4.6.4.1 Reading the MDF Model
The mdfModel() methods provide entry points to start navigation through the MDF model.
Client code can use the Closure overloads to navigate into the content of the found MDF
objects. Inside the called closure the related MDF object is available as closure parameter.
The following types of entry points are provided here:
• mdfModel(TypedAsrPath) searches an object with the specified AUTOSAR path
• mdfModel(TypedDefRef) searches all objects with the specified definition
• mdfModel(Class) searches all objects with the specified model type (meta class)
• mdfModel(String) searches for model elements with by different properties, see 4.6.4.2
on page 81 for details.
When a closure is being used, the object found by mdfModel() is provided as parameter when
this closure is called:
code {
// Create a type - safe AUTOSAR path for a MIVariableDataPrototype
def asrPath =
AsrPath . create ("/ PortInterfaces / PiSignal_Dummy / DeSignal_Dummy ",
MIVariableDataPrototype )
// Use the Java - Style syntax
def d a t a D e f P r o p s M d f = mdfModel ( asrPath ) . s w D a t a D e f P r o p s
// Or use the Closure syntax to navigate
// Enter the MDF model tree starting at the object with this path
mdfModel ( asrPath ) {
// Parameter type is MIVariableDataPrototype :
dataPrototype ->
// Traverse down to the swDataDefProps
dataPrototype . swDataDefProps { MISwDataDefProps props
println "Do something ... "
}
}
}
Listing 4.76: Navigate into an MDF object starting with an AUTOSAR path
The mdfModel() method itself returns the found object too. Retrieving the objects member
(as property) is then possible directly using the returned object.
An alternative is using a closure to navigate into the MDF object and access its member
there:
© 2017, Vector Informatik GmbH
79 of 250

---

Chapter 4.
AutomationInterface API Reference
// Get an MDF object and get its members directly
def obj = mdfModel ( asrPath )
// Type MIVariableDataPrototype
def props = obj . s w D a t a D e f P r o p s
// Type MISwDataDefProps
// Get an MDF object and get its members using a closure
def props2
def obj2 = mdfModel ( asrPath ) {
props2 = swDataDefProps
}
// The results are the same
a s s e r t obj == obj2
a s s e r t props == props2
Listing 4.77: Find an MDF object and retrieve some content data
Closures can be nested to navigate deeply into the MDF model tree:
mdfModel ( asrPath ) {
int count = 0
swDataDefProps {
// swDataDefPropsVariant is a List < MISwDataDefPropsConditional >
// Execute the following for ALL elements of this List
List v = swDataDefPropsVariant {
println "Do something ... "
count ++
}
}
a s s e r t count >= 1
}
Listing 4.78: Navigating deeply into an MDF object with nested closures
When a member doesn’t exist during navigation into a deep MDF model tree, the specified
closure is not called:
mdfModel ( asrPath ) {
int count = 0
a s s e r t ad mi nD at a == null
adminData {
count ++
}
a s s e r t count == 0
}
Listing 4.79: Ignoring non-existing member closures
Retrieving a Child by Shortname or Definition
There are multiple ways to retrieve children
from an MDF model object, by the shortname or by its definition. The shortname can be used
at the object with childByName() or at the child list with byName().
childByName
The childByName(MIARObject, String, Closure) method calls the passed
Closure, if the request child exists. And returns the child MIReferrable below the specified
object which has this relative AUTOSAR path (not starting with ’/’).
© 2017, Vector Informatik GmbH
80 of 250

---

Chapter 4.
AutomationInterface API Reference
MIContainer canGeneral = ...
canGeneral . childByName (" CanMainFunctionRWPeriods "){ child ->
// Do something
}
Listing 4.80: Get a MIReferrable child object by name
Lists containing Referrables
• The method byName(String) retrieves the child with the shortname, or null, if no child
exists with this shortname.
• The method byName(String, Closure) retrieves the child with the shortname, or null,
if no child exists with this shortname. Then the closure is executed with the child as
closure parameter, if the child is not null. The child is finally returned.
• The method byName(Class, String) retrieves the child with the shortname and type,
or null, if no child exists with this shortname.
• The method byName(Class, String, Closure) retrieves the child with the shortname
and type, or null, if no child exists with this shortname. Then the closure is executed
with the child as closure parameter, if the child is not null. The child is finally returned.
• The method getAt(String) all members with this relative AUTOSAR path. Groovy
also allows to write list["ShortnameToSearchFor"].
// The asrPath points to an MISenderReceiverInterface
def pr ot ot yp e = mdfModel ( asrPath )
// byName () with shortname
def data1 = p ro to ty pe . d a t a E l e m e n t . byName ( " D e S i g n a l _ D u m m y " )
a s s e r t data1 . name == " D e S i g n a l _ D u m m y "
// byName () with type and shortname
def data2 = p ro to ty pe . d a t a E l e m e n t . byName ( M I V a r i a b l e D a t a P r o t o t y p e , " DeS ignal2 " )
// getAt () with shortname
def data3 = p ro to ty pe . d a t a E l e m e n t [ " D eS ig na l3 " ]
Listing 4.81: Retrieve child from list with byName()
Lists containing Parameters and Containers
• The method getAt(TypedDefRef) returns all children with the passed definition. Groovy
also allows to write list[DefRef].
4.6.4.2 Reading the MDF Model by String
The method mdfModel(String) searches for model elements by multiple ways at once. The
method evaluates the specified property in the following order, it will continue, if nothing was
found:
• AUTOSAR path, see mdfModel(AsrPath), if the path begins with an ’/’ and the model
element is no definition object (MIParamConfMultiplicity)
– Example: /ActiveEcuc/MyCan/MyContainer
© 2017, Vector Informatik GmbH
81 of 250

---

Chapter 4.
AutomationInterface API Reference
• ObjectLink, see AsrObjectLink, if the path begins with an ’/’ and the model element is
no definition object (type MIParamConfMultiplicity)
– Example: /ActiveEcuc/MyCan/MyContainer[0:ParameterDef]
• Definition path, see mdfModel(DefRef), if the path begins with an ’/’
– Example: /MICROSAR/Can
• AUTOSAR path relative to the ActiveEcuc package, if it does not begin with an ’/’
– Example: MyCan/MyContainer
• Definition path as DefRef with wildcard ANY starting at the moduleConfiguration, if it
does not begin with an ’/’
– Example: Can/CanGeneral
• Definition path as DefRef with wildcards, if it does begin with a valid wildcard like
/[ANY], see EDefRefWildcard.
– Example: /[ANY]/Can/CanGeneral
• Shortname of an MIARElement if the path does not contain any ’/’.
– Example: MyContainer
This method does not limit the search to the ActiveEcuC, so it can be used to retrieve any
object with the path String.
Remark: Even in post-build selectable variant models this method expects to find at most one
object because script code will never run in an unfiltered context.
Caution: This is a potential slow operation, you should use other mdfModel() methods, if
possible. Because this method must traverse the whole model in some cases.
def m o d u l e C f g 1 = mdfModel ( " / A c t i v e E c u C / Can " ) . single
def m o d u l e C f g 2 = mdfModel ( " Can " ) . single
def m o d u l e C f g 3 = mdfModel ( " /[ ANY ]/ Can " ) . single
def pa ra me te r
= mdfModel ("/ ActiveEcuc / MyCan / MyContainer [0: ParameterDef ]").
singleOrNull
Listing 4.82: Get elements with mdfModel(String)
4.6.4.3 Writing the MDF Model
Writing to the MDF model can be done with the same mdfModel(AsrPath) API, but you have
to call specific methods to modify the model objects. The methods are devided in the following
use cases:
• Change a simple property like Strings
• Change or create a single child relateion (0:1)
• Create a new child for a child list (0:*)
• Update an existing child from a child list (0:*)
You have to open a transaction before you can modify the MDF model, see chapter 4.6.6 on
page 95 for details about transactions.
© 2017, Vector Informatik GmbH
82 of 250

---

Chapter 4.
AutomationInterface API Reference
4.6.4.4 Simple Property Changes
The properties of MDF model object simply be changed by with the setter method of the model
object. Simple setter exist for example for the types:
• String
• Enums
• Integer
• Double
transaction {
// The asrPath points to an MIVariableDataPrototype
mdfModel ( asrPath ) { dataPrototype ->
dataPrototype . category = " NewCategory "
}
}
Listing 4.83: Changing a simple property of an MIVariableDataPrototype
4.6.4.5 Creating single Child Members (0:1)
For single child members (0:1), the automation API provides and additional method for the
getter get<Element>OrCreate() for convenient child object creation. The methods will create
the element, instead of returning null.
transaction {
// The asrPath points to an MIVariableDataPrototype
mdfModel ( asrPath ) {
int count = 0
a s s e r t a dm in Da ta == null
adminDataOrCreate {
count ++
}
a s s e r t count == 1
a s s e r t a dm in Da ta != null
}
}
Listing 4.84: Creating non-existing member by navigating into its content with OrCreate()
If the compile time child type is not instatiatable, you have to provide the concrete type by
get<Element>OrCreate(Class childType).
transaction {
// The asrPath points to an MIVariableDataPrototype
mdfModel ( asrPath ) {
introductionOrCreate ( MIBlockLevelContent ) { docuBlock ->
a s s e r t docuBlock in st an ce of M I B l o c k L e v e l C o n t e n t
}
}
}
Listing 4.85: Creating child member by navigating into its content with OrCreate() with type
© 2017, Vector Informatik GmbH
83 of 250

---

Chapter 4.
AutomationInterface API Reference
4.6.4.6 Creating and adding Child List Members (0:*)
For child list members, the automation API provides many createAndAdd() methods for con-
venient child object creation. These method will always create the element, regardless if the
same element (e.g. same ShortName) already exists.
If you want to update element see the chapter 4.6.4.7 on page 86.
transaction {
// The asrPath points to an MIVariableDataPrototype
mdfModel ( asrPath ) {
a s s e r t a dm in Da ta . sdg . empty
adminData {
sdg . createAndAdd ( MISdg ) {
gid = " NewGidValue "
}
}
a s s e r t a dm in Da ta . sdg . first . gid == " N e w G i d V a l u e "
}
}
Listing 4.86: Creating new members of child lists with createAndAdd() by type
These methods are available — but be aware that not all of these methods are available for all
child lists. Adding parameters, for example, is only permitted in the parameter child list of an
MIContainer instance.
All Lists:
• The method createAndAdd() creates a new MDF object of the lists content type and
appends it to this list. If the type is not instantiatable the method will thrown a Mo-
delException. The new object is finally returned.
• The method createAndAdd(Closure) creates a new MDF object of the lists content type
and appends it to this list. If the type is not instantiatable the method will thrown a
ModelException. Then the closure is executed with the new object as closure parameter.
The new object is finally returned.
• The method createAndAdd(Class) creates a new MDF object of the specified type and
appends it to this list. The new object is finally returned.
• The method createAndAdd(Class, Closure) creates a new MDF object of the specified
type and appends it to this list. Then the closure is executed with the new object as
closure parameter. The new object is finally returned.
• The method createAndAdd(Class, Integer) creates a new MDF object of the specified
type and inserts it to this list at the specified index position. The new object is finally
returned.
• The method createAndAdd(Class, Integer, Closure) creates a new MDF object of
the specified type and inserts it to this list at the specified index position. Then the
closure is executed with the new object as closure parameter. The new object is finally
returned.
© 2017, Vector Informatik GmbH
84 of 250

---

Chapter 4.
AutomationInterface API Reference
Lists containing Referrables
• The method createAndAdd(String) creates a new child with the specified shortname
and appends it to this list. The new object is finally returned. The used type is the lists
content type. If the type is not instantiatable the method will thrown a ModelException.
• The method createAndAdd(String, Closure) creates a new MIReferrable with the
specified shortname and appends it to this list. Then the closure is executed with the new
object as closure parameter. The new object is finally returned. The used type is the lists
content type. If the type is not instantiatable the method will thrown a ModelException.
• The method createAndAdd(Class, String) creates a new MIReferrable with the spe-
cified type and shortname and appends it to this list. The new object is finally returned.
• The method createAndAdd(Class, String, Closure) creates a new MIReferrable with
the specified type and shortname and appends it to this list. Then the closure is executed
with the new object as closure parameter. The new object is finally returned.
• The method createAndAdd(Class, String, Integer) creates a new MIReferrable with
the specified type and shortname and inserts it to this list at the specified index position.
The new object is finally returned.
• The method createAndAdd(Class, String, Integer, Closure) creates a new MIRe-
ferrable with the specified type and shortname and inserts it to this list at the specified
index position. Then the closure is executed with the new object as closure parameter.
The new object is finally returned.
Lists containing Parameters and Containers
• The method createAndAdd(TypedDefRef) creates a new Ecuc object (container or para-
meter) with the specified definition and appends it to this list. The new object is finally
returned.
• The method createAndAdd(TypedDefRef, Closure) creates a new Ecuc object (contai-
ner or parameter) with the specified definition and appends it to this list. Then the closure
is executed with the new object as closure parameter. The new object is finally returned.
• The method createAndAdd(TypedDefRef, Integer) creates a new Ecuc object (contai-
ner or parameter) with the specified definition and inserts it to this list at the specified
index position. The new object is finally returned.
• The method createAndAdd(TypedDefRef, Integer, Closure) creates a new Ecuc ob-
ject (container or parameter) with the specified definition and inserts it to this list at
the specified index position. Then the closure is executed with the new object as closure
parameter. The new object is finally returned.
Lists containing Containers
• The method createAndAdd(TypedDefRef, String) creates a new container with the
specified definition and shortname and appends it to this list.
The new container is
finally returned.
• The method createAndAdd(TypedDefRef, String, Closure) creates a new container
with the specified definition and shortname and appends it to this list. Then the closure
is executed with the new container as closure parameter. The new container is finally
returned.
© 2017, Vector Informatik GmbH
85 of 250

---

Chapter 4.
AutomationInterface API Reference
• The method createAndAdd(TypedDefRef, String, Integer) creates a new container
with the specified definition and shortname and inserts it to this list at the specified index
position. The new container is finally returned.
• The method createAndAdd(TypedDefRef, String, Integer, Closure) creates a new
container with the specified definition and shortname and inserts it to this list at the
specified index position. Then the closure is executed with the new container as closure
parameter. The new container is finally returned.
4.6.4.7 Updating existing Elements
For child list members, the automation API provides many byNameOrCreate() methods for
convenient child object update and creation on demand. These method will create the element
if id does not exists, or return the existing element.
transaction {
// The path points to an MISenderReceiverInterface
mdfModel ( asrPath ) { sendRecIf ->
def dataList = s en dR ec If . d a t a E l e m e n t
def d a t a E l e m e n t = dataList . b y N a m e O r C r e a t e ( " M y D a t a E l e m e n t " )
dataElement . name = " NewName "
def d a t a E l e m e n t 2 = dataList . b y N a m e O r C r e a t e ( " NewName " )
a s s e r t d a t a E l e m e n t == d a t a E l e m e n t 2
}
}
Listing 4.87: Updating existing members of child lists with byNameOrCreate() by type
These methods are available — but be aware that not all of these methods are available for all
child lists. Updating container, for example, is only permitted in the parameter child list of an
MIContainer instance.
Lists containing Referrables
• The method byNameOrCreate(String) retrieves the child with the passed shortname, or
creates the child, if it does not exist. The shortname is automatically set before returning
the new child.
• The method byNameOrCreate(TypedDefRef, String,Closure) retrieves the child with
the passed shortname, or creates the child, if it does not exist. The shortname is auto-
matically set before returning the new child. Then the closure is executed with the child
as closure parameter. The child is finally returned.
• The method byNameOrCreate(Class, String) retrieves the child with the passed type
and shortname, or creates the child, if it does not exist. The shortname is automatically
set before returning the new child.
• The method byNameOrCreate(Class, String,Closure) retrieves the child with the pas-
sed type and shortname, or creates the child, if it does not exist. The shortname is auto-
matically set before returning the new child. Then the closure is executed with the child
as closure parameter. The child is finally returned.
© 2017, Vector Informatik GmbH
86 of 250

---

Chapter 4.
AutomationInterface API Reference
Lists containing Containers
• The method byNameOrCreate(TypedDefRef, String) retrieves the child with the passed
definition and shortname, or creates the child, if it does not exist. The definition and
shortname are automatically set before returning the new child.
• The method byNameOrCreate(TypedDefRef, String, Closure) retrieves the child with
the passed definition and shortname, or creates the child, if it does not exist. The definition
and shortname are automatically set before returning the new child. Then the closure is
executed with the child as closure parameter. The child is finally returned.
4.6.4.8 Deleting Model Objects
The method moRemove(MIObject) deletes the specified object from the model. This method
must be called inside a transaction because it changes the model content.
Special case: If this method is being called on an active module configuration, it actually calls
IOperations.deactivateModuleConfiguration(MIModuleConfiguration) to deactivate the
module correctly.
// MIParameterValue param = ...
transaction {
a s s e r t ! param . m o I s R e m o v e d ()
param . moRemove ()
a s s e r t param . m o I s R e m o v e d ()
}
Listing 4.88: Delete a parameter instance
For details about model object deletion and access to deleted objects, read section 5.1.7.4 on
page 178 ff.
moIsRemoved
The getMoIsRemoved(MIObject) method returns true if the specified object
has been removed (deleted) from the MDF model.
MIObject obj = ...
if (! obj . m o I s R e m o v e d () ) {
work with obj ...
}
Listing 4.89: Check is a model instance is deleted
4.6.4.9 Duplicating Model Objects
The duplicate(MIObject) method copies (clones) a complete MDF model sub-tree and adds
it as child below the same parent.
• The source object must have a parent. The clone will be added to the same MDF feature
below the same parent then
• AUTOSAR UUIDs will not be cloned. The clone will contain new UUIDs to guarantee
unambiguousness
© 2017, Vector Informatik GmbH
87 of 250

---

Chapter 4.
AutomationInterface API Reference
This method can clone any model sub-tree, also see IOperations.deepClone(MIObject, MI-
Object) for details.
Note: This operation must be executed inside of a transaction.
// MIContainer container = ...
transaction {
def newCont = co nt ai ne r . du pl ic at e ()
// The duplicated container newCont
}
Listing 4.90: Duplicates a container under the same parent
4.6.4.10 Special properties and extensions
asrPath
The getAsrPath(MIReferrable) method returns the AUTOSAR path of the speci-
fied object.
MIContainer canGeneral = ...
AsrPath path = canGeneral . asrPath
Listing 4.91: Get the AsrPath of an MIReferrable instance
See chapter 5.4.2 on page 199 for more details about AsrPaths.
asrObjectLink
The getAsrObjectLink(MIARObject) method returns the AsrObjectLink of
the specified object.
MIParameterValue param = ...
AsrObjectLink link = param . asrObjectLink
Listing 4.92: Get the AsrObjectLink of an AUTOSAR model instance
See chapter 5.4.3 on page 200 for more details about AsrObjectLinks.
defRef
The getDefRef() method returns the DefRef of the model object.
MIParameterValue param = ...
DefRef defRef = param . defRef
Listing 4.93: Get the DefRef of an Ecuc model instance
The MIParameterValue.setDefRef(DefRef) method sets the definition of this parameter to
the defRef.
MIParameterValue param = ...
DefRef newDefinition = ...
param . defRef = newDefinition
Listing 4.94: Set the DefRef of an Ecuc model instance
If the specified DefRef has a wildcard, the parameter must have a parent to calculate the
absolute definition path - otherwise a ModelCeHasNoParentException will be thrown.
If is has no wildcard and no parent, the absolute definition path of the defRef will be used.
© 2017, Vector Informatik GmbH
88 of 250

---

Chapter 4.
AutomationInterface API Reference
If the parameter has a parent or and parents definition does not match the defRefs parent
definition, this method fails with InconsistentParentDefinitionException.
The MIContainer.setDefRef(DefRef) method sets the definition of this container to the de-
fRef.
See chapter 5.4.4 on page 200 for more details about DefRefs.
ceState
The CeState is an object which aggregates states of a related MDF object. Client
code can e.g. check with the CeState if an Ecuc object has a related pre-configuration value.
The getCeState(MIObject) method returns the CeState of the specified model object.
MIParameterValue param = ...
IParameterStatePublished state = param . ceState
Listing 4.95: Get the CeState of an Ecuc parameter instance
See chapter 5.4.5 on page 203 for more details about the CeState.
ceState - User-defined Flag
The method isUserDefined() returns true, if the ecuc confi-
guration element like parameters is flagged as user-defined.
MIParameterValue param = ...
def flag = param . ceState . u s e r D e f i n e d
Listing 4.96: Retrieve the user-defined flag of an Ecuc parameter in Groovy
The method setUserDefined(boolean) sets or removes the user-defined flag of a ecuc confi-
guration element like parameters.
Note: This method must executed inside a transaction because it modifies the model state.
MIParameterValue param = ...
transaction {
param . ceState . userDefined = true
}
Listing 4.97: Set an Ecuc parameter instance to user defined
EcuConfigurationAccess and EcucDefinitionAccess
The Groovy automation interface also
provides special access methods for Ecuc elements (module configurations, container and para-
meter) to the
• EcuConfigurationAccess (see 5.5.1 on page 205)
• EcucDefinitionAccess (see 5.5.2 on page 210)
The getEcucDefinition() method returns the IEcucDefinition of the model object.
MIParameterValue param = ...
IEcucDefinition definition = param . ecucDefinition
Listing 4.98: Get the IEcucDefinition of an Ecuc model instance
The getEcuConfiguration() method returns the IEcucHasDefinition of the model object.
© 2017, Vector Informatik GmbH
89 of 250

---

Chapter 4.
AutomationInterface API Reference
MIParameterValue param = ...
IEcucHasDefinition cfg = param . ecuConfiguration
Listing 4.99: Get the IEcucHasDefinition of an Ecuc model instance
These methods are the same as for bswmd model objects.
4.6.4.11 Reverse Reference Resolution - ReferencesPointingToMe
You can resolve all references in the MDF model in the reverse direction, so you can start at a
reference target and navigate to all references which point to the reference target.
referencesPointingToMe
The getReferencesPointingToMe() method returns all reference
parameters in the active ecuc pointing to specified target (MIReferrable) object. It returns an
empty collection if the target object is invisible or removed.
The getReferencesPointingToMe(DefRef) method returns all reference parameters in the
active ecuc with the specified definition (DefRef) pointing to the specified target (MIReferrable)
object. It returns an empty collection if the target object is invisible, removed or the specified
definition is null.
List < MIReferenceValue > refs = container . referencesPointingToMe
// Or
DefRef refDefRef = // DefRef to reference parameter
def refByDef = c on ta in er . g e t R e f e r e n c e s P o i n t i n g T o M e ( refDefRef )
Listing 4.100: referencesPointingToMe sample
systemDescriptionObjectsPointingToMe
The method getSystemDescriptionObjectsPoin-
tingToMe() returns all objects located in the system description which are parent objects of
references pointing to the specified target. It returns an empty collection if the object is invisible
or removed.
List < MIObject > references =
systemDescElement . systemDescriptionObjectsPointingToMe
Listing 4.101: systemDescriptionObjectsPointingToMe sample
4.6.4.12 AUTOSAR Root Object
The getAUTOSAR() method returns the AUTOSAR root object (the root object of the MDF
model tree of AUTOSAR data).
MIAUTOSAR root = AUTOSAR
Listing 4.102: Get the AUTOSAR root object
4.6.4.13 ActiveEcuC
The activeEcuc access methods provide access to the module configurations of the Ecuc mo-
del.
© 2017, Vector Informatik GmbH
90 of 250

---

Chapter 4.
AutomationInterface API Reference
// Get the modules as Collection < MIModuleConfiguration >
Collection modules = activeEcuc . allModules
Listing 4.103: Get the active Ecuc and all module configurations
// Iterate over all module configurations
activeEcuc {
int count = 0
allModules . each { moduleCfg ->
count ++
}
a s s e r t count > 1
}
Listing 4.104: Iterate over all module configurations
activeEcuc {
// Parameter type is IActiveEcuc
ecuc ->
def defRef = DefRef . create ( E D e f R e f W i l d c a r d . AUTOSAR , " EcuC " )
// Get the modules as Collection < MIModuleConfiguration >
Collection foundModules = ecuc . modules ( defRef )
a s s e r t ! f o u n d M o d u l e s . empty
}
Listing 4.105: Get module configurations by definition
4.6.4.14 DefRef based Access to Containers and Parameters
The Groovy automation interface for the MDF model provides some overloaded access methods
for
• MIModuleConfiguration.getSubContainer()
• MIContainer.getSubContainer()
• MIContainer.getParameter()
to offer convenient filtering access to the subContainer and parameter child lists.
activeEcuc {
// Parameter type is IActiveEcuc
ecuc ->
def module = ecuc . modules ( EcuC . DefRef ) . first
// Get containers as List < MIContainer >
def c o n t a i n e r s = module . s u b C o n t a i n e r ( E c u c G e n e r a l . DefRef )
// Get parameters as List < MIParameterValue >
def cpuType = co nta in er s . first . parameter ( CPUType . DefRef )
a s s e r t cpuType . size () == 1
}
Listing 4.106: Get subContainers and parameters by definition
© 2017, Vector Informatik GmbH
91 of 250

---

Chapter 4.
AutomationInterface API Reference
4.6.4.15 Ecuc Parameter and Reference Value Access
The Groovy automation interface also provides special access methods for Ecuc parameter
values. These methods are implemented as extensions of the Ecuc parameter and value types
and can therefore be called directly at the parameter or reference instance.
Value Checks
• hasValue(MIParameterValue)
returns true if the parameter (or reference) has a value.
• containsBoolean(MINumericalValue)
returns true if the parameter value contains a valid boolean with the same semantic as
IModelAccess.containsBoolean(MINumericalValue).
Call this method in advance
to guarantee that getAsBoolean(MINumericalValueVariationPoint) doesn’t lead to
errors.
• containsInteger(MINumericalValue)
returns true if the parameter value contains a valid integer with the same semantic as
IModelAccess.containsInteger(MINumericalValue).
Call this method in advance
to guarantee that getAsInteger(MINumericalValueVariationPoint) doesn’t lead to
errors.
• containsDouble(MINumericalValue)
returns true if the parameter value contains a valid double (AUTOSAR float) with the
same semantic as
IModelAccess.containsFloat(MINumericalValue).
Call this method in advance
to guarantee that getAsDouble(MINumericalValueVariationPoint) doesn’t lead to er-
rors.
// MINumericalValue param = ...
if (! param . hasValue () ) {
scriptLogger . warn " The parameter has no value !"
}
if ( param . c o n t a i n s I n t e g e r () ) {
int value = param . value . a sI nt eg er
}
Listing 4.107: Check parameter values
Parameters
• getAsLong(MINumericalValueVariationPoint) returns the value as native long.
Throws NumberFormatException if the value string doesn’t represent an integer value.
Throws ArithmeticException if the value will not exactly fit in a long.
• getAsInteger(MINumericalValueVariationPoint) returns the value as native int.
© 2017, Vector Informatik GmbH
92 of 250

---

Chapter 4.
AutomationInterface API Reference
Throws NumberFormatException if the value string doesn’t represent an integer value.
Throws ArithmeticException if the value will not exactly fit in an int.
• getAsBigInteger(MINumericalValueVariationPoint) returns the value as BigInte-
ger.
Throws NumberFormatException if the value string doesn’t represent an integer value.
• getAsDouble(MINumericalValueVariationPoint) returns the value as Double.
Throws NumberFormatException if the value string doesn’t represent a float value.
• getAsBigDecimal(MINumericalValueVariationPoint) returns the value as BigDeci-
mal.
Note: This method will possibly return MBigDecimal.POSITIVE_INFINITY, MBigDeci-
mal.NEGATIVE_INFINITY or MBigDecimal.NaN.
If it is necessary to do computations with these special numbers,
use getAsDouble(MINumericalValueVariationPoint) instead.
Throws NumberFormatException if the value string doesn’t represent a float value.
• getAsBoolean(MINumericalValueVariationPoint) returns the value as Boolean.
Throws NumberFormatException if the value string doesn’t represent a boolean value.
• asCustomEnum(MITextualValue, Class) returns the value of the enum parameter as a
custom enum literal. If the Class destClass implements the IModelEnum interface, the lite-
rals are mapped via these information form the IModelEnum interface. Read the JavaDoc
of IModelEnum for more details.
// MINumericalValue param = ...
// MINumericalValueVariationPoint is the type of param . value
l o n g lo ng Va lu e = param . value . asLong
a s s e r t l on gV al ue == 10
int intValue = param . value . a sI nt eg er
a s s e r t intValue == 10
BigInteger bigIntValue = param . value . asBigInteger
a s s e r t b i g I n t V a l u e == B i g I n t e g e r . valueOf (10)
Double doubleValue = param . value . asDouble
a s s e r t Math . abs ( doubleValue -10.0) <= 0.0001
Listing 4.108: Get integer parameter value
References
• getAsAsrPath(MIARRef) returns the reference value as AUTOSAR path.
• getAsAsrPath(MIReferenceValue) returns the reference parameters value as AUTOSAR
path.
• getRefTarget(MIReferenceValue) returns the reference parameters target object (the
object referenced by this parameter). It returns null if the target cannot be resolved or
the reference parameter doesn’t contain a value reference.
© 2017, Vector Informatik GmbH
93 of 250

---

Chapter 4.
AutomationInterface API Reference
// MIReferenceValue refParam = ...
def asrPath1 = refParam . a sA sr Pa th
def asrPath2 = refParam . value . a sA sr Pa th
a s s e r t asrPath1 == asrPath2
String pathString = refParam . value . value
a s s e r t asrPath1 . a u t o s a r P a t h S t r i n g == p a t h S t r i n g
def target1 = refParam . re fT ar ge t
def target2 = refParam . value . re fT ar ge t
a s s e r t target1 == target2
Listing 4.109: Get reference parameter value
4.6.5 SystemDescription Access
The systemDescription API provides methods to retrieve system description data like the path
to the flat extract or the flat map instance.
It is grouped by the AUTOSAR version. So the getAutosar4() methods provides access to
AUTOSAR 4 model elements.
The getPaths() provides common paths to elements like:
• FlatMap path
• FlatExtract path
• FlatCompositionType path
AsrPath flatExtractPath = systemDescription . paths . flatExtractPath
AsrPath flatMapPath = systemDescription . paths . flatMapPath
Listing 4.110: Get the FlatExtract and FlatMap paths by the SystemDescription API
systemDescription {
autosar4 {
flatExtract . ifPresent { theFlatExtract ->
// do something with the flatMap
}
}
}
// Or in property style
def t h e F l a t E x t r a c t O p t = s y s t e m D e s c r i p t i o n . autosar4 . f l a t E x t r a c t
if ( t h e F l a t E x t r a c t O p t ) {
def t h e F l a t E x t r a c t = t h e F l a t E x t r a c t O p t . get ()
}
Listing 4.111: Get FlatExtract instance by the SystemDescription API
© 2017, Vector Informatik GmbH
94 of 250

---

Chapter 4.
AutomationInterface API Reference
4.6.6 Transactions
Model changes must always be executed within a transaction. The automation API provides
some simple means to execute transactions.
For details about transactions read 5.1.7 on page 177.
scriptTask (" TaskName ", DV_PROJECT ){
code {
transaction {
// Your transaction code here
}
}
}
Listing 4.112: Execute a transaction
scriptTask (" TaskName ", DV_PROJECT ){
code {
transaction (" Transaction name ") {
// The transactionName property is available inside a transaction
String name = transactionName
}
}
}
Listing 4.113: Execute a transaction with a name
The transaction name has no additional semantic. It is only be used for logging and to improve
error messages.
Nested Transactions
If you open a transaction inside of a transaction the inner transaction is
ignored and it is as no transaction call was done. So be aware that nested transactions are no
real transaction, which leads to the fact the these nested transactions can not be undone.
If you want to know whether a transaction is already running, see the transactions API be-
low.
4.6.6.1 Transactions API
The Transactions API with the keyword transactions provides access to running transactions
or the transaction history.
You can use method isTransactionRunning() to check if a transaction is currently running.
The method returns true, if a transaction is running in the current Thread.
© 2017, Vector Informatik GmbH
95 of 250

---

Chapter 4.
AutomationInterface API Reference
scriptTask (" TaskName ", DV_PROJECT ){
code {
// Switch to the transactions API
transactions {
// Check if a transaction is running
a s s e r t
isTransactionRunning () == false
// Open a transaction
transaction {
// Now a transaction is running
a s s e r t
isTransactionRunning () == true
}
}
// Or the short form
transactions . isTransactionRunning ()
}
}
Listing 4.114: Check if a transaction is running
TransactionHistory
The transaction history API provides some methods to handle transaction
undo and redo. This way, complex model changes can be reverted quite easily.
• The undo() method executes an undo of the last transaction. If the last transaction frame
cannot be undone or if the undo stack is empty this method returns without any changes.
• The undoAll() method executes undo until the transaction stack is empty or an undoable
transaction frame appears on the stack.
• The redo() method executes an redo of the last undone transaction. If the last undone
transaction frame cannot be redone or if the redo stack is empty this method returns
without any changes.
• The canUndo() method returns true if the undo stack is not empty and the next undo
frame can be undone. This method changes nothing but you can call it to find out if the
next undo() call would actually undo something.
• The canRedo() method returns true if the redo stack is not empty and the next redo
frame can be redone. This method changes nothing but you can call it to find out if the
next redo() call would actually redo something.
scriptTask (" TaskName ", DV_PROJECT ){
code {
transaction (" TransactionName ") {
// Your transaction code here
}
transactions {
a s s e r t
transactionHistory . canUndo ()
transactionHistory . undo ()
a s s e r t ! t r a n s a c t i o n H i s t o r y . canUndo ()
}
}
}
Listing 4.115: Undo a transaction with the transactionHistory
© 2017, Vector Informatik GmbH
96 of 250

---

Chapter 4.
AutomationInterface API Reference
scriptTask (" TaskName ", DV_PROJECT ){
code {
transaction (" TransactionName ") {
// Your transaction code here
}
transactions {
transactionHistory . undo ()
a s s e r t
transactionHistory . canRedo ()
transactionHistory . redo ()
a s s e r t ! t r a n s a c t i o n H i s t o r y . canRedo ()
}
}
}
Listing 4.116: Redo a transaction with the transactionHistory
4.6.6.2 Operations
The model operations implement convenient means to execute complex model changes like
AUTOSAR module activation or cloning complete model sub-trees. The operations API is
available inside of a transaction with the keyword operation. The class IOperations defines
the available methods.
• The method activateModuleConfiguration(DefRef) activates the specified module con-
figuration. This covers:
– Creation of the module including the reference in the ActiveEcuC (the ECUC-VALUE-
COLLECTION)
– Creation of mandatory containers and parameters (lower multiplicity > 0)
– Applying the recommended configuration
– Applying the pre-configuration values
Note: If the DefRef has a wildcard, activateModuleConfiguration(DefRef) tries to
activate the most specific module definition matching the wildcard, if unique. If it is not
unique the method will throw an exception. For example the DefRef /[ANY]/Dio will
activate the /MICROSAR/Dio instead of /AUTOSAR/EcucDefs/Dio.
transaction {
// Activates the Dio module
operations . activateModuleConfiguration ( sipDefRef . Dio )
}
Listing 4.117: Activation of the ModuleConfiguration Dio
• The method deactivateModuleConfiguration(MIModuleConfiguration) deletes the
specified module configuration from the model. In case of a split configuration, the re-
lated persistency location is being removed from the project settings. In XML file base
configurations, the related file is being deleted during the next project save if it doesn’t
contain configuration objects anymore.
© 2017, Vector Informatik GmbH
97 of 250

---

Chapter 4.
AutomationInterface API Reference
If the module configuration is referenced from the active-ECUC this link is being removed
too.
• The method changeBswImplementation(MIModuleConfiguration, MIBswImplementa-
tion) changes the BSW-implementation of a module configuration including the definition
of all contained containers and parameters.
• The deepClone(MIObject, MIObject) operation copies (clones) a complete MDF model
sub-tree and adds it as child below the specified parent.
– The source object must have a parent. The clone will be added to the same MDF
feature below the destination parent then
– AUTOSAR UUIDs will not be cloned. The clone will contain new UUIDs to gua-
rantee unambiguousness
• The method createModelObject(Class) creates a new element of the passed modelClass
(meta class). The modelObject must be added to the whole AUTOSAR model, before
finishing the transaction.
• setConfigurationVariantOfAllModuleConfigurations(EEcucConfigurationVariant)
sets the implementation configuration variant of all active MIModuleConfiguration. If a
module configuration does not support the requested variant it is ignored.
Supported enum values are:
– com.vector.cfg.model.access.ecuconfiguration.EEcucConfigurationVariant
∗ VARIANT_PRE_COMPILE
∗ VARIANT_LINK_TIME
∗ VARIANT_POST_BUILD_LOADABLE
This is for post-build loadable only! See the method setConfigurationVariant() in class
IEcucModuleConfiguration for details.
• The method createUniqueMappedAutosarPackage() can be used to create new MIAR-
Packages in new arxml files.
It creates an new instance of the specified AUTOSAR
package and adds it to the model tree. All non-existing parent packages will be created
too.
The new package (including new created parent packages) will be mapped uniquely to
the specified location (Path and AUTOSAR version).
4.6.7 Model Synchronization
The Model synchronization provides operation to solve and synchronize common model rela-
ted items. The model synchronization API is available inside of an active project with the
keyword modelSynchronization. The class IModelSynchronizationApi defines the available
methods.
The method synchronize() synchronizes the model for all registered model synchronization
elements like validations and other operations. The method will open a transaction, if isSyn-
chronizationRequired() returns true, otherwise this method does nothing.
© 2017, Vector Informatik GmbH
98 of 250

---

Chapter 4.
AutomationInterface API Reference
// Execute the model synchronization
modelSynchronization . synchronize ()
// Or more elaborated , but means the same
modelSynchronization {
if ( s y n c h r o n i z a t i o n R e q u i r e d ) {
synchronize ()
}
}
Listing 4.118: Model synchronization inside an open project
4.6.8 Post-build selectable Variance
The variance access API is the entry point for convenient access to variant AUTOSAR mo-
del content.
It provides means to filter variant model content and access variant specific
data.
For details about post-build selectable variance and model views read 5.2 on page 179.
4.6.8.1 Investigate Project Variance
The projects variance can be analyzed using the variance keyword. These methods can be
called then:
• The method hasPostBuildVariance() returns true if the active project contains post-
build variants.
• The method getInvariantValuesView() returns the invariant values view.
• The method getInvariantEcucDefView() returns the invariant Ecuc definition view.
• The method getCurrentlyActiveView() returns the currently active model view.
• The method getAllVariantViews() returns all available variant model views (one IPrede-
finedVariantView per predefined variant).
• The method variantView(String) returns the IPredefinedVariantView with the given
name.
scriptTask (" TaskName ", DV_PROJECT ){
code {// Activates the DoorLeftFront variant
variance . variantView (" DoorLeftFront "). activeWith {
// Now all MDF model accesses are executed in the variant "
DoorLeftFront "
}
}
}
Listing 4.119: Retrieve and use a variant view by name
• The method getAllVariantViewsOrInvariant() returns the same as the method ge-
tAllVariantViews() if the project contains variants. If the project contains no variants
(see hasPostBuildVariance()) the method returns a list containing only the IInvari-
antView.
© 2017, Vector Informatik GmbH
99 of 250

---

Chapter 4.
AutomationInterface API Reference
This helps to create code working with both variant and non-variant projects.
scriptTask (" TaskName ", DV_PROJECT ){
code {
def a c t i v e V i e w 1 = variance . c u r r e n t l y A c t i v e V i e w
a s s e r t a c t i v e V i e w 1 i n s t a n c e o f I I n v a r i a n t V a l u e s V i e w
// ... or with a closure
variance {
def a c t i v e V i e w 2 = c u r r e n t l y A c t i v e V i e w
a s s e r t a c t i v e V i e w 1 == a c t i v e V i e w 2
a s s e r t a c t i v e V i e w 1 == i n v a r i a n t V a l u e s V i e w
// Get number of variants
int num = a l l V a r i a n t V i e w s . size ()
a s s e r t num == 4
}
}
}
Listing 4.120: The default view is the IInvariantValuesView
4.6.8.2 Variant Model Objects
The following model object extensions provide convenient means to investigate model object
variance in detail.
• The method activeWith(IModelView, Closure) executes code under visibility of the
specified model view.
• The method isModelInvariant(MIObject) returns true if the object and all its parents
has no variation point conditions. If this is true, this model object instance is visible in
all variant views.
• The method isValueInvariant(MIObject) returns true if the object has the same value
in all variants.
For details about invariant views see 5.2.1.4 on page 182.
• The method isEcucDefInvariant(MIObject) returns true if the object is invariant ac-
cording to its EcuC definition.
See IInvariantEcucDefView for more details to the concept.
• The method isVisible(MIObject) returns true if the object is visible in the current
model view.
• The method isVisibleInModelView(MIObject, IModelView) returns true if the object
is visible in the specified model view.
• The method isNeverVisible(MIObject) returns true if the object is invisible in all
variant views.
• The method getVisibleVariantViews(MIObject) returns all variant views the specified
object is visible in.
• The method getVisibleVariantViewsOrInvariant(MIObject) For semantic details see
IModelViewManager.getVisibleVariantViewsOrInvariant(MIObject).
© 2017, Vector Informatik GmbH
100 of 250

---

Chapter 4.
AutomationInterface API Reference
• The method asViewedModelObject(MIObject) returns a new IViewedModelObject in-
stance using the currently active view.
• The method getVariantSiblings(MIObject) returns MDF object instances representing
the same object but in all variants.
For details about the sibling semantic see 5.2.1.3 on page 181.
• The method getVariantSiblingsWithoutMyself(MIObject) returns the same collection
as getVariantSiblings(MIObject) but without the specified object.
// IPredefinedVariantView viewDoorLeftFront = ...
// MIParameterValue variantParameter = ...
viewDoorLeftFront . activeWith {
a s s e r t variance . c u r r e n t l y A c t i v e V i e w == v i e w D o o r L e f t F r o n t
// The parameter instance is not visible in all variants ...
a s s e r t ! v a r i a n t P a r a m e t e r . i s M o d e l I n v a r i a n t ()
// ... but all variants have a sibling with the same value
a s s e r t
variantParameter . isValueInvariant ()
}
Listing 4.121: Execute code in a model view
© 2017, Vector Informatik GmbH
101 of 250

---

Chapter 4.
AutomationInterface API Reference
4.6.9 Additional Model API
4.6.9.1 User Annotations
In DaVinci Configurator the user can add AUTOSAR annotations to configuration elements.
You can create, modify, read and delete these annotations like in the UI editors.
All sub types of MIHasAnnotation elements support annotations like:
• MIModuleConfigurations
• MIContainers
• MIParameterValues
• MIIdentifiables
Although annotations are stored in the data model, their changeable state is independent of
the configuration element changeable state. Annotations can be added/changed/deleted on
every existing configuration element with valid definition, except the project was opened in
read-only mode.
The IUserAnnotation interface provide methods like:
• getLabel() - Returns the label of the annotation, like getName() of a container
• setLabel() - Changes the label
• getText() - Returns the text of the annotation.
• setText() - Changes the text
• isChangeable() - Returns true, if the annotation is changeable
• moRemove() - Deletes the annotation
Access User Annotations
The getUserAnnotations(MIARObject) method returns the IU-
serAnnotations for the model element. The returned list provides additional methods defined
in IUserAnnotationList.
// We already have the container " cont " or any other model element
def m y C o n t a i n e r = cont
def annos = m y C o n t a i n e r . u s e r A n n o t a t i o n s // Retrieve the list of a n n o t a t i o n s
def anno = annos . byLabel ( " MyLabel " )
// Select the annotation with " MyLabel "
def text = anno . text
// Get the Text
// Or short
text = myContainer . userAnnotations [" MyLabel "]. text
Listing 4.122: Get a UserAnnotation of a container
Creation and Modification of User Annotations
You can create new User Annotations with
the methods:
• createAndAdd(label)
• byLabelOrCreate(label)
© 2017, Vector Informatik GmbH
102 of 250

---

Chapter 4.
AutomationInterface API Reference
transaction {
// We already have the container " cont "
def anno = cont . u s e r A n n o t a t i o n s . c r e a t e A n d A d d ( " MyAnno " )
anno . text = "My Text "
}
Listing 4.123: Create a new UserAnnotation
transaction {
// We already have the container " cont "
def anno = cont . u s e r A n n o t a t i o n s . b y L a b e l O r C r e a t e ( " MyAnno " )
anno . text = "My Text "
}
Listing 4.124: Create or get the existing UserAnnotation by label name
Notes
The IUserAnnotationList is not updated, when the underlying model changes. You
have to retrieve a new instance of IUserAnnotationList to reflect changes.
The IUserAnnotationList is read only list and does not permit any modify operations defi-
ned in java.util.List, but certain operations like createAndAdd(String) will affect the list
content. If you delete a contained IUserAnnotation the list will not be updated.
© 2017, Vector Informatik GmbH
103 of 250

---

Chapter 4.
AutomationInterface API Reference
4.7 Generation
The Automation Interface provides generation API for different generation use cases:
• Normal code generation, see 4.7.1
– Including external generation steps
• SWC Templates and Contract Phase Headers generation, see 4.7.3 on page 111
4.7.1 Code Generation
The block generation encapsulates all settings and commands which are related to code ge-
neration of BSW modules:
The basic structure is the following:
generation {
settings {
// Settings like the selection of generators for execution are done
here
externalGenerationSteps {
// Settings related to externalGenerationSteps can be done here
}
}
// The execution of the generation or validation can be started here
}
Listing 4.125: Basic structure
4.7.1.1 Generation Settings
The class IGenerationSettingsApi encapsulates all settings which belong to a generation
process.
E.g.
• Select the generators to execute
• Select the target type (Real, VTT)
• Select the external generation steps
• If the module supports multiple module configurations, select the configurations which
shall be generated
The following chapters show samples for the standard use cases.
Generation with default Project Settings
The following snippet executes a validation with
the default project settings.
© 2017, Vector Informatik GmbH
104 of 250

---

Chapter 4.
AutomationInterface API Reference
scriptTask (" validate_with_default_settings "){
code {generation{
validate ()
}
}
}
Listing 4.126: Validate with default project settings
To execute a generation with the standard project settings the following snippet can be used.
The validation is executed implicitly before the generation because of AUTOSAR require-
ments.
scriptTask (" generate_with_default_settings "){
code {generation{
generate ()
}
}
}
Listing 4.127: Generate with standard project settings
Generation of one Module
This sample selects one specific module and starts the generation.
There are two ways to open an settings block:
• settings
– This keyword creates empty settings. E.g. no module is selected for execution.
• settingsFromProject
– This keyword takes the project settings as template. E.g. modules from the project
settings are initially activated and can optionally be refined by explicit selections.
scriptTask (" generate_one_module "){
code {generation{
settings {
// To take the project settings as template use
// settingsFromProject {
selectGeneratorsByDefRef ("/ MICROSAR / Aaa ")
}generate()
}
}
}
Listing 4.128: Generate one module
Instead of selecting the generator directly by its DefRef, there is also the possibility to fetch
the generator object and select this object for execution.
© 2017, Vector Informatik GmbH
105 of 250

---

Chapter 4.
AutomationInterface API Reference
scriptTask (" generate_one_module "){
code {generation{
settings {
// To take the project settings as template use
// settingsFromProject {
def gens = g e n e r a t o r B y D e f R e f ( " / MICROSAR / Aaa " )
selectGenerators ( gens )
}generate()
}
}
}
Listing 4.129: Generate one module
Generation of multiple Modules
To select more than one generator the following snippet can
be used.
scriptTask (" generate_two_modules "){
code {generation{
settings {
selectGeneratorsByDefRef ("/ MICROSAR / Aaa ", "/ MICROSAR / Bbb ")
}generate()
}
}
}
Listing 4.130: Generate two modules
Generation of Multi Instance Modules
Some module definitions have a upper multiplicity
greater than one. (E.g. [0:5] or [0:*]) This means it is allowed to create more than one module
configuration from this module definition. If the related generator is started with the default
API, all available module configurations are selected for generation. The following API can be
used to generate only a subset of all related module configurations.
© 2017, Vector Informatik GmbH
106 of 250

---

Chapter 4.
AutomationInterface API Reference
scriptTask (" generate_one_module_with_two_configs "){
code {generation{
settings {
def gen = g e n e r a t o r B y D e f R e f ( " / MICROSAR / M u l t i I n s t M o d u l e " )
// clear default selection
gen . deselectAllModuleInstances ()
// Select the module configurations to generate
gen . selectModuleInstance ( AsrPath . create ("/ ActiveEcuC /
MultiInstModule1 "))
// Instead of the full qualified path , the module configuration
short name can also be used
gen . selectModuleInstance (" MultiInstModule2 ")
}generate()
}
}
}
Listing 4.131: Generate one module with two configurations
4.7.1.2 Generation of External Generation Step
Besides the internal generators, which are covered by the topics above, there are also external
generation steps which can be executed with the following API. A new block externalGenera-
tionSteps within the settings block encapsulates all settings related to external generation
scripts.
scriptTask (" generate_ext_gen_step "){
code {generation{
settings {
externalGenerationSteps {
// To take the project settings as template use
// externalGenerationStepsFromProject {}
selectStep (" ExtGen1 ")
selectStep (" ExtGen2 ")
}
}generate()
}
}
}
Listing 4.132: Execute an external generation step
4.7.1.3 Evaluate generation or validation results
Each validation and generation process has an overall result which states if the execution has
been successfully or not. Additionally to the overall state, the state of one specific generator can
also be of interest. To provide a possibility to access this information all methods for validate
and generate return an IGenerationResultModel.
© 2017, Vector Informatik GmbH
107 of 250

---

Chapter 4.
AutomationInterface API Reference
scriptTask (" generate_with_default_settings "){
code {generation{
def result = generate ()
println " Overall result : " + result . result
println " Duration
: " + result . formattedDuration
// Access results of each generator or generation step
result . generationResultRoot . allGeneratorAndStepElements . each {
println " Generator name : " + it. name
println " Result
: " + it. currentState
}
}
}
}
Listing 4.133: Evaluate the generation result
© 2017, Vector Informatik GmbH
108 of 250

---

Chapter 4.
AutomationInterface API Reference
4.7.2 Generation Task Types
There are three types of IScriptTaskTypesfor the generation process:
• Generation Step: DV_GENERATION_STEP
• Custom Workflow Step: DV_CUSTOM_WORKFLOW_STEP
• Generation Process Start: DV_ON_GENERATION_START
• Generation Process End: DV_ON_GENERATION_END
The general description of the type is in chapter 4.3.1.4 on page 31. The following code samples
show the usage of these task types:
Generation Step
A sample for the DV_GENERATION_STEP type:
scriptTask (" GenStepTask ", DV_GENERATION_STEP ){
taskDescription " Task is executed as Generation Step "
def myArg = n e w U s e r D e f i n e d A r g u m e n t (
" myArgument ",
String ,
" Defines a user argument for the GenerationStep ")
code { phase , generationType , resultSink ->
def myArgVal = myArg . value
// The value myArgVal was passed from the generation step in the
project settings editor
scriptLogger . info " MyArg is: $myArgVal "
scriptLogger . info " GenerationType is: $generationType "
if ( phase . c a l c u l a t i o n ) {
// Execute code before / after calculation
transaction {
// Modify the Model in the calculation phase
}
}
if ( phase . v a l i d a t i o n ) {
// Execute code before / after validation
}
if ( phase . g e n e r a t i o n ) {
// Execute code before / after generation
}
}
}
Listing 4.134: Use a script task as generation step during generation
The Generation Step can also report validation results into the passed resultSink. See chap-
ter 4.8.5.10 on page 124 for a sample how to create an validation-result and report it.
The generationType defines if the current generation is for the REAL or VTT platform.
© 2017, Vector Informatik GmbH
109 of 250

---

Chapter 4.
AutomationInterface API Reference
Custom Workflow Step
A sample for the DV_CUSTOM_WORKFLOW_STEP type:
scriptTask (" GenStepTask ", DV_CUSTOM_WORKFLOW_STEP ){
taskDescription " Task is executed as custom workflow step "
def myArg = n e w U s e r D e f i n e d A r g u m e n t (
" myArgument ",
String ,
" User argument for the step ")
code {
def myArgVal = myArg . value
// The value myArgVal was passed from the custom workflow step in the
project settings editor
scriptLogger . info " MyArg is: $myArgVal "
}
}
Listing 4.135: Use a script task as custom workflow step
Generation Process Start
A sample for the DV_ON_GENERATION_START type:
scriptTask (" GenStartTask ", DV_ON_GENERATION_START ){
taskDescription " The task is automatically executed at generation start "
code { phasesToExecute , generators ->
scriptLogger . info " Phases are : $phasesToExecute "
scriptLogger . info " Generators to execute are : $generators "
// Execute code before the generation will start
}
}
Listing 4.136: Hook into the GenerationProcess at the start with script task
Generation Process End
A sample for the DV_ON_GENERATION_END type:
scriptTask (" GenEndTask ", DV_ON_GENERATION_END ){
taskDescription " The task is automatically executed at generation end "
code { generationResult , generators ->
scriptLogger . info " Process result was : $generationResult "
scriptLogger . info " Executed Generators : $generators "
// Execute code after the generation process was finished
}
}
Listing 4.137: Hook into the GenerationProcess at the end with script task
© 2017, Vector Informatik GmbH
110 of 250

---

Chapter 4.
AutomationInterface API Reference
4.7.3 Software Component Templates and Contract Phase Headers Generation
The Software Component Templates and Contract Phase Headers (Swct) generation automation
API provides access to configure and start the Swct generation.
The block generation.swct encapsulates all settings and commands which are related to this
use case.
The basic structure is the following:
generation . swct {
settings {
// Settings like the selection of components to generate
}
// The execution of the generation can be started here
generate ()
}
Listing 4.138: Basic Swct structure
4.7.3.1 Swct Generation Settings
The class IGenerationSwctSettingsApi encapsulates all settings which belong to a Swct ge-
neration process.
Examples:
• Select the software components to execute
• Retrieve the available software components
The following chapters show samples for the standard use cases.
4.7.3.2 Generation with default Project Settings
To execute the Swct generation with the standard project settings the following snippet can be
used:
scriptTask (" generate_with_default_settings "){
code {generation.swct{
generate ()
}
}
}
Listing 4.139: SWC Templates and Contract Headers generation with standard project settings
4.7.3.3 Generation of all Software Components
To execute the Swct generation for all available software components the following snippet can
be used:
© 2017, Vector Informatik GmbH
111 of 250

---

Chapter 4.
AutomationInterface API Reference
scriptTask (" generate_with_default_settings "){
code {generation.swct{
settings . selectAll ()
generate ()
}
}
}
Listing 4.140: SWC Templates and Contract Headers generation of all components
4.7.3.4 Generation of one Software Component
This sample selects one specific software component and starts the generation. There are two
ways to open an settings block:
• settings
– This keyword creates empty settings. E.g. no component is selected for execution.
• settingsFromProject
– This keyword takes the project settings as template. E.g. component from the pro-
ject settings are initially activated and can optionally be refined by explicit selections.
scriptTask (" generate_one_component "){
code {generation.swct{
settings {
selectSoftwareComponent (" MyApplType ")
}
generate ()
}
}
}
Listing 4.141: SWC Templates and Contract Headers generation of one selected component
Instead of selecting the software component directly by its Name, there is also the possibility to
fetch the software component object and select() this object for execution.
scriptTask (" generate_one_component "){ code {
generation . swct {
settings {
def sw = s o f t w a r e C o m p o n e n t B y N a m e ( " M y App l T yp e " )
// Select the software component
sw. select ()
// You could also retrieve information about the component
def asrPath = sw . asrPath
if ( sw . selected ) {
/* Do something */ }
}generate()
}
}}
Listing 4.142: Swct generation get component and select component
© 2017, Vector Informatik GmbH
112 of 250

---

Chapter 4.
AutomationInterface API Reference
4.7.3.5 Generation of multiple Software Components
To select more than one Software Component the following snippet can be used.
scriptTask (" generate_one_component "){
code {generation.swct{
settings {
// Select the tow software components
selectSoftwareComponent (" MyApplType "," MySecondApplType ")
}
generate ()
}
}
}
Listing 4.143: Swct generation of multiple components
4.7.3.6 Evaluate generation results
The same API is used as for the normal generation, see chapter 4.7.1.3 on page 107 for de-
tails.
© 2017, Vector Informatik GmbH
113 of 250

---

Chapter 4.
AutomationInterface API Reference
4.8 Validation
4.8.1 Introduction
All examples in this chapter are based on the situation of the figure 4.6. The module and the
validators are not from the real MICROSAR stack, but just for the examples. There is a module
Tp that has 3 Buffer containers and each Buffer has a Size parameter with value=3.
There is also a validator that requires the Size parameter to be a multiple of 4. For each Size
parameter that violates this constraint, a validation-result with ID Tp00012 is created.
Such a validation-result has 2 solving-actions. One that sets the Size to the next smaller valid
value, and one that sets the Size to the next bigger valid value. The letter solving-action is
marked as preferred-solving-action.
There is also a Tp00011 result that stands for any other result. The examples will not touch
it.
Figure 4.6: example situation with the GUI
4.8.2 Access Validation-Results
A validation{} block gives access to the validation API of the consistency component. That
means accessing the validation-results which are shown in the GUI in the validation view,
and solving them by executing solving-actions which are also shown in the GUI beneath each
validation-result (with a bulb icon).
getValidationResults() waits for background-validation-idle and returns all validation-results
© 2017, Vector Informatik GmbH
114 of 250

---

Chapter 4.
AutomationInterface API Reference
of any kind. The returned collection has no deterministic order, especially it is not the same
order as in the GUI.
scriptTask (" CheckValidationResults_filterByOriginId ", DV_PROJECT ){
code {validation{
// access all validation - results
def a l l R e s u l t s = v a l i d a t i o n R e s u l t s
a s s e r t a l l R e s u l t s . size () > 3
// filter based on methods of IValidationResultUI e.g. isId ()
def t p 1 2 R e s u l t s = v a l i d a t i o n R e s u l t s . filter { it . isId ( " Tp " , 12) }
a s s e r t t p 1 2 R e s u l t s . size () == 3
}
// alternative access to validation - results without a validation block
a s s e r t v a l i d a t i o n . v a l i d a t i o n R e s u l t s . size () > 3
}
}
Listing 4.144: Access all validation-results and filter them by ID
4.8.3 Model Transaction and Validation-Result Invalidation
Before we continue in this chapter with solving validation-results, the following information is
import to know:
Relation to model transactions:
Solving validation-results with solving-actions always creates a transaction implicitly.
An
IllegalStateException will be thrown if this is done within an explicitly opened tran-
saction.
Invalidation of validation-results:
Any model modification may invalidate any validation-result. In that case, the responsible
validator creates a new validation-result if the inconsistency still exists. Whether this happens
for a particular modification/validation-result depends on the validator implementation and is
not visible to the user/client.
Trying to solve an invalidated validation-result will throw an IllegalStateException. The-
refore it is not safe to solve a particular ISolvingActionUI that was fetched before the last
transaction. Instead, please fetch a solving-action after the last transaction, or use the method
ISolver.solve(Closure) which is the most preferred way of solving validation-results with
solving-actions.
See chapter 4.8.4.1 on the following page for details.
4.8.4 Solve Validation-Results with Solving-Actions
A single validation-result can be solved by calling solve() on one of its solving-actions.
© 2017, Vector Informatik GmbH
115 of 250

---

Chapter 4.
AutomationInterface API Reference
scriptTask (" SolveSingleResultWithSolvingAction ", DV_PROJECT ){
code {validation{
def t p 1 2 R e s u l t s = v a l i d a t i o n R e s u l t s . filter { it . isId ( " Tp " , 12) }
a s s e r t t p 1 2 R e s u l t s . size () == 3
// Take first ( any ) validation - result and filter its solving -
actions based on methods of ISolvingActionUI
tp12Results . first . solvingActions . filter {
it. description . contains (" next bigger valid value ")
}. single . solve () // reduce the collection to a single
ISolvingActionUI and call solve ()
a s s e r t
validationResults . filter {it. isId ("Tp", 12) }. size () == 2
// One Tp12 validation - result solved
}
}
}
Listing 4.145: Solve a single validation-result with a particular solving-action
4.8.4.1 Solver API
getSolver() gives access to the ISolver API, which has advanced methods for bulk soluti-
ons.
ISolver.solve(Closure) allows to solve multiple validation-results within one transaction.
You should always use this method to solve multiple validation-results at once instead of calling
ISolvingActionUI.solve() in a loop. This is very important, because solving one validation-
result, may cause invalidation of another one. And calling ISolvingActionUI.solve() of an
invalidated validation-result throws an IllegalStateException. Also, invalidated validation-
results may get recalculated and you would miss the recalculated validation-results with the
loop approach. But with ISolver.solve(Closure) you can solve invalidated->recalculated
results as well as results which didn’t exist at the time of the call (but have been caused by
solving some other validation-result).
ISolver.solve(Closure) first waits for background-validation-idle in order to have reprodu-
cible results.
The closure may contain multiple statements like:
result { specify result predicate }. withAction { select solving action }
All statements together will be used as a mapper from any solvable validation-result to a
particular solving-action.
The order of these statements does not affect the solving action
execution order. The statement order might only be relevant if multiple statements match on
a particular result, but would select a different solving-action. In that case, the first statement
that successfully selects a solving-action wins.
© 2017, Vector Informatik GmbH
116 of 250

---

Chapter 4.
AutomationInterface API Reference
scriptTask (" SolveMultipleResults ", DV_PROJECT ){
code {
validation {
a s s e r t
validationResults . size () == 4
solver . solve {
// Call result () and pass a closure that works as filter
// based on methods of IValidationResultUI .
result {
isId ("Tp", 12)
}. withAction {
containsString (" next bigger valid value ")
}
// On the return value , call withAction () and pass a closure that
// selects a solving - action based on methods
// of IValidationResultForSolvingActionSelect
// multiple result () calls can be placed in one solve () call .
result { isId (" Com ", 34) }. withAction { containsString (" recalculate ")}
}
a s s e r t
validationResults . size () == 1
// Three Tp12 and zero Com34 ( didn 't exist ) results solved . One other
left
}}}
Listing 4.146: Fast solve multiple results within one transaction
Solve all PreferredSolvingActions
ISolver.solveAllWithPreferredSolvingAction() sol-
ves all validation-results with its preferred solving- action of each validation-result (solving-
action return by IValidationResultUI.getPreferredSolvingAction()). Validation-results
without a preferred solving-action are skipped.
This method first waits for background-validation-idle in order to have reproducible results.
scriptTask (" SolveAllWithPreferred ", DV_PROJECT ){
code {
validation {
a s s e r t
validationResults . size () == 4
solver . solveAllWithPreferredSolvingAction ()
a s s e r t
validationResults . size () == 1
// this would do the same
transactions . transactionHistory . undo ()
a s s e r t
validationResults . size () == 4
solver . solve {
result { true }. withAction { preferred }
}
a s s e r t
validationResults . size () == 1
}}}
Listing 4.147: Solve all validation-results with its preferred solving-action (if available)
© 2017, Vector Informatik GmbH
117 of 250

---

Chapter 4.
AutomationInterface API Reference
4.8.5 Advanced Topics
4.8.5.1 Access Validation-Results of a Model Object
You can retrieve validation-results also from any model object (MDF, Domain or BswmdMo-
del).
MIObject.getValidationResults() returns the validation-results of an MIObject. These are
those results for which IValidationResultUI.matchErroneousCE(MIObject) returns true.
scriptTask (" CheckValidationResultsOfObject ", DV_PROJECT ){
code {// sampleDefRefs contains DefRef constants just for this example.
Please use the real DefRefs from your SIP
// a Buffer container
def bu ff er 00 2 = mdfModel ( AsrPath . create ( " / A cti ve Ec u C / Tp / B uff er _0 02 " ) )
// the Size parameter
def si ze Pa ra m = b uf fe r0 02 . p ar am et er ( s a m p l e D e f R e f s . t p B u f f e r S i z e D e f R e f ) .
single
// the result exists for the Size parameter , not for the Buffer
container
a s s e r t s iz eP ar am . v a l i d a t i o n R e s u l t s . size () == 1
a s s e r t b uf fe r0 02 . v a l i d a t i o n R e s u l t s . size () == 0
}
}
Listing 4.148: Access all validation-results of a particular object
MIObject.getValidationResultsRecursive() returns the validation-results of an MIObject
and all its children. So this will return all results of the whole subtree, like an editor displays
results at parent objects.
IViewedModelObject.getValidationResults() returns the validation-results for the element
matching the model object and the model view, like BswmdModel objects.
IViewedModelObject.getValidationResultsRecursive() returns the validation-results of an
MIObject for the elements like BswmdModel objects all its children. This will also filter for the
correct IModelView. So this will return all results of the whole subtree, like an editor displays
results at parent objects.
4.8.5.2 Access Validation-Results of a DefRef
DefRef.getValidationResults() returns all validation-results which match the passed defi-
nition. So every configuration element which matches the validation-result and is an instance
of definition.
The used project for this call is the active project, see ScriptApi.getActiveProject().
© 2017, Vector Informatik GmbH
118 of 250

---

Chapter 4.
AutomationInterface API Reference
scriptTask (" CheckValidationResultsOfDefRef ", DV_PROJECT ){
code {// sampleDefRefs contains DefRef constants just for this example.
Please use the real DefRefs from your SIP
a s s e r t
sampleDefRefs . tpBufferSizeDefRef . validationResults . size () == 3
}
}
Listing 4.149: Access all validation-results of a particular DefRef
4.8.5.3 Filter Validation-Results using an ID Constant
Groovy allows you to spread list elements as method arguments using the spread operator. This
allows you to define constants for the isId(String,int) method.
scriptTask (" FilterResultsUsingAnIdConstant2 ", DV_PROJECT ){
code {validation{
def t p1 2C on st = [ " Tp " ,12]
a s s e r t
validationResults . size () > 3
a s s e r t
validationResults . filter {it. isId (* tp12Const )}. size () == 3
}
}
}
Listing 4.150: Filter validation-results using an ID constant
4.8.5.4 Identification of a Particular Solving-Action
A so called solving-action-group-ID identifies a solving-action uniquely within one validation-
result. In other words, two solving-actions, which do semantically the same, from two validation-
results of the same result-ID (origin + number), belong to the same solving-action-group. This
semantical group may have an optional solving-action-group-ID, that can be used for solving-
action identification within one validation-result.
Keep in mind that the solving-action-group-ID is only unique within one validation-result-ID,
and that the group-ID assignment is optional for a validator implementation.
In order to find out the solving-action-group-IDs, press CTRL+SHIFT+F9 with a selected validation-
result to copy detailed information about that result including solving-action-group-IDs (if as-
signed) to the clipboard.
If group-IDs are assigned, it is much safer to use these for solving-action identification than
description-text matching, because a description-text may change.
© 2017, Vector Informatik GmbH
119 of 250

---

Chapter 4.
AutomationInterface API Reference
f i n a l int S A _ G R O U P _ I D _ T P 1 2 _ N E X T _ B I G G E R _ V A L I D _ V A L U E = 2
scriptTask (" SolveMultipleResultsByGroupId ", DV_PROJECT ){
code {
validation {
a s s e r t
validationResults . size () == 4
solver . solve {
result { isId ("Tp", 12) }
. withAction {
byGroupId ( SA_GROUP_ID_TP12_NEXT_BIGGER_VALID_VALUE )
}
// instead of . withAction { containsString (" next bigger valid value ")}
}
a s s e r t
validationResults . size () == 1
// Three Tp12 validation - results solved .
}
}
}
Listing 4.151: Fast solve multiple validation-results within one transaction using a solving-
action-group-ID
4.8.5.5 Validation-Result Description as MixedText
IValidationResultUI.getDescription() returns an IMixedText that describes the inconsis-
tency.
IMixedText is a construct that represents a text, whereby parts of that text can also hold the
object which they represent. This allows a consumer e.g. a GUI to make the object-parts of
the text clickable and to reformat these object-parts as wanted.
Consumers which don’t need these advanced features can just call IMixedText.toString()
which returns a default format of the text.
4.8.5.6 Further IValidationResultUI Methods
The following listing gives an overview of other "properties" of an IValidatonResultUI.
© 2017, Vector Informatik GmbH
120 of 250

---

Chapter 4.
AutomationInterface API Reference
scriptTask (" IValidationResultUIApiOverview ", DV_PROJECT ){
code {
validation {
def r = v a l i d a t i o n R e s u l t s . filter { it . isId ( " Tp " , 12) }. first
a s s e r t r . id . origin == " Tp "
a s s e r t r . id . id == 12
a s s e r t r . d e s c r i p t i o n . toString () . contains ( " must be a multiple of " )
a s s e r t r . severity == E V a l i d a t i o n S e v e r i t y T y p e . ERROR
a s s e r t r . s o l v i n g A c t i o n s . size () == 2
a s s e r t r . g e t S o l v i n g A c t i o n B y G r o u p I d (2) . d e s c r i p t i o n . contains ( " next bigger
valid value ")
// this result has a preferred - solving - action
a s s e r t r . p r e f e r r e d S o l v i n g A c t i o n == r . g e t S o l v i n g A c t i o n B y G r o u p I d (2)
// results with lower severity than ERROR can be acknowledged in the GUI
a s s e r t r . a c k n o w l e d g e m e n t . i sP re se nt () == false
// if the cause was an exception , r. cause . get () returns it
a s s e r t r . cause . i sP re se nt () == false
// an ERROR result gets reduced to WARNING if one of its erroneous CEs is
user - defined (user - overridden )
a s s e r t r . i s R e d u c e d S e v e r i t y () == false
// on - demand results are visualized with a gear - wheel icon
a s s e r t r . i s O n D e m a n d R e s u l t () == false
}
}
}
Listing 4.152: IValidationResultUI overview
4.8.5.7 IValidationResultUI in a variant (Post Build Selectable) Project
scriptTask (" IValidationResultUIInAVariantProject ", DV_PROJECT ){
code {validation{
def r = v a l i d a t i o n R e s u l t s . filter { it . isId ( " Tp " , 12) }. first
a s s e r t r . i s G e n e r a l V a r i a n t C o n t e x t () // either it is a general result
...
a s s e r t r . p r e d e f i n e d V a r i a n t C o n t e x t s . size () == 0 // or it is assigned
to one or more ( but never all ) variants
// If a validator assigns a result to all variants , it will be a
general result at UI - side .
}
}
}
Listing 4.153: IValidationResultUI in a variant (post build selectable) project
4.8.5.8 Erroneous CEs of a Validation-Result
IValidationResultUI.getErroneousCEs() returns a collection of IDescriptor, each descri-
bing a CE that gets an error annotation in the GUI.
To check for a certain model element is affected by the result please use the methods, which
return true, if a model is affected by the validation-result:
© 2017, Vector Informatik GmbH
121 of 250

---

Chapter 4.
AutomationInterface API Reference
• IValidationResultUI.matchErroneousCE(MIObject)
• IValidationResultUI.matchErroneousCE(IHasModelObject)
• IValidationResultUI.matchErroneousCE(MIHasDefinition, DefRef)
scriptTask (" IValidationResultUIErroneousCEs ", DV_PROJECT ){
code {validation{
// sampleDefRefs contains DefRef constants just for this example .
Please use the real DefRefs from your SIP
def result = v a l i d a t i o n R e s u l t s . filter { it . isId ( " Tp " , 12) }. first
// Retrieve the model element to check
def m o d e l E l e m e n t // = r e t r i e v e E l e m e n t ...
// Check if the model object is affected by the validation - result
a s s e r t result . m a t c h E r r o n e o u s C E ( m o d e l E l e m e n t )
}
}
}
Listing 4.154: CE is affected by (matches) an IValidationResultUI
Advanced Descriptor Details
An IDescriptor is a construct that can be used to "point to"
some location in the model. A descriptor can have several kinds of aspects to describe where it
points to. Aspect kinds are e.g. IMdfObjectAspect, IDefRefAspect, IMdfMetaClassAspect,
IMdfFeatureAspect.
getAspect(Class) gets a particular aspect if available, otherwise null.
A descriptor has a parent descriptor. This allows to describe a hierarchy.
E.g. if you want to express that something with definition X is missing as a child of the existing
MDF object Y. In this example you have a descriptor with an IDefRefAspect containing the
definition X. This descriptor that has a parent descriptor with an IMdfObjectAspect containing
the object Y.
The term descriptor refers to a descriptor together with its parent-descriptor hierarchy.
© 2017, Vector Informatik GmbH
122 of 250

---

Chapter 4.
AutomationInterface API Reference
i m p o r t com . vector . cfg . model . c e d e s c r i p t o r . aspect .*
scriptTask (" IValidationResultUIErroneousCEs ", DV_PROJECT ){
code {validation{
// sampleDefRefs contains DefRef constants just for this example .
Please use the real DefRefs from your SIP
def result = v a l i d a t i o n R e s u l t s . filter { it . isId ( " Tp " , 12) }. first
def d e s c r i p t o r = result . e r r o n e o u s C E s . single // this result in this
example has only a single erroneous -CE descriptor
def d e f R e f A s p e c t = d e s c r i p t o r . ge tA sp ect ( I D e f R e f A s p e c t . class )
a s s e r t d e f R e f A s p e c t != null ; // this de sc ri pt or in this example has
an IDefRefAspect
a s s e r t d e f R e f A s p e c t . defRef . equals ( s a m p l e D e f R e f s . t p B u f f e r S i z e D e f R e f )
def o b j e c t A s p e c t = d e s c r i p t o r . ge tA sp ect ( I M d f O b j e c t A s p e c t . class )
a s s e r t o b j e c t A s p e c t != null // // this d es cr ip to r in this example
has an IMdfObjectAspect
// An IMdfObjectAspect would be unavailable for a descriptor
describing that something is missing
def p a r e n t O b j e c t A s p e c t = d e s c r i p t o r . parent . get Aspect (
IMdfObjectAspect . class )
a s s e r t
parentObjectAspect != null
// Dealing with descriptors is universal , but needs more code .
Using these methods might fit your needs .
a s s e r t result . m a t c h E r r o n e o u s C E ( o b j e c t A s p e c t . getO bject () )
a s s e r t result . m a t c h E r r o n e o u s C E ( p a r e n t O b j e c t A s p e c t . ge tObject () ,
sampleDefRefs . tpBufferSizeDefRef )
}
}
}
Listing 4.155: Advanced
use
case
-
Retrieve
Erroneous
CEs
with
descriptors
of
an
IValidationResultUI
4.8.5.9 Examine Solving-Action Execution
The easiest and most reliable option for verifying solving-action execution is to check the pre-
sence of validation-results afterwards.
This is also the feedback strategy of the GUI. After multiple solving-actions have been solved,
the GUI does not show the execution result of each individual solving-action, but just the
remaining validation-results after the operation. Only if a single solving-action is to be solved,
and that fails, the GUI shows the message of that failure including the reason.
The following describes further options of examination:
ISolvingActionUI.solve() returns an ISolvingActionExecutionResult.
An ISolvin-
gActionExecutionResult represents the result of one solving action execution. Use isOk() to
find out if it was successful. Call getUserMessage() to get the failure reason.
ISolver.solve(Closure) returns an ISolvingActionSummaryResult.
An ISolvingActi-
onSummaryResult represents the execution of multiple results.
ISolvingActionSummary-
Result.isOk() returns true if getExecutionResult() is EExecutionResult.SUCCESSFUL or
EExecutionResult.WARNING, this is if at least one sub-result was ok.
Call getSubResults() to get a list of ISolvingActionExecutionResults.
© 2017, Vector Informatik GmbH
123 of 250

---

Chapter 4.
AutomationInterface API Reference
i m p o r t com . vector . cfg . util . activity . e x e c r e s u l t . E E x e c u t i o n R e s u l t
scriptTask (" SolvingReturnValue ", DV_PROJECT ){
code {validation{
a s s e r t
validationResults . size () == 4
// In this example , three validation - results have a preferred
solving action .
// One of the three cannot be solved because a parameter is user -
defined .
def s u m m a r y R e s u l t = solver . s o l v e A l l W i t h P r e f e r r e d S o l v i n g A c t i o n ()
a s s e r t
validationResults . size () == 2 // Two have been solved , one
with a preferred solving - action is left .
a s s e r t
summaryResult . executionResult == EExecutionResult . WARNING
// DemoAsserts is just for this example to show what kind of sub -
results the summaryResult contains .
DemoAsserts . summaryResultContainsASubResultWith ("OK", summaryResult )
// two such sub - results for the validation - results with preferred -
solving - action that could be solved
DemoAsserts . summaryResultContainsASubResultWith ([" invalid
modification "," not changeable "," Reason ","is user - defined "],
summaryResult )
// such a sub - result for the failed preferred solving action due to
the user - defined parameter
DemoAsserts . summaryResultContainsASubResultWith (" Maximum solving
attempts reached for the validation - result of the following
solving - action ", summaryResult )
// Cfg5 takes multiple attempts to solve a result because other
changes may eliminate a blocking reason , but stops after an
execution limit is reached .
}
}
}
Listing 4.156: Examine an ISolvingActionSummaryResult
4.8.5.10 Create a Validation-Result in a Script Task
The resultCreation API provides methods to create new IValidationResults, which could
then be reported to a IValidationResultSink. This is can be used to report validation-results
similar to a validator/generator, but from within a script task.
ValidationResultSink
The IValidationResultSink must be obtained by the context and is
not provided by the creation API. E.g. some script tasks pass an IValidationResultSink as
argument (like DV_GENERATION_STEP).
Or you have to activate the MD license option for development during script task creation by
calling the method requiresMDDevelopmentLicense(), then you could retrieve an IValida-
tionResultSink from the method getResultSink().
Reporting ValidationResult in Task providing a ResultSink
This sample applies to task types
providing a ResultSink in the Task API, like DV_GENERATION_STEP.
© 2017, Vector Informatik GmbH
124 of 250

---

Chapter 4.
AutomationInterface API Reference
scriptTask (" ScriptTaskCreationResult " /* Insert with task type providing
resultSink */ ){
code {
validation {
resultCreation {
// The ValidationResultId group multiple results
def valId = c r e a t e V a l i d a t i o n R e s u l t I d F o r S c r i p t T a s k (
/* ID */ 1234 ,
/* Description */ " Summary of the ValidationResultId ",
/* Severity */ EValidationSeverityType . ERROR )
// Create a new resultBuilder
def builder = n e w R e s u l t B u i l d e r ( valId , " D e s c r i p t i o n of the Result " )
// You can add multiple elements as error objects to mark them
builder . addErrorObject ( sipDefRef . EcucGeneral . bswmdModel (). single )
// Add more calls when needed
// Create the result from the builder
def va lR es ul t = builder . b u i l d R e s u l t ()
// You need to report the result to a resultSink
// You have to get the sink from the context , e.g. script task args
// a sample line would be
resultSinkForTask . reportValidationResult ( valResult )
}
}
}}
Listing 4.157: Create a ValidationResult
Reporting ValidationResult with MD License Option for Development
This sample can be
used in every task types but you need a MD license option for development to retrieve the
ResultSink.
scriptTask (" ScriptTaskCreationResult ", DV_PROJECT ){
// Result reporting requires an MD license for development
requiresMDDevelopmentLicense ()
code {
validation {
resultCreation {
// The ValidationResultId group multiple results
def valId = c r e a t e V a l i d a t i o n R e s u l t I d F o r S c r i p t T a s k (
/* ID */ 1234 ,
/* Description */ " Summary of the ValidationResultId ",
/* Severity */ EValidationSeverityType . ERROR )
// Create a new resultBuilder
def builder = n e w R e s u l t B u i l d e r ( valId , " D e s c r i p t i o n of the Result " )
// Create the result from the builder
def va lR es ul t = builder . b u i l d R e s u l t ()
// When MD license is enabled you can access a resultSink
resultSink . reportValidationResult ( valResult )
}}}}
Listing 4.158: Report a ValidationResult when MD license option is available
© 2017, Vector Informatik GmbH
125 of 250

---

Chapter 4.
AutomationInterface API Reference
4.8.5.11 Turn off auto-solving-action execution
Auto-solving-action execution is a feature to simplify configuration by automatically adjusting
dependent data after a change was made by the user. This feature runs synchronous to the user
change and may have impact on UI responsiveness. If UI response time is not acceptable, this
should be reported to Vector.
Using setEnabled(boolean), auto-solving-action execution can be disabled to find out if this
is the cause and as an interim workaround.
If auto-solving-action execution is disabled, data might get out of sync after a user change,
E.g. Vtt dual target sync, BSW Internal Behavior, ... . In that case, these have to be solved
manually with the corresponding validaton-result’s solving action.
This setting is stored as user-independent project setting.
This setting can only be changed if isChangeable() returns true (false e.g. due to read-only
project), otherwise an IllegalStateException is thrown.
scriptTask (" SolvingReturnValue ", DV_PROJECT ){
code {validation{
settings {
if ( a u t o S o l v i n g A c t i o n E x e c u t i o n . c h an ge ab le ) {
autoSolvingActionExecution . enabled = false
}
}
}
}
}
Listing 4.159: Turn off auto solving action execution
© 2017, Vector Informatik GmbH
126 of 250

---

Chapter 4.
AutomationInterface API Reference
4.9 Update Workflow
The Update Workflow derives the initial EcuC from the input files and updates the project
accordingly. The Update Workflow API comprises modification of variants, modification of the
input files list and the execution of an update workflow.
4.9.1 Method Overview
• workflow: the workflow closure is the central entry point for the Workflow API.
– update: contains all settings for the Update Workflow and executes the update after
leaving the closure block.
∗ input: supports the modification of the input files list and specific settings.
· communication: the communication closure contains settings for the com-
munication extract and communication legacy input files (like cbd, ldf or
fibex). Take a look at the JavaDoc of ICommunicationApi for all possible
settings.
4.9.2 Example: Content of Input Files has changed.
In case of a changed content of input files, the update workflow can be started with the work-
flow.update(dpaProjectFilePath) method. This will start the Update Workflow, with the
input files as selected in the DaVinci Configurator GUI. The parameter dpaProjectFilePath
accepts the same types and has the same semantic as resolvePath described in 4.4.3.1 on
page 36.
scriptTask (" UpdateExistingProject ", DV_APPLICATION ) {
code {
workflow . update pathToDpaFile
}
}
Listing 4.160: "Update existing project"
The update workflow is started at the end of the update-closure.
© 2017, Vector Informatik GmbH
127 of 250

---

Chapter 4.
AutomationInterface API Reference
4.9.3 Example: List of Input Files shall be changed
scriptTask (" ChangeListOfComExtractsAndUpdate ", DV_APPLICATION ) {
code {
def e x t r a c t P a t h = paths . r e s o l v e P a t h ( e x t r a c t F i l e )
def d i a g E x t r a c t P a t h = paths . r e s o l v e P a t h ( d i a g E x t r a c t )
workflow . update ( dpaProjectFile ){
updateSettings {
updateMode = ECUC_ONLY
uuidUsageInStandardConfigurationEnabled = false ;
uuidUsageInSystemDescriptionEnabled = false ;
}input{
communication {
extract {
extractFiles { exFilePathList ->
// clear the list of communication extracts
exFilePathList . clear ()
// adds an communication extract
exFilePathList . add ( extractPath . asPersistablePath ())
}
// change the selection of the ecuInstance
// Note : this closure is deferred executed .
ecuInstanceSelection {
r e t u r n
availableEcuInstances [0]
}
}
}diagnostic{
extract {
extractFiles { exFilePathList ->
// clear the list of communication extracts
exFilePathList . clear ()
// adds an communication extract
exFilePathList . add ( diagExtractPath . asPersistablePath ())
}
// change the selection of the ecuInstance
// Note : this closure is deferred executed .
ecuInstanceSelection {
r e t u r n
availableEcuInstances [0]
}
}
}
}}}}
Listing 4.161: Change list of communication extracts and update
Note: The code in the ecuInstanceSelection closure is deferred executed.
The
access to variables, declared outside of this closure is not allowed.
This example shows the complete replacement of the current list of communication extracts
with one extract and the selection of the first ecuInstance in the new extract. The update
workflow is executed after the update closure block is left.
4.9.4 Prerequisites
The Update Workflow can’t be executed while the Project to update is open. E.g. in a IPro-
jectRef.openProject closure block or in a ScriptTask with the DV_PROJECT ScriptTaskType.
© 2017, Vector Informatik GmbH
128 of 250

---

Chapter 4.
AutomationInterface API Reference
Becaue the update workflow has to close and open the project during update, which would
cause strange behavior in your client code.
© 2017, Vector Informatik GmbH
129 of 250

---

Chapter 4.
AutomationInterface API Reference
4.10 Domains
The domain APIs are specifically designed to provide high convenience support for typical
domain use cases.
The domain API is the entry point for accessing the different domain interfaces. It is available
in opened projects in the form of the IDomainApi interface.
IDomainApi provides methods for accessing the different domain-specific APIs.
Each dom-
ain’s API is available via the domain’s name. For an example see the communication domain
API 4.10.1.
getDomain() allows accessing the IDomainApi like a property.
scriptTask ('taskName ') {
code {
// IDomainApi is available as " domain " property
def d om ai nA pi = domain
}
}
Listing 4.162: Accessing IDomainApi as a property
domain(Closure) allows accessing the IDomainApi in a scope-like way.
scriptTask ('taskName ') {
code {
domain {
// IDomainApi is available inside this Closure
}
}
}
Listing 4.163: Accessing IDomainApi in a scope-like way
4.10.1 Communication Domain
The communication domain API is specifically designed to support communication related
use cases. It is available from the IDomainApi 4.10 in the form of the ICommunicationApi
interface.
getCommunication() allows accessing the ICommunicationApi like a property.
scriptTask ('taskName ') {
code {
// ICommunicationApi is available as " communication " property
def c o m m u n i c a t i o n = domain . c o m m u n i c a t i o n
}
}
Listing 4.164: Accessing ICommunicationApi as a property
communication(Closure) allows accessing the ICommunicationApi in a scope-like way.
© 2017, Vector Informatik GmbH
130 of 250

---

Chapter 4.
AutomationInterface API Reference
scriptTask ('taskName ') {
code {
domain . communication {
// ICommunicationApi is available inside this Closure
}
}
}
Listing 4.165: Accessing ICommunicationApi in a scope-like way
The following use cases are supported:
Accessing Can Controllers
getCanControllers() returns a list of all ICanControllers in
the configuration 4.10.1.1 on the following page.
© 2017, Vector Informatik GmbH
131 of 250

---

Chapter 4.
AutomationInterface API Reference
4.10.1.1 CanControllers
An ICanController instance represents a CanController MIContainer providing support for
use cases exceeding those supported by the model API.
scriptTask (' OptimizeAcceptanceFilters ', DV_APPLICATION ) {
code {
// replace $dpaFile with the path to your project
def t h e P r o j e c t = projects . o p e n P r o j e c t ( " $dpaFile " ) {
transaction {
domain . communication {
// open acceptance filters of all CanControllers
canControllers *. openAcceptanceFilters ()
// open acceptance filters of first CanController
canControllers . first . openAcceptanceFilters ()
canControllers [0]. openAcceptanceFilters () // same as above
// open acceptance filters of second CanController
// (if there is a second CanController )
canControllers [1]?. openAcceptanceFilters ()
// open acceptance filters of a dedicated CanController
canControllers . filter { it. name . contains 'CH0 ' }. single .
openAcceptanceFilters ()
// accessing a dedicated CanController
def ch0 = c a n C o n t r o l l e r s . filter { it . name . contains ' CH0 ' }. single
// assert : ch0 's first CanFilterMask value is XXXXXXXXXXX
a s s e r t ' X X X X X X X X X X X ' == ch0 . c a n F i l t e r M a s k s [0]. filter
// set CanFilterMask value to 01111111111
ch0 . canFilterMasks [0]. filter = ' 01111111111 '
a s s e r t ' 0 1 1 1 1 1 1 1 1 1 1 ' == ch0 . c a n F i l t e r M a s k s [0]. filter
// automatic acceptance filter optimization
ch0 . optimizeFilters { fullCan = true }
}
}
}scriptLogger.info('Successfully optimized Can acceptance filters.')
}
}
Listing 4.166: Optimizing Can Acceptance Filters
Opening Acceptance Filters
openAcceptanceFilters() opens all of this ICanController’s
acceptance filters.
Optimizing Acceptance Filters
optimizeFilters(Closure) optimizes this ICanControl-
ler’s acceptance filter mask configurations. The given Closure is delegated to the IOpti-
mizeAcceptanceFiltersApi interface for parameterizing the optimization.
Using setFullCan(boolean) it can be specified whether the optimization shall take full can
objects into account or not.
© 2017, Vector Informatik GmbH
132 of 250

---

Chapter 4.
AutomationInterface API Reference
Creating new CanFilterMasks
createCanFilterMask() creates a new ICanFilterMask for
this ICanController.
Accessing a CanController’s CanFilterMasks
getCanFilterMasks() returns all of this ICan-
Controller’s ICanFilterMasks.
Accessing a CanController’s MIContainer
getMdfObject() returns the MIContainer repre-
sented by this ICanController.
4.10.1.2 CanFilterMasks
An ICanFilterMask instance represents a CanFilterMask MIContainer providing support for
use cases exceeding those supported by the model API.
For example code see 4.10.1.1 on the previous page. The following use cases are supported:
Filter Types
ECanAcceptanceFilterType lists the possible values for an ICanFilterMask’s
filter type.
STANDARD results in a standard Can acceptance filter value with length 11.
EXTENDED results in an extended Can acceptance filter value with length 29.
MIXED results in a mixed Can acceptance filter value with length 29.
Accessing a CanFilterMask’s Filter Type
getFilterType() returns this ICanFilterMask’s
filter type.
Specifying a CanFilterMask’s Filter Type
Using setFilterType(ECanAcceptanceFilterType)
this ICanFilterMask’s filter type can be specified.
Accessing a CanFilterMask’s Filter Value
getFilter() returns this ICanFilterMask’s filter
value. A CanFilterMask’s filter value is a String containing the characters ’0’, ’1’ and ’X’
(don’t care). For determining if a given Can ID passes the filter it is matched bit for bit against
the String’s characters. The character at index 0 is matched against the most significant bit.
The character at index length() - 1 is matched against the least significant bit. The length
of the String corresponds to the CanFilterMask’s filter type.
Specifying a CanFilterMask’s Filter Value
Using setFilter(String) this ICanFilterMask’s
filter value can be specified.
Accessing a CanFilterMask’s MIContainer
getMdfObject() returns the MIContainer repre-
sented by this ICanFilterMask.
© 2017, Vector Informatik GmbH
133 of 250

---

Chapter 4.
AutomationInterface API Reference
4.10.2 Diagnostics Domain
The diagnostics domain API is specifically designed to support diagnostics related use cases.
It is available from the IDomainApi 4.10 on page 130 in the form of the IDiagnosticsApi
interface.
getDiagnostics() allows accessing the IDiagnosticsApi like a property.
scriptTask ('taskName ') {
code {
// IDiagnosticsApi is available as " diagnostics " property
def d i a g n o s t i c s = domain . d i a g n o s t i c s
}
}
Listing 4.167: Accessing IDiagnosticsApi as a property
diagnostics(Closure) allows accessing the IDiagnosticsApi in a scope-like way.
scriptTask ('taskName ') {
code {
domain . diagnostics {
// IDiagnosticsApi is available here
}
}
}
Listing 4.168: Accessing IDiagnosticsApi in a scope-like manner
The following use cases are supported:
Dem Events
The API provides access and creation of IDemEvents in the configuration. See
chapter 4.10.2.1 on the next page for more details.
Check for OBD II
isObd2Enabled() checks, if OBD II is available in the configuration.
Enable OBD II
setObd2Enabled(boolean) enables or disables OBD II in the configuration.
Note, that OBD II can only be enabled, if a valid SIP license was found.
Check for WWH-OBD
isWwhObdEnabled() checks, if WWH-OBD is available in the confi-
guration.
Enable WWH-OBD
setWwhObdEnabled(boolean) enables or disables WWH-OBD in the
configuration. Note, that WWH-OBD can only be enabled, if a valid SIP license was found.
© 2017, Vector Informatik GmbH
134 of 250

---

Chapter 4.
AutomationInterface API Reference
4.10.2.1 DemEvents
An IDemEvent instance represents a diagnostic event and and provides usecase centric functio-
nalities to modify and query diagnostic events.
Accessing Dem Events
getDemEvents() returns a list of all IDemEvents in the configuration.
Creating Dem Events
createDemEvent(Closure) is used to create diagnostic events of dif-
ferent kinds.
The method can be configured to create different types of DTCs/Events:
1. UDS Event: This is the default type of event, when only an ’eventName’ and a ’dtc’
number is specified. A new DemEventParameter container with the given shortname and
a new DemDTCClass with the given DemUdsDTC is created.
scriptTask ('taskName ') {
code {
transaction {
domain . diagnostics {
def udsEvent = c r e a t e D e m E v e n t {
eventName = " NewUdsEvent "
dtc = 0 x30
}
}}}}
Listing 4.169: Create a new UDS DTC with event
2. OBD II Event: If OBD II is enabled for the loaded configuration, and a ’obd2Dtc’ is spe-
cified instead of a ’dtc’, the method will create an OBD II relevant event. The difference
is, that it will set the parameter DemObdDTC instead of DemUdsDTC. It is also pos-
sible to specify ’dtc’ as well as ’obd2dtc’, which will result in both DTC parameters are set.
scriptTask ('taskName ') {
code {
transaction {
domain . diagnostics {
// OBD must be enabled and legislation must be OBD2
// Enable OBD2
obd2Enabled = true
def o bd 2E ve nt = c r e a t e D e m E v e n t {
eventName = ' NewOBD2Event '
obd2Dtc = 0 x40
}
def o b d 2 C o m b i n e d E v e n t = c r e a t e D e m E v e n t {
eventName = ' UDS_OBD2_Combined_Event '
dtc = 0 x31
obd2Dtc = 0 x41
}
}}}}
Listing 4.170: Enable OBD II and create a new OBD related DTC with event
© 2017, Vector Informatik GmbH
135 of 250

---

Chapter 4.
AutomationInterface API Reference
3. WWH-OBD Event: If WWH-OBD is enabled for the loaded configuration, and a ’ww-
hObdDtcClass’ with a value other than ’NO_CLASS’ is specified, the method will create
a WWH-OBD relevant event. Note that WWH-OBD relevant events usually du reference
the so called MIL indicator, thus this reference will be set by default in the newly created
DemEventParameter.
scriptTask ('taskName ') {
code {
transaction {
domain . diagnostics {
// OBD must be enabled , and legislation must be WWH - OBD
// The parameter '/ Dem / DemGeneral / DemMILIndicatorRef ' must
be set
wwhObdEnabled = true
def w w h O b d E v e n t = c r e a t e D e m E v e n t {
eventName = ' WWHOBD_Event '
dtc = 0 x50
// wwhObdClass != NO_CLASS indicates WWH - OBD event
wwhObdDtcClass = CLASS_A
}
}}}}
Listing 4.171: Enable WWH-OBD and create a new OBD related DTC with event
4. J1939 Event: The last type of event is a J1939 related event, which can be created when
J1939 is licensed and available for the loaded configuration. This is done in a similar way
as for UDS events, but additionally specifying ’spn’, ’fmi’ values as well as the name of
the referenced ’nodeAddress’.
scriptTask ('taskName ') {
code {
def n o d e A d d r e s s C o n t a i n e r = mdfModel ( AsrPath . create ( " / A c tiv eE cu C /
Dem / DemConfigSet / DemJ1939NodeAddress ", MIContainer ))
transaction {
domain . diagnostics {
// J1939 Event creation
// J1939 must be enabled and License must be available .
j1939Enabled = true
def j 1 9 3 9 E v e nt = c r e a t e D e m E v e n t {
eventName ' J1939_Event '
dtc 0 x30
spn 90
fmi 13
nodeAddress nodeAddressContainer
}
}}}}
Listing 4.172: Open a project, enable J1939 and create a new J1939 DTC with event
Important Note:
For every DTC numbers apply the rule, that if there are already DemDTCClasses with
the given number, they will be used. In such a case, no new DemDTCClass container is
created.
© 2017, Vector Informatik GmbH
136 of 250

---

Chapter 4.
AutomationInterface API Reference
4.10.3 Mode Management Domain
The mode management domain API is specifically designed to support mode management
related use cases. It is available from the IDomainApi 4.10 on page 130 in the form of the
IModeManagementApi interface.
getModeManagement() allows accessing the IModeManagementApi like a property.
scriptTask ('taskName ') {
code {
// IModeManagementApi is available as " modeManagement " property
def m o d e M a n a g e m e n t = domain . m o d e M a n a g e m e n t
}
}
Listing 4.173: Accessing IModeManagementApi as a property
modeManagement(Closure) allows accessing the IModeManagementApi in a scope-like way.
scriptTask ('taskName ') {
code {
domain . modeManagement {
// IModeManagementApi is available inside this Closure
}
}
}
Listing 4.174: Accessing IModeManagementApi in a scope-like way
4.10.3.1 BswM Auto Configuration
The IBswMAutoConfigurationApi allows for semi-automatic creation of dedicated parts of the
BswM configuration. The BswM auto configuration takes an input consisting of "features" and
"parameters" to be provided via the IBswMAutoConfigurationApi. Each feature may have
zero, one or more sub-features and zero, one or more parameters.
The corresponding BswM configuration content is derived based on the (de)activation of features
and the values assigned to the parameters.
The available features and parameters depend strongly on the project’s input data and general
project setup. They can be addressed by String identifiers. These identifiers are best obtained
from the corresponding auto configuration assistant of the BSW management editor in the Cfg5
GUI.
© 2017, Vector Informatik GmbH
137 of 250

---

Chapter 4.
AutomationInterface API Reference
scriptTask (' EcuStateHandlingAutoConfiguration ', DV_PROJECT ) {
code {
// In projects with post - build selectable variance switching to an
// IPredefinedVariantView for performing auto configuration is mandatory
variance . variantView ('Left '). activeWith {
domain . modeManagement . bswMAutoConfig ('Ecu State Handling ') {
activate '/ ECU State Machine / Support ComM '
set '/ ECU State Machine / Self Run Request Timeout ' to 0.2
set '/ ECU State Machine / Number of Run Request User ' to 4
overrides {
if ( addition || removal ) {
keepOverride
} else if ( BswMArgumentRef . DEFREF . isDefinitionOf ( element )
&& feature ('/ ECU State Machine / Support ComM / CAN00_f26020e5 ').
enabled
&& parameter ('/ ECU State Machine / Number of PostRun Request
User '). value == 4) {
discardOverride
} else {
keepOverride
}
}
}
}
}
}
Listing 4.175: ECU State Handling Auto Configuration
Executing the BswM Auto Configuration
IModeManagementApi.bswMAutoConfig(String,
Closure) delegates the given code to the IBswMAutoConfigurationApi of the given BswM
auto configuration domain.
Activating BswM Auto Configuration Features
activate(String) activates the BswM auto
configuration feature with the given identifier. All enabled sub-features of the specified feature
are also activated. Imagine the features displayed in a tree structure (like in Cfg5 GUI) where
checking a tree node automatically checks all children.
Deactivating BswM Auto Configuration Features
deactivate(String) deactivates the BswM
auto configuration feature with the given identifier. All enabled sub-features of the specified
feature are also deactivated. Imagine the features displayed in a tree structure (like in Cfg5
GUI) where unchecking a tree node automatically unchecks all children.
Assigning Values to BswM Auto Configuration Parameters
set(String) sets the parameter
with the given identifier to the specified value. Supported value types are boolean, BigInteger,
BigDecimal, String and MIReferrable (reference parameters).
Manually Adapting the BswM Auto Configuration Content
The BswM auto configuration
mechanism is useful for creating large parts of the BswM configuration based on certain built-in
heuristics. Where these heuristics fail to fulfill detailed project specific requirements manual
adaptations to the auto-generated configuration content become necessary.
© 2017, Vector Informatik GmbH
138 of 250

---

Chapter 4.
AutomationInterface API Reference
Per default manual adjustments are kept in the configuration. But subsequent BswM auto
configuration runs may render previously applied adjustments obsolete or dysfunctional. Using
overrides(Closure) a callback can be registered to be called for each detected adaptation. The
callback can decide for each adjustment if it is to remain in the configuration or if it is to be over-
written by the BswM auto configuration. For details on which information is provided to this
callback please refer to the javadoc provided with IBswMAutoConfigurationOverride.
Inspecting BswM Auto Configuration Domains
The getBswMAutoConfigDomains() met-
hod of the IModeManagementApi interface provides read-access to all available BswM auto
configuration domains. Available features and parameters can be inspected for various proper-
ties. See javadoc of IBswMAutoConfigurationDomain, IBswMAutoConfigurationFeature and
IBswMAutoConfigurationParameter for details.
domain . modeManagement {
// In projects with post - build selectable variance switching to an
// IPredefinedVariantView for inspecting auto configuration is mandatory
variance . variantView ('Left '). activeWith {
// get all BswM auto configuration domains
def e c u S t a t e H a n d l i n g D o m a i n = b s w M A u t o C o n f i g D o m a i n s . forEach {
scriptLogger . info it. identifier
}
def i sE na bl ed = b s w M A u t o C o n f i g D o m a i n ' Ecu State Handling ' feature '/ ECU
State Machine / Support ComM ' enabled
def i s A c t i v a t e d = b s w M A u t o C o n f i g D o m a i n ' Ecu State Handling ' feature '/ ECU
State Machine / Support ComM ' activated
if ( is En ab le d && i s A c t i v a t e d ) {
// activation state can be toggled at enabled features only
bswMAutoConfig ('Ecu State Handling ') {
deactivate '/ ECU State Machine / Support ComM '
}
}
bswMAutoConfigDomain ('Ecu State Handling ') {
// this code is delegated to the 'Ecu State Handling '
// auto configuration domain
def p1 = pa ra me te r '/ ECU State Machine / Self Run Request Timeout ' value
scriptLogger . info 'Self Run Request Timeout = ' + p1
def p2 = pa ra me te r '/ ECU State Machine / Number of Run Request User ' value
scriptLogger . info 'Number of Run Request User = ' + p2
// get all root features
rootFeatures . forEach { scriptLogger . info it. identifier }
// get all sub - features of a feature
feature '/ ECU State Machine / Support ComM ' subFeatures . forEach {
scriptLogger . info it. identifier
}
// get all parameters of a feature
feature '/ ECU State Machine ' parameters . forEach {
scriptLogger . info it. identifier
}
}
}
}
Listing 4.176: Inspecting Auto Configuration Elements
© 2017, Vector Informatik GmbH
139 of 250

---

Chapter 4.
AutomationInterface API Reference
4.10.4 Runtime System Domain
The runtime system domain API is specifically designed to support runtime system related
use cases.
It is available from the IDomainApi (see 4.10 on page 130) in the form of the
IRuntimeSystemApi interface.
getRuntimeSystem() allows accessing the IRuntimeSystemApi like a property.
scriptTask ('taskName ') {
code {
// IRuntimeSystemApi is available as " runtimeSystem " property
def r u n t i m e S y s t e m = domain . r u n t i m e S y s t e m
}
}
Listing 4.177: Accessing IRuntimeSystemApi as a property
runtimeSystem(Closure) allows accessing the IRuntimeSystemApi in a scope-like way.
scriptTask ('taskName ') {
code {
domain . runtimeSystem {
// IRuntimeSystemApi is available inside this Closure
}
}
}
Listing 4.178: Accessing IRuntimeSystemApi in a scope-like way
The following use cases are supported:
4.10.4.1 Component Port Connection
A component port (IComponentPort) represents a port prototype and its corresponding com-
ponent prototype, and in case of a delegation port the corresponding top level composition type
(Ecu Composition).
The connecting component ports use case allows connecting (a.k.a. mapping) different ports in
a similar way the component connection assistant does.
Selecting component ports to map
The entry point is to select a collection of component
ports and auto-map them to the possible target component ports by applying the matching
rules of the component connection assistant.
selectComponentPorts(Closure) allows the selection of IComponentPorts using predicates.
Predicates
To select the component ports predicates can be provided to narrow down the
component ports to be connected: this corresponds to the manual selection of certain component
ports in the component connection assistant.
Per default the predicates are combined via logical AND. To realize other combinations, use
the ’or’,’not’ and ’and’ predicates.
© 2017, Vector Informatik GmbH
140 of 250

---

Chapter 4.
AutomationInterface API Reference
Component Port Predicates
• unconnected() matches unconnected component ports.
• connected() matches connected component ports.
• senderReceiver() matches component ports whose port has a sender/receiver port in-
terface.
• clientServer() matches component ports whose port has a client/server port interface.
• modeSwitch() matches component ports whose port has a mode-switch port interface.
• nvData() matches component ports whose port has a NvData port interface.
• parameter() matches component ports whose port has a parameter (calibration) port
interface.
• provided() matches provided component ports (p-port).
• required() matches required component ports (r-port).
• providedRequired() matches provided-required component ports (pr-port).
• delegation() matches delegation ports (ports of the Ecu composition).
• application() matches component ports whose port interface is an application port
interface.
• service() matches component ports whose port interface is an service port interface.
• name(String) matches component ports with the given port name.
• name(Pattern) matches component ports with the given port name pattern.
• asrPath(String) matches component ports with the given port autosar path.
• asrPath(Pattern) matches component ports with the given port autosar path pattern.
• component(String) matches component ports with the given component name.
• component(Pattern) matches component ports with the given component name pattern.
• componentAsrPath(String) matches the component ports with the given component
autosar path.
• componentAsrPath(Pattern) matches component ports with the given component auto-
sar path pattern.
• portInterfaceMapping(String) matches component ports for whose port interfaces a
port interface mapping with the given port interface mapping name exists.
• portInterfaceMapping(Pattern) matches component ports for whose port interfaces a
port interface mapping with the given port interface mapping name pattern exists.
• portInterfaceMappingAsrPath(String) matches component ports for whose port in-
terfaces a port interface mapping with the given port interface mapping autosar path
exists.
• portInterfaceMappingAsrPath(Pattern) matches component ports for whose port in-
terfaces a port interface mapping with the given port interface mapping autosar path
pattern exists.
© 2017, Vector Informatik GmbH
141 of 250

---

Chapter 4.
AutomationInterface API Reference
• filterAdvanced(Closure) matches component ports for whose the given closure results
to true.
• and(Closure) combines the predicates inside the closure with a logical AND.
• or(Closure) combines the predicates inside the closure with a logical OR.
• not(Closure) negates the combination of predicates inside the closure.
Examples
scriptTask (" selectAllPorts ", DV_PROJECT ){
code {
transaction {
domain . runtimeSystem {
def s e l e c t e d P o r t s =
selectComponentPorts {
// no predicates : select ALL component ports
} getComponentPorts ()
scriptLogger . infoFormat (" Selected {0} component ports .", selectedPorts .
size ())
}
}
}
}
Listing 4.179: Selects all component ports
scriptTask (" selectAllUnconnectedPorts ", DV_PROJECT ){
code {
transaction {
domain . runtimeSystem {
def s e l e c t e d P o r t s =
selectComponentPorts {
unconnected () // select all unconnected component ports
} getComponentPorts ()
scriptLogger . infoFormat (" Selected {0} component ports .", selectedPorts .
size ())
}
}
}
}
Listing 4.180: Selects all unconnected component ports
© 2017, Vector Informatik GmbH
142 of 250

---

Chapter 4.
AutomationInterface API Reference
scriptTask (" selectAllUnconnectedSRAndConnectedModePorts ", DV_PROJECT ){
code {
transaction {
domain . runtimeSystem {
def s e l e c t e d P o r t s =
selectComponentPorts {
// start with logical OR
or {
and { // unconnected sender / receiver ports
unconnected ()
senderReceiver ()
}
and { // connected modeSwitch ports
connected ()
modeSwitch ()
}
}
} getComponentPorts ()
scriptLogger . infoFormat (" Selected {0} component ports .", selectedPorts .
size ())
}
}
}
}
Listing 4.181: Select all unconnected sender/receiver or connected mode-switch component
ports
Auto-Mapping
The use case of auto-mapping component ports is based on the selection of
component ports: it offers the methods to auto-map.
autoMap() tries to auto-map the selection of component ports according the component con-
nection assistant default rules.
Examples for autoMap()
scriptTask (" automapAll ", DV_PROJECT ){
code {
transaction {
domain . runtimeSystem {
def m a p p e d C o n n e c t o r s =
selectComponentPorts {
// no predicates : select ALL component ports
} autoMap ()
scriptLogger . infoFormat (" Created {0} mappings .", mappedConnectors . size
())
}
}
}
}
Listing 4.182: Tries to auto-map all ports
© 2017, Vector Informatik GmbH
143 of 250

---

Chapter 4.
AutomationInterface API Reference
scriptTask (" automapAllUnconnected ", DV_PROJECT ){
code {
transaction {
domain . runtimeSystem {
def m a p p e d C o n n e c t o r s =
selectComponentPorts {
unconnected () // select all unconnected component ports
} autoMap ()
scriptLogger . infoFormat (" Created {0} mappings .", mappedConnectors . size
())
}
}
}
}
Listing 4.183: Tries to auto-map all unconnected component ports
scriptTask (" autoMapUnconnectedSRCS ", DV_PROJECT ){
code {
transaction {
domain . runtimeSystem {
def m a p p e d C o n n e c t o r s =
selectComponentPorts {
// select all unconnected client / server and unconnected
sender / receiver ports
unconnected ()
or {
clientServer ()
senderReceiver ()
}
} autoMap ()
scriptLogger . infoFormat (" Created {0} mappings .", mappedConnectors . size ()
)
}
}
}
}
Listing 4.184: Tries to auto-map all unconnected sender/receiver and client/server ports
i m p o r t com . vector . cfg . model . sysdesc . api . port . I C o m p o n e n t P o r t
scriptTask (" autoMapAdvancedfilter ", DV_PROJECT ){
code {
transaction {
domain . runtimeSystem {
def m a p p e d C o n n e c t o r s =
selectComponentPorts {
// select component port by own custom filter predicate
filterAdvanced { IComponentPort port ->
" MyUUID ". equals ( port . getMdfPort (). getUuid2 ())
}
} autoMap ()
scriptLogger . infoFormat (" Created {0} mappings .", mappedConnectors . size ()
)
}
}
}
}
Listing 4.185: Tries to auto-map port determined by advanced filter
© 2017, Vector Informatik GmbH
144 of 250

---

Chapter 4.
AutomationInterface API Reference
autoMapTo(Closure) tries to auto-map the selection of component ports according the compo-
nent connection assistant rules but offers more control for the auto-mapping: Inside the closure
additional predicates for narrowing down the target component ports can be defined and code
to evaluate and change the auto-mapper results can be provided.
Narrowing down the target component ports may be useful to gain better matches for the auto-
mapper: In case several target component ports match equally, no auto-mapping is performed.
So reducing the target component ports my improve the results of the auto-mapping.
The component port selection will produce trace, info and warning logs. To see them, activate
the ’com.vector.cfg.dom.runtimesys.groovy.api.IComponentPortSelection’ logger with
the appropriate log level.
Control the auto-mapping in autoMapTo(Closure)
selectTargetPorts(Closure) allows to define predicates to narrow down the target ports for
the auto-mapping. The predicates are used to filter the possible target component ports which
were computed from the source component port selection.
scriptTask (" autoMapUnconnectedToComponentPrototype ", DV_PROJECT ){
code {
transaction {
domain . runtimeSystem {
def m a p p e d C o n n e c t o r s =
selectComponentPorts {
unconnected () // select all unconnected ports
} autoMapTo {
selectTargetPorts {
component " App1 " // and auto - map them to all ports of
component " App1 "
}
}
scriptLogger . infoFormat (" Created {0} mappings .", mappedConnectors . size ()
)
}
}
}
}
Listing 4.186: Tries to auto map all unconnected ports to the ports of one component prototype
evaluateMatches(Closure) allows to evaluate and change the results of the auto-mapping. It
corresponds to the confirm page of the component connection assistant.
For each source component port the provided closure is called: Parameters are the source
component port, the optional matched target component port (or null), and a list of all potential
target component ports (respecting the selectTargetPorts(Closure) predicates). The return
value must be a list of target component ports.
© 2017, Vector Informatik GmbH
145 of 250

---

Chapter 4.
AutomationInterface API Reference
i m p o r t com . vector . cfg . dom . r u n t i m e s y s . api . as si st an t . co nn ec ti on .
ISourceComponentPort
i m p o r t com . vector . cfg . dom . r u n t i m e s y s . api . as si st an t . co nn ec ti on .
ITargetComponentPort
scriptTask (" automapAllUnconnectedAndEvaluateMatches ", DV_PROJECT ){
code {
transaction {
domain . runtimeSystem {
def m a p p e d C o n n e c t o r s =
selectComponentPorts {
unconnected ()
} autoMapTo {
evaluateMatches {
ISourceComponentPort sourcePort ,
ITargetComponentPort optionalMatchedTargetPort ,
List < ITargetComponentPort > potentialTargetPorts ->
if ( s o u r c e P o r t . g e t P o r t N a m e () . equals ( " M y E x c e p t i o n a l P o r t "
)) {
// example for excluding a port from auto - mapping
by having a close look
// sourcePort . getMdfPort () ....
r e t u r n n u l l
}
// default : do not change the auto - matched port
[ optionalMatchedTargetPort ]
}
}
scriptLogger . infoFormat (" Created {0} mappings .", mappedConnectors . size ()
)
}
}
}
}
Listing 4.187: Tries to auto-map all unconnected ports and evaluate matches
© 2017, Vector Informatik GmbH
146 of 250

---

Chapter 4.
AutomationInterface API Reference
i m p o r t com . vector . cfg . dom . r u n t i m e s y s . api . as si st an t . co nn ec ti on .
ISourceComponentPort
i m p o r t com . vector . cfg . dom . r u n t i m e s y s . api . as si st an t . co nn ec ti on .
ITargetComponentPort
scriptTask (" automap1ToN ", DV_PROJECT ){
code {
transaction {
domain . runtimeSystem {
def m a p p e d C o n n e c t o r s =
selectComponentPorts {
// select single delegation port
delegation ()
name " rDelegationSRPort1 "
} autoMapTo {
selectTargetPorts {
// select a collection of target ports ( names start with
" rSRPort ")
name ~" rSRPort .*"
}evaluateMatches {
ISourceComponentPort sourcePort ,
ITargetComponentPort optionalMatchedTargetPort ,
List < ITargetComponentPort > potentialTargetPorts ->
// return all potentialTargetPorts for 1:n
connections , not only the one matched best
potentialTargetPorts
}
}
scriptLogger . infoFormat (" Created {0} mappings .", mappedConnectors . size ()
)
}
}
}
}
Listing 4.188: Auto-map a component port and realize 1:n connection by using evaluate matches
forceConnectionWhen1To1() allows to force a mapping even the usual auto-mapping rules will
not match. Precondition is that the collections of source component ports and target component
ports only contain one component port each. Otherwise no mapping is done.
© 2017, Vector Informatik GmbH
147 of 250

---

Chapter 4.
AutomationInterface API Reference
scriptTask (" autoMapTwoNonMatchingPorts ", DV_PROJECT ){
code {
transaction {
domain . runtimeSystem {
def m a p p e d C o n n e c t o r s =
selectComponentPorts {
// select a single source component port
name " prNVPort1 "
component " NvApp1 "
} autoMapTo {
selectTargetPorts {
// select a single target component port
name " rSRPort2 "
component " App2 "
}
// force the connection even names do not match at all
forceConnectionWhen1To1 ()
}
scriptLogger . infoFormat (" Created {0} mappings .", mappedConnectors . size ()
)
}
}
}
}
Listing 4.189: Create mapping between two ports which names do not match.
4.10.4.2 Data Mapping
The data mapping use case allows to connect signal instances and data elements/operations in
a similar way the data mapping assistant does.
Communication Element
A data element or an operations to be data-mapped is represented
by an ICommunicationElement. A data element is represented by the subtype IDataCommuni-
cationElement, an operation is represented by the subtype IOperationCommunicationEle-
ment. A communication element contains the full context information (component prototype,
port prototype, data type hierarchy) necessary for data mapping.
Signal Instance
The system signals and system signal groups to be data-mapped are represen-
ted by a signal instance (IAbstractSignalInstance). ISignalInstance represents a system
signal, ISignalGroupInstance represents a system signal group. ’Signal instance’ means that
the system signal or system signal group is at least referenced by one ISignal or ISignalGroup.
System signals or system signal groups which are not referenced by an ISignal or ISignalGroup
are not represented as signal instance and so are not available for data mapping.
The entry point for data mapping is either to select a collection of signal instances and auto-map
them to the possible target communication elements or vice versa by applying the matching
rules of the data mapping assistant.
Mapping signal instances
selectSignalInstances(Closure) allows the selection of IAb-
stractSignalInstances using predicates.
Per default the predicates are combined via logical AND. To realize other combinations, use
the ’or’,’not’ and ’and’ predicates.
© 2017, Vector Informatik GmbH
148 of 250

---

Chapter 4.
AutomationInterface API Reference
Signal Instance Predicates
• unmapped() matches signal instances which are not data-mapped.
• mapped() matches signal instances which are data-mapped.
• signalGroup() matches signal instances which are a signal group instance.
• groupSignal() matches signal instances which are a group signal.
• transformed() matches signal instances which are transformation signals.
• tx() matches signal instances whose direction is compatible to EDirection.Tx.
• rx() matches signal instances whose direction is compatible to EDirection.Rx.
• name(String) matches signal instances with the given name.
• name(Pattern) matches signal instances with the given name pattern.
• asrPath(String) matches signal instances with the given autosar path.
• asrPath(Pattern) matches signal instances with the given autosar path pattern.
• iSignal(String) matches signal instances which are referenced at least by one ISignal/I-
SignalGroup with the given name.
• iSignal(Pattern) matches signal instances which are referenced at least by one ISig-
nal/ISignalGroup with the given name pattern.
• iSignalAsrPath(String) matches signal instances which are referenced at least by one
ISignal/ISignalGroup with the given autosar path.
• iSignalAsrPath(Pattern) matches signal instances which are referenced at least by one
ISignal/ISignalGroup with the given autosar path pattern.
• physicalChannel(String) matches signal instances which are referenced by at least an
ISignal/ISignalGroup for which an ISignalTriggering exists for a PhysicalChannel with
the given name.
• physicalChannel(Pattern) matches signal instances which are referenced by at least an
ISignal/ISignalGroup for which an ISignalTriggering exists for a PhysicalChannel with
the given name pattern.
• physicalChannelAsrPath(String) matches signal instances which are referenced by at
least an ISignal/ISignalGroup for which an ISignalTriggering exists for a PhysicalChannel
with the given autosar path.
• physicalChannelAsrPath(Pattern) matches signal instances which are referenced by at
least an ISignal/ISignalGroup for which an ISignalTriggering exists for a PhysicalChannel
with the given autosar path pattern.
• communicationCluster(String) matches signal instances which are referenced by at
least an ISignal/ISignalGroup which is sent via a PhysicalChannel of a Communication-
Cluster with the given name.
• communicationCluster(Pattern) matches signal instances which are referenced by at
least an ISignal/ISignalGroup which is sent via a PhysicalChannel of a Communication-
Cluster with the given name pattern.
© 2017, Vector Informatik GmbH
149 of 250

---

Chapter 4.
AutomationInterface API Reference
• communicationClusterAsrPath(String) matches signal instances which are referenced
by at least an ISignal/ISignalGroup which is sent via a PhysicalChannel of a Communi-
cationCluster with the given autosar path.
• communicationClusterAsrPath(Pattern) matches signal instances which are referenced
by at least an ISignal/ISignalGroup which is sent via a PhysicalChannel of a Communi-
cationCluster with the given autosar path pattern.
• pdu(String) matches signal instances which are referenced by at least an ISignal/ISig-
nalGroup for which an ISignalToIPduMapping exists for a Pdu with the given name.
• pdu(Pattern) matches signal instances which are referenced by at least an ISignal/I-
SignalGroup for which an ISignalToIPduMapping exists for a Pdu with the given name
pattern.
• pduAsrPath(String) matches signal instances which are referenced by at least an ISig-
nal/ISignalGroup for which an ISignalToIPduMapping exists for a Pdu with the given
autosar path.
• pduAsrPath(Pattern) matches signal instances which are referenced by at least an ISig-
nal/ISignalGroup for which an ISignalToIPduMapping exists for a Pdu with the given
autosar path pattern.
• frame(String) matches signal instances which are referenced by at least an ISignal/I-
SignalGroup which is sent via a Pdu for that a PduToFrameMapping exists for a Frame
with the given name.
• frame(Pattern) matches signal instances which are referenced by at least an ISignal/I-
SignalGroup which is sent via a Pdu for that a PduToFrameMapping exists for a Frame
with the given name pattern.
• frameAsrPath(String) matches signal instances which are referenced by at least an ISig-
nal/ISignalGroup which is sent via a Pdu for that a PduToFrameMapping exists for a
Frame with the given autosar path.
• frameAsrPath(Pattern) matches signal instances which are referenced by at least an
ISignal/ISignalGroup which is sent via a Pdu for that a PduToFrameMapping exists for
a Frame with the given autosar path pattern.
• filterAdvanced(Closure) matches signal instances for which the given closure results
to true.
• and(Closure) combines the predicates inside the closure with a logical AND.
• or(Closure) combines the predicates inside the closure with a logical OR.
• not(Closure) negates the combination of predicates inside the closure.
Examples
© 2017, Vector Informatik GmbH
150 of 250

---

Chapter 4.
AutomationInterface API Reference
scriptTask (" SelectAllUnmappedSignalInstances ", DV_PROJECT ){
code {
transaction {
domain . runtimeSystem {
def s i g n a l I n s t a n c e s =
selectSignalInstances {
unmapped () // select all signal instances which are not yet
data mapped
} getSignalInstances ()
scriptLogger . infoFormat (" Selected {0} signal instances .",
signalInstances . size ())
}
}
}
}
Listing 4.190: Select all unmapped signal instances
scriptTask (" SelectAllUnmappedRxOrTransformedSignalInstances ", DV_PROJECT ){
code {
transaction {
domain . runtimeSystem {
def s i g n a l I n s t a n c e s =
selectSignalInstances {
// the signal instances should not be data - mapped yet
unmapped ()
or { // and should either be a rx signal or a transformation
signal
rx ()
transformed ()
}
} getSignalInstances ()
scriptLogger . infoFormat (" Selected {0} signal instances .",
signalInstances . size ())
}
}
}
}
Listing 4.191: Select all unmapped rx or transformed signal instances
© 2017, Vector Informatik GmbH
151 of 250

---

Chapter 4.
AutomationInterface API Reference
i m p o r t com . vector . cfg . model . sysdesc . api . com . I A b s t r a c t S i g n a l I n s t a n c e
scriptTask (" SelectSignalInstancesUsingAdvancedFilter ", DV_PROJECT ){
code {
transaction {
domain . runtimeSystem {
def s i g n a l I n s t a n c e s =
selectSignalInstances {
filterAdvanced { IAbstractSignalInstance signalInstance ->
// implement own custom filter
def m df Ob je ct = s i g n a l I n s t a n c e . g e t M d f O b j e c t ()
// work on directly on autosar model level ...
// select signal instance only which has admin data
def select = false
mdfObject . adminData {
select = true
}select
}
} getSignalInstances ()
scriptLogger . infoFormat (" Selected {0} signal instances .",
signalInstances . size ())
}
}
}
}
Listing 4.192: Select signal instances using an advanced filter
Auto-Mapping
The use case of auto-mapping signal instances is based on the selection of
signal instances: it offers the methods to auto-map.
autoMap() tries to auto-map the selection of IAbstractSignalInstances (ISignalInstance
or ISignalGroupInstance) according the data mapping assistant default rules. Therefore the
selection of possible target communication elements is computed and tried to match to the
selected signal instances.
Examples for autoMap()
scriptTask (" autoDatamapAllUnmappedSignalInstances ", DV_PROJECT ){
code {
transaction {
domain . runtimeSystem {
def d a t a M a p p i n g s =
selectSignalInstances {
unmapped ()
} autoMap ()
scriptLogger . infoFormat (" Created {0} data mappings .",
dataMappings . size ())
}
}
}
}
Listing 4.193: Auto data map all unmapped signal instances
autoMapTo(Closure) tries to auto-map the selection of signal instances according the data
mapping assistant rules but offers more control for the auto-mapping: Inside the closure ad-
ditional predicates for narrowing down the target communication elements can be defined and
code to evaluate and change the auto-mapper results can be provided.
© 2017, Vector Informatik GmbH
152 of 250

---

Chapter 4.
AutomationInterface API Reference
autoMapTo(Closure) will produce trace, info and warning logs.
To see them, activate the
’com.vector.cfg.dom.runtimesys.groovy.api.ISignalInstanceSelection’ logger with the
appropriate log level.
Control the auto-mapping in autoMapTo(Closure)
selectTargetCommunicationElements(Closure) allows to define predicates to narrow down
the target communciation elements for the auto-mapping. The predicates are used to filter
the possible target communication elements which were computed from the signal instance
selection.
evaluateMatches(Closure) allows to evaluate and change the results of the auto-mapping. It
corresponds to the confirm page of the data mapping assistant.
For each signal instance the provided closure is called: Parameters are the signal instance,
the optional matched target communication element (or null), and a list of all potential tar-
get communication elements (respecting the selectTargetCommunicationElements(Closure)
predicates). The return value must be a communication element or null.
i m p o r t com . vector . cfg . model . sysdesc . api . com . I A b s t r a c t S i g n a l I n s t a n c e
i m p o r t com . vector . cfg . model . sysdesc . api . com . I C o m m u n i c a t i o n E l e m e n t
scriptTask (" autoDatamapAllUnmappedSignalInstancesAndEvaluate ", DV_PROJECT ){
code {
transaction {
domain . runtimeSystem {
def d a t a M a p p i n g s =
selectSignalInstances {
unmapped ()
} autoMapTo {
selectTargetCommunicationElements {
unmapped ()
}evaluateMatches {
IAbstractSignalInstance signal ,
ICommunicationElement optionalMatchedComElement ,
List < ICommunicationElement >
potentialComElements
->// evaluate
optionalMatchedComElement
}
}
scriptLogger . infoFormat (" Created {0} data mappings .",
dataMappings . size ())
}
}
}
}
Listing 4.194: Auto data map all unmapped signal instances to unmapped communication
elements and evaluate
Nested Array of Primitives
expandNestedArraysOfPrimitive(boolean) allows to control
the expansion of nested arrays of primitive globally. Per default, arrays are fully expanded
(allowing to data map each array element). By setting the value to ’false’, all nested arrays of
primitive are not expanded and can be directly data-mapped to a signal.
© 2017, Vector Informatik GmbH
153 of 250

---

Chapter 4.
AutomationInterface API Reference
i m p o r t com . vector . cfg . model . sysdesc . api . com . I A b s t r a c t S i g n a l I n s t a n c e
i m p o r t com . vector . cfg . model . sysdesc . api . com . I C o m m u n i c a t i o n E l e m e n t
scriptTask (" autoDatamapAllSignalInstancesAndDoNotExpandNestedArrayElements ",
DV_PROJECT ){
code {
transaction {
domain . runtimeSystem {
def d a t a M a p p i n g s =
selectSignalInstances {
} autoMapTo {
// do not expand nested array elements
expandNestedArraysOfPrimitive false
evaluateMatches {
IAbstractSignalInstance signal ,
ICommunicationElement optionalMatchedComElement ,
List < ICommunicationElement >
potentialComElements ->
// perform manual mapping to a signal group
if ( signal . getName () . equals ( " e l e m B _ c 2 5 5 f 5 e 3 8 f d 8 b 2 1 d " ) ) {
for ( final I C o m m u n i c a t i o n E l e m e n t c o m El eme nt :
potentialComElements ) {
if ( c o m E l e m e n t . g e t F u l l y Q u a l i f i e d N a m e () . equals ( " App2 .
rSRPort1 . Element_2 ")) {
r e t u r n c o m E l e m e n t
}
}
}
// now check : for the group signal the the record element
representing an array is not expanded
if ( signal . getName () . equals ( " f i e l d A _ f 1 d 3 7 8 3 e 2 3 5 e 8 8 d 3 " ) ) {
// group signal
for ( final I C o m m u n i c a t i o n E l e m e n t c o m El eme nt :
potentialComElements ) {
if ( c o m E l e m e n t . g e t F u l l y Q u a l i f i e d N a m e () . equals ( " App2 .
rSRPort1 . Element_2 . RecordElement ")) {
// do some direct mapping here
}
}
}optionalMatchedComElement
}
}
scriptLogger . infoFormat (" Created {0} data mappings .", dataMappings . size
())
}
}
}
}
Listing 4.195: Auto data map all signal instances and do not expand nested array elements
expandNestedArraysOfPrimitive(String,boolean) allows to control the expansion of nested
arrays of primitive for single nested arrays. Per default, the expandNestedArraysOfPrimi-
tive(boolean) applies. For the given fully qualified communication element name, the global
setting can be overridden.
© 2017, Vector Informatik GmbH
154 of 250

---

Chapter 4.
AutomationInterface API Reference
i m p o r t com . vector . cfg . model . sysdesc . api . com . I A b s t r a c t S i g n a l I n s t a n c e
i m p o r t com . vector . cfg . model . sysdesc . api . com . I C o m m u n i c a t i o n E l e m e n t
scriptTask (" autoDatamapAllSignalInstancesAndDoExpandSpecificNestedArrayElement "
, DV_PROJECT ){
code {
transaction {
domain . runtimeSystem {
def d a t a M a p p i n g s =
selectSignalInstances {
} autoMapTo {
// do not expand nested array elements
expandNestedArraysOfPrimitive false
expandNestedArraysOfPrimitive ( " App2 . rSRPort1 . Element_2 .
RecordElement ",true )
evaluateMatches {
IAbstractSignalInstance signal ,
ICommunicationElement optionalMatchedComElement ,
List < ICommunicationElement >
potentialComElements ->
// perform manual mapping to a signal group
if ( signal . getName () . equals ( " e l e m B _ c 2 5 5 f 5 e 3 8 f d 8 b 2 1 d " ) ) {
for ( final I C o m m u n i c a t i o n E l e m e n t c o m El eme nt :
potentialComElements ) {
if ( c o m E l e m e n t . g e t F u l l y Q u a l i f i e d N a m e () . equals ( " App2 .
rSRPort1 . Element_2 ")) {
r e t u r n c o m E l e m e n t
}
}
}
// now check : for the group signal the the record element
representing an array is expanded :
// the single array elements can be mapped
if ( signal . getName () . equals ( " f i e l d A _ f 1 d 3 7 8 3 e 2 3 5 e 8 8 d 3 " ) ) {
// group signal
for ( final I C o m m u n i c a t i o n E l e m e n t c o m El eme nt :
potentialComElements ) {
if ( c o m E l e m e n t . g e t F u l l y Q u a l i f i e d N a m e () . equals ( " App2 .
rSRPort1 . Element_2 . RecordElement [0] ")) {
// do some direct mapping to array element here
}
}
}optionalMatchedComElement
}
}
scriptLogger . infoFormat (" Created {0} data mappings .", dataMappings . size
())
}
}
}
}
Listing 4.196: Auto data map all signal instances and expand specific nested array element
Mapping communication elements
selectCommunicationElements(Closure) allows the se-
lection of ICommunicationElements using predicates.
Per default the predicates are combined via logical AND. To realize other combinations, use
the ’or’,’not’ and ’and’ predicates.
© 2017, Vector Informatik GmbH
155 of 250

---

Chapter 4.
AutomationInterface API Reference
Communication Element Predicates
• unconnected() matches communication elements whose component port is unconnected.
• connected() matches communication elements whose component port is connected.
• senderReceiver() matches communication elements whose port has a sender/receiver
port interface.
• clientServer() matches communication elements whose port has a client/server port
interface.
• provided() matches communication elements whose port is a provided port (p-port).
• required() matches communication elements whose port is a required port (r-port).
• delegation() matches communication elements whose port is delegation port.
• unmapped() matches communication elements whose are not data-mapped.
• mapped() matches communication elements whose are data-mapped.
• name(String) matches communication elements with the given data element or operation
name.
• name(Pattern) matches communication elements with the given data element or opera-
tion name pattern.
• asrPath(String) matches communication elements with the given data element or ope-
ration autosar path.
• asrPath(Pattern) matches communication elements with the given data element or ope-
ration autosar path pattern.
• component(String) matches communication elements with the given component name.
• component(Pattern) matches communication elements with the given component name
pattern.
• componentAsrPath(String) matches communication elements with the given component
name autosar path.
• componentAsrPath(Pattern) matches communication elements with the given compo-
nent name autosar path pattern.
• port(String) matches communication elements with the given component port name.
• port(Pattern) matches communication elements with the given component port name
pattern.
• portAsrPath(String) matches communication elements with the given component port
autosar path.
• portAsrPath(Pattern) matches communication elements with the given component port
autosar path pattern.
• filterAdvanced(Closure) Add a custom predicated which matches communication ele-
ments for which the given closure results to true.
• and(Closure) combines the predicates inside the closure with a logical AND.
• or(Closure) combines the predicates inside the closure with a logical OR.
• not(Closure) negates the combination of predicates inside the closure.
© 2017, Vector Informatik GmbH
156 of 250

---

Chapter 4.
AutomationInterface API Reference
Examples
scriptTask (" SelectAllUnmappedDelPortComElements ", DV_PROJECT ){
code {
transaction {
domain . runtimeSystem {
def c o m E l e m e n t s =
selectCommunicationElements {
// select all unmapped delegation communication elements
delegation ()
unmapped ()
} getCommunicationElements ()
scriptLogger . infoFormat (" Selected {0} communication elements .",
comElements . size ())
}
}
}
}
Listing 4.197: Select all unmapped delegation port communication elements
i m p o r t com . vector . cfg . model . sysdesc . api . com . I C o m m u n i c a t i o n E l e m e n t
i m p o r t com . vector . cfg . model . sysdesc . api . com . I D a t a C o m m u n i c a t i o n E l e m e n t
scriptTask (" SelectComElementsUsingAdvancedFilter ", DV_PROJECT ){
code {
transaction {
domain . runtimeSystem {
def c o m E l e m e n t s =
selectCommunicationElements {
// advanced filter :
// only select communication elements
// which represent data elements of a specific data type
filterAdvanced { ICommunicationElement comElement ->
if ( c o m E l e m e n t i n s t a n c e o f I D a t a C o m m u n i c a t i o n E l e m e n t ) {
def m d f D a t a E l e m e n t = c o m E l em en t .
getDataElementOrOperationMdfObject ()
// check directly on autosar model level
r e t u r n
mdfDataElement . type . refTarget . name . equals ("
myCustomDataType ")
}
f a l s e
}
} getCommunicationElements ()
scriptLogger . infoFormat (" Selected {0} communication elements .",
comElements . size ())
}
}
}
}
Listing 4.198: Select communication elements using an advanced filter
autoMap() tries to auto-map the selection of ICommunicationElements (IDataCommunicationElement
or IOperationCommunicationElement) according the data mapping assistant default rules.
Therefore the selection of possible target signal instances is computed and tried to match to
the selected communciation elements.
Examples for autoMap()
© 2017, Vector Informatik GmbH
157 of 250

---

Chapter 4.
AutomationInterface API Reference
scriptTask (" autoDatamapAllUnmappedSRDelPortComElements ", DV_PROJECT ){
code {
transaction {
domain . runtimeSystem {
def d a t a M a p p i n g s =
selectCommunicationElements {
// select all unmapped sender / receiver delegation ports
delegation ()
unmapped ()
senderReceiver ();
} autoMap ()
scriptLogger . infoFormat (" Created {0} data mappings .", dataMappings . size
())
}
}
}
}
Listing 4.199: Auto data map all unmapped sender/receiver delegation port communication
elements
autoMapTo(Closure) tries to auto-map the selection of communciation elements according the
data mapping assistant rules but offers more control for the auto-mapping: Inside the closure
additional predicates for narrowing down the target signal instances can be defined and code
to evaluate and change the auto-mapper results can be provided.
autoMapTo(Closure) will produce trace, info and warning logs.
To see them, activate the
’com.vector.cfg.dom.runtimesys.groovy.api.ICommunicationElementSelection’ logger with
the appropriate log level.
Control the auto-mapping in autoMapTo(Closure)
selectTargetSignalInstances(Closure) allows to define predicates to narrow down the tar-
get signal instances for the auto-mapping. The predicates are used to filter the possible target
signal instances which were computed from the communication element selection.
evaluateMatches(Closure) allows to evaluate and change the results of the auto-mapping. It
corresponds to the confirm page of the data mapping assistant.
For each communication element the provided closure is called: Parameters are the communi-
cation element, the optional matched target signal instance (or null), and a list of all potential
target signal instances (respecting the selectTargetSignalInstances(Closure) predicates).
The return value must be a signal instance or null.
© 2017, Vector Informatik GmbH
158 of 250

---

Chapter 4.
AutomationInterface API Reference
i m p o r t com . vector . cfg . model . sysdesc . api . com . I A b s t r a c t S i g n a l I n s t a n c e
i m p o r t com . vector . cfg . model . sysdesc . api . com . I C o m m u n i c a t i o n E l e m e n t
scriptTask (" autoDatamapAllUnmappedComElementsAndEvaluate ", DV_PROJECT ){
code {
transaction {
domain . runtimeSystem {
def d a t a M a p p i n g s =
selectCommunicationElements {
unmapped () // only unmapped communication elements
} autoMapTo {
selectTargetSignalInstances {
// only map to unmapped rx signal instances
unmapped ()
rx ()
}evaluateMatches {
ICommunicationElement
communicationElement ,
IAbstractSignalInstance optionalMatchedSignalInstance ,
List < IAbstractSignalInstance >
potentialSignalinstances ->
// evaluate the match here
if ( o p t i o n a l M a t c h e d S i g n a l I n s t a n c e != null ) {
def m d f S y s t e m S i g n a l =
optionalMatchedSignalInstance . getMdfObject ()
;
// check more specific ...
}optionalMatchedSignalInstance
}
}
scriptLogger . infoFormat (" Created {0} data mappings .", dataMappings . size
())
}
}
}
}
Listing 4.200: Auto data map all unmapped communication elements to unmapped rx signal
instances and evaluate
Nested Array of Primitives
expandNestedArraysOfPrimitive(boolean) allows to control
the expansion of nested arrays of primitive globally. Per default, arrays are fully expanded
(allowing to data map each array element). By setting the value to ’false’, all nested arrays of
primitive are not expanded and can be directly data-mapped to a signal.
© 2017, Vector Informatik GmbH
159 of 250

---

Chapter 4.
AutomationInterface API Reference
i m p o r t com . vector . cfg . model . sysdesc . api . com . I A b s t r a c t S i g n a l I n s t a n c e
i m p o r t com . vector . cfg . model . sysdesc . api . com . I S i g n a l G r o u p I n s t a n c e
i m p o r t com . vector . cfg . model . sysdesc . api . com . I C o m m u n i c a t i o n E l e m e n t
scriptTask (" autoDatamapDoNotExpandNestedArrayElements ", DV_PROJECT ){
code {
transaction {
domain . runtimeSystem {
def d a t a M a p p i n g s =
selectCommunicationElements {
} autoMapTo {
expandNestedArraysOfPrimitive false // do not expand nested arrays
of primitive
evaluateMatches {
ICommunicationElement
communicationElement ,
IAbstractSignalInstance optionalMatchedSignalInstance ,
List < IAbstractSignalInstance >
potentialSignalInstances ->
if ( " App2 . rSRPort1 . E le me nt _2 " . equals ( c o m m u n i c a t i o n E l e m e n t .
getFullyQualifiedName ())) {
// manual matching : map to first signal group
for ( I A b s t r a c t S i g n a l I n s t a n c e p o t e n t i a l S i g n a l :
potentialSignalInstances ) {
if ( p o t e n t i a l S i g n a l in st an ce o f I S i g n a l G r o u p I n s t a n c e
) {
r e t u r n
potentialSignal
}
}
}
if ( " App2 . rSRPort1 . E le me nt _2 . R e c o r d E l e m e n t " . equals (
communicationElement . getFullyQualifiedName ())) {
// now the RecordElement which represents an array is
directly offered to map
// ....
}optionalMatchedSignalInstance
}
}
scriptLogger . infoFormat (" Created {0} data mappings .", dataMappings . size
())
}
}
}
}
Listing 4.201: Autodatamap and do not expand nested array elements
expandNestedArraysOfPrimitive(String,boolean) allows to control the expansion of nested
arrays of primitive for single nested arrays. Per default, the expandNestedArraysOfPrimi-
tive(boolean) applies. For the given fully qualified communication element name, the global
setting can be overridden.
The fully qualified communication element name is e.g. determinable when using the data
mapping assistant, performing an arbitrary signal group mapping of the root data element,
and using the right-mouse menu its ’Copy fully qualified name’ action on the nested array
element.
© 2017, Vector Informatik GmbH
160 of 250

---

Chapter 4.
AutomationInterface API Reference
i m p o r t com . vector . cfg . model . sysdesc . api . com . I A b s t r a c t S i g n a l I n s t a n c e
i m p o r t com . vector . cfg . model . sysdesc . api . com . I S i g n a l G r o u p I n s t a n c e
i m p o r t com . vector . cfg . model . sysdesc . api . com . I C o m m u n i c a t i o n E l e m e n t
scriptTask (" autoDatamapDoExpandSpecificNestedArrayElement ", DV_PROJECT ){
code {
transaction {
domain . runtimeSystem {
def d a t a M a p p i n g s =
selectCommunicationElements {
} autoMapTo {
// do not generally expand nested arrays of primitive
expandNestedArraysOfPrimitive false
// but expand the following specific record element
expandNestedArraysOfPrimitive (" App2 . rSRPort1 . Element_2 .
RecordElement ",true )
evaluateMatches {
ICommunicationElement
communicationElement ,
IAbstractSignalInstance optionalMatchedSignalInstance ,
List < IAbstractSignalInstance >
potentialSignalInstances ->
if ( " App2 . rSRPort1 . E le me nt _2 " . equals (
communicationElement . getFullyQualifiedName ())) {
// manual matching : map to first signal group
for ( I A b s t r a c t S i g n a l I n s t a n c e p o t e n t i a l S i g n a l :
potentialSignalInstances ) {
if ( p o t e n t i a l S i g n a l in st an ce of
ISignalGroupInstance ) {
r e t u r n
potentialSignal
}
}
}
if ( " App2 . rSRPort1 . E le me nt _2 . R e c o r d E l e m e n t [0] " . equals (
communicationElement . getFullyQualifiedName ())) {
// the RecordElement ( representing an array of
primitive )
is expanded to map the single array
elements
// ....
}optionalMatchedSignalInstance
}
}
scriptLogger . infoFormat (" Created {0} data mappings .", dataMappings . size
())
}
}
}
}
Listing 4.202: Autodatamap and do expand a specific nested array element
© 2017, Vector Informatik GmbH
161 of 250

---

Chapter 4.
AutomationInterface API Reference
4.11 Persistency
The persistency API provides methods which allow to import and export model data from
and to files. The files are normally in the AUTOSAR .arxml format.
4.11.1 Model Export
The modelExporty allows to export MDF model data into .arxml files.
To access the export functionality use one of the getModelExport() or modelExport(Closure)
methods.
// You can access the API in every active project
def ex po rt Ap i = p e r s i s t e n c y . m o d e l E x p o r t
// Or you use a closure
persistency . modelExport {
}
Listing 4.203: Accessing the model export persistency API
4.11.1.1 Export ActiveEcuc
The method exportActiveEcuc(Object) exports the whole ActiveEcuC configuration into a
single file of type Path.
scriptTask ('taskName ') {
code {
def t e m p E x p o r t F o l d e r = paths . r e s o l v e T e m p P a t h ( " . " )
def r e s u l t F i l e = p e r s i s t e n c y . m o d e l E x p o r t . e x p o r t A c t i v e E c u c (
tempExportFolder )
}
}
Listing 4.204: Export the ActiveEcuc to a file
4.11.1.2 Export Post-build selectable Variants
The method exportPostbuildVariants(Object) exports the Post-build variants info. This
will export the ActiveEcuc and miscellaneous data. The ActiveEcuC is exported into one file
(even for split DPA-projects) per variant into <project-name>.<variant-name>.ecuc.arxml.
Miscellaneous data is exported into one file per variant. The files contain all data of the project
except:
• ModuleConfigurations, ModuleDefinitions
• BswImplementations, EcuConfigurations
• Variant information like EvaluatedVariantSet
The created files are <project-name>.<variant-name>.misc.arxml.
The method returns a List<Path> of exported files.
© 2017, Vector Informatik GmbH
162 of 250

---

Chapter 4.
AutomationInterface API Reference
scriptTask ('taskName ') {
code {
persistency . modelExport {
def t e m p E x p o r t F o l d e r = paths . r e s o l v e T e m p P a t h ( " . " )
def fileList = e x p o r t P o s t b u i l d V a r i a n t s ( t e m p E x p o r t F o l d e r )
}
}
}
Listing 4.205: Export a Post-build selectable project as variant files
4.11.1.3 Advanced Export
The advanced export use case provides access to multiple IModelExporter for special export
use cases like export the system description for the RTE.
Normally you would retrieve an IModelExporter by its ID via getExporter(String). On
this exporter you can call IModelExporter.export(Object) to export the model, or IMo-
delExporter.exportAsPostbuildVariants(Object) to export the model as variant divided
data.
You can retrieve a list of supported exporters from getAvailableExporter(). The list can
differ from data loaded in your project.
scriptTask ('taskName ') {
code {
def t e m p E x p o r t F o l d e r = paths . r e s o l v e T e m p P a t h ( " . " )
// Export with an exporter in one line
persistency . modelExport [" activeEcuc "]. export ( tempExportFolder )
}
}
Listing 4.206: Export the project with an exporter
scriptTask ('taskName ') {
code {
def t e m p E x p o r t F o l d e r = paths . r e s o l v e T e m p P a t h ( " . " )
def fileList
// Switch to the persistency export API
persistency . modelExport {
// The getAvailableExporter () returns all exporters in the system
def e x p o r t e r L i s t = g e t A v a i l a b l e E x p o r t e r ()
// Select an exporter by its ID
def e x p o r t e r O p t = g e t E x p o r t e r ( " a c t i v eEc uc " )
exporterOpt . ifPresent { exporter ->
// Export into folder , when exporter exists
fileList = exporter . export ( tempExportFolder )
}
}
}
}
Listing 4.207: Export the project with an exporter and checks
© 2017, Vector Informatik GmbH
163 of 250

---

Chapter 4.
AutomationInterface API Reference
Export an Model Tree
The method exportModelTree(Object, MIObject) exports the spe-
cified model object and the subtree into a single file of type Path.
scriptTask ('taskName ') {
code {
def e x p o r t F o l d e r = paths . r e s o l v e T e m p P a t h ( " . " )
MIARPackage autosarPkg = mdfModel ( AsrPath . create ("/ MICROSAR "))
def r e s u l t F i l e = p e r s i s t e n c y . m o d e l E x p o r t . e x p o r t M o d e l T r e e ( exportFolder ,
autosarPkg )
}
}
Listing 4.208: Export an AUTOSAR package to a file
Export an Model Tree including all referenced Elements
You could also export model trees
including all referenced elements with the exporter modelTreeClosure:
scriptTask ('taskName ') {
code {
def e x p o r t F o l d e r = paths . r e s o l v e T e m p P a t h ( " . " )
MIARPackage microsarPkg = mdfModel ( AsrPath . create ("/ MICROSAR "))
MIARPackage autosarPkg = mdfModel ( AsrPath . create ("/ AUTOSAR "))
persistency . modelExport [" modelTreeClosure "]. export ( exportFolder ,
autosarPkg , microsarPkg )
}
}
Listing 4.209: Exports two elements and all references elements
4.11.2 Model Import
The modelImport allows to import MDF model data from .arxml files.
To access the import functionality use one of the getModelImport() or modelImport(Closure)
methods.
Currently no import API is provided. Please inform Vector, if you need an import
API.
// You can access the API in every active project
def im po rt Ap i = p e r s i s t e n c y . m o d e l I m p o r t
// Or you use a closure
persistency . modelImport {
}
Listing 4.210: Accessing the model import persistency API
© 2017, Vector Informatik GmbH
164 of 250

---

Chapter 4.
AutomationInterface API Reference
4.12 Utilities
4.12.1 Constraints
Constraints provides general purpose constraints for checking given parameter values throug-
hout the automation interface. These constraints are referenced from the AutomationInterface
documentation wherever they apply. The AutomationInterface takes a fail fast approach ve-
rifying provided parameter values as early as possible and throwing appropriate exceptions if
values violate the corresponding constraints.
The following constraints are provided:
IS_NOT_NULL
Ensures that the given Object is not null.
IS_NON_EMPTY_STRING
Ensures that the given String is not empty.
IS_VALID_FILE_NAME
Ensures that the given String can be used as a file name.
IS_VALID_PROJECT_NAME
Ensures that the given String can be used as a name for a
project. A valid project name starts with a letter [a-zA-Z] contains otherwise only characters
matching [a-zA-Z0-9_] and is at most 128 characters long.
IS_NON_EMPTY_ITERABLE
Ensures that the given Iterable is not empty.
IS_VALID_AUTOSAR_SHORT_NAME
Ensures that the given String conforms to the
syntactical requirements for AUTOSAR short names.
IS_VALID_AUTOSAR_SHORT_NAME_PATH
Ensures that the given String conforms
to the syntactical requirements for AUTOSAR short name paths.
IS_WRITABLE
Ensures that the file or folder represented by the given Path exists and can
be written to.
IS_READABLE
Ensures that the file or folder represented by the given Path exists and can
be read.
IS_EXISTING_FOLDER
Ensures that the given Path points to an existing folder.
IS_EXISTING_FILE
Ensures that the given Path points to an existing file.
IS_CREATABLE_FOLDER
Ensures that the given Path either points to an existing folder
which can be written to or points to a location at which a corresponding folder could be
created.
© 2017, Vector Informatik GmbH
165 of 250

---

Chapter 4.
AutomationInterface API Reference
IS_DCF_FILE
Ensures that the given Path points to a DaVinci Developer workspace file
(.dcf file).
IS_DPA_FILE
Ensures that the given Path points to a DaVinci project file (.dpa file).
IS_ARXML_FILE
Ensures that the given Path points to an .arxml file.
IS_SYSTEM_DESCRIPTION_FILE
Ensures that the given Path points to a system des-
cription input file (.arxml, .dbc, .ldf, .xml or .vsde file).
IS_COMPATIBLE_DA_VINCI_DEV_EXECUTABLE
Ensures that the given Path points
to a compatible DaVinci Developer executable (DaVinciDEV.exe).
4.12.2 Converters
General purpose converters (java.util.Functions) for performing value conversions throug-
hout the automation interface are provided. These converters are referenced from the Automa-
tionInterface documentation wherever they apply. The AutomationInterface is typed strongly.
In some cases, however, e.g. when specifying file locations, it is desirable to allow for a range
of possibly parameter types. This is achieved by accepting parameters of type Object and
converting the given parameters to the desired type.
The following converters are provided:
ScriptConverters.TO_PATH
Attempts to convert arbitrary Objects to Paths using
IAutomationPathsApi.resolvePath(Object) 4.4.3.2 on page 36.
ScriptConverters.TO_SCRIPT_PATH
Attempts to convert arbitrary Objects to Paths using
IAutomationPathsApi.resolveScriptPath(Object) 4.4.3.3 on page 37.
ScriptConverters.TO_VERSION
Attempts to convert arbitrary Objects to IVersions. The
following conversions are implemented:
• For null or IVersion arguments the given argument is returned. No conversion is applied.
• Strings are converted using Version.valueOf(String).
• Numbers are converted by converting the int obtained from Number.intValue() using
Version.valueOf(int).
• All other Objects are converted by converting the String obtained from Object.toString().
ScriptConverters.TO_BIG_INTEGER
Attempts to convert arbitrary Objects to BigInte-
gers. The following conversions are implemented:
• For null or BigInteger arguments the given argument is returned. No conversion is
applied.
• Integers, Longs, Shorts and Bytes are converted using BigInteger.valueOf(long).
© 2017, Vector Informatik GmbH
166 of 250

---

Chapter 4.
AutomationInterface API Reference
• All other types of objects are interpreted as Strings (Object.toString()) and passed
to BigInteger.BigInteger(String).
ScriptConverters.TO_BIG_DECIMAL
Attempts to convert arbitrary Objects to BigDeci-
mals. The following conversions are implemented:
• For null or BigDecimal arguments the given argument is returned. No conversion is
applied.
• Floats and Doubles, are converted using BigDecimal.valueOf(double).
• Integers, Longs, Shorts and Bytes are converted using BigDecimal.valueOf(long).
• All other types of objects are interpreted as Strings (Object.toString()) and passed
to BigDecimal.BigDecimal(String).
ModelConverters.TO_MDF
Attempts to convert arbitrary Objects to MDFObjects.
The
following conversions are implemented:
• For null or MDFObject arguments the given argument is returned. No conversion is
applied.
• IHasModelObjects are converted using their getMdfModelElement() method.
• IViewedModelObjects are converted using their getMdfObject() method.
• For all other Objects ClassCastExceptions are thrown.
For thrown Exceptions see the used functions described above.
© 2017, Vector Informatik GmbH
167 of 250

---

Chapter 4.
AutomationInterface API Reference
4.13 Advanced Topics
This chapter contains advanced use cases and classes for special tasks. For a normal script these
items are not relevant.
4.13.1 Java Development
It is also possible to write automation scripts in plain Java code, but this is not recommended.
There are some items in the API, which need a different usage in Java code.
This chapter describes the differences in the Automation API when used from Java code.
4.13.1.1 Script Task Creation in Java Code
Java code could not use the Groovy syntax to provide script tasks. So another way is needed
for this. The IScriptFactory interface provides the entry point that Java code could provide
script tasks. The createScript(IScriptCreationApi) method is called when the script is
loaded.
This interface is not necessary for Groovy clients.
p u b l i c c l a s s
MyScriptFactoryAsJavaCode implements IScriptFactory {
@Override
p u b l i c v o i d c r e a t e S c r i p t ( I S c r i p t C r e a t i o n A p i creation ) {
creation . scriptTask (" TaskFromFactory ", IScriptTaskTypeApi .
DV_APPLICATION ,
( taskBuilder ) -> {
taskBuilder . code (
( scriptExecutionContext , taskArgs ) -> {
// Your script task code here
r e t u r n n u l l ;
});
});
creation . scriptTask (" Task2 ", IScriptTaskTypeApi . DV_PROJECT ,
( taskBuilder ) -> {
taskBuilder . code (
( scriptExecutionContext , taskArgs ) -> {
// Your script task code for Task2
here
r e t u r n n u l l ;
});
});
}
}
Listing 4.211: Java code usage of the IScriptFactory to contribute script tasks
You should try to use Groovy when possible, because it is more concise than the Java code,
without any difference at script task creation and execution.
4.13.1.2 Java Code accessing Groovy API
Most of the Automation API is usable from both languages Java and Groovy, but some methods
are written for Groovy clients. To use it from Java you have to write some glue code.
© 2017, Vector Informatik GmbH
168 of 250

---

Chapter 4.
AutomationInterface API Reference
Differences are:
• Accessing Properties
• Using API entry points.
• Creating Closures
Accessing Properties
Properties are not supported by Java so you have to use the getter/setter
methods instead.
API Entry Points
Most of the Automation API is added to the object by so called Dy-
namicObjects.
This is not available in Java, so you have to call IScriptExecutionCon-
text.getInstance(Class) instead.
So if you want to access The IWorkflowApi you have
to write:
// Java code :
IScriptExecutionContext scriptCtx = ...;
IWorkflowApi workflow = scriptCtx . getInstance ( IWorkflowApiEntryPoint . class ).
getWorkflow ()
// Instead of Groovy code :
workflow {
}
Listing 4.212: Accessing WorkflowAPI in Java code
Creating Closure instances from Java lambdas
The class Closures provides API to create
Closure instances from Java FunctionalInterfaces.
The from() methods could be used to call Groovy API from Java classes, which only accepts
Closure instances.
Sample:
Closure <?> c = Closures . from (( param ) -> {
// Java lambda
});
Listing 4.213: Java Closure creation sample
Creating Closure Instances from Java Methods
You could also create arbitrary Closures
from any Java method with the class MethodClosure. This is describe in:
http://melix.github.io/blog/2010/04/19/coding_a_groovy_closure_in.html1
4.13.1.3 Java Code in dvgroovy Scripts
It is not possible to write Java classes when using the .dvgroovy script file. You have to create
an automation script project, see chapter 7 on page 217.
1Last accessed 2016-05-24
© 2017, Vector Informatik GmbH
169 of 250

---

Chapter 4.
AutomationInterface API Reference
4.13.2 Unit testing API
The Automation Interface provides an connector to execute unit tests as script task. This is
helpful, if you want to write tests for:
• Generators
• Validations
• Workflow rules
• ...
Normally a script task executes it’s code block, but the unit test task will execute all contained
unit tests instead.
4.13.2.1 JUnit4 Integration
The AutomationInterface can execute JUnit 4 test cases and test suites.
Execution of JUnit Test Classes
A simple unit test class will look like:
i m p o r t org . junit . Test ;
p u b l i c c l a s s S c r i p t J U n i t T e s t {
@Test
p u b l i c v o i d t e s t Y o u r L o g i c () {
// Write your test code here
}
Listing 4.214: Run all JUnit tests from one class
You can access the Automation API with the ScriptApi class. See chapter 4.4.8 on page 45
for details.
Execution of multiple Tests with JUnit Suite
To execute multiple tests you have to group
the tests into a test suite.
i m p o r t org . junit . runner . RunWith ;
i m p o r t org . junit . runners . Suite ;
i m p o r t org . junit . runners . Suite . S u i t e C l a s s e s ;
@RunWith ( Suite . class )
@SuiteClasses ({
// Two test classes
ScriptJUnitTest .class ,
ScriptSpockTest .class ,
// Another JUnit suite
InnerSuiteScriptJUnitTests .class ,
})
p u b l i c c l a s s
AllMyScriptJUnitTests {
Listing 4.215: Run all JUnit tests using a Suite
You can also group test suites in test suites and so on.
© 2017, Vector Informatik GmbH
170 of 250

---

Chapter 4.
AutomationInterface API Reference
4.13.2.2 Execution of Spock Tests
The AutomationInterface can also execute Spock tests. See:
• Homepage: https://github.com/spockframework/spock2
• Documentation: http://spockframework.github.io/spock/docs/1.0/index.html3
It is also possible to group multiple Spock test into a JUnit Test Suite.
Usage sample:
i m p o r t spock . lang . S p e c i f i c a t i o n
c l a s s S c r i p t S p o c k T e s t extends S p e c i f i c a t i o n {
def " Simple Spock test " () {
when :
// Add your test logic here
def m y E x p e c t e d S t r i n g = " Expected "
then :
myExpectedString == " Expected "
}
}
Listing 4.216: Run unit test with the Spock framework
You can access the Automation API with the ScriptApi class. See chapter 4.4.8 on page 45
for details.
You have to add a Spock dependency in your build.gradle file:
dependencies {
compileDvCfg "org.spockframework:spock-core:1.0-groovy-2.4"
}
Note: after the change you have to call Gradle to update the IntelliJ IDEA project.
gradlew idea
4.13.2.3 Registration of Unit Tests in Scripts
A test or the root suite class has to be registered in a script to be executable. The first argument
is the taskName for the UnitTests the second is the class of the tests.
// You can add a unit test inside a script
unitTestTask (" MyUnitTest ", AllMyScriptJUnitTests . class )
Listing 4.217: Add a UnitTest task with name MyUnitTest
It is also possible to reference the test/suite class directly as a script inside of a script project.
So you don’t have to create a script as a wrapper.
2Last accessed 2016-05-24
3Last accessed 2016-05-24
© 2017, Vector Informatik GmbH
171 of 250

---

Chapter 4.
AutomationInterface API Reference
project . ext . automationClasses = [
" sample . MyScript ",
" sample . MyUnitTestSuite ", // This is a test suite
// Add here your test or suite class with full qualified name
]
Listing 4.218: The projectConfig.gradle file content for unit tests
© 2017, Vector Informatik GmbH
172 of 250

---

5 Data models in detail
This chapter describes several details and concepts of the involved data models. Be aware that
the information here is focused on the Java API. In most cases it is more convenient using the
Groovy APIs described in 4.6 on page 66. So, whenever possible use the Groovy API and read
this chapter only to get background information when required.
5.1 MDF model - the raw AUTOSAR data
The MDF model is being used to store the AUTOSAR model loaded from several ARXML
files. It consists of Java interfaces and classes which are generated from the AUTOSAR meta-
model.
5.1.1 Naming
The MDF interfaces have the prefix MI followed by the AUTOSAR meta-model name of the class
they represent. For example, the MDF interface related to the meta-model class ARPackage
(AUTOSAR package in the top-level structure of the meta-model) is MIARPackage.
5.1.2 The models inheritance hiearchy
The MDF model therefore implements (nearly) the same inheritance hierarchy and associations
as defined by the AUTOSAR model. These interfaces provide access to the data stored in the
model.
See figure 5.1 on the following page shows the (simplified) inheritance hierarchy of the ECUC
container type MIContainer. What we can see in this example:
• A container is an MIIdentifiable which again is a MIReferrable. The MIReferrable
is the type which holds the shortname (getName()). All types which inherit from the
MIReferrable have a shortname (MIARPackage, MIModuleConfiguration, ...)
• A container is also a MIHasContainer. This is an artificial base class (not part of the
AUTOSAR meta-model) which provides all features of types which have sub-containers.
The MIModuleConfiguration therefore has the same base type
• A container also inherits from MIHasDefinition. This is an artificial base class (not
part of the AUTOSAR meta-model) which provides all features of types which have an
AUTOSAR definition. The MIModuleConfiguration and MIParameterValue therefore
has the same base type
• All MIIdentifiables can hold ADMIN-DATA and ANNOTATIONs
• All MDF objects in the AUTOSAR model tree inherit from MIObject which is again an
MIObject
© 2017, Vector Informatik GmbH
173 of 250

---

Chapter 5.
Data models in detail
Figure 5.1: ECUC container type inheritance
5.1.2.1 MIObject and MDFObject
The MIObject is the base interface for all AUTOSAR model objects in the DaVinci Configurator
data model. It extends MDFObject which is the base interface of all model objects. Your
client code shall always use MIObject, when AUTOSAR model objects are used, instead of
MDFObject.
The figure 5.2 on the next page describes the class hierarchy of the MIObject.
5.1.3 The models containment tree
The root node of the AUTOSAR model is MIAUTOSAR. Starting at this object the complete model
tree can be traversed. MIAUTOSAR.getSubPackage() for example returns a list of MIARPackage
objects which again have child objects and so on.
Figure 5.3 on the following page shows a simple example of an MDF object containment hierar-
chy. This example contains two AUTOSAR packages with module configurations below.
© 2017, Vector Informatik GmbH
174 of 250

---

Chapter 5.
Data models in detail
Figure 5.2: MIObject class hierarchy and base interfaces
Figure 5.3: Autosar package containment
© 2017, Vector Informatik GmbH
175 of 250

---

Chapter 5.
Data models in detail
In general, objects which have child objects provide methods to retrieve them.
• MIAUTOSAR.getSubPackage() for example returns a list of child packages
• MIContainer.getSubContainer() returns the list of sub-containers and
MIContainer.getParameter() all parameter-values and reference-values of a container
5.1.4 The ECUC model
The interfaces and classes which represent the ECUC model don’t exactly follow the AUTOSAR
meta-model naming. because they are designed to store AUTOSAR 3 and AUTOSAR 4 models
as well.
Affected interfaces are:
• MIModuleConfiguration and its child objects (containers, parameters, . . . )
• MIModuleDef and its child objects (containers definitions, parameter definitions, . . . )
The ECUC model also unifies the handling of parameter- and reference-values. Both, parameter-
values and reference-values of a container, are represented as MIParameterValue in the MDF
model.
5.1.5 Order of child objects
Child object lists in the MDF model have the same order as the data specified in the ARXML
files. So, loading model objects from AXRML doesn’t change the order.
5.1.6 AUTOSAR references
All AUTOSAR reference objects in the MDF model have the base interface MIARRef.
Figure 5.4 on the next page shows this type hierarchy for the definition reference of an ECUC
container.
In ARXML, such a reference can be specified as:
<DEFINITION-REF DEST="ECUC-PARAM-CONF-CONTAINER-DEF">
/MIRCOSAR/Com/ComGeneral
</DEFINITION-REF>
• MIARRef.getValue() returns the AUTOSAR path of the object, the reference points to
(as specified in the ARXML file). In the example above "/MIRCOSAR/Com/ComGeneral"
would be this value
• MIContainerDefARRef.getRefTarget() on the other hand returns the referenced MDF
object if it exists. This method is located in a specific, typesafe (according to the type it
points to) reference interface which extends MIARRef. So, if an object with the AUTOSAR
path "/MIRCOSAR/Com/ComGeneral" exists in the model, this method will return it
© 2017, Vector Informatik GmbH
176 of 250

---

Chapter 5.
Data models in detail
Figure 5.4: The ECUC container definition reference
5.1.7 Model changes
5.1.7.1 Transactions
The MDF model provides model change transactions for grouping several model changes into
one atomic change.
A solving action, for example, is being executed within a transaction for being able to change
model content. Validation and generator developers don’t need to care for transactions. The
tools framework mechanisms guarantee that their code is being executed in a transaction were
required.
The tool guarantees that model changes cannot be executed outside of transactions. So, for
example, during validation of model content the model cannot be changed. A model change
here would lead to a runtime exception.
5.1.7.2 Undo/redo
On basis of model change transactions, MDF provides means to undo and redo all changes
made within one transaction. The tools GUI allows the user to execute undo/redo on this
granularity.
5.1.7.3 Event handling
MDF also supports model change events. All changes made in the model are reported by this
asynchronous event mechanism. Validations, for example, detect this way which areas of the
model need to be re-validated. The GUI listens to events to update its editors and views when
model content changes.
© 2017, Vector Informatik GmbH
177 of 250

---

Chapter 5.
Data models in detail
5.1.7.4 Deleting model objects
Model objects must be deleted by a special service API. In Java code that’s:
IModelOperationsPublished.deleteFromModel(MDFObject).
Deleting an object means:
• All associations of the object are deleted. The connection to its parent object, for example,
is being deleted which means that the object is not a member of the model tree anymore
• The object itself is being deleted. In fact, it is not really deleted (and garbage collected)
as a Java object but only marked as removed. Undo of the transaction, which deleted this
object, removes this marker and restores the deleted associations
5.1.7.5 Access to deleted objects
All subsequent access to content of deleted objects throws a runtime exception. Reading the
shortname of an MIContainer, for example.
5.1.7.6 Set-methods
Model interfaces provide get-methods to read model content. MDF also offers set-methods for
fields and child objects with multiplicity 0..1 or 1..1.
These set-methods can be used to change model content.
• MIARRef.getValue() for example returns a references AUTOSAR path
• MIARRef.setValue(String newValue) sets a new path
5.1.7.7 Changing child list content
MDF doesn’t offer set-methods for fields and child objects with multiplicity 0..* or 1..*.
MIContainer.getSubContainer(), for example, returns the list of sub-containers but there is
no MIContainer.setSubContainer() method to change the sub-containers.
Changing child lists means changing the list itself.
• To add a new object to a child list, client code must use the lists add() method. MIContai-
ner.getSubContainer().add(container), for example, adds a container as additional
sub-container. This added object is being appended at the end of the list
• Removing child list objects is a side-effect of deleting this object. The delete operation
removes it from the list automatically
5.1.7.8 Change restrictions
The tools transaction handling implements some model consistency checks to avoid model chan-
ges which shall be avoided. Such changes are, for example:
• Creating duplicate shortnames below one parent object (e.g. two sub-containers with the
same shortname)
• Changing or deleting pre-configured parameters
© 2017, Vector Informatik GmbH
178 of 250

---

Chapter 5.
Data models in detail
When client code tries to change the model this way, the related model change transaction is
being canceled and the model changes are reverted (unconditional undo of the transaction). A
special case here are solving actions. When a solving action inconsistently changes the model,
only the changes made by this solving action are reverted (partial transaction undo of one
solving action execution).
5.2 Post-build selectable
5.2.1 Model views
5.2.1.1 What model views are
After project load, the MDF model contains all objects found in the ARXML files. Variation
points are just data structures in the model without any special meaning in MDF.
If you want to deal with variants you must use model views. A model view filters access to the
MDF model based on the variant definition and the variation points.
There is one model view per variant. If you use this variants model view, the MDF model
filters exactly what this variant contains.
All other objects become invisible.
When your
retrieve parameters of a container for example, you’ll see only parameters contained in your
selected variant.
f i n a l b o o l e a n i sV is ib le = M o d e l A c c e s s U t i l . i sV is ib le ( t . p a r a m V a r i a n t A ) ;
Listing 5.1: Check object visibility
5.2.1.2 The IModelViewManager project service
The IModelViewManager handles model visibility in general. It provides the following me-
ans:
• Get all available variants
• Execute code with visibility of a specific predefined variant only. This means your code
sees all objects contained in the specified variant. All objects which are not contained in
this variant will be invisible
• Execute code with visibility of invariant data only (see IInvariantView).
• Execute code with unfiltered model visibility. This means that your code sees all objects
unconditionally. If the project contains variant data, you see all variants together
It additionally provides detailed visibility information for single model objects:
• Get all variants, a specific object is visible in
• Find out if an object is visible in a specific variant
f i n a l List < I P r e d e f i n e d V a r i a n t V i e w > variants = viewMgr . g e t A l l V a r i a n t V i e w s () ;
Listing 5.2: Get all available variants
© 2017, Vector Informatik GmbH
179 of 250

---

Chapter 5.
Data models in detail
try ( final I M o d e l V i e w E x e c u t i o n C o n t e x t context = viewMgr . e x e c u t e W i t h M o d e l V i e w ( t .
variantViewA )) {
assertIsVisible (t. paramInvariant );
assertIsVisible (t. paramVariantA );
assertNotVisible (t. paramVariantB );
}
try ( final I M o d e l V i e w E x e c u t i o n C o n t e x t context = viewMgr . e x e c u t e W i t h M o d e l V i e w ( t .
variantViewB )) {
assertIsVisible (t. paramInvariant );
assertNotVisible (t. paramVariantA );
assertIsVisible (t. paramVariantB );
}
try ( final I M o d e l V i e w E x e c u t i o n C o n t e x t context = viewMgr . e x e c u t e U n f i l t e r e d () ) {
assertIsVisible (t. paramInvariant );
assertIsVisible (t. paramVariantA );
assertIsVisible (t. paramVariantB );
}
Listing 5.3: Execute code with variant visibility
Important remark:
It is essential that the execute...() methods are used exactly as imple-
mented in the listing above. The try (...)
{...} construct is a new Java 7 feature which
guarantees that resources are closed whenever (and how ever) the try block is being left. For
details read:
http://docs.oracle.com/javase/tutorial/essential/exceptions/tryResourceClose.html
© 2017, Vector Informatik GmbH
180 of 250

---

Chapter 5.
Data models in detail
Collection < IPredefinedVariantView > visibleVariants = viewMgr .
getVisibleVariantViews (t. paramInvariant );
assertThat ( visibleVariants . size () , equalTo (2) );
assertThat ( visibleVariants , containsInAnyOrder (t. variantViewA , t. variantViewB ))
;
visibleVariants = viewMgr . getVisibleVariantViews (t. paramVariantA );
assertThat ( visibleVariants . size () , equalTo (1) );
assertThat ( visibleVariants , containsInAnyOrder (t. variantViewA ));
Listing 5.4: Get all variants, a specific object is visible in
5.2.1.3 Variant siblings
Variant siblings of an MDF object are MDF object instances which represent the same object
but in other variants.
The method IModelVarianceAccessPublished.getVariantSiblings() provides access to these
sibling objects:
This method returns MDF object instances representing the same object but in all variants. The
collection returned contains the object itself including all siblings from other variants.
The calculation of siblings depends on the object-type as follows:
• Ecuc Module Configuration:
Since module configurations are never variant, this method always returns a collection
which contains the specified object only
• Ecuc Container:
For siblings of a container all of the following conditions apply:
– They have the same AUTOSAR path
– They have the same definition path (containers with the same AUTOSAR path but
different definitions may occur in variant models - but they are not variant siblings
because they differ in type)
• Ecuc Parameter:
For siblings of a parameter all of the following conditions apply:
– The parent containers have the same AUTOSAR path
– The parameter siblings have the same definition path
The parameter values are not relevant so parameter siblings may have different values.
Multi-instance parameters are special. In this case the method returns all multi-instance
siblings of all variants.
• System description object:
For siblings of MIReferrables all of the following conditions apply:
– They have the same meta-class
– They have the same AUTOSAR path
For siblings of non-MIReferrables all of the following conditions apply:
– Their nearest MIReferrable-parents are either the same object or variant siblings
© 2017, Vector Informatik GmbH
181 of 250

---

Chapter 5.
Data models in detail
– Their containment feature paths below these nearest MIReferrable-parents is equal
Special use cases: When the specified object is not a member of the model tree (the object
itself or one of its parents has no parent), it also has no siblings. In this case this method
returns a collection containing the specified object only.
Remark concerning visibility: This method returns all siblings independent of the currently
visible objects. This means that the returned collection probably contains objects which are
not visible by the caller! It also means that the specified object itself doesn’t need to be visible
for the caller.
5.2.1.4 The Invariant model views
There are use cases which require to see the invariant model content only. One example are
generators for modules which don’t support variance at all.
There are two different invariant views currently defined:
• Value based invariance (values are equal in all variants):
The IInvariantValuesView contains objects were all variant siblings have the same value
and exist in all variants. One of the siblings is contained
• Definition based invariance (values which shall be equal in all variants):
The IInvariantEcucDefView contains objects which are not allowed to be variant accor-
ding to the BSWMD rules. One of the siblings is contained
All Invariant views derive from the same interface IInvariantView, so if you want to use an
invariant view and not specifying the exact view, you could use the IInvariantView interface.
The figure 5.5 describes the hierarchy.
Figure 5.5: Invariant views hierarchy
The InvariantValues model view
The IInvariantValuesView contains only elements which
have one of the following properties:
• The element and no parent has any MIVariationPoint with a post-build condition
• All variant siblings have the same value and exist in all variants. Then one of the siblings
is contained in the IInvariantValuesView
So the semantic of the InvariantValues model view is that all values are equal in all vari-
ants.
© 2017, Vector Informatik GmbH
182 of 250

---

Chapter 5.
Data models in detail
You could retrieve an instance of IInvariantValuesView by calling IModelViewManager.
getInvariantValuesView().
IModelViewManager viewMgr =...;
IInvariantValuesView invariantView = viewMgr . getInvariantValuesView ();
// Use the invariantView like any other model view
Listing 5.5: Retrieving an InvariantValues model view
Example
The figure 5.6 describes an example for a module with containers and the visibility
in the IInvariantValuesView.
• Container A is invisible because it is contained in variant 1 only
• Container B and C are visible because they are contained in all variants
• Parameter a is visible because it is contained in all variants with the same value
• Parameter b is invisible: It is contained in all variants but with different values
• Parameter c is invisible because it is contained in variant 3 only
Figure 5.6: Example of a model structure and the visibility of the IInvariantValuesView
Specification
See also the specification for details of the IInvariantValuesView.
The Invariant EcuC definition model view
The IInvariantEcucDefView contains the same
objects as the invariant values view but additionally excludes all objects which, by (EcuC /
BSWMD) definition, support variance. Using this view you can avoid dealing with objects which
are accidentally equal by value (in your test configurations) but potentially can be different
because they support variance.
More exact the IInvariantEcucDefView will additionally exclude elements which have the
following properties:
• If the parent module configuration specifies VARIANT-POST-BUILD-SELECTABLE as
implementation configuration variant
– All objects ( MIContainer, MINumericalValue, ...) are excluded, which support
variance according to their EcuC definition. (potentially variant objects)
© 2017, Vector Informatik GmbH
183 of 250

---

Chapter 5.
Data models in detail
• If the parent module configuration doesn’t specify VARIANT-POST-BUILD-SELECTABLE
as implementation configuration variant. All contained objects do not support variance,
so the view actually shows the same objects as the IInvariantValuesView.
The implementation configuration variant in fact overwrites the objects definition for elements
in the ModuleConfiguration.
Reasons to Use the view
The EcucDef view guarantees that you don’t access potentially
variant data without using variant specific model views. So it allows you to improve code
quality in your generator.
When your test configuration for example contains equal values for a parameter which is po-
tentially variant you will see this parameter in the invariant values view but not in the EcucDef
view. Consequences if you access data in other module configurations: When the BSWMD file
of this other module is being changed, e.g. a parameter now supports variance, objects can
become invisible due to this change. You are forced to adapt your code then.
Usage
You could retrieve an instance of IInvariantEcucDefView by calling IModelViewMa-
nager.getInvariantEcucDefView(). And then use is as any other IModelView.
IModelViewManager viewMgr =...;
IInvariantEcucDefView invariantView = viewMgr . getInvariantEcucDefView ();
// Use the invariantView like any other model view
Listing 5.6: Retrieving an InvariantEcucDefView model view
Specification
See also the specification for details of the IInvariantEcucDefView.
5.2.1.5 Accessing invisible objects
When you switch to a model view, objects which are not contained in the related variant become
invisible. This means that access to their content leads to an InvisibleVariantObjectFea-
tureException.
To simplify handling of invisible objects, some model services provide model access even for
invisible objects in variant projects. The affected classes and interfaces are:
• ModelUtil
• ModelAccessUtil
• IReferrableAccess
• IModelAccess
• IModelCompareService
• DefRef
• AsrPath
• IEcucDefinitionAccess (all methods which deal with configuration side objects)
Only a subset of the methods in these services work with invisible objects (read the methods
JavaDoc for details). The general policy to select exactly these methods was:
© 2017, Vector Informatik GmbH
184 of 250

---

Chapter 5.
Data models in detail
• Support access to type and object identity of MDF objects (definition and AUTOSAR
path)
• Parameter value or other content related information must still be retrieved in a context
the object is visible in
• Also not contained are methods which change model content. E.g. deleting invisible
objects, set parameter values, ...
5.2.1.6 IViewedModelObject
The IViewedModelObject is a container for one MIObject and an IModelView that was used
when viewing the MIObject.
The interface provides getter for the MIObject, and the IModelView which was active during
creation of the IViewedModelObject. So the IViewedModelObject represents a tuple of MI-
Object and IModelView.
This could be used to preserve the state/tuple of a MIObject and IModelView, for later retrie-
val.
Examples:
• BswmdModel objects
• Elements for validation results, retrieved in a certain view
• Model Query API like ModelTraverser, to preserve IModelView information
Notes:
A IViewedModelObject is immutable and will not update any state. Especially not when the
visibility of the getMdfObject(), is changed after the construction of the IViewedModelOb-
ject.
It is not guaranteed, that the MIObject is visible in the creation IModelView, after the model is
changed. It is also possible to create an IViewedModelObject of a MIObject and a IModelView,
where the MIObject is invisible.
The method getCreationModelView() returns the IModelView of the IViewedModelObject,
which was active when the model object was viewed IViewedModelObject.
5.2.2 Variant specific model changes
The CFG5 data model provides an execution context which guarantees that only the selected
variant is being modified. Objects which are visible in more than one variant are cloned auto-
matically. The clones and the object which is being modified (or their parents) automatically
get a variation point with the required post-build conditions.
The following picture shows how this execution context works:
See figure 5.7 on the following page.
• Before modifying the parameter, this instance is invariant. The same MDF instance is
visible in all variants
• When the client code changes the parameter value, the model automatically clones the
parameter first
© 2017, Vector Informatik GmbH
185 of 250

---

Chapter 5.
Data models in detail
Figure 5.7: Variant specific change of a parameter value
• Only the parameter instance which is visible in the currently active view is being modified.
The content of other variants stays untouched
Remark: This change mode is implicitly turned off when executing code in the IInvariant-
View or in an unfiltered context.
try ( final I M o d e l V i e w E x e c u t i o n C o n t e x t v i e w C o n t e x t = viewMgr .
executeWithModelView ( variantView )) {
try ( final I M o d e l V i e w E x e c u t i o n C o n t e x t m o d e C o n t e x t = viewMgr .
executeWithVariantSpecificModelChanges ()) {
ma. setAsString ( parameter , " Vector - Informatik ");
}
}
Listing 5.7: Execute code with variant specific changes
5.2.3 Variant common model changes
The CFG5 data model provides an execution context which guarantees that model objects are
modified in all variants.
The behavior of this mode depends on the mode flag parameter as follows:
• mode == ALL : All parameters and containers are affected
• mode == DEFINITION_BASED : Only those parameters and containers are af-
fected which do not support variance (according to their definition in the BSWMD file
and the implementation configuration variant of their module configuration)
• mode == OFF : Doesn’t turn on this change mode (this value is used internally only)
Remark: This method doesn’t allow to reduce the scope of this change mode. So if ALL is
already set, this method doesn’t permit to use DEFINITION_BASED (or OFF) to reduce the
effective amount of objects. ALL will be still active then.
The following picture shows how this execution context works:
See figure 5.8 on the next page.
• We start with a variant model which contains one parameter in two instances - one per
variant - with the values 3 and 7
• When the client code sets the parameter value in variant 1 to 4, the model automatically
modifies the variant sibling in variant 2
• As a result, the parameter has the same value in all variants
This change mode works with parameters and containers. The following operations are suppor-
ted:
© 2017, Vector Informatik GmbH
186 of 250

---

Chapter 5.
Data models in detail
Figure 5.8: Variant common change of a parameter value
• Container/parameter creation: The created object afterwards exists in all variants
the related parent exists in. Already existing objects are not modified. Missing objects
are created
• Container/parameter deletion: The deleted object afterwards is being removed from
all variants the related parent exists in. So actually all variant siblings are deleted
• Parameter value change: The parameter exists and has the same value in all variants
the parent container exists in. If a parameter instance is missing in a variant, it is being
created
Special behavior for multi-instance parameters:
• This mode guarantees that a set of multi-instance parameters is equal in all variants
• Only the values of multi-instance parameters are relevant. Their order can be different in
different variants
• Beside the values, this change mode guarantees that all variants contain the same number
of parameter instances. So, when a multi-instance set is being modified in a variant view,
this change mode creates or deletes objects in other variants to guarantee an equal number
of instances in all variant sibling sets
Remark: This change mode is implicitly turned on with the mode flag ALL when code is
being executed in the IInvariantView. It is being ignored implicitly when executing code in
an unfiltered context.
5.3 BswmdModel details
5.3.1 BswmdModel - DefinitionModel
The BswmdModel provides a type safe and easy access to data of BSW modules (Ecu configu-
ration elements).
Example:
• Access a single parameter /MICROSAR/ComM/ComMGeneral/ComMUseRte
You can to write: comM.getComMGeneral().getComMUseRte()
© 2017, Vector Informatik GmbH
187 of 250

---

Chapter 5.
Data models in detail
• Access containers[0:*] /MICROSAR/ComM/ComMChannel
You can to write:
for (ComMChannel channel : comM.getComMChannel()){
int value = channel.getComMChannelId().getValue();
}
The DaVinci Configurator internal Model (MDF model) has 1:1 relationship to your Bswmd-
Model. The BswmdModel will retrieve all data from the underlying MDF model.
Figure 5.9: The relationship between the MDF model and the BswmdModel
DefinitionModel
The DefinitionModel is the base implementation of every BswmdModel.
Every BswmdModel class is a subclass of the DefinitionModel where the classes begin with
GI, like GIContainer.
5.3.1.1 Types of DefinitionModels
There are two types of DefinitionModels:
1. BswmdModel (formally known as DefinitionTyped BswmdModel)
2. DefRef API (formally known as Untyped BswmdModel)
The BswmdModel consists of generated classes for the module definition elements like Mo-
duleDefinitions, Containers, Parameters in bswmd files. The generated class contains
getter methods for each child element. So you can access every child by the corresponding
getter method with compile time safety of the sub type.
The BswmdModel derives from the DefinitionModel DefRef API, so the BswmdModel
contains all functionalities of the DefRef API.
The DefRef API of the DefinitionModel provides an generic access to the Ecu configuration
structure via DefRefs. There are NO generated classes for the Definition structure. The
DefRef API uses the base classes of the DefinitionModel to provide this DefRef based access.
Every interface in the DefinitionModel starts with an GI. The Ecu Configuration elements have
corresponding base interfaces for each element:
© 2017, Vector Informatik GmbH
188 of 250

---

Chapter 5.
Data models in detail
• ModuleConfiguration - GIModuleConfiguration
• Container - GIContainer
• ChoiceContainer - GIChoiceContainer
• Parameter - GIParameter<?>
– Integer Parameter - GIParameter<BigInteger>
– Boolean Parameter - GIParameter<Boolean>
– Float Parameter - GIParameter<BigDecimal>
– String Parameter - GIParameter<String>
• Reference - GIReference<?>
– Container Reference - GIReferenceToContainer
– Foreign Reference- GIReference<Class>
So there are different classes for the different model types, e.g. all MDF classes start with MI,
the Untyped start with GI and DefinitionTyped classes are generated. The table 5.1 contrasts
the different model types and their corresonding classes.
AUTOSAR type
MDFModel
“Untyped” BswmdModel
“DefinitionTyped”
ModuleConfiguration
MIModuleConfiguration
GIModuleConfiguration
CanIf
(generated)
Container
MIContainer
GIContainer
CanIfPrivateCfg
(generated)
String Parameter
MITextualValue
GIParameter<String>
GString
Integer Parameter
MINumericalValue
GIParameter<BigInteger>
GInteger
Reference to Container
MIReferenceValue
GIReferenceToContainer
CanIfCtrlDrvInitHohConfigRef
(generated)
Enum Parameter
MITextualValue
GIParameter<String>
CanIfDispatchBusOffUL
(generated)
Table 5.1: Different Class types in different models
Note: The GString in the table is not the Groovy GString class.
It is com.vector.cfg.gen.core.bswmdmodel.param.GString.
5.3.1.2 DefRef Getter methods of Untyped Model
The DefRef API classes have no getter methods for the specific child types, but the children
could be retrieve via the generic getter methods like:
• GIContainer.getSubContainers()
• GIContainer.getParameters()
• GIContainer.getParameters(TypedDefRef)
• GIContainer.getParameter(TypedDefRef)
• GIContainer.getReferencesToContainer(TypedDefRef)
• GIModuleConfiguration.getSubContainer(TypedDefRef)
• GIParameter.getValueMdf()
Additionally there are methods to retrieve other referenced elements, like parent of reference
reverse lookup:
© 2017, Vector Informatik GmbH
189 of 250

---

Chapter 5.
Data models in detail
• GIContainer.getParent()
• GIContainer.getParent(DefRef)
• GIContainer.getReferencesPointingToMe()
• GIContainer.getReferencesPointingToMe(DefRef)
The following listing describe the usage of the untyped bswmd method in both models:
// Get the container from external method getCanIfInitConfigBswmd () ...
f i n a l G I C o n t a i n e r c an If In it = g e t C a n I f I n i t C o n f i g B s w m d () ;
// Gets all subcontainers from a container CanIfRxPduConfig from the canIfInit
instance
f i n a l List < GIContainer > s u b C o n t a i n e r s = ca nI fI ni t . g e t S u b C o n t a i n e r s (
CanIfRxPduConfig . DEFREF . castToTypedDefRef ());
if ( s u b C o n t a i n e r s . isEmpty () ) {
// ERROR Handling
}
f i n a l G I C o n t a i n e r cont = s u b C o n t a i n e r s . get (0) ;
// Gets exactly one CanIfCanRxPduHrhRef reference from the cont instance
f i n a l GIReference < MIContainer > child = cont . g e t R e f e r e n c e ( C a n I f C a n R x P d u H r h R e f .
DEFREF . castToTypedDefRef ());
Listing 5.8: Sample code to access element in an Untyped model with DefRefs
f i n a l
GIReferenceToContainer ref = getCanIfCanRxPduHrhRefBswmd ();
f i n a l G I C o n t a i n e r target = ref . g e t R e f T a r g e t () ;
Listing 5.9: Resolves a Refference traget of an Reference Parameter
f i n a l GIParameter < BigInteger > param = g e t C a n I f I n i t C o n f i g B s w m d () . g e t P a r a m e t e r (
CanIfInitConfiguration . CANIF_NUMBER_OF_CAN_TXPDU_IDS_DEFREF );
f i n a l B i g I n t e g e r value = param . g e t V a l u e M d f () ;
Listing 5.10: The value of a GIParameter
The figure 5.10 on the next page shows the available DefRef navigation methods for the Untyped
model. There are more methods to navigate with the DefRef API through the a DefinitionModel,
please look into the Javadoc documentation of the GI... classes for more functionality.
© 2017, Vector Informatik GmbH
190 of 250

---

Chapter 5.
Data models in detail
Figure 5.10: SubContainer DefRef navigation methods
5.3.1.3 References
All references in the BswmdModel are subtypes of GIReference. The generated model contains
generated DefintionTyped classes for references to container, for the other references their are
only Untyped classes like GInstanceReference.
A GIReference has the method getRefTargetMdf(), this will always return the target in the
MDF model as MIReferrable. For non GIReferenceToContainer this is the normal way to
resolve references, but for reference to container you should always try to use the method
getRefTarget(), which will not leave the BswmdModel.
Note: Try to use getRefTarget() as much as possible.
References to container
The following references are references to container (References poin-
ting to container) and are subtypes of the GIReferenceToContainer.
• Normal Reference
© 2017, Vector Informatik GmbH
191 of 250

---

Chapter 5.
Data models in detail
• SymbolicNameReference
• ChoiceReference
References have the method getRefTarget(), which returns the target as BswmdModel object,
if the type is known at model generation time, the type will be the generated type. Otherwise
the return type is GIContainer.
Note: It is always allowed to call getRefTarget(), also for references pointing to external
types.
Figure 5.11: Untyped reference interfaces in the BswmdModel
SymbolicNameReferences
SymbolicNameReferences have the same methods as GIReferen-
ceToContainer and the additional methods getRefTargetParameterMdf(), which returns the
target parameter as MIObject The method getRefTargetParameter() return a BswmdModel
object, if the type is known at model generation time, the type will be the generated type.
Otherwise the return type is GIParameter.
Note: It is always allowed to call getRefTargetParameter(), also for references pointing to
external types.
5.3.1.4 Post-build selectable with BswmdModel
The BswmdModel supports the Post-build selectable use case, in respect that you do not have
to switch nor cache the corresponding IModelView. The BswmdModel objects cache the so
called Creation ModelView and switch transparently to that view when accessing the Model.
So you don’t have to switch to the correct view on access. See figure 5.12 on the following page.
You only have to ensure, that the requested IModelView is active or passed as parameter, when
you create an instance at the GIModelFactory. Note: A lazy created object will inherit the
view of the existing element.
© 2017, Vector Informatik GmbH
192 of 250

---

Chapter 5.
Data models in detail
Figure 5.12: Creating a BswmdModel in the Post-build selectable use case
5.3.1.5 Creation ModelView of the BswmdModel
Every GIModelObject (BswmdModel object) has a creation IModelView. This is the IModel-
View, which was active or passed during creation of the BswmdModel. At every method call to
the BswmdModel, the model will switch to this view.
Using the creation ModelView of the BswmdModel
The method getCreationModelView()
returns the IModelView of this GIModelObject, which was active during the creation of this
BswmdModel.
The method executeWithCreationModelView() executes the code under visibility of the ge-
tCreationModelView() of this GIModelObject.
The returned IModelViewExecutionContext must be used within a Java "try-with-
resources" feature. It makes sure, that the old view is restored when the try is comple-
ted.
GIModelObject myModelObject = ...;
try ( final I M o d e l V i e w E x e c u t i o n C o n t e x t context = m y M o d e l O b j e c t .
executeWithCreationModelView ()) {
// do some operations
...
}
Listing 5.11: Java: Execute code with creation IModelView of BswmdModel object
The method executeWithCreationModelView(Runnable) executes the Runnable code under
visibility of the getCreationModelView() of this GIModelObject.
GIModelObject myModelObject = ...;
myModelObject . executeWithCreationModelView (() ->{
// do some operations
});
Listing 5.12: Java: Execute code with creation IModelView of BswmdModel object via runnable
© 2017, Vector Informatik GmbH
193 of 250

---

Chapter 5.
Data models in detail
The method executeWithCreationModelView() executes the Supplier code under visibility
of the getCreationModelView() of this GIModelObject. You could use this method, if you
want to return an object from this operation.
GIModelObject myModelObject = ...;
ReturnType returnVal = myModelObject . executeWithCreationModelView (() ->{
// do some operations
r e t u r n theValue ;
});
Listing 5.13: Java: Execute code with creation IModelView of BswmdModel object
5.3.1.6 Lazy Instantiating
The BswmdModel is instantiated lazily; this means when you create a ModuleConfiguration
object only one object for the module configuration is created.
When you call a getXXX() method on the configuration it will create the requested sub element,
if it exists. So you can start at any point in the model (e.g. a Subcontainer) and the model is
build successively, by your calls.
It is also allowed to call a getParent() on a Subcontainer, if the parent was not created yet.
The technique could be used in validations, when the creation of the full BswmdModel is too
expensive. Then you can create only the needed container; by an MDF model object.
5.3.1.7 Optional Elements
All elements (Container, Parameter . . . ) are considered as optional if they have a multiplicity
of 0:1. The BswmdModel provide a special handling of optional elements. This shall support
you to recognize optional element during development (in the most cases some kind of special
handling is needed). An optional Element has other access methods as a required Element: The
method getXXX() will not return the element, it will return a GIOptional<Element> object
instead. You can ask the GIOptional object if the element exists (optElement.exists()).
Then you can call optElement.get() to retrieve the real object.
You also have the choice to use the method existsXXX(). This method is equivalent to ge-
tXXX().exists(). The difference is that you get a compile error, if you try to use the optional
element without any check. When you are sure that the element must exist you can directly call
getXXXUnsafe(). Note: If you use any of the get methods (optElement.get() or getXXXUns-
afe()) and the element does not exist the normal BswmdModelException is thrown.
5.3.1.8 Class and Interface Structure of the BswmdModel
The upper part of the figure 5.13 on the next page shows the Untyped API (GI. . . interfaces).
The bottom left part is an example of DefinitionTyped (generated) class for the CanIf module.
The bottom right part are the classes used by the DefinitionTyped model, but are not visible
in the Untyped model.
© 2017, Vector Informatik GmbH
194 of 250

---

Chapter 5.
Data models in detail
Figure 5.13: Class and Interface Structure of the BswmdModel
5.3.1.9 BswmdModel write access
The BswmdModel supports a write access for ecu configuration elements. This means new
elements can be created and existing elements can be modified and deleted by the BswmdMo-
del.
NOTE: The model is in read-only state by default, so no objects could be created. For this reason
all calls to an API which creates or deletes elements has to be executed within a transaction.
See ModelDocumentation chapter "Model changes" for more details.
Optional and required Elements (0:1/1:1 Multiplicity)
For optional or required elements,
the following additional methods are generated, if BswmdModelWriteAccess is enabled:
• get...OrNull(): Returns the requested element or null if it is missing.
• get...OrCreate(): Returns the existing requested element or implicitly creates a new
one if it is missing.
E.g. EcucGeneral:
© 2017, Vector Informatik GmbH
195 of 250

---

Chapter 5.
Data models in detail
Ecuc ecuc = getEcucModuleConfig ();
// Gets the EcucGeneral container or null if it is missing .
EcucGeneral ecucGeneralOrNull = ecuc . getEcucGeneralOrNull ();
// Gets the existing EcucGeneral container or creates a new one if it is
missing .
EcucGeneral ecucGeneralOrCreate = ecuc . getEcucGeneralOrCreate ();
Listing 5.14: Additional write API methods for EcucGeneral
Multiple elements (Upper Multiplicity > 1)
For each multiple element, the return type
for these elements is changed from List<> to GIPList<> for parameter and GICList<> for
container, if BswmdModelWriteAccess is enabled. These new interfaces provide methods which
allow creating and adding new children for the corresponding elements:
• createAndAdd(): Creates a new child element, appends it to the list and returns the new
element.
• createAndAdd(int index): Creates a new child element, inserts it to the list at the
specified index position and returns the new element.
• For GICList<> only:
– createAndAdd(String shortName): Creates a new child element with the specified
shortName, appends it to the list and returns the new element.
– createAndAdd(String shortName, int index): Creates a new child element with
the specified shortName, inserts it to the list at the specified index position and
returns the new element.
– byName(String shortName): Gets the container by specified shortName or throws
an exception if it is missing.
– byNameOrNull(String shortName): Gets the container by specified shortName or
null if it is missing.
– byNameOrCreate(String shortName): Gets the container by specified shortName
or implicitly creates a new one if it is missing.
– exists(String shortname): Returns true if the container exists, otherwise false.
E.g. EcucCoreDefinition:
© 2017, Vector Informatik GmbH
196 of 250

---

Chapter 5.
Data models in detail
Ecuc ecuc = getEcucModuleConfig ();
// Gets the EcucCoreDefinition list ( create EcucHardware container if it is
missing )
GICList < EcucCoreDefinition > ecucCores = ecuc . getEcucHardwareOrCreate ().
getEcucCoreDefinition ();
// Adds two EcucCores
EcucCoreDefinition core0 = ecucCores . createAndAdd (" EcucCore0 ");
EcucCoreDefinition core1 = ecucCores . createAndAdd (" EcucCore1 ");
if ( e cu cC or es . exists ( " E cu cC or e0 " ) ) {
// Sets EcucCoreId from EcucCore0 to 0
ecucCores . byName (" EcucCore0 "). getEcucCoreId (). setValue (0) ;
}
// Creates a new EcucCore by method byNameOrCreate
EcucCoreDefinition core2 = ecucCores . byNameOrCreate (" EcucCore2 ");
...
Listing 5.15: EcucCoreDefinition as GICList<EcucCoreDefinition>
Other write API
• Deleting model objects: It is also possible to delete objects from the model.
– moRemove: Deletes the specified object from the model.
– moIsRemoved: Returns true, if the object was removed from repository, or is invisible
in the current active IModelView.
// Deletes the container ' EcucGeneral ' from the model .
ecucGeneral . moRemove ();
// Deletes the parameter ' EcuCSafeBswChecks ' from the model .
ecucGeneral . getEcuCSafeBswChecks . moRemove ();
// Deletes the child container ' EcucCoreDefinition ' with shortname 'EcucCore0 '
from the model .
ecucCores . byName (" EcucCore0 "). moRemove ();
// Checks if the container ' EcucGeneral ' was removed from repository , or is
invisible in the current active `IModelView `.
if ( e c u c G e n e r a l . m o I s R e m o v e d () ) {
...
}
Listing 5.16: Deleting model objects
• Duplication of containers: The method duplicate() copies a container with all its
children and appends it to the same parent.
© 2017, Vector Informatik GmbH
197 of 250

---

Chapter 5.
Data models in detail
// Duplicates the container ' EcucGeneral '
EcucGeneral duplicatedEcucGeneral = ecucGeneral . duplicate ();
// Duplicates the child container ' EcucCoreDefinition ' with shortname '
EcucCore0 '
EcucCoreDefinition duplicatedEcucCore0 = ecucCores . byName (" EcucCore0 ").
duplicate ();
Listing 5.17: Duplication of containers
• Parameter values: The method setValue(VALUE) sets the value of a parameter. This
method checks if the specified parameters configuration object is available and sets the
new value. If the parameter object is missing it is implicitly created in the model.
// Sets the value of the parameter ' EcuCSafeBswChecks ' to 'true '
ecucGeneral . getEcuCSafeBswChecks . setValue ( true );
Listing 5.18: Set parameter values with the BswmdModel Write API
• Reference targets: The method setRefTarget(REF_TARGET) sets the target of a re-
ference. This method sets the specified target object as reference target of the specified
reference parameter. If the reference parameter object is missing it is implicitly created
in the model.
// Gets the container 'OsCounter ' with shortname ' SystemTimer '
OsCounter osCounterTarget = os. getOsCounters . byName (" SystemTimer ");
// Sets the reference target of the parameter ' CanCounterRef '
can . getCanGeneral (). getCanCounterRef (). setRefTarget ( osCounterTarget );
Listing 5.19: Set reference targets with the BswmdModel Write API
© 2017, Vector Informatik GmbH
198 of 250

---

Chapter 5.
Data models in detail
5.3.2 BswmdModel generation
The BswmdModel for the automation interface is generated automatically by the DaVinciCon-
figurator.
5.3.2.1 DerivativeMapping
If the SIP contains one or more modules with a DerivativeMapping, the BswmdModel classes for
these modules can only be generated for one certain derivative. By default, the first derivative
is selected, sorted by UUID.
If a other derivative shall be selected for BswmdModel generation a Settings.xml file can be
defined in the SIP at <SIP-ROOT-PATH>\DaVinciConfigurator\Generators.
Sample file:
<Settings >
<Settings Name =" com . vector . cfg . gen . bswmdmodelgenerator .
BswmdAutomationModelSettings ">
<! -- Selects the derivative with the name or UUID specified by
Value -->
<Setting Name =" SelectedDerivative " Value =" SPX546B "/>
</ Settings >
</ Settings >
Listing 5.20: Settings.xml sample for DerivativeMapping
5.4 Model Utility Classes
5.4.1 AutosarUtil
The class AutosarUtil is a static utility class. Its methods are not directly related to the MDF
model but are useful when client code deals with AUTOSAR paths and shortnames on string
basis.
Some of these methods are
• isValidShortname(String): Checks if this shortname is valid according the rules, the
AUTOSAR standard defines (character set for example)
• getLastShortname(String): Returns the last shortname of the specified AUTOSAR
path
• getFirstShortname(String): Returns the first shortname of the specified AUTOSAR
path
• getAllShortnames(String): Returns all shortnames of the specified AUTOSAR path
5.4.2 AsrPath
The AsrPath class represents an AUTOSAR path without a connection to any model.
AsrPaths are constant; their values cannot be changed after they are created. This class is
immutable!
© 2017, Vector Informatik GmbH
199 of 250

---

Chapter 5.
Data models in detail
5.4.3 AsrObjectLink
This class implements an immutable identifier for AUTOSAR objects.
An AsrObjectLink can be created for each object in the MDF AUTOSAR model tree. The
main use case of object links is to identify an object unambiguously at a specific point in time for
logging reasons. Additionally and under specific conditions it is also possible to find the releated
MDF object using its AsrObjectLink instance. But this search-by-link cannot be guaranteed
for each object type and after model changes (details and restrictions below).
5.4.3.1 Object links depend on the MDF object type
• Referrables
The object link is actually identical with the AUTOSAR path
• Ecuc objects with a definition (module, container and parameter)
The object link additionally stores the DefRef
• Ecuc parameters
The object link additionally stores the parameters index. This is the index of all parame-
ters with the same definition below the same parent container instance in the unfiltered
model view
5.4.3.2 Restrictions of object links
• They are immutable and will therefore become invalid when the model changes
• So they don’t guarantee that the related MDF object can be retrieved after the model
has been changed. Search-by-link may even find another object or throw an exception in
this case
5.4.3.3 Examples for object link strings
The method getObjectLinkString() returns for example the following strings:
• For a container or module configuration object, the AUTOSAR path is returned: "/Acti-
veEcuC/Can/CanGeneral"
• For a parameter, the parents AUTOSAR path, the last shortname of its definition and a
positional index in the list of parameters with the same definition is used: "/ActiveEcu-
C/Can/CanGeneral[2:SomeDefName]"
• In case of variant objects, all variants, this object is visible in, are added: /ActiveEcuC/-
Can/CanConfigSet/CanHardwareObject[0:CanControllerRef]{VariantA, VariantB}
5.4.4 DefRefs
The DefRef class represents an AUTOSAR definition reference (e.g. /MICROSAR/CanIf) wit-
hout a connection to any model. A DefRef replaces the String which represents a definition
reference. You shall always use a DefRef instance, when you want to reference something by
it’s definition.
© 2017, Vector Informatik GmbH
200 of 250

---

Chapter 5.
Data models in detail
The class abstracts the behavior of definition references in the AUTOSAR model (e.g. AUTO-
SAR 3 and AUTOSAR 4 handling).
DefRefs are constant; their values can not be changed after they are created. All DefRef classes
are immutable.
A DefRef represents the definition reference as two parts:
• Package part - e.g. /MICROSAR
• Definition without the package part - e.g. CanIf/CanIfGeneral
This is used to navigate through the AUTOSAR model with refinements and wildcards. So you
have to create a DefRef with the two parts separated.
The figure 5.14 shows the structure of the DefRef class and its sub classes.
Figure 5.14: DefRef class structure
Creation
You can create a DefRef object with following public static methods (partial):
• DefRef.create(DefRef, String) - Parent DefRef, Child name
• DefRef.create(IDefRefWildcard, String) - Wildcard, Definition without package
• DefRef.create(MIHasDefinition) - Model object
• DefRef.create(MIHasDefinition, String) - Parent object, Child name
• DefRef.create(MIParamConfMultiplicity) - Definition object
• DefRef.create(String, String) - Package part, Definition without package
Wildcards
DefRef instances can also have a wildcard instead of a package String (IDefRefWildcard).
The wildcard is used to match on multiple packages. See chapter 5.4.4.2 on the next page for
details.
© 2017, Vector Informatik GmbH
201 of 250

---

Chapter 5.
Data models in detail
Useful Methods
This section describes some useful methods (Please look at the javadoc of
the DefRef class for a full documentation):
• defRef.isDefinitionOf(MIHasDefinition) - Checks the definition of the configuration
element and returns true if the element has the definition. The "defRef" object is e.g.
from the Constants class.
– Note: The method isDefinitionOf() returns false, if the element is removed or
invisible.
• defRef.asDefinitionOf(MIHasDefinition, Class<>) - Checks the definition of the
configuration element and returns the element casted to the configuration subtype, or
null.
– Note: The method asDefinitionOf() returns null, if the element is removed or
invisible.
MIObject yourObject = ...;
DefRef yourDefRef = ...;
if ( y o u r D e f R e f . i s D e f i n i t i o n O f ( y o u r O b j e c t ) {
// It is the correct instance
// Do something
}
// Or with an integrated cast in the TypedDefRef case
f i n a l M I C o n t a i n e r c on ta in er = y o u r D e f R e f . a s D e f i n i t i o n O f ( y ou rO bj ec t ) ;
if ( c on ta in er
!= null ){
// Do something
}
Listing 5.21: DefRef isDefinitionOf methods
5.4.4.1 TypedDefRefs
The TypedDefRef class represents an AUTOSAR definition reference with the type of the
AUTOSAR (MDF) model. So every TypedDefRef knows which Definition, Configuration and
Value element is correct for the Definition path.
The DEF_TYPE, CONFIG_TYPE and VALUE_TYPE are Java generics and are used many APIs to
return the specific type of a request.
In addition the most TypedDefRefs also provide additional TypeInfo data, like the Multiplicity
of the element. See TypeInfo javadoc for more details.
5.4.4.2 DefRef Wildcards
The DefRef class supports so called wildcards, which could be used to match on multiple
packages at once, like the /[MICROSAR] wildcard matches on any DefRef package starting with
/MICROSAR. E.g. /MICROSAR, /MICROSAR/S12x, ....
Every wildcard is of type IDefRefWildcard. An IDefRefWildcard instance could be passed
to the DefRef.create(IDefRefWildcard, String) method to create a DefRef with wildcard
information.
© 2017, Vector Informatik GmbH
202 of 250

---

Chapter 5.
Data models in detail
Predefined DefRef Wildcards
The class EDefRefWildcard contains the predefined IDefRef-
Wildcards for the DefRef class. These IDefRefWildcards could be used to create DefRefs,
without creating your own wildcard for the standard use cases
The DefRef.create(String, String) method will parse the first String to find a wildcard
matching the EDefRefWildcards.
Predefined wildcards:
The class EDefRefWildcard defines the following wildcards, with the
specified semantic:
• EDefRefWildcard.ANY /[ANY]: Matches on any package path. It is equal to any package
and any packages refines from ANY wildcard.
• EDefRefWildcard.AUTOSAR /[AUTOSAR]: Matches on the AUTOSAR3 and AUTOSAR4
packages (see DefRef class). It is equal to the AUTOSAR packages, but not to refined
packages e.g. /MICROSAR. Any packages which refined from AUTOSAR also refines
from AUTOSAR wildcard.
• EDefRefWildcard.NOT_AUTOSAR_STMD /[!AUTOSAR_STMD]: Matches on any package ex-
cept the AUTOSAR packages. It is equal to any package, except AUTOSAR packages.
Any package refines from NOT_AUTOSAR_STMD wildcard, except AUTOSAR packages.
• EDefRefWildcard.MICROSAR /[MICROSAR]: Matches on any package stating with /MI-
CROSAR (also /MICROSAR/S12x). It is equal to any package stating with /MICRO-
SAR. Any package starting with /MICROSAR refines from MICROSAR wildcard.
• EDefRefWildcard.NOT_MICROSAR /[!MICROSAR]: Matches on any package path not star-
ting with /MICROSAR. It is equal to any package not starting with /MICROSAR. Any
package, which does not start with /MICROSAR, refines from NOT_MICROSAR wildcard.
Also the AUTOSAR packages refine from NOT_MICROSAR wildcard.
Creation of the DefRef with Wildcard
The elements of EDefRefWildcard could be passed
to the DefRef constructor:
DefRef myDefRef = DefRef . create ( EDefRefWildcard . MICROSAR , " CanIf ");
Listing 5.22: Creation of DefRef with wildcard from EDefRefWildcard
Custom DefRef Wildcards
You could create your own wildcard by implementing the interface
IDefRefWildcard. Please choose a good name for your wildcard, because this could be displayed
to the user, e.g. in Validation results. The matches(DefRef) method shall return true, if the
passed DefRef matches the wildcard constraints.
Every wildcard string shall have the notation /[NameOfWildcard].
E.g.
/[MICROSAR], /[!MICROSAR].
5.4.5 CeState
The CeState is an object which allows to retrieve different states of a configuration entity
(typically containers or parameters).
The most important APIs for generator and script code are:
• IParameterStatePublished
© 2017, Vector Informatik GmbH
203 of 250

---

Chapter 5.
Data models in detail
• IContainerStatePublished
5.4.5.1 Getting a CeState object
The BSWMD models implement methods to get the CeState for a specific CE as the following
listing shows (the types GIParameter and GIContainer are interface base types in the BSWMD
models):
GIParameter parameter = ...;
IParameterStatePublished parameterState = parameter . getCeState ();
GIContainer container = ...;
IContainerStatePublished containerState = container . getCeState ();
Listing 5.23: Getting CeState objects using the BSWMD model
5.4.5.2 IParameterStatePublished
The IParameterStatePublished specifies a type-safe published API for parameter states. It
mainly covers the following state information
• Does this parameter have a pre-configuration value?
What is this value?
The same
information is being provided for recommended and initial (derived) values
• Is this parameter user-defined?
• Is value change or deletion allowed in the current configuration phase (post-build loadable
use case)?
• What is the configuration class of this parameter
The figure 5.15 shows the inheritance hierarchy of the IParameterStatePublished class and
its sub classes.
Figure 5.15: IParameterStatePublished class structure
Parameters have different types of state information:
© 2017, Vector Informatik GmbH
204 of 250

---

Chapter 5.
Data models in detail
• Simple state retrieval
Example: The method isUserDefined() returns true when the parameter has a user-
defined flag.
• States and values (pre-configuration, recommended configuration and inital (derived)
values)
Example: The method hasPreConfigurationValue() returns true when the parameter
has a pre-configured value. getPreConfigurationValue() returns this value.
• States and reasons
Example: The method isDeletionAllowedAccordingToCurrentConfigurationPhase()
returns true if the parameter can be deleted in the current configuration phase (post-build
loadable projects only). getNotDeletionAllowedAccordingToCurrentConfigurationP-
haseReasons() returns the reasons if deletion is not allowed.
5.4.5.3 IContainerStatePublished
The IContainerStatePublished specifies a type-safe published API for container states. It
mainly covers the following state information
• Does this container have a pre-configuration container (includes access to this container)?
The same information is being provided for recommended and initial (derived) values
• Is change or deletion allowed in the current configuration phase (post-build loadable use
case)?
• In which configuration phase has this container been created in (post-build loadable use
case)?
• What is the configuration class of this container
The figure 5.16 on the next page shows the inheritence hierarchy of the IContainerStatePu-
blished class and its sub classes.
This API provides state information similar to IParameterStatePublished. Some of the states
are container-specific, of course. getCreationPhase(), for example, which returns the phase a
container in a post-build loadable configuration has been created in.
5.5 Model Services
5.5.1 EcucDefinitionAccess
The IEcucDefinitionAccess provides convenient and typesafe access to definition objects
(module, container, parameter and reference definitions). The contained def() methods take
MDF definition objects and return wrappers which can be used to retrieve specific characteristics
of definitions.
Example:
© 2017, Vector Informatik GmbH
205 of 250

---

Chapter 5.
Data models in detail
Figure 5.16: IContainerStatePublished class structure
IEcucDefinitionAccess eda ;
MIIntegerParamDef intParamDef ;
// Get the integer definition wrapper
IEcucIntegerDefinition def = eda . def ( intParamDef );
// Get the ( optional ) default value
Optional < BigInteger > defaultOpt = def . getDefault ();
b o o l e a n
hasDefault = defaultOpt . isPresent ();
BigInteger defaultValue = defaultOpt . get ();
// Get the multiplicity
IEcucDefMultiplicity multiplicity = def . getMultiplicity ();
BigInteger lower = multiplicity . getLower ();
BigInteger upper = multiplicity . getUpper ();
Listing 5.24: Integer parameter definition access examples
5.5.1.1 Post-build loadable
EcucModuleDefinition
IEcucModuleDefinition is the interface of the module definition wrap-
per. It provides the following method(s):
getSupportedConfigurationVariants()
The getSupportedConfigurationVariants() method returns a collection of supported confi-
guration variants. Never returns null but an empty collection if no supported config variants
are specified.
The returned collection never contains the following literals:
© 2017, Vector Informatik GmbH
206 of 250

---

Chapter 5.
Data models in detail
• EEcucConfigurationVariant.PRECONFIGURED_CONFIGURATION
• EEcucConfigurationVariant.RECOMMENDED_CONFIGURATION
This method is for post-build loadable only!
Remark about AUTOSAR versions: Prior to AUTOSAR 4.2.1 the module definitions used
the following valid values:
• VARIANT-PRE-COMPILE
• VARIANT-LINK-TIME
• VARIANT-POST-BUILD-LOADABLE
• VARIANT-POST-BUILD-SELECTABLE
VARIANT-POST-BUILD was invalid! With AUTOSAR 4.2.1 and later, the following values are
valid (because the loadable and selectable specifications have been separated):
• VARIANT-PRE-COMPILE
• VARIANT-LINK-TIME
• VARIANT-POST-BUILD
VARIANT-POST-BUILD-LOADABLE and VARIANT-POST-BUILD-SELECTABLE are invalid!
This method takes the AUTOSAR version into account and returns the post-build loadable
relevant specification only.
EcucContainerDefinition
IEcucContainerDefinition is the interface of the container defi-
nition wrapper. It provides the following method(s):
getMultiplicityConfigurationClass()
The getMultiplicityConfigurationClass(EEcucConfigurationVariant) method returns the
multiplicity configuration class for the specified module implementation variant. The returned
value defines in which configuration phase the number of container instances latest may change
if the module implements the specified variant.
Supported values for the variant are
• EEcucConfigurationVariant.VARIANT_PRE_COMPILE
• EEcucConfigurationVariant.VARIANT_LINK_TIME
• EEcucConfigurationVariant.VARIANT_POST_BUILD_LOADABLE
Other values lead to an IllegalArgumentException.
This method doesn’t take the multiplicity into account. It only investigates the multiplicity
configuration class as specified in the related container definition. So it still may return EEcuc-
ConfigurationClass.POST_BUILD even if the multiplicity is 1:1 for example. The post-build
loadable use case differs here from post-build selectable (see supportsVariantMultiplicity())
because the changeability in the post-build phase is being inherited from parent objects. So, if
you want to find out if a container actually permits changes in the post-build phase, you should
use IContainerStatePublished.
This method is for post-build loadable only!
Remark about AUTOSAR versions: Prior to AUTOSAR 4.2.1 the container definitions
contained the postBuildChangeable flag to define post-build loadable support. This method
© 2017, Vector Informatik GmbH
207 of 250

---

Chapter 5.
Data models in detail
internally investigates the postBuildChangeable flag in this case but the multiplicityCon-
figClass table for AUROSAR 4.2.1 and newer versions.
EcucCommonAttributes
IEcucCommonAttributes is the base interface of all parameter and
reference definition wrappers. It provides the following method(s):
getMultiplicityConfigurationClass()
The getMultiplicityConfigurationClass(EEcucConfigurationVariant) method returns the
multiplicity configuration class for the specified module implementation variant. The returned
value defines in which configuration phase the number of parameter instances latest may change
if the module implements the specified variant.
Supported values for the variant are
• EEcucConfigurationVariant.VARIANT_PRE_COMPILE
• EEcucConfigurationVariant.VARIANT_LINK_TIME
• EEcucConfigurationVariant.VARIANT_POST_BUILD_LOADABLE
Other values lead to an IllegalArgumentException.
This method doesn’t take the multiplicity into account. It only investigates the multiplicity
configuration class as specified in the related parameter definition. So it still may return EEcuc-
ConfigurationClass.POST_BUILD even if the multiplicity is 1:1 for example. The post-build
loadable use case differs here from post-build selectable (see supportsVariantMultiplicity())
because the changeability in the post-build phase is being inherited from parent objects. So,
if you want to find out if a parameter actually permits changes in the post-build phase, you
should use IParameterStatePublished.
This method is for post-build loadable only!
Remark about AUTOSAR versions: Prior to AUTOSAR 4.2.1 the parameter definitions
contain the implementationConfigClass table to define post-build loadable support. This
method internally investigates the implementationConfigClass in this case but the multi-
plicityConfigClass table for AUROSAR 4.2.1 and newer versions.
getValueConfigurationClass()
The getValueConfigurationClass(EEcucConfigurationVariant) method returns the value
configuration class for the specified module implementation variant. The returned value defines
in which configuration phase the value of parameter instances latest may change if the module
implements the specified variant.
Supported values for the variant are
• EEcucConfigurationVariant.VARIANT_PRE_COMPILE
• EEcucConfigurationVariant.VARIANT_LINK_TIME
• EEcucConfigurationVariant.VARIANT_POST_BUILD_LOADABLE
Other values lead to an IllegalArgumentException.
This method never returns EEcucConfigurationClass.LINK.
This method is for post-build loadable only!
Remark about AUTOSAR versions: Prior to AUTOSAR 4.2.1 the parameter definitions
contain the implementationConfigClass table to define post-build loadable support. This
© 2017, Vector Informatik GmbH
208 of 250

---

Chapter 5.
Data models in detail
method internally investigates the implementationConfigClass in this case but the value-
ConfigClass table for AUROSAR 4.2.1 and newer versions.
5.5.1.2 Post-build selectable
EcucModuleDefinition
IEcucModuleDefinition is the interface of the module definition wrap-
per. It provides the following method(s):
supportsPostBuildVariance()
The supportsPostBuildVariance() method returns true if this module configuration supports
post-build selectable.
Remark about AUTOSAR versions: Prior to AUTOSAR 4.2.1 the module definitions
supportedSupportedConfigurationVariants defined both, post-build loadable and selectable
support. With AUTOSAR 4.2.1 the supportedSupportedConfigurationVariants specifies
post-build loadable only and this method returns the value of the new postBuildVariantSup-
port flag.
EcucCommonAttributes
IEcucContainerDefinition is the interface of the container defini-
tion wrapper. It provides the following method(s):
supportsVariantMultiplicity()
The supportsVariantMultiplicity() method returns true if this container type supports
variant multiplicity. If true is returned this means that different variants may contain different
number of instances of this container type.
This method takes the multiplicity into account. So, if the container definition specifies the
multiplicity with lower == upper, it always returns false. Concerning post-build selectable it
never makes sense to permit variance if lower and upper multiplicity are equal.
This method is for post-build selectable only!
Remark about AUTOSAR versions: Prior to AUTOSAR 4.2.1 the container definitions
contained the postBuildChangeable flag to define post-build loadable support. This method
internally investigates the postBuildChangeable flag in this case but the postBuildVariant-
Multiplicity flag for AUROSAR 4.2.1 and newer versions.
supportsVariantShortname()
The supportsVariantShortname() method returns true if one of the following conditions
apply.
• supportsVariantMultiplicity() returns true
• The ADMIN-DATA flag postBuildSelectableChangeable is true
The use case for this specification are 1:1 containers. When this method returns true, 1:1
containers may have different shortnames in different variants. This is a Vector specific semantic
which is not provided by AUTOSAR.
EcucCommonAttributes
IEcucCommonAttributes is the base interface of all parameter and
reference definition wrappers. It provides the following method(s):
supportsVariantMultiplicity()
The supportsVariantMultiplicity() method returns true if this parameter type supports
© 2017, Vector Informatik GmbH
209 of 250

---

Chapter 5.
Data models in detail
variant multiplicity. If true is returned this means that different variants may contain different
number of instances of this parameter type.
This method takes the multiplicity into account. So, if the parameter definition specifies the
multiplicity with lower == upper, it always returns false. Concerning post-build selectable it
never makes sense to permit variance if lower and upper multiplicity are equal.
This method is for post-build selectable only!
Remark about AUTOSAR versions: Prior to AUTOSAR 4.2.1 the parameter definitions
contain the implementationConfigClass table to define post-build selectable support. This
method internally investigates the implementationConfigClass in this case but the post-
BuildVariantMultiplicity flag for AUROSAR 4.2.1 and newer versions.
supportsVariantValue()
The supportsVariantValue() method returns true if this parameter type supports a variant
value. If true is returned this means that different variants may contain different values in
instances of this parameter type.
This method is for post-build selectable only!
Remark about AUTOSAR versions: Prior to AUTOSAR 4.2.1 the parameter definitions
contain the implementationConfigClass table to define post-build selectable support. This
method internally investigates the implementationConfigClass in this case but the post-
BuildVariantValue flag for AUROSAR 4.2.1 and newer versions.
5.5.2 EcuConfigurationAccess
The IEcuConfigurationAccess provides convenient and typesafe access to configuration ob-
jects (modules, containers, parameters and references). The contained cfg() methods take
MDF (ECU configuration) objects and return wrappers which can be used to retrieve specific
characteristics of the configuration content.
Example:
IEcuConfigurationAccess eca ;
MINumericalValue intParam ;
// Get the parameter wrapper
IEcucNumericalParameter numCfg = eca . cfg ( intParam );
// Check if this is an integer parameter
if ( numCfg i n s t a n c e o f I E c u c I n t e g e r P a r a m e t e r ) {
IEcucIntegerParameter intCfg = ( IEcucIntegerParameter ) numCfg ;
// Get the parameter value
b o o l e a n hasValue = intCfg . hasValue () ;
BigInteger value = intCfg . getValue ();
// Get the related definition wrapper
IEcucIntegerDefinition def = intCfg . getEcucDefinition ();
}
Listing 5.25: Integer parameter configuration access examples
© 2017, Vector Informatik GmbH
210 of 250

---

Chapter 5.
Data models in detail
5.5.2.1 Post-build loadable
EcucModuleConfiguration
IEcucModuleConfiguration is the base interface of all module
configuration wrappers. It provides the following method(s):
getConfigurationVariant()
The getConfigurationVariant() method returns the modules configuration variant.
This method never returns null. If the module has no value specified, this method returns a
default value as follows:
• EEcucConfigurationVariant.VARIANT_PRE_COMPILE, if it is contained in the supported
config variants of the related module definition
• otherwise EEcucConfigurationVariant.VARIANT_LINK_TIME, if it is contained in the
supported config variants of the related module definition
• otherwise EEcucConfigurationVariant.VARIANT_POST_BUILD_LOADABLE, if it is contai-
ned in the supported config variants of the related module definition
• otherwise EEcucConfigurationVariant.VARIANT_PRE_COMPILE, even if not contained in
the supported config variants of the related module definition or if the definition is not
available
Remark about AUTOSAR versions: Prior to AUTOSAR 4.2.1 the module configurations
implementation config variant defined if this module implements post-build loadable and/or
selectable. With AUTOSAR 4.2.1 the implementation config variant defines only if the module
implements post-build loadable.
The post-build selectable aspect has been separated from
this definition. This method handles the loadable semantic, independent of the AUTOSAR
version.
This is for post-build loadable only!
setConfigurationVariant()
The setConfigurationVariant(EEcucConfigurationVariant) method sets the specified im-
plementation configuration variant.
This is for post-build loadable only!
Supported values are
• EEcucConfigurationVariant.VARIANT_PRE_COMPILE
• EEcucConfigurationVariant.VARIANT_LINK_TIME
• EEcucConfigurationVariant.VARIANT_POST_BUILD_LOADABLE
Remarks concerning AUTOSAR versions:
• If the modules definition has schema version 4.2.1 or higher, the specified value is being
written directly to the model
• If the modules definition has a schema version lower than 4.2.1, the modules imple-
mentation configuration variant in the MDF model encodes both, post-build loadable
and post-build selectable.
The following behavior is being implemented in this case:
© 2017, Vector Informatik GmbH
211 of 250

---

Chapter 5.
Data models in detail
Current model value
Parameter
Result in the model
PRE_COMPILE
PRE_COMPILE
PRE_COMPILE
LINK_TIME
LINK_TIME
POST_BUILD_LOADABLE
POST_BUILD_LOADABLE
LINK_TIME
PRE_COMPILE
PRE_COMPILE
LINK_TIME
LINK_TIME
POST_BUILD_LOADABLE
POST_BUILD_LOADABLE
POST_BUILD_LOADABLE
PRE_COMPILE
PRE_COMPILE
LINK_TIME
LINK_TIME
POST_BUILD_LOADABLE
POST_BUILD_LOADABLE
POST_BUILD_SELECTABLE
PRE_COMPILE
POST_BUILD_SELECTABLE
LINK_TIME
POST_BUILD_SELECTABLE
POST_BUILD_LOADABLE
POST_BUILD
POST_BUILD
PRE_COMPILE
POST_BUILD_SELECTABLE
LINK_TIME
POST_BUILD_SELECTABLE
POST_BUILD_LOADABLE
POST_BUILD
EcucContainer
IEcucContainer is the base interface of all container wrappers. It provides
the following method(s):
getEffectiveMultiplicityConfigurationClass()
The getEffectiveMultiplicityConfigurationClass() method walks up the model tree to
find the related module configuration. Then it uses the module implementation configuration
variant to return the selected configuration class as specified in the container definition.
This method never returns null. In case the detection of the configuration class fails (e.g. if the
related module configuration cannot be detected), this method returns EEcucConfiguration-
Class.PRE_COMPILE by default. It also never returns EEcucConfigurationClass.LINK.
This method is for post-build loadable only!
getEffectiveMultiplicityConfigurationClassDefRef()
The getEffectiveMultiplicityConfigurationClass(DefRef) method walks up the model
tree to find the related module configuration. Then it uses the module implementation con-
figuration variant to return the selected configuration class of the specified parameter defini-
tion.
This method never returns null. In case the detection of the configuration class fails (e.g. if the
related module configuration cannot be detected), this method returns EEcucConfiguration-
Class.PRE_COMPILE by default. It also never returns EEcucConfigurationClass.LINK.
This method is for post-build loadable only!
getEffectiveValueConfigurationClass()
The getEffectiveValueConfigurationClass(DefRef) method walks up the model tree to
find the related module configuration. Then it uses the module implementation configuration
variant to return the selected configuration class of the specified parameter definition.
This method never returns null. In case the detection of the configuration class fails (e.g. if the
related module configuration cannot be detected), this method returns EEcucConfiguration-
Class.PRE_COMPILE by default. It also never returns EEcucConfigurationClass.LINK.
This method is for post-build loadable only!
EcucParameter
IEcucParameter is the base interface of all parameter and reference wrappers.
It provides the following method(s):
getEffectiveMultiplicityConfigurationClass()
The getEffectiveMultiplicityConfigurationClass() method walks up the model tree to
© 2017, Vector Informatik GmbH
212 of 250

---

Chapter 5.
Data models in detail
find the related module configuration. Then it uses the module implementation configuration
variant to return the selected configuration class as specified in the parameter definition.
This method never returns null. In case the detection of the configuration class fails (e.g. if
the related module configuration cannot be detected), this method returns EEcucConfigura-
tionClass.PRE_COMPILE by default.
This is for post-build loadable only!
getEffectiveValueConfigurationClass()
The getEffectiveValueConfigurationClass() method walks up the model tree to find the
related module configuration. Then it uses the module implementation configuration variant to
return the selected configuration class as specified in the parameter definition.
This method never returns null. In case the detection of the configuration class fails (e.g. if
the related module configuration cannot be detected), this method returns EEcucConfigura-
tionClass.PRE_COMPILE by default.
This is for post-build loadable only!
5.5.2.2 Post-build selectable
EcucModuleConfiguration
IEcucModuleConfiguration is the base interface of all module
configuration wrappers. It provides the following method(s):
supportsPostBuildVariance()
The supportsPostBuildVariance() method returns true if this module configuration supports
post-build selectable.
This is for post-build selectable only!
What this method actually does:
• It checks if the related definition specifies post-build selectable as supported
• It checks if the module configuration implements post-build variance. That’s true in the
following cases
– If the modules definition has schema version 4.2.1 or higher: Check if the modules
ADMIN-DATA flag "postBuildVariantSupport" is true (false is default if this flag is
missing)
– If the modules definition has a schema version lower than 4.2.1: Check if the modu-
les implementation configuration variant contains one of the following values VARI-
ANT_POST_BUILD_SELECTABLE or VARIANT_POST_BUILD
It returns true if both conditions are true.
setPostBuildVarianceSupport()
The setPostBuildVarianceSupport(boolean) method sets the post-build support flag in the
module configuration.
This is for post-build selectable only!
Remarks concerning AUTOSAR versions:
• If the modules definition has schema version 4.2.1 or higher, this method sets the modules
ADMIN-DATA flag "postBuildVariantSupport" to the specified value.
© 2017, Vector Informatik GmbH
213 of 250

---

Chapter 5.
Data models in detail
• If the modules definition has a schema version lower than 4.2.1, the modules imple-
mentation configuration variant in the MDF model encodes both, post-build loadable
and post-build selectable.
The following behavior is being implemented in this case:
Current model value
Parameter
Result in the model
PRE_COMPILE
true
POST_BUILD_SELECTABLE
false
PRE_COMPILE
LINK_TIME
true
POST_BUILD_SELECTABLE
false
LINK_TIME
POST_BUILD_LOADABLE
true
POST_BUILD
false
POST_BUILD_LOADABLE
POST_BUILD_SELECTABLE
true
POST_BUILD_SELECTABLE
false
PRE_COMPILE
POST_BUILD
true
POST_BUILD
false
POST_BUILD_LOADABLE
EcucContainer
IEcucContainer is the base interface of all container wrappers. It provides
the following method(s):
supportsVariantMultiplicity()
The supportsVariantMultiplicity() method returns true if the related module configura-
tion supports variance and this containers definition support variant multiplicity. If true is
returned this means that different variants may contain different number of instances of this
container.
If the container has no definition, this method returns false.
This method is for post-build selectable only!
EcucParameter
IEcucParameter is the base interface of all parameter and reference wrappers.
It provides the following method(s):
supportsVariantMultiplicity()
The supportsVariantMultiplicity() method returns true if the related module configura-
tion supports variance and this parameters definition support variant multiplicity. If true is
returned this means that different variants may contain different number of instances of this
parameter.
If the parameter has no definition, this method returns false.
This is for post-build selectable only!
supportsVariantValue()
The supportsVariantValue() method returns true if the related module configuration sup-
ports variance and this parameters definition support variant values. If true is returned this
means that different variants may contain different values in instances of this parameter.
If the parameter has no definition, this method returns false.
This is for post-build selectable only!
© 2017, Vector Informatik GmbH
214 of 250

---

6 AutomationInterface Content
6.1 Introduction
This chapter describes the content of the DaVinci Configurator AutomationInterface.
6.2 Folder Structure
The AutomationInterface consists of the following files and folders:
• BswmdModel: contains the generated BswmdModel that is automatically created by
the DaVinci Configurator during startup
• Core
– AutomationInterface
∗ _doc (find more details to its content in chapter 6.3)
· DVCfg_AutomationInterfaceDocumentation.pdf: this document
· javadoc: Javadoc HTML pages
· templates: script file and script project templates for a simple start of
script development
∗ buildLibs: AutomationInterface Gradle Plugin to provide the build logic to
build script projects, see also 7.7 on page 221
∗ libs: compile bindings to Groovy and to the DaVinci Configurator Automati-
onInterface, used by IntelliJ IDEA and Gradle
∗ licenses: the licenses of the used open source libraries
6.3 Script Development Help
The help for the AutomationInterface script development is distributed among the following
sources:
• DVCfg_AutomationInterfaceDocumentation.pdf (this document)
• Javadoc HTML Pages
• Script Templates
6.3.1 DVCfg_AutomationInterfaceDocumentation.pdf
You find this document as described in chapter 6.2. It provides a good overview of architecture,
available APIs and gives an introduction of how to get started in script development. The focus
of the document is to provide an overview and not to be complete in API description. To get
a complete and detailed description of APIs and methods use the Javadoc HTML Pages as
described in 6.3.2 on the next page.
© 2017, Vector Informatik GmbH
215 of 250

---

Chapter 6.
AutomationInterface Content
6.3.2 Javadoc HTML Pages
You find this documentation as described in chapter 6.2 on the preceding page. Open the file
index.html to access the complete DaVinci Configurator AutomationInterface API reference. It
contains descriptions of all classes and methods that are part of the AutomationInterface.
The Javadoc is also accessible at your source code in the IDE for script development.
6.3.3 Script Templates
You find the Script Templates as described in chapter 6.2 on the previous page. You may copy
them for a quick startup in script development.
6.4 Libs and BuildLibs
The AutomationInterface contains libraries to build projects, see buildLibs in 6.2 on the pre-
ceding page . And it contains other libraries which are described in libs in 6.2 on the previous
page.
© 2017, Vector Informatik GmbH
216 of 250

---

7 Automation Script Project
7.1 Introduction
An automation script project is a normal Java/Groovy development project, where the built
artifact is a single jar file. The jar file is created by the build system, see chapter 7.7 on
page 221.
It is the recommended way to develop scripts, containing more tasks or multiple classes.
The project provides IDE support for:
• Code completion
• Syntax highlighting
• API Documentation
• Debug support
• Build support
The recommended IDE is IntelliJ IDEA.
7.2 Automation Script Project Creation
To create a new script project please follow the instructions in chapter 2.4 on page 12.
7.3 Project File Content
An automation project will at least contain the following files and folders:
• Folders
– .gradle - Gradle temp folder - DO NOT commit it into a version control system
– build - Gradle build folder - DO NOT commit it into a version control system
– gradle - Gradle bootstrap folder - Please commit it into your version control system
– src - Source folder containing your Groovy, Java sources and resource files
• Files
– Gradle files - see 7.7.2 on page 222 for details
∗ gradlew.bat
∗ build.gradle
∗ settings.gradle
∗ projectConfig.gradle
∗ dvCfgAutomationBootstrap.gradle
© 2017, Vector Informatik GmbH
217 of 250

---

Chapter 7.
Automation Script Project
– IntelliJ Project files (optional) - DO NOT commit it into a version control system
∗ ProjectName.iws
∗ ProjectName.iml
∗ ProjectName.ipr
The IntelliJ Project files (*.iws, *.iml, *.ipr) can be recreated with the command in the
windows command shell (cmd.exe): gradlew idea
7.4 IntelliJ IDEA Usage
7.4.1 Supported versions
The supported IntelliJ IDEA versions are:
• 2016.1
• 2016.2
• 2016.3
Please use one of the versions above. With other versions, there could be problems with the
editing, code completion and so on.
The free Community edition is fully sufficient, but you could also use the Ultimate edi-
tion.
7.4.2 Building Projects
Project Build
The standard way to build projects is to choose the option <ProjectName>
[build] in the Run Menu in the toolbar and to press the Run Button beneath that menu.
Figure 7.1: Project Build
Project Continuous Build
A further option is provided for the case you prefer an automatic
project building each time you save your implementation.
If you choose the menu option
<ProjectName> continuous [build] in the toolbar the Run Button has to be pressed only
one time to start the continuous building. Hence forward each saving of your implementation
triggers an automatic building of the script project.
But be aware that the continuous build option is available for .java and .groovy
files only. In case of changes in e.g. .gradle files you still have to press the Run Button in
order to build the project.
Figure 7.2: Project Continuous Build
The Continuous Build process can be stopped with the Stop Button in the Run View.
© 2017, Vector Informatik GmbH
218 of 250

---

Chapter 7.
Automation Script Project
Figure 7.3: Stop Continuous Build
If you want to exit the IntelliJ IDEA while the Continuous Build process is still running, you
will be asked to disconnect from it. Having disconnected you are allowed to exit the IDE.
Figure 7.4: Disconnect from Continuous Build Process
7.4.3 Debugging with IntelliJ
Be aware that only script projects and not script files are debuggable.
To enable debugging you must start DaVinci Configurator application with the enableDebugger
option as described in 7.6 on page 221.
In the IntelliJ IDEA choose the option <ProjectName> [debug] in the Run Menu located
in the toolbar. Pressing the Debug Button starts a debug session.
Figure 7.5: Project Debug
Set your breakpoints in IntelliJ IDEA and execute the task. To stop the debug session press
the Stop Button in the Debugger View.
© 2017, Vector Informatik GmbH
219 of 250

---

Chapter 7.
Automation Script Project
Figure 7.6: Stop Debug Session
If you want to exit the IntelliJ IDEA while the Debug process is still running, you will be asked
to disconnect from it. Having disconnected you are allowed to exit the IDE.
Figure 7.7: Disconnect from Debug Process
7.4.4 Troubleshooting
Code completion, Compilation
If the code completion or compilation does not work, please
verify that the Java JDK settings in the IntelliJ IDEA are correct. You have to set the Project
JDK and the Gradle JDK setting. See 2.4.3 on page 15.
Gradle build, build button
If the Gradle build does nothing after start or the build button is
grayed, please verify that the Java JDK settings in the IntelliJ IDEA are correct. You have to
set the Gradle JDK setting. See 2.4.3 on page 15.
If the build button is marked with an error, please make sure that the Gradle plugin inside of
IntelliJ IDEA is installed. Open File->Settings...->Plugins and select the Gradle plugin.
IntelliJ Build
You shall not use the IntelliJ menu "Build" or the context menu entries "Make
Project", "Make Module", "Rebuild Project" or "Compile". The project shall be build with
Gradle not with IntelliJ IDEA. So you have to select one of the Run Configuration (Run menu)
to build the project as described in chapter 7.4 on page 218.
Groovy SDK not configured
If you get the message ’Groovy SDK is not configured for ...’
in IntelliJ IDEA you probably have to migrate your project as described in chapter 7.5 on the
next page.
Debugging - DaVinci Configurator does not start
If the DaVinciCfg.exe does not start when
the enableDebugger option is passed, please check if the default port (8000) is free, or choose
another free port by appending the port number to the enableDebugger option.
Compile errors - Could not find com.vector.cfg:DVCfgAutomationInterface
If you get com-
pile errors inside of the IntelliJ IDEA, after updating the DaVinci Configurator or moving
projects.
Please execute the Project Migration to newer DaVinci Configurator Version step,
see 7.5 on the following page.
© 2017, Vector Informatik GmbH
220 of 250

---

Chapter 7.
Automation Script Project
7.5 Project Migration to newer DaVinci Configurator Version
If you update your DaVinci Configurator version in your SIP, it could be necessary to execute
the IntelliJ IDEA task of Gradle to update your compile dependencies.
Steps to execute:
1. Close IntelliJ IDEA.
2. Update the DaVinci Configurator in your SIP
3. Open a command shell (cmd.exe) at your project folder
• Folder containing the gradlew.bat
4. Type gradlew idea and press enter
5. Wait until the task has finished
6. Open IntelliJ IDEA
This will update the compile time dependencies of your Automation Script Project according
to the new DaVinci Configurator version.
After this, please read the Changes (see chapter 8 on page 227) in the new release and update
your script, if something of interest has changed.
7.6 Debugging Script Project
Be aware that only script projects and not script files are debuggable.
To debug a script project, any java debugger could be used. Simply add the enableDebugger
parameter to the commandline of the DaVinci Configurator and attach your debugger.
DVCfgCmd -s MyApplScriptTask --enableDebugger
You could attach a debugger at port 8000 (default). If the DaVinci Configurator does not start
with the option, please see 7.4.4 on the preceding page.
Different Debug Port
DVCfgCmd -s MyApplScriptTask --enableDebugger <YOUR-PORT> --waitForDebugger
Example:
DVCfgCmd -s MyApplScriptTask --enableDebugger 12345 --waitForDebugger
You could attach a debugger at port 12345 (select any free port) and the DVCfgCmd process will
wait until the debugger is attached. You could also use these commandline parameters with
the DaVinciCFG.exe to debug a script project with the DaVinci Configurator UI.
7.7 Build System
The build system uses Gradle1 to build a single Jar file. It also setups the dependencies to the
DaVinci Configurator and create the IntelliJ IDEA project.
1http://gradle.org/ [2016-05-25]
© 2017, Vector Informatik GmbH
221 of 250

---

Chapter 7.
Automation Script Project
To setup the Gradle installation, see chapter 2.4.4 on page 15.
7.7.1 Jar Creation and Output Location
The call to gradlew build in the root directory of your automation script project will create
the jar file. The jar file is then located in:
• <ProjectRoot>\build\libs\<ProjectName>-<ProjectVersion>.jar
7.7.2 Gradle File Structure
The default automation project contains the following Gradle build files:
• gradlew.bat
– Gradle batch file to start Gradle (Gradle Wrapper2)
• build.gradle
– General build file - You can modify it to adapt the build to your needs
• settings.gradle
– General build project settings - See Gradle documentation3
• projectConfig.gradle
– Contains automation project specific settings - You can modify it to adapt the build
to your needs
• dvCfgAutomationBootstrap.gradle
– This is the internal bootstrap file. DO NOT change the file content.
7.7.2.1 projectConfig.gradle File settings
The file contains two essential parts of the build:
• Names of the scripts to load (automationClasses)
• The path to the DaVinci Configurator installation (dvCfgInstallation)
• Project version (version)
automationClasses
You have to add your classes to the list of automationClasses to
make them loadable.
The syntax of automationClasses is a list of Strings, of all classes as full qualified Class
names.
Syntax: "javaPkg.subPkg.ClassName"
2https://docs.gradle.org/current/userguide/gradle_wrapper.html [2016-05-25]
3https://docs.gradle.org/current/dsl/org.gradle.api.initialization.Settings.html [2016-05-25]
© 2017, Vector Informatik GmbH
222 of 250

---

Chapter 7.
Automation Script Project
// The property project . ext . automationClasses defines the classes to load
project . ext . automationClasses = [
" sample . MyScript ",
" otherPkg . MyOtherScript ",
" javapkg . ClassName "
]
Listing 7.1: The automationClasses list in projectConfig.gradle
dvCfgInstallation
The dvCfgInstallation defines the path to the DaVinci Configurator in-
stallation in your SIP. The installation is needed to retrieve the build dependencies and the
generated model.
You can change the path to any location containing the correct version of the DaVinci Confi-
gurator.
// Please specify the path to your DaVinci Configurator installation
project . ext . dvCfgInstallation = new File ("<PATH -TO - DaVinciConfiguratorFolder >")
Listing 7.2: The dvCfgInstallation in projectConfig.gradle
You could also evaluate SystemEnv variables, other project properties or Gradle settings to
define the path dependent of the development machine, instead of encoding an absolute path.
This will help, when the project is committed to a version control system. But this is project
dependent and out of scope of the provided template project.
// Use a System environment variable as path to the DaVinci Configurator
project . ext . dvCfgInstallation = new File ( System . getenv (' YOUR_ENV_VARIABLE '))
Listing 7.3: The dvCfgInstallation with an System env in projectConfig.gradle
version
The project.version defines the version of your Automation project, e.g. defines
the version suffix of the jar file.
7.7.3 Advanced Build Topics
7.7.3.1 Usage of external Libraries (Jars) in the AutomationProject
You could reference external libraries (Jar files) in your AutomationProject. But you have to
configure the libraries in the Gradle build files. DO NOT add a dependency in IntelliJ, this
will not work.
The easiest and prefered way is the use a library from any Maven repository like MavenCentral
or JCenter. This will also handle versions, and transitive dependencies automatically.
Otherwise you could download the jar file an place it in your project4, but this is NOT recom-
mended.
The referenced libraries will be automatically bundled into your Automation project, see chapter
includeDependenciesIntoJarfor details.
4See Gradle online documentation, how to add local jar files to the build dependencies
© 2017, Vector Informatik GmbH
223 of 250

---

Chapter 7.
Automation Script Project
How to add a Library?
We assume we have a jar from a Maven repository like Apache Commons
IO (the identifier would be ’commons-io:commons-io:2.5’, See MavenCentral).
• Open your build.gradle
• Add the code for the dependency
dependencies {
// Change the identifier to your library to use
compile 'commons -io: commons -io :2.5 '
// You could add multiple libraries with additional compile lines
}
• Optional: if you are behind a proxy or firewall:
– You must either set proxy options for gradle 5
– Prefered way: use a Maven repository inside your network: To set a repository,
add before the dependencies block:
repositories {
// URL to your repository . The URL below is the Vector internal network
server .
// Please change the URL to your server
maven { url 'http :// vistrcfgci1 .vi. vector . int / artifactory / all ' }
// Or reference MavenCentral server
mavenCentral ()
}
• Update the IntelliJ IDEA project
1. Close IntelliJ IDEA.
2. Open a command shell (cmd.exe) at your project folder
– Folder containing the gradlew.bat
3. Type gradlew idea and press enter
4. Wait until the task has finished
5. Open IntelliJ IDEA
Now your project has access to the specified library.
7.7.3.2 Static Compilation of Groovy Code
The AutomationInterface contains a Groovy compiler extension. This allows you to use Auto-
mation API in static compiled Groovy code.
You have to mark your classes or methods with:
5Gradle and Java online documentation for details how to set proxy settings
© 2017, Vector Informatik GmbH
224 of 250

---

Chapter 7.
Automation Script Project
@CompileStatic ( extensions = 'com . vector . cfg . groovy . extensions .
AutomationTypeChecking ')
def myMethod () {
}
@CompileStatic ( extensions = 'com . vector . cfg . groovy . extensions .
AutomationTypeChecking ')
c l a s s MyClass {
}
Listing 7.4: @CompileStatic with Automation API
The same applies, if you want to use the @TypeChecked annotation:
@TypeChecked ( extensions = 'com . vector . cfg . groovy . extensions .
AutomationTypeChecking ')
def myMethod () {
}
Listing 7.5: @TypeChecked with Automation API
7.7.3.3 Gradle dvCfgAutomation API Reference
The DaVinci Configurator build system provides a Gradle DSL API to set properties of the
build. The entry point is the keyword dvCfgAutomation
dvCfgAutomation {
classes project . ext . automationClasses
}
Listing 7.6: DaVinci Configurator build Gradle DSL API
The following methods are defined inside of the dvCfgAutomation block:
• classes (Type List<String>) - Defines the automation classes to load
• useBswmdModel (Type boolean) - Enables or disables the usage of the BswmdModel inside
of the script project.
• useJarSignerDaemon (Type boolean) - Enables or disables the usage of the Jar Signer
Daemon process.
• includeDependenciesIntoJar (Type boolean) - Enables or disables the inclusion of
dependencies during build
useBswmdModel
The useBswmdModel enables or disables the usage of the BswmdModel in-
side of the project.
This is helpful, if you want to create a project, which shall run with
different SIPs. This prevent the inclusion of the BswmdModel. The default is true (Use the
BswmdModel) if nothing is specified.
dvCfgAutomation {
useBswmdModel false
}
Listing 7.7: DaVinci Configurator build Gradle DSL API - useBswmdModel
© 2017, Vector Informatik GmbH
225 of 250

---

Chapter 7.
Automation Script Project
useJarSignerDaemon
The useJarSignerDaemon enables or disables the usage of the usage of
the Jar Signer Daemon process. The process is spawned when a jar file shall be signed. This
will speedup the build process especially when thr project is built often. The daemon is closed
automatically, when not used in a certain time span.
The default of useJarSignerDaemon is true.
The Gradle task stopJarSignerDaemon will stop any running Signer daemon.
dvCfgAutomation {
useJarSignerDaemon true
}
Listing 7.8: DaVinci Configurator build Gradle DSL API - useJarSignerDaemon
includeDependenciesIntoJar
The includeDependenciesIntoJar enables or disables bund-
ling of gradle runtime dependencies (e.g. referenced jar files) into the resulting project jar. If
includeDependenciesIntoJar is enabled the project jar file will contain all jar dependencies
under the folder jars inside of the jar file.
The default of includeDependenciesIntoJar is true.
dvCfgAutomation {
includeDependenciesIntoJar false
}
Listing 7.9: DaVinci Configurator build Gradle DSL API - includeDependenciesIntoJar
© 2017, Vector Informatik GmbH
226 of 250

---

8 AutomationInterface Changes between
Versions
This chapter describes the supported functionality of different versions and all API changes
between different MICROSAR releases.
8.1 Currently Supported Features
The table below contains a list of functionalities of the DaVinci Configurator Automation
Interface.
Legend: A functionality is available if the Since column contains the DaVinci Configurator
version (see Since). Otherwise the functionality is not yet available.
Component
Functionality
Since
Scripts
Loading, Execution, Script-Projects
5.13
User defined Script Task Arguments in UI and Cmd
5.14 SP1
Stateful Script Tasks
5.14
Project
Open, modify, save and close project
5.13
Accessing the active UI project
5.13
Create a new project
5.13
Access to project settings
Open ARXML files as Project without DPA
5.14
Switch configuation phase (Post-build loadable)
Model
Access to the whole AUTOSAR model (EcuC and System-
5.13
Desc)
Transaction support (Undo, Redo)
5.13
Type save access to ECU model using definitions provided by
5.13
the generated BswmdModel
Post-build selectable support
5.13
Access of variants, Access/Modification of variant data
5.13
Post-build loadable support
5.13
CE-States: UserDefined, Changeable, Deletable
5.13
Consideration of pre-configuration status
5.13
Access and modification of User Annotations at the configura-
5.15
tion element
Generation
Generate code for specific modules
5.13
Generate code for predefined code generation sequence
5.13
Execute external generation steps
5.13
Custom workflow execution
Modify code generation sequence to enable/disable specific mo-
5.13
dules or generation steps
SWC Templates and Contract Headers Generation
5.15
Add a ScriptTask as external generation step
5.13
Add a ScriptTask as custom workflow step
5.14
Validation
Access to project validation result
5.13
Access to validation results of specific model elements
5.13
© 2017, Vector Informatik GmbH
227 of 250

---

Chapter 8.
AutomationInterface Changes between Versions
Solve valdiation results (by group, by id, by solving action type
5.13
(preferred solving action))
Update Work-
Updating a project
5.13
flow
Input file access and modification (non-variant)
5.13
Input file access and modification (variant)
5.15
Configuration of system description merge
Access to update report
Reporting
Create predefined project reports
Create report based on specific CE set
Diff and Merge
Diff and Merge a Project (ActiveEcuC)
Diff and Merge a Project (SystemDescription)
Access to diff report
Persistency
Export of configuration artefacts
5.14
Export of ActiveEcuc
5.14
Export of Post-build selectable Variants per Variant
5.14
Export of AUTOSAR model trees
5.15
Export of Module Configurations
Import of configuration artefacts (Please inform Vector, if you
need an import)
Import of Module Configurations
Domains
Base
Nothing planned
Communication
Access and modification of Can controller configuration
5.13
Access and modification of Can filter masks
5.13
Access and modification of CanBusTimings registers
Access and modification of FullCan flag of PDUs
PDU and Channel abstraction
Diagnostic
Access and modification of Diagnostic Data Identifier
Access and modification of Diagnostic Event Data
5.14
Access and modification of Diagnostic Events
5.14
Setup of event memory blocks
Access and modification of Production error handling
I/O
Nothing planned
Memory
Memory Domain Model Partitions, Memory blocks
FeeOptimization
Mode Manage-
BSW Management
5.15
ment
API to provide the auto configuration (e.g. ECU state, module
5.15
initialization, communication control, ...)
API to configure logical expressions
API for custom configuration
Watchdogs: Access to the watchdogs settings and supervised
entities
Initialization: Auto initialization and reset, Access to driver
init lists
Runtime
Sy-
Component Port Connection
5.14
stem
Data Mapping
5.14
Task Mapping
Component prototype creation
© 2017, Vector Informatik GmbH
228 of 250

---

Chapter 8.
AutomationInterface Changes between Versions
Communication
Nothing planned
Control
© 2017, Vector Informatik GmbH
229 of 250

---

Chapter 8.
AutomationInterface Changes between Versions
8.2 Changes in MICROSAR AR4-R18 - Cfg5.15
8.2.1 General
The Cfg5.15 (AR4-R18) automation interface is mostly compatible to the Cfg5.14. So a script
written with Cfg5.14 will also run in the Cfg5.15 version.
8.2.2 Automation Script Project
You have to migrate your project to the new compile bindings. Please execute the instructions
in chapter 7.5 on page 221.
8.2.2.1 Supported IntelliJ IDEA Version
The IntelliJ IDEA version 2016.3 was added to the supported versions. See 7.4.1 on page 218
for details.
8.2.2.2 BuildSystem
Groovy - Static compilation
The AutomationInterface Groovy compiler extension added.
This allows you to use Automation API in static compiled Groovy code.
See 7.7.3.2 on
page 224.
includeDependenciesIntoJar
The includeDependenciesIntoJar Gradle build setting added.
See 7.7.3.3 on page 225 for details. The Gradle build will now automatically include jar depen-
dencies into your project jar.
8.2.3 Script Execution
8.2.3.1 User defined arguments
The ScriptTask user defined arguments now support validators to validate the input before
executing the task, like checking if the file exists. This provides fast user feedback. See 4.4.9.1
on page 47 for details.
8.2.4 Project Handling
New API added to create empty raw AUTOSAR model projects, see chapter 4.5.6.1 on page 65
for details.
8.2.5 Project Creation vVIRTUALtarget settings
New API added to customize vVIRTUALtarget project and executable settings for project
creation. See chapter 4.5.3.7 on page 60 for details.
© 2017, Vector Informatik GmbH
230 of 250

---

Chapter 8.
AutomationInterface Changes between Versions
8.2.6 Model changes
These changes could break your existing client code, if you have used these interfaces or met-
hods.
• Some interfaces have been renamed or moved:
– Interface MIMcFunctionDataRefSet moved
∗ from package com.vector.cfg.model.mdf.ar4x.commonstructure.
measurementcalibrationsupport
to package com.vector.cfg.model.mdf.ar4x.commonstructure.
measurementcalibrationsupport.rptsupport
– Interface MIMcFunctionDataRefSetConditional moved
∗ from package com.vector.cfg.model.mdf.ar4x.commonstructure.
measurementcalibrationsupport
to package com.vector.cfg.model.mdf.ar4x.commonstructure.
measurementcalibrationsupport.rptsupport
– Interface MIMcFunctionDataRefSetContent moved
∗ from package com.vector.cfg.model.mdf.ar4x.commonstructure.
measurementcalibrationsupport
to package com.vector.cfg.model.mdf.ar4x.commonstructure.
measurementcalibrationsupport.rptsupport
– Interface MIFt moved
∗ from package com.vector.cfg.model.mdf.model.autosar.commonpatterns.
textmodel.languagedatamodel.specializedloverviewparagraph
to package com.vector.cfg.model.mdf.model.autosar.commonpatterns.
textmodel.singlelanguagedata.specializedsloverviewparagraph
– Interface MIFt moved
∗ from package com.vector.cfg.model.mdf.model.autosar.commonpatterns.
textmodel.languagedatamodel.specializedlparagraph
to package com.vector.cfg.model.mdf.model.autosar.commonpatterns.
textmodel.singlelanguagedata.specializedslparagraph
• Some methods have been changed or removed:
– Interface com.vector.cfg.model.mdf.ar4x.diagnosticextract.dcm.
diagnosticservice.databyidentifier.MIDiagnosticDataByIdentifier
∗ MIDiagnosticDataIdentifierARRef getDataIdentifier()
changed to
MIDiagnosticAbstractDataIdentifierARRef getDataIdentifier()
∗ void setDataIdentifier(MIDiagnosticDataIdentifierARRef)
changed to
void setDataIdentifier(MIDiagnosticAbstractDataIdentifierARRef)
– Some ...Owner() methods were removed. The usage of these methods is not recom-
mended. Instead use the MIObject.miImmediateComposite() method.
© 2017, Vector Informatik GmbH
231 of 250

---

Chapter 8.
AutomationInterface Changes between Versions
8.2.7 Model Automation API
8.2.7.1 IVarianceApi
New method IVarianceApi.getAllVariantViewsOrInvariant() added.
8.2.7.2 Access methods
New access methods for the EcuConfigurationAccess and EcucDefinitionAccess added.
See
chapter 4.6.4.10 on page 89 for details.
New MDF access method added mdfModel(String). This method tries to resolve a model
element by testing multiple ways. See chapter 4.6.4.2 on page 81 details.
8.2.7.3 Reverse Reference Resolution - ReferencesPointingToMe
New methods to query references starting from reference targets added. See chapter 4.6.4.11
on page 90 for details.
8.2.7.4 Operations
New method setConfigurationVariantOfAllModuleConfigurations() added to IOperati-
ons class. See chapter 4.6.6.2 on page 97 for details.
New method createUniqueMappedAutosarPackage() added to IOperations class. See chap-
ter 4.6.6.2 on page 97 for details.
8.2.7.5 User Annotations
New API to access and modify User Annotations was added. See chapter 4.6.9.1 on page 102
for details.
8.2.7.6 Variance
New method variance.variantView(String name) added to retrieve a variant view by name.
8.2.7.7 Model Synchronization
New API added to execution the new Model Synchronization operation. See chapter 4.6.7 on
page 98 for details.
8.2.8 Persistency
New Persistency model exporter added exportModelTree(). See chapter 4.11 on page 162 for
details.
© 2017, Vector Informatik GmbH
232 of 250

---

Chapter 8.
AutomationInterface Changes between Versions
8.2.9 Workflow
New workflow API added to configure settings with updateSettings{}:
• Select the update mode (ECUC_ONLY, ECUC_AND_DEVELOPER_WORKSPACE)
• Parameter uuidUsageInStandardConfigurationEnabled
• Parameter uuidUsageInSystemDescriptionEnabled
8.2.10 Validation
8.2.10.1 Validation-Result Access Methods
New two new methods added to retrieve validation by model object in a recursive manner like
the editors.
• MIObject.getValidationResultsRecursive()
• IViewedModelObject.getValidationResultsRecursive()
8.2.11 Generation
8.2.11.1 SWC Templates and Contract Headers Generation
The SWC Templates and Contract Headers Generation (Swct) automation API was added, see
chapter 4.7.3 on page 111 for details.
8.2.12 BswmdModel
8.2.12.1 BswmdModel Groovy
Two new methods added to access the BswmdModel by MDF model objects in a generic way,
without knowing a DefRef. This is handy, if you want traverse an unknown Ecu configuration
structure.
• GIContainer bswmdModel(MIContainer)
• GIModuleConfiguration bswmdModel(MIModuleConfiguration) Both methods return
the base bswmd model types for the corresponding MDF model objects.
New methods added to access BswmdModel elements by path and or by Type:
• List bswmdModel(Class)
• List bswmdModel(Class, Closure)
• List bswmdModel(Class, String)
• List bswmdModel(Class, String, Closure)
© 2017, Vector Informatik GmbH
233 of 250

---

Chapter 8.
AutomationInterface Changes between Versions
8.2.12.2 DerivativeMapping
Until R17 modules with DerivativeMapping were ignored from the DaVinciConfigurator and no
BswmdModel classes were generated for these modules. Just the corresponding AsrXxx (e.g.
AsrOs) model classes were included in the BswmdModel. Now the BswmdModel classes for
these modules are generated for one certain derivative.
By default, the first derivative is selected, sorted by UUID. The AsrXxx usages have to be
replaced by the actual module in the scripts. See 5.3.2.1 on page 199 for more details.
8.2.13 Mode Management Domain
Introduced BswM auto configuration API for automatically creating dedicated parts of the
BswM configuration. See chapter 4.10.3.1 on page 137 for details.
8.2.14 Runtime System Domain
8.2.14.1 Data Mapping
’autoMapTo’ allows control now about the handling of nested arrays of primitive. See 4.10.4.2
on page 153 and 4.10.4.2 on page 159.
© 2017, Vector Informatik GmbH
234 of 250

---

Chapter 8.
AutomationInterface Changes between Versions
8.3 Changes in MICROSAR AR4-R17 - Cfg5.14
8.3.1 General
This is the first stable version of the DaVinci Configurator AutomationInterface.
8.3.2 Script Execution
8.3.2.1 Stateful Script Tasks
A new API was added to support cache and retrieve data over multiple script task executions.
See 4.4.10 on page 50 for more details.
8.3.3 Automation Script Project
You have to migrate your project to the new compile bindings. Please execute the instructions
in chapter 7.5 on page 221.
8.3.3.1 Groovy
The used Groovy version was updated from 2.4.5 to 2.4.7, please see Groovy website for de-
tails.
8.3.3.2 Supported IntelliJ IDEA Version
The IntelliJ IDEA version 2016.2 was added to the supported versions. See 7.4.1 on page 218
for details.
8.3.3.3 BuildSystem
Gradle
The used default Gradle version was updated from 2.13 to 3.0, please see Gradle
website for details.
useJarSignDaemon
The useJarSignDaemon Gradle build setting added. See 7.7.3.3 on page 225
for details.
8.3.4 Converter Refactoring
The converters previously provided by com.vector.cfg.automation.api.Converters have
been moved to the new com.vector.cfg.automation.scripting.api.ScriptConverters and
com.vector.cfg.model.groovy.api.ModelConverters.
8.3.5 UserInteraction
UserInteraction API added to show messages to the user, see 4.4.5.1 on page 40.
© 2017, Vector Informatik GmbH
235 of 250

---

Chapter 8.
AutomationInterface Changes between Versions
8.3.6 Project Load
8.3.6.1 AUTOSAR Arxml Files
New API added to open AUTOSAR arxml files as a temporary project. See chapter 4.5.6 on
page 64 for details.
8.3.7 Model
Script Tasks Types
The existing script task type DV_MODULE_ACTIVATION renamed to the new
name DV_ON_MODULE_ACTIVATION.
A new DV_ON_MODULE_DEACTIVATION task type added, which is execution when a module con-
figuration is deleted.
8.3.7.1 Transactions
A new ITransactionsApi added which provide access to the transactionHistory and API to re-
trieve information of running transactions. A new method transactions.isTransactionRunning()
added.
The ITransactionHistoryApiwas moved to the new ITransactionsApi. The access to the
history is now transactions.transactionHistory{}.
Operations
The new operations added:
• deactivateModuleConfiguration() to delete a module configuration
• activateModuleConfiguration(DefRef, String shortName) to activate a module con-
figuration with the specified short name
• createModelObject(Class<T>) to create arbitrary MDF model objects
• parameter.setUserDefined(boolean) method added to set and reset the user defined
flag
8.3.7.2 MDF Model Read and Write
The whole MDF model API was changed from the old mdfRead() and mdfWrite() to one
method mdfModel() with explicit write/create methods. You have to change all your mdfRead()
and mdfWrite() calls to mdfModel(). And every mdfWrite() closure the implicit creation to
explicit create calls.
This was necessary due to the fact that the old implicit API leads to surprising results, when
methods are called, which use the read API, but called in a write context. So the method would
yield different results, when called in different contexts.
The new MDF model API will never create any elements implicitly. Now there are explicit
create methods, like in the BswmdModel:
• For 0:1 elements: get<Element>OrCreate() method
• For 0:* elements: list.createAndAdd() and byNameOrCreate() methods
© 2017, Vector Informatik GmbH
236 of 250

---

Chapter 8.
AutomationInterface Changes between Versions
The write context is not needed anymore, but you have to open a transaction() before calling
any write API.
See the chapter 4.6.4.1 on page 79 for the read API and 4.6.4.3 on page 82 for the write
API.
8.3.7.3 SystemDescription Access
The SystemDescription Access API added to retrieve paths to elements like flat map, flat extract
and the corresponding model elements. See chapter 4.6.5 on page 94 for details.
8.3.7.4 ActiveEcuc
The class IActiveEcuc was renamed to IActiveEcucApi to reflect that it is not the active ecuc
element, but the API of the active ecuc.
8.3.8 Persistency
New Persistency API added to import and export model data. See chapter 4.11 on page 162
for details.
8.3.9 Generation
The generation script tasks DV_GENERATION_ON_START and DV_GENERATION_ON_END renamed
to DV_ON_GENERATION_START and DV_ON_GENERATION_END.
The new script task type DV_CUSTOM_WORKFLOW_STEP added to execute tasks in the custom
workflow. See 4.3.1.4 on page 31 for details.
The return type of validation and generation methods has changed to IGenerationResultMo-
del. This type provides more detailed information about the executed steps.
8.3.10 BswmdModel
8.3.10.1 Writing with BswmdModel
The BswmdModel supports now a write access for ecuc configuration elements. This means new
elements can be created and existing elements can be modified and deleted by the BswmdModel.
See 5.3.1.9 on page 195 for more details.
8.3.11 BswmdModel Groovy
bswmdModelRead
The BswmdModel access was changed from the old bswmdModelRead() to
the new bswmdModel() method. This was done to support the new write access.
Domain Object Navigation
The BswmdModel API now support the navigation from domain
model to the BswmdModel. See 4.6.3.6 on page 78.
© 2017, Vector Informatik GmbH
237 of 250

---

Chapter 8.
AutomationInterface Changes between Versions
8.3.12 Diagnostics Domain
Introduced new API which allows creation and querying of diagnostic events. Also OBD and
J1939 state of the configuration can be queried.
8.3.13 Communication Domain
Communication Domain API moved from
com.vector.cfg.dom.com.model.groovy into
com.vector.cfg.dom.com.groovy.api.
Can Controller classes moved from
com.vector.cfg.dom.com.model.groovy.can into
com.vector.cfg.dom.com.groovy.can.
8.3.14 Runtime System Domain
Runtime System API IRuntimeSystemApi now provides functionality to map ports and system
signals.
Entry points are the selectComponentPorts, selectSignalInstances and selectCommuni-
cationElements methods.
© 2017, Vector Informatik GmbH
238 of 250

---

Chapter 8.
AutomationInterface Changes between Versions
8.4 Changes in MICROSAR AR4-R16 - Cfg5.13
8.4.1 General
This is the first version of the DaVinci Configurator AutomationInterface.
8.4.2 API Stability
The API is not stable yet and could still be changed in later releases. So it could be necessary
to migrate your code when you update to later versions of the DaVinci Configurator.
8.4.3 Beta Status
Some features of the AutomationInterface are have beta status. This will change for later
versions of the AutomationInterface. Which means that some features:
• Are not fully tested
• Missing documentation
• Missing functionality
© 2017, Vector Informatik GmbH
239 of 250

---

9 Appendix
© 2017, Vector Informatik GmbH
240 of 250

---

Chapter 9.
Appendix
Nomenclature
AI
Automation Interface
AU T OSAR AUTomotive Open System ARchitecture
CE
Configuration Entity (typically a container or parameter)
Cf g
DaVinci Configurator
Cf g5 DaVinci Configurator
DV
DaVinci
IDE
Integrated Development Environment
J AR
Java Archive
J DK Java Development Kit
J RE
Java Runtime Environment
M DF Meta-Data-Framework
M SN ModuleShortName
© 2017, Vector Informatik GmbH
241 of 250

---

Figures
Figures
2.1
Script Samples location
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
11
2.2
Script Locations View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
11
2.3
Script Tasks View
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
11
2.4
Create New Script Project... Button . . . . . . . . . . . . . . . . . . . . . . . . .
12
2.5
Project Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
13
2.6
Project Build . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
14
2.7
Project SDK Setting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15
2.8
Gradle JVM Setting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15
3.1
DaVinci Configurator components and interaction with scripts
. . . . . . . . . .
17
3.2
Structure of scripts and script tasks
. . . . . . . . . . . . . . . . . . . . . . . . .
19
4.1
The API overview and containment structure . . . . . . . . . . . . . . . . . . . .
24
4.2
IScriptTaskType interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
29
4.3
Script Task Execution Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . .
35
4.4
ScriptingException and sub types . . . . . . . . . . . . . . . . . . . . . . . . . . .
42
4.5
Search for active project in getActiveProject() . . . . . . . . . . . . . . . . . . . .
53
4.6
example situation with the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
5.1
ECUC container type inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
5.2
MIObject class hierarchy and base interfaces
. . . . . . . . . . . . . . . . . . . . 175
5.3
Autosar package containment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
5.4
The ECUC container definition reference . . . . . . . . . . . . . . . . . . . . . . . 177
5.5
Invariant views hierarchy
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
5.6
Example of a model structure and the visibility of the IInvariantValuesView . . . 183
5.7
Variant specific change of a parameter value . . . . . . . . . . . . . . . . . . . . . 186
5.8
Variant common change of a parameter value . . . . . . . . . . . . . . . . . . . . 187
5.9
The relationship between the MDF model and the BswmdModel . . . . . . . . . 188
5.10 SubContainer DefRef navigation methods . . . . . . . . . . . . . . . . . . . . . . 191
5.11 Untyped reference interfaces in the BswmdModel . . . . . . . . . . . . . . . . . . 192
5.12 Creating a BswmdModel in the Post-build selectable use case . . . . . . . . . . . 193
5.13 Class and Interface Structure of the BswmdModel
. . . . . . . . . . . . . . . . . 195
5.14 DefRef class structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
5.15 IParameterStatePublished class structure
. . . . . . . . . . . . . . . . . . . . . . 204
5.16 IContainerStatePublished class structure . . . . . . . . . . . . . . . . . . . . . . . 206
7.1
Project Build . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
7.2
Project Continuous Build . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
7.3
Stop Continuous Build . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
7.4
Disconnect from Continuous Build Process . . . . . . . . . . . . . . . . . . . . . . 219
7.5
Project Debug
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
7.6
Stop Debug Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
7.7
Disconnect from Debug Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
© 2017, Vector Informatik GmbH
242 of 250

---

Tables
Tables
5.1
Different Class types in different models . . . . . . . . . . . . . . . . . . . . . . . 189
© 2017, Vector Informatik GmbH
243 of 250

---

Listings
3.1
Static field memory leak . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
22
3.2
Memory leak with closure variable . . . . . . . . . . . . . . . . . . . . . . . . . .
23
4.1
Task creation with default type . . . . . . . . . . . . . . . . . . . . . . . . . . . .
25
4.2
Task creation with TaskType Application . . . . . . . . . . . . . . . . . . . . . .
26
4.3
Task creation with TaskType Project . . . . . . . . . . . . . . . . . . . . . . . . .
26
4.4
Define two tasks is one script . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
26
4.5
Script creation with IDE support . . . . . . . . . . . . . . . . . . . . . . . . . . .
26
4.6
Task with isExecutableIf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
27
4.7
Script with description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
27
4.8
Task with description
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
28
4.9
Task with description and help text
. . . . . . . . . . . . . . . . . . . . . . . . .
28
4.10 Access automation API in Groovy clients by the IScriptExecutionContext . . . .
33
4.11 Access to automation API in Java clients by the IScriptExecutionContext . . . .
34
4.12 Script task code block arguments . . . . . . . . . . . . . . . . . . . . . . . . . . .
34
4.13 Resolves a path with the resolvePath() method . . . . . . . . . . . . . . . . . . .
36
4.14 Resolves a path with the resolvePath() method . . . . . . . . . . . . . . . . . . .
37
4.15 Resolves a path with the resolveScriptPath() method . . . . . . . . . . . . . . . .
37
4.16 Resolves a path with the resolveProjectPath() method . . . . . . . . . . . . . . .
38
4.17 Resolves a path with the resolveSipPath() method . . . . . . . . . . . . . . . . .
38
4.18 Resolves a path with the resolveTempPath() method . . . . . . . . . . . . . . . .
38
4.19 Get the project output folder path . . . . . . . . . . . . . . . . . . . . . . . . . .
39
4.20 Get the SIP folder path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
39
4.21 Usage of the script logger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
40
4.22 Usage of the script logger with message formatting . . . . . . . . . . . . . . . . .
40
4.23 Usage of the script logger with Groovy GString message formatting . . . . . . . .
40
4.24 UserInteraction from a script . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
41
4.25 Stop script task execution by throwing an ScriptClientExecutionException . . . .
42
4.26 Changing the return code of the console application by throwing an ScriptClien-
tExecutionException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
43
4.27 Using your own defined method . . . . . . . . . . . . . . . . . . . . . . . . . . . .
44
4.28 Using your own defined class
. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
44
4.29 Using your own defined method with a daVinci block . . . . . . . . . . . . . . . .
44
4.30 ScriptApi.scriptCode{} usage in own method . . . . . . . . . . . . . . . . . . . .
45
4.31 ScriptApi.scriptCode() usage in own method
. . . . . . . . . . . . . . . . . . . .
45
4.32 ScriptApi.activeProject{} usage in own method . . . . . . . . . . . . . . . . . . .
46
4.33 ScriptApi.activeProject() usage in own method . . . . . . . . . . . . . . . . . . .
46
4.34 Script task UserDefined argument with no value
. . . . . . . . . . . . . . . . . .
46
4.35 Define and use script task user defined arguments from commandline . . . . . . .
47
4.36 Script task UserDefined argument with default value . . . . . . . . . . . . . . . .
47
4.37 Script task UserDefined argument with multiple values . . . . . . . . . . . . . . .
47
4.38 Script task UserDefined argument with predefined validator . . . . . . . . . . . .
48
4.39 Script task UserDefined argument with own validator
. . . . . . . . . . . . . . .
48
4.40 executionData - Cache and retrieve data during one script task execution . . . .
50
4.41 sessionData - Cache and retrieve data over multiple script task executions . . . .
50
4.42 sessionData and executionData syntax samples . . . . . . . . . . . . . . . . . . .
51
4.43 Accessing IProjectHandlingApi as a property . . . . . . . . . . . . . . . . . . . .
52
© 2017, Vector Informatik GmbH
244 of 250

---

Listings
4.44 Accessing IProjectHandlingApi in a scope-like way . . . . . . . . . . . . . . . . .
52
4.45 Switch the active project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
53
4.46 Accessing the active IProject
. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
54
4.47 Creating a new project (mandatory parameters only) . . . . . . . . . . . . . . . .
54
4.48 Creating a new project (with some optional parameters) . . . . . . . . . . . . . .
55
4.49 Creating a new project with custom VTT settings
. . . . . . . . . . . . . . . . .
61
4.50 Opening a project from .dpa file
. . . . . . . . . . . . . . . . . . . . . . . . . . .
62
4.51 Parameterizing the project open procedure
. . . . . . . . . . . . . . . . . . . . .
62
4.52 Opening, modifying and saving a project . . . . . . . . . . . . . . . . . . . . . . .
63
4.53 Opening Arxml files as project
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
64
4.54 Create an empty AUTOSAR model
. . . . . . . . . . . . . . . . . . . . . . . . .
65
4.55 Read with BswmdModel objects starting with a module DefRef (no type decla-
ration) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
67
4.56 Read with BswmdModel objects starting with a module class (strong typing) . .
67
4.57 Read with BswmdModel objects with closure argument
. . . . . . . . . . . . . .
68
4.58 Read with BswmdModel object for an MDF model object . . . . . . . . . . . . .
68
4.59 Write with BswmdModel required/optional objects . . . . . . . . . . . . . . . . .
69
4.60 Write with BswmdModel multiple objects . . . . . . . . . . . . . . . . . . . . . .
70
4.61 Write with BswmdModel - Duplicate a container . . . . . . . . . . . . . . . . . .
70
4.62 Write with BswmdModel - Delete elements
. . . . . . . . . . . . . . . . . . . . .
71
4.63 Read system description starting with an AUTOSAR path in closure . . . . . . .
72
4.64 Read system description starting with an AUTOSAR path in property style . . .
73
4.65 Changing a simple property of an MIVariableDataPrototype . . . . . . . . . . . .
73
4.66 Creating non-existing member by navigating into its content with OrCreate() . .
73
4.67 Creating new members of child lists with createAndAdd() by type . . . . . . . .
74
4.68 Updating existing members of child lists with byNameOrCreate() by type . . . .
74
4.69 BswmdModel usage with import . . . . . . . . . . . . . . . . . . . . . . . . . . .
75
4.70 Read with BswmdModel the EcuC module configuration . . . . . . . . . . . . . .
76
4.71 Read with BswmdModel the EcuC module configuration with DefRef
. . . . . .
76
4.72 Write with BswmdModel the EcucGeneral container . . . . . . . . . . . . . . . .
76
4.73 Usage of the sipDefRef API to retrieve DefRefs in script files
. . . . . . . . . . .
77
4.74 Usage of generated DefRefs form the bswmd model . . . . . . . . . . . . . . . . .
78
4.75 Switch from a domain model object to the corresponding BswmdModel object . .
78
4.76 Navigate into an MDF object starting with an AUTOSAR path . . . . . . . . . .
79
4.77 Find an MDF object and retrieve some content data . . . . . . . . . . . . . . . .
80
4.78 Navigating deeply into an MDF object with nested closures . . . . . . . . . . . .
80
4.79 Ignoring non-existing member closures . . . . . . . . . . . . . . . . . . . . . . . .
80
4.80 Get a MIReferrable child object by name
. . . . . . . . . . . . . . . . . . . . . .
81
4.81 Retrieve child from list with byName() . . . . . . . . . . . . . . . . . . . . . . . .
81
4.82 Get elements with mdfModel(String) . . . . . . . . . . . . . . . . . . . . . . . . .
82
4.83 Changing a simple property of an MIVariableDataPrototype . . . . . . . . . . . .
83
4.84 Creating non-existing member by navigating into its content with OrCreate() . .
83
4.85 Creating child member by navigating into its content with OrCreate() with type
83
4.86 Creating new members of child lists with createAndAdd() by type . . . . . . . .
84
4.87 Updating existing members of child lists with byNameOrCreate() by type . . . .
86
4.88 Delete a parameter instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
87
4.89 Check is a model instance is deleted . . . . . . . . . . . . . . . . . . . . . . . . .
87
4.90 Duplicates a container under the same parent . . . . . . . . . . . . . . . . . . . .
88
4.91 Get the AsrPath of an MIReferrable instance . . . . . . . . . . . . . . . . . . . .
88
4.92 Get the AsrObjectLink of an AUTOSAR model instance . . . . . . . . . . . . . .
88
4.93 Get the DefRef of an Ecuc model instance . . . . . . . . . . . . . . . . . . . . . .
88
© 2017, Vector Informatik GmbH
245 of 250

---

Listings
4.94 Set the DefRef of an Ecuc model instance . . . . . . . . . . . . . . . . . . . . . .
88
4.95 Get the CeState of an Ecuc parameter instance . . . . . . . . . . . . . . . . . . .
89
4.96 Retrieve the user-defined flag of an Ecuc parameter in Groovy . . . . . . . . . . .
89
4.97 Set an Ecuc parameter instance to user defined . . . . . . . . . . . . . . . . . . .
89
4.98 Get the IEcucDefinition of an Ecuc model instance . . . . . . . . . . . . . . . . .
89
4.99 Get the IEcucHasDefinition of an Ecuc model instance . . . . . . . . . . . . . . .
90
4.100referencesPointingToMe sample . . . . . . . . . . . . . . . . . . . . . . . . . . . .
90
4.101systemDescriptionObjectsPointingToMe sample . . . . . . . . . . . . . . . . . . .
90
4.102Get the AUTOSAR root object . . . . . . . . . . . . . . . . . . . . . . . . . . . .
90
4.103Get the active Ecuc and all module configurations
. . . . . . . . . . . . . . . . .
91
4.104Iterate over all module configurations
. . . . . . . . . . . . . . . . . . . . . . . .
91
4.105Get module configurations by definition . . . . . . . . . . . . . . . . . . . . . . .
91
4.106Get subContainers and parameters by definition
. . . . . . . . . . . . . . . . . .
91
4.107Check parameter values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
92
4.108Get integer parameter value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
93
4.109Get reference parameter value . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
94
4.110Get the FlatExtract and FlatMap paths by the SystemDescription API
. . . . .
94
4.111Get FlatExtract instance by the SystemDescription API . . . . . . . . . . . . . .
94
4.112Execute a transaction
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
95
4.113Execute a transaction with a name . . . . . . . . . . . . . . . . . . . . . . . . . .
95
4.114Check if a transaction is running . . . . . . . . . . . . . . . . . . . . . . . . . . .
96
4.115Undo a transaction with the transactionHistory . . . . . . . . . . . . . . . . . . .
96
4.116Redo a transaction with the transactionHistory . . . . . . . . . . . . . . . . . . .
97
4.117Activation of the ModuleConfiguration Dio
. . . . . . . . . . . . . . . . . . . . .
97
4.118Model synchronization inside an open project . . . . . . . . . . . . . . . . . . . .
99
4.119Retrieve and use a variant view by name . . . . . . . . . . . . . . . . . . . . . . .
99
4.120The default view is the IInvariantValuesView . . . . . . . . . . . . . . . . . . . . 100
4.121Execute code in a model view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
4.122Get a UserAnnotation of a container . . . . . . . . . . . . . . . . . . . . . . . . . 102
4.123Create a new UserAnnotation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
4.124Create or get the existing UserAnnotation by label name . . . . . . . . . . . . . . 103
4.125Basic structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
4.126Validate with default project settings . . . . . . . . . . . . . . . . . . . . . . . . . 105
4.127Generate with standard project settings . . . . . . . . . . . . . . . . . . . . . . . 105
4.128Generate one module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
4.129Generate one module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
4.130Generate two modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
4.131Generate one module with two configurations . . . . . . . . . . . . . . . . . . . . 107
4.132Execute an external generation step
. . . . . . . . . . . . . . . . . . . . . . . . . 107
4.133Evaluate the generation result . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
4.134Use a script task as generation step during generation . . . . . . . . . . . . . . . 109
4.135Use a script task as custom workflow step . . . . . . . . . . . . . . . . . . . . . . 110
4.136Hook into the GenerationProcess at the start with script task . . . . . . . . . . . 110
4.137Hook into the GenerationProcess at the end with script task
. . . . . . . . . . . 110
4.138Basic Swct structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
4.139SWC Templates and Contract Headers generation with standard project settings 111
4.140SWC Templates and Contract Headers generation of all components . . . . . . . 112
4.141SWC Templates and Contract Headers generation of one selected component . . 112
4.142Swct generation get component and select component
. . . . . . . . . . . . . . . 112
4.143Swct generation of multiple components . . . . . . . . . . . . . . . . . . . . . . . 113
4.144Access all validation-results and filter them by ID . . . . . . . . . . . . . . . . . . 115
© 2017, Vector Informatik GmbH
246 of 250

---

Listings
4.145Solve a single validation-result with a particular solving-action
. . . . . . . . . . 116
4.146Fast solve multiple results within one transaction . . . . . . . . . . . . . . . . . . 117
4.147Solve all validation-results with its preferred solving-action (if available) . . . . . 117
4.148Access all validation-results of a particular object . . . . . . . . . . . . . . . . . . 118
4.149Access all validation-results of a particular DefRef
. . . . . . . . . . . . . . . . . 119
4.150Filter validation-results using an ID constant . . . . . . . . . . . . . . . . . . . . 119
4.151Fast solve multiple validation-results within one transaction using a solving-
action-group-ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
4.152IValidationResultUI overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
4.153IValidationResultUI in a variant (post build selectable) project . . . . . . . . . . 121
4.154CE is affected by (matches) an IValidationResultUI . . . . . . . . . . . . . . . . . 122
4.155Advanced use case - Retrieve Erroneous CEs with descriptors of an IValidation-
ResultUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
4.156Examine an ISolvingActionSummaryResult . . . . . . . . . . . . . . . . . . . . . 124
4.157Create a ValidationResult . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
4.158Report a ValidationResult when MD license option is available . . . . . . . . . . 125
4.159Turn off auto solving action execution . . . . . . . . . . . . . . . . . . . . . . . . 126
4.160"Update existing project"
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
4.161Change list of communication extracts and update . . . . . . . . . . . . . . . . . 128
4.162Accessing IDomainApi as a property . . . . . . . . . . . . . . . . . . . . . . . . . 130
4.163Accessing IDomainApi in a scope-like way . . . . . . . . . . . . . . . . . . . . . . 130
4.164Accessing ICommunicationApi as a property . . . . . . . . . . . . . . . . . . . . . 130
4.165Accessing ICommunicationApi in a scope-like way
. . . . . . . . . . . . . . . . . 131
4.166Optimizing Can Acceptance Filters . . . . . . . . . . . . . . . . . . . . . . . . . . 132
4.167Accessing IDiagnosticsApi as a property . . . . . . . . . . . . . . . . . . . . . . . 134
4.168Accessing IDiagnosticsApi in a scope-like manner . . . . . . . . . . . . . . . . . . 134
4.169Create a new UDS DTC with event . . . . . . . . . . . . . . . . . . . . . . . . . . 135
4.170Enable OBD II and create a new OBD related DTC with event . . . . . . . . . . 135
4.171Enable WWH-OBD and create a new OBD related DTC with event . . . . . . . 136
4.172Open a project, enable J1939 and create a new J1939 DTC with event . . . . . . 136
4.173Accessing IModeManagementApi as a property . . . . . . . . . . . . . . . . . . . 137
4.174Accessing IModeManagementApi in a scope-like way . . . . . . . . . . . . . . . . 137
4.175ECU State Handling Auto Configuration . . . . . . . . . . . . . . . . . . . . . . . 138
4.176Inspecting Auto Configuration Elements . . . . . . . . . . . . . . . . . . . . . . . 139
4.177Accessing IRuntimeSystemApi as a property . . . . . . . . . . . . . . . . . . . . . 140
4.178Accessing IRuntimeSystemApi in a scope-like way
. . . . . . . . . . . . . . . . . 140
4.179Selects all component ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
4.180Selects all unconnected component ports . . . . . . . . . . . . . . . . . . . . . . . 142
4.181Select all unconnected sender/receiver or connected mode-switch component ports143
4.182Tries to auto-map all ports
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
4.183Tries to auto-map all unconnected component ports
. . . . . . . . . . . . . . . . 144
4.184Tries to auto-map all unconnected sender/receiver and client/server ports . . . . 144
4.185Tries to auto-map port determined by advanced filter
. . . . . . . . . . . . . . . 144
4.186Tries to auto map all unconnected ports to the ports of one component prototype 145
4.187Tries to auto-map all unconnected ports and evaluate matches
. . . . . . . . . . 146
4.188Auto-map a component port and realize 1:n connection by using evaluate matches147
4.189Create mapping between two ports which names do not match. . . . . . . . . . . 148
4.190Select all unmapped signal instances . . . . . . . . . . . . . . . . . . . . . . . . . 151
4.191Select all unmapped rx or transformed signal instances . . . . . . . . . . . . . . . 151
4.192Select signal instances using an advanced filter
. . . . . . . . . . . . . . . . . . . 152
4.193Auto data map all unmapped signal instances . . . . . . . . . . . . . . . . . . . . 152
© 2017, Vector Informatik GmbH
247 of 250

---

Listings
4.194Auto data map all unmapped signal instances to unmapped communication ele-
ments and evaluate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
4.195Auto data map all signal instances and do not expand nested array elements
. . 154
4.196Auto data map all signal instances and expand specific nested array element . . . 155
4.197Select all unmapped delegation port communication elements . . . . . . . . . . . 157
4.198Select communication elements using an advanced filter . . . . . . . . . . . . . . 157
4.199Auto data map all unmapped sender/receiver delegation port communication
elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
4.200Auto data map all unmapped communication elements to unmapped rx signal
instances and evaluate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
4.201Autodatamap and do not expand nested array elements . . . . . . . . . . . . . . 160
4.202Autodatamap and do expand a specific nested array element
. . . . . . . . . . . 161
4.203Accessing the model export persistency API . . . . . . . . . . . . . . . . . . . . . 162
4.204Export the ActiveEcuc to a file . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
4.205Export a Post-build selectable project as variant files . . . . . . . . . . . . . . . . 163
4.206Export the project with an exporter . . . . . . . . . . . . . . . . . . . . . . . . . 163
4.207Export the project with an exporter and checks . . . . . . . . . . . . . . . . . . . 163
4.208Export an AUTOSAR package to a file
. . . . . . . . . . . . . . . . . . . . . . . 164
4.209Exports two elements and all references elements . . . . . . . . . . . . . . . . . . 164
4.210Accessing the model import persistency API . . . . . . . . . . . . . . . . . . . . . 164
4.211Java code usage of the IScriptFactory to contribute script tasks . . . . . . . . . . 168
4.212Accessing WorkflowAPI in Java code . . . . . . . . . . . . . . . . . . . . . . . . . 169
4.213Java Closure creation sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
4.214Run all JUnit tests from one class
. . . . . . . . . . . . . . . . . . . . . . . . . . 170
4.215Run all JUnit tests using a Suite . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
4.216Run unit test with the Spock framework . . . . . . . . . . . . . . . . . . . . . . . 171
4.217Add a UnitTest task with name MyUnitTest
. . . . . . . . . . . . . . . . . . . . 171
4.218The projectConfig.gradle file content for unit tests . . . . . . . . . . . . . . . . . 172
5.1
Check object visibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
5.2
Get all available variants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
5.3
Execute code with variant visibility . . . . . . . . . . . . . . . . . . . . . . . . . . 180
5.4
Get all variants, a specific object is visible in
. . . . . . . . . . . . . . . . . . . . 181
5.5
Retrieving an InvariantValues model view . . . . . . . . . . . . . . . . . . . . . . 183
5.6
Retrieving an InvariantEcucDefView model view . . . . . . . . . . . . . . . . . . 184
5.7
Execute code with variant specific changes . . . . . . . . . . . . . . . . . . . . . . 186
5.8
Sample code to access element in an Untyped model with DefRefs
. . . . . . . . 190
5.9
Resolves a Refference traget of an Reference Parameter
. . . . . . . . . . . . . . 190
5.10 The value of a GIParameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
5.11 Java: Execute code with creation IModelView of BswmdModel object . . . . . . 193
5.12 Java: Execute code with creation IModelView of BswmdModel object via runnable193
5.13 Java: Execute code with creation IModelView of BswmdModel object . . . . . . 194
5.14 Additional write API methods for EcucGeneral . . . . . . . . . . . . . . . . . . . 196
5.15 EcucCoreDefinition as GICList<EcucCoreDefinition> . . . . . . . . . . . . . . . 197
5.16 Deleting model objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
5.17 Duplication of containers
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
5.18 Set parameter values with the BswmdModel Write API
. . . . . . . . . . . . . . 198
5.19 Set reference targets with the BswmdModel Write API . . . . . . . . . . . . . . . 198
5.20 Settings.xml sample for DerivativeMapping . . . . . . . . . . . . . . . . . . . . . 199
5.21 DefRef isDefinitionOf methods
. . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
5.22 Creation of DefRef with wildcard from EDefRefWildcard
. . . . . . . . . . . . . 203
5.23 Getting CeState objects using the BSWMD model . . . . . . . . . . . . . . . . . 204
© 2017, Vector Informatik GmbH
248 of 250

---

Listings
5.24 Integer parameter definition access examples
. . . . . . . . . . . . . . . . . . . . 206
5.25 Integer parameter configuration access examples
. . . . . . . . . . . . . . . . . . 210
7.1
The automationClasses list in projectConfig.gradle . . . . . . . . . . . . . . . . . 223
7.2
The dvCfgInstallation in projectConfig.gradle . . . . . . . . . . . . . . . . . . . . 223
7.3
The dvCfgInstallation with an System env in projectConfig.gradle
. . . . . . . . 223
7.4
@CompileStatic with Automation API . . . . . . . . . . . . . . . . . . . . . . . . 225
7.5
@TypeChecked with Automation API . . . . . . . . . . . . . . . . . . . . . . . . 225
7.6
DaVinci Configurator build Gradle DSL API . . . . . . . . . . . . . . . . . . . . 225
7.7
DaVinci Configurator build Gradle DSL API - useBswmdModel . . . . . . . . . . 225
7.8
DaVinci Configurator build Gradle DSL API - useJarSignerDaemon . . . . . . . 226
7.9
DaVinci Configurator build Gradle DSL API - includeDependenciesIntoJar . . . 226
© 2017, Vector Informatik GmbH
249 of 250

---

Listings
Todo list
© 2017, Vector Informatik GmbH
250 of 250

---

Document Outline

• 1 Introduction
  • 1.1 General
  • 1.2 Facts
• 2 Getting started with Script Development
  • 2.1 General
  • 2.2 Automation Script Development Types
  • 2.3 Script File
  • 2.4 Script Project
    • 2.4.1 Script Project Development
    • 2.4.2 Java JDK Setup
    • 2.4.3 IntelliJ IDEA Setup
    • 2.4.4 Gradle Setup
• 3 AutomationInterface Architecture
  • 3.1 Components
  • 3.2 Languages
    • 3.2.1 Why Groovy
  • 3.3 Script Structure
    • 3.3.1 Scripts
    • 3.3.2 Script Tasks
    • 3.3.3 Script Locations
  • 3.4 Script loading
    • 3.4.1 Internal Script Reload Behavior
  • 3.5 Script editing
  • 3.6 Licensing
  • 3.7 Script Coding Conventions and Constraints
    • 3.7.1 Usage of static fields
    • 3.7.2 Usage of Outer Closure Scope Variables
    • 3.7.3 States over script task execution
    • 3.7.4 Usage of Threads
    • 3.7.5 Usage of DaVinci Configurator private Classes Methods or Fields
• 4 AutomationInterface API Reference
  • 4.1 Introduction
  • 4.2 Script Creation
    • 4.2.1 Script Task Creation
      • 4.2.1.1 Script Creation with IDE Code Completion Support
      • 4.2.1.2 Script Task isExecutableIf
    • 4.2.2 Description and Help
  • 4.3 Script Task Types
    • 4.3.1 Available Types
      • 4.3.1.1 Application Types
      • 4.3.1.2 Project Types
      • 4.3.1.3 UI Types
      • 4.3.1.4 Generation Types
  • 4.4 Script Task Execution
    • 4.4.1 Execution Context
      • 4.4.1.1 Code Block Arguments
    • 4.4.2 Task Execution Sequence
    • 4.4.3 Script Path API during Execution
      • 4.4.3.1 Path Resolution by Parent Folder
      • 4.4.3.2 Path Resolution
      • 4.4.3.3 Script Folder Path Resolution
      • 4.4.3.4 Project Folder Path Resolution
      • 4.4.3.5 SIP Folder Path Resolution
      • 4.4.3.6 Temp Folder Path Resolution
      • 4.4.3.7 Other Project and Application Paths
    • 4.4.4 Script logging API
    • 4.4.5 User Interactions and Inputs
      • 4.4.5.1 UserInteraction
    • 4.4.6 Script Error Handling
      • 4.4.6.1 Script Exceptions
      • 4.4.6.2 Script Task Abortion by Exception
      • 4.4.6.3 Unhandled Exceptions from Tasks
    • 4.4.7 User defined Classes and Methods
    • 4.4.8 Usage of Automation API in own defined Classes and Methods
      • 4.4.8.1 Access the Automation API like the Script code{} Block
      • 4.4.8.2 Access the Project API of the current active Project
    • 4.4.9 User defined Script Task Arguments in Commandline
      • 4.4.9.1 User defined Argument Validators
      • 4.4.9.2 Call Script Task with Task Arguments
    • 4.4.10 Stateful Script Tasks
  • 4.5 Project Handling
    • 4.5.1 Projects
    • 4.5.2 Accessing the active Project
    • 4.5.3 Creating a new Project
      • 4.5.3.1 Mandatory Settings
      • 4.5.3.2 General Settings
      • 4.5.3.3 Target Settings
      • 4.5.3.4 Post Build Settings
      • 4.5.3.5 Folders Settings
      • 4.5.3.6 DaVinci Developer Settings
      • 4.5.3.7 vVIRTUALtarget Settings
    • 4.5.4 Opening an existing Project
      • 4.5.4.1 Parameterized Project Load
      • 4.5.4.2 Open Project Details
    • 4.5.5 Saving a Project
    • 4.5.6 Opening AUTOSAR Files as Project
      • 4.5.6.1 Raw AUTOSAR models as Project
  • 4.6 Model
    • 4.6.1 Introduction
    • 4.6.2 Getting Started
      • 4.6.2.1 Read the ActiveEcuc
      • 4.6.2.2 Write the ActiveEcuc
      • 4.6.2.3 Read the SystemDescription
      • 4.6.2.4 Write the SystemDescription
    • 4.6.3 BswmdModel in AutomationInterface
      • 4.6.3.1 BswmdModel Package and Class Names
      • 4.6.3.2 Reading with BswmdModel
      • 4.6.3.3 Writing with BswmdModel
      • 4.6.3.4 Sip DefRefs
      • 4.6.3.5 BswmdModel DefRefs
      • 4.6.3.6 Switching from Domain Models to BswmdModel
    • 4.6.4 MDF Model in AutomationInterface
      • 4.6.4.1 Reading the MDF Model
      • 4.6.4.2 Reading the MDF Model by String
      • 4.6.4.3 Writing the MDF Model
      • 4.6.4.4 Simple Property Changes
      • 4.6.4.5 Creating single Child Members (0:1)
      • 4.6.4.6 Creating and adding Child List Members (0:*)
      • 4.6.4.7 Updating existing Elements
      • 4.6.4.8 Deleting Model Objects
      • 4.6.4.9 Duplicating Model Objects
      • 4.6.4.10 Special properties and extensions
      • 4.6.4.11 Reverse Reference Resolution - ReferencesPointingToMe
      • 4.6.4.12 AUTOSAR Root Object
      • 4.6.4.13 ActiveEcuC
      • 4.6.4.14 DefRef based Access to Containers and Parameters
      • 4.6.4.15 Ecuc Parameter and Reference Value Access
    • 4.6.5 SystemDescription Access
    • 4.6.6 Transactions
      • 4.6.6.1 Transactions API
      • 4.6.6.2 Operations
    • 4.6.7 Model Synchronization
    • 4.6.8 Post-build selectable Variance
      • 4.6.8.1 Investigate Project Variance
      • 4.6.8.2 Variant Model Objects
    • 4.6.9 Additional Model API
      • 4.6.9.1 User Annotations
  • 4.7 Generation
    • 4.7.1 Code Generation
      • 4.7.1.1 Generation Settings
      • 4.7.1.2 Generation of External Generation Step
      • 4.7.1.3 Evaluate generation or validation results
    • 4.7.2 Generation Task Types
    • 4.7.3 Software Component Templates and Contract Phase Headers Generation
      • 4.7.3.1 Swct Generation Settings
      • 4.7.3.2 Generation with default Project Settings
      • 4.7.3.3 Generation of all Software Components
      • 4.7.3.4 Generation of one Software Component
      • 4.7.3.5 Generation of multiple Software Components
      • 4.7.3.6 Evaluate generation results
  • 4.8 Validation
    • 4.8.1 Introduction
    • 4.8.2 Access Validation-Results
    • 4.8.3 Model Transaction and Validation-Result Invalidation
    • 4.8.4 Solve Validation-Results with Solving-Actions
      • 4.8.4.1 Solver API
    • 4.8.5 Advanced Topics
      • 4.8.5.1 Access Validation-Results of a Model Object
      • 4.8.5.2 Access Validation-Results of a DefRef
      • 4.8.5.3 Filter Validation-Results using an ID Constant
      • 4.8.5.4 Identification of a Particular Solving-Action
      • 4.8.5.5 Validation-Result Description as MixedText
      • 4.8.5.6 Further IValidationResultUI Methods
      • 4.8.5.7 IValidationResultUI in a variant (Post Build Selectable) Project
      • 4.8.5.8 Erroneous CEs of a Validation-Result
      • 4.8.5.9 Examine Solving-Action Execution
      • 4.8.5.10 Create a Validation-Result in a Script Task
      • 4.8.5.11 Turn off auto-solving-action execution
  • 4.9 Update Workflow
    • 4.9.1 Method Overview
    • 4.9.2 Example: Content of Input Files has changed.
    • 4.9.3 Example: List of Input Files shall be changed
    • 4.9.4 Prerequisites
  • 4.10 Domains
    • 4.10.1 Communication Domain
      • 4.10.1.1 CanControllers
      • 4.10.1.2 CanFilterMasks
    • 4.10.2 Diagnostics Domain
      • 4.10.2.1 DemEvents
    • 4.10.3 Mode Management Domain
      • 4.10.3.1 BswM Auto Configuration
    • 4.10.4 Runtime System Domain
      • 4.10.4.1 Component Port Connection
      • 4.10.4.2 Data Mapping
  • 4.11 Persistency
    • 4.11.1 Model Export
      • 4.11.1.1 Export ActiveEcuc
      • 4.11.1.2 Export Post-build selectable Variants
      • 4.11.1.3 Advanced Export
    • 4.11.2 Model Import
  • 4.12 Utilities
    • 4.12.1 Constraints
    • 4.12.2 Converters
  • 4.13 Advanced Topics
    • 4.13.1 Java Development
      • 4.13.1.1 Script Task Creation in Java Code
      • 4.13.1.2 Java Code accessing Groovy API
      • 4.13.1.3 Java Code in dvgroovy Scripts
    • 4.13.2 Unit testing API
      • 4.13.2.1 JUnit4 Integration
      • 4.13.2.2 Execution of Spock Tests
      • 4.13.2.3 Registration of Unit Tests in Scripts
• 5 Data models in detail
  • 5.1 MDF model - the raw AUTOSAR data
    • 5.1.1 Naming
    • 5.1.2 The models inheritance hiearchy
      • 5.1.2.1 MIObject and MDFObject
    • 5.1.3 The models containment tree
    • 5.1.4 The ECUC model
    • 5.1.5 Order of child objects
    • 5.1.6 AUTOSAR references
    • 5.1.7 Model changes
      • 5.1.7.1 Transactions
      • 5.1.7.2 Undo/redo
      • 5.1.7.3 Event handling
      • 5.1.7.4 Deleting model objects
      • 5.1.7.5 Access to deleted objects
      • 5.1.7.6 Set-methods
      • 5.1.7.7 Changing child list content
      • 5.1.7.8 Change restrictions
  • 5.2 Post-build selectable
    • 5.2.1 Model views
      • 5.2.1.1 What model views are
      • 5.2.1.2 The IModelViewManager project service
      • 5.2.1.3 Variant siblings
      • 5.2.1.4 The Invariant model views
      • 5.2.1.5 Accessing invisible objects
      • 5.2.1.6 IViewedModelObject
    • 5.2.2 Variant specific model changes
    • 5.2.3 Variant common model changes
  • 5.3 BswmdModel details
    • 5.3.1 BswmdModel - DefinitionModel
      • 5.3.1.1 Types of DefinitionModels
      • 5.3.1.2 DefRef Getter methods of Untyped Model
      • 5.3.1.3 References
      • 5.3.1.4 Post-build selectable with BswmdModel
      • 5.3.1.5 Creation ModelView of the BswmdModel
      • 5.3.1.6 Lazy Instantiating
      • 5.3.1.7 Optional Elements
      • 5.3.1.8 Class and Interface Structure of the BswmdModel
      • 5.3.1.9 BswmdModel write access 
    • 5.3.2 BswmdModel generation
      • 5.3.2.1 DerivativeMapping
  • 5.4 Model Utility Classes
    • 5.4.1 AutosarUtil
    • 5.4.2 AsrPath
    • 5.4.3 AsrObjectLink
      • 5.4.3.1 Object links depend on the MDF object type
      • 5.4.3.2 Restrictions of object links
      • 5.4.3.3 Examples for object link strings
    • 5.4.4 DefRefs
      • 5.4.4.1 TypedDefRefs
      • 5.4.4.2 DefRef Wildcards
    • 5.4.5 CeState
      • 5.4.5.1 Getting a CeState object
      • 5.4.5.2 IParameterStatePublished
      • 5.4.5.3 IContainerStatePublished
  • 5.5 Model Services
    • 5.5.1 EcucDefinitionAccess
      • 5.5.1.1 Post-build loadable
      • 5.5.1.2 Post-build selectable
    • 5.5.2 EcuConfigurationAccess
      • 5.5.2.1 Post-build loadable
      • 5.5.2.2 Post-build selectable
• 6 AutomationInterface Content
  • 6.1 Introduction
  • 6.2 Folder Structure
  • 6.3 Script Development Help
    • 6.3.1 DVCfg_AutomationInterfaceDocumentation.pdf
    • 6.3.2 Javadoc HTML Pages
    • 6.3.3 Script Templates
  • 6.4 Libs and BuildLibs
• 7 Automation Script Project
  • 7.1 Introduction
  • 7.2 Automation Script Project Creation
  • 7.3 Project File Content
  • 7.4 IntelliJ IDEA Usage
    • 7.4.1 Supported versions
    • 7.4.2 Building Projects
    • 7.4.3 Debugging with IntelliJ
    • 7.4.4 Troubleshooting
  • 7.5 Project Migration to newer DaVinci Configurator Version
  • 7.6 Debugging Script Project
  • 7.7 Build System
    • 7.7.1 Jar Creation and Output Location
    • 7.7.2 Gradle File Structure
      • 7.7.2.1 projectConfig.gradle File settings
    • 7.7.3 Advanced Build Topics
      • 7.7.3.1 Usage of external Libraries (Jars) in the AutomationProject
      • 7.7.3.2 Static Compilation of Groovy Code
      • 7.7.3.3 Gradle dvCfgAutomation API Reference
• 8 AutomationInterface Changes between Versions
  • 8.1 Currently Supported Features
  • 8.2 Changes in MICROSAR AR4-R18 - Cfg5.15
    • 8.2.1 General
    • 8.2.2 Automation Script Project
      • 8.2.2.1 Supported IntelliJ IDEA Version
      • 8.2.2.2 BuildSystem
    • 8.2.3 Script Execution
      • 8.2.3.1 User defined arguments
    • 8.2.4 Project Handling
    • 8.2.5 Project Creation vVIRTUALtarget settings
    • 8.2.6 Model changes
    • 8.2.7 Model Automation API
      • 8.2.7.1 IVarianceApi
      • 8.2.7.2 Access methods
      • 8.2.7.3 Reverse Reference Resolution - ReferencesPointingToMe
      • 8.2.7.4 Operations
      • 8.2.7.5 User Annotations
      • 8.2.7.6 Variance
      • 8.2.7.7 Model Synchronization
    • 8.2.8 Persistency
    • 8.2.9 Workflow
    • 8.2.10 Validation
      • 8.2.10.1 Validation-Result Access Methods
    • 8.2.11 Generation
      • 8.2.11.1 SWC Templates and Contract Headers Generation
    • 8.2.12 BswmdModel
      • 8.2.12.1 BswmdModel Groovy
      • 8.2.12.2 DerivativeMapping
    • 8.2.13 Mode Management Domain
    • 8.2.14 Runtime System Domain
      • 8.2.14.1 Data Mapping
  • 8.3 Changes in MICROSAR AR4-R17 - Cfg5.14
    • 8.3.1 General
    • 8.3.2 Script Execution
      • 8.3.2.1 Stateful Script Tasks
    • 8.3.3 Automation Script Project
      • 8.3.3.1 Groovy
      • 8.3.3.2 Supported IntelliJ IDEA Version
      • 8.3.3.3 BuildSystem
    • 8.3.4 Converter Refactoring
    • 8.3.5 UserInteraction
    • 8.3.6 Project Load
      • 8.3.6.1 AUTOSAR Arxml Files
    • 8.3.7 Model
      • 8.3.7.1 Transactions
      • 8.3.7.2 MDF Model Read and Write
      • 8.3.7.3 SystemDescription Access
      • 8.3.7.4 ActiveEcuc
    • 8.3.8 Persistency
    • 8.3.9 Generation
    • 8.3.10 BswmdModel
      • 8.3.10.1 Writing with BswmdModel
    • 8.3.11 BswmdModel Groovy
    • 8.3.12 Diagnostics Domain
    • 8.3.13 Communication Domain
    • 8.3.14 Runtime System Domain
  • 8.4 Changes in MICROSAR AR4-R16 - Cfg5.13
    • 8.4.1 General
    • 8.4.2 API Stability
    • 8.4.3 Beta Status
• 9 Appendix
  • Nomenclature
  • Figures
  • Tables
  • Listings
  • ToDos

---