0
# Core Data Models & Services
1

2
The DDM API's core data models and services provide the foundation for all Dynamic Data Mapping operations. This includes entity models for structures, templates, forms, and data records, along with comprehensive service layers for CRUD operations, business logic, and database persistence.
3

4
## Capabilities
5

6
### Primary Entity Models
7

8
Core entity models representing the main DDM data structures.
9

10
```java { .api }
11
// Core structure model - defines form schemas and field definitions
12
interface DDMStructure extends PersistedModel, MVCCModel, StagedModel {
13
    long getStructureId();
14
    long getGroupId();
15
    long getClassNameId();
16
    String getStructureKey();
17
    String getName();
18
    String getDescription();
19
    String getDefinition();
20
    String getStorageType();
21
    int getType();
22
    DDMForm getDDMForm();
23
    DDMFormLayout getDDMFormLayout();
24
}
25

26
// Template model - defines rendering templates for structures
27
interface DDMTemplate extends PersistedModel, MVCCModel, StagedModel, WorkflowedModel {
28
    long getTemplateId();
29
    long getGroupId();
30
    long getClassNameId();
31
    long getClassPK();
32
    String getTemplateKey();
33
    String getName();
34
    String getDescription();
35
    String getType();
36
    String getMode();
37
    String getLanguage();
38
    String getScript();
39
    String getSmallImageURL();
40
}
41

42
// Form instance model - represents deployed forms based on structures
43
interface DDMFormInstance extends PersistedModel, MVCCModel, StagedModel, WorkflowedModel {
44
    long getFormInstanceId();
45
    long getGroupId();
46
    long getStructureId();
47
    String getName();
48
    String getDescription();
49
    DDMFormInstanceSettings getSettings();
50
    String getVersion();
51
}
52

53
// Form submission record - represents individual form submissions
54
interface DDMFormInstanceRecord extends PersistedModel, MVCCModel, StagedModel, WorkflowedModel {
55
    long getFormInstanceRecordId();
56
    long getGroupId();
57
    long getFormInstanceId();  
58
    String getFormInstanceVersion();
59
    long getStorageId();
60
    String getVersion();
61
    DDMFormValues getDDMFormValues();
62
}
63

64
// Content storage model - stores serialized form data
65
interface DDMContent extends PersistedModel {
66
    long getContentId();
67
    long getGroupId();
68
    String getName();
69
    String getDescription();
70
    String getData();
71
}
72

73
// Data provider instance model - external data source configuration
74
interface DDMDataProviderInstance extends PersistedModel, MVCCModel, StagedModel {
75
    long getDataProviderInstanceId();
76
    long getGroupId();
77
    String getName();
78
    String getDescription();
79
    String getDefinition();
80
    String getType();
81
    DDMDataProviderInstanceSettings getSettings();
82
}
83
```
84

85
### Structure Management Services
86

87
Services for managing data structures that define form schemas and field definitions.
88

89
```java { .api }
90
interface DDMStructureLocalService extends BaseLocalService, PersistedModelLocalService {
91
    /**
92
     * Adds a new structure with form definition and layout
93
     */
94
    DDMStructure addStructure(
95
        long userId, long groupId, long parentStructureId, long classNameId,
96
        String structureKey, Map<Locale, String> nameMap, Map<Locale, String> descriptionMap,
97
        DDMForm ddmForm, DDMFormLayout ddmFormLayout, String storageType,
98
        int type, ServiceContext serviceContext) throws PortalException;
99

100
    /**
101
     * Updates an existing structure
102
     */
103
    DDMStructure updateStructure(
104
        long userId, long structureId, long parentStructureId, 
105
        Map<Locale, String> nameMap, Map<Locale, String> descriptionMap,
106
        DDMForm ddmForm, DDMFormLayout ddmFormLayout, ServiceContext serviceContext) 
107
        throws PortalException;
108

109
    /**
110
     * Deletes a structure and its associated data
111
     */
112
    DDMStructure deleteStructure(long structureId) throws PortalException;
113

114
    /**
115
     * Retrieves structures by group
116
     */
117
    List<DDMStructure> getStructures(long groupId);
118

119
    /**
120
     * Retrieves structures by group and class name
121
     */
122
    List<DDMStructure> getStructures(long groupId, long classNameId);
123

124
    /**
125
     * Searches for structures with pagination
126
     */
127
    Hits search(long companyId, long[] groupIds, long classNameId, String keywords,
128
        int type, int status, int start, int end, Sort sort) throws PortalException;
129
}
130

131
interface DDMStructureService extends BaseService {
132
    /**
133
     * Remote service methods (subset of LocalService with permission checks)
134
     */
135
    DDMStructure addStructure(long groupId, long parentStructureId, long classNameId,
136
        String structureKey, Map<Locale, String> nameMap, Map<Locale, String> descriptionMap,
137
        DDMForm ddmForm, DDMFormLayout ddmFormLayout, String storageType,
138
        int type, ServiceContext serviceContext) throws PortalException;
139
    
140
    DDMStructure updateStructure(long structureId, long parentStructureId,
141
        Map<Locale, String> nameMap, Map<Locale, String> descriptionMap,
142
        DDMForm ddmForm, DDMFormLayout ddmFormLayout, ServiceContext serviceContext) 
143
        throws PortalException;
144
}
145
```
146

147
### Template Management Services
148

149
Services for managing templates that define how structures are rendered.
150

151
```java { .api }
152
interface DDMTemplateLocalService extends BaseLocalService, PersistedModelLocalService {
153
    /**
154
     * Adds a new template with script and configuration
155
     */
156
    DDMTemplate addTemplate(
157
        long userId, long groupId, long classNameId, long classPK,
158
        long resourceClassNameId, String templateKey, Map<Locale, String> nameMap,
159
        Map<Locale, String> descriptionMap, String type, String mode,
160
        String language, String script, boolean cacheable,
161
        boolean smallImage, String smallImageURL, File smallImageFile,
162
        ServiceContext serviceContext) throws PortalException;
163

164
    /**
165
     * Updates an existing template
166
     */
167
    DDMTemplate updateTemplate(
168
        long userId, long templateId, long classPK, Map<Locale, String> nameMap,
169
        Map<Locale, String> descriptionMap, String type, String mode,
170
        String language, String script, boolean cacheable,
171
        boolean smallImage, String smallImageURL, File smallImageFile,
172
        ServiceContext serviceContext) throws PortalException;
173

174
    /**
175
     * Copies a template to create a new one
176
     */
177
    DDMTemplate copyTemplate(long userId, long templateId, ServiceContext serviceContext) 
178
        throws PortalException;
179

180
    /**
181
     * Retrieves templates by group and class name
182
     */
183
    List<DDMTemplate> getTemplates(long groupId, long classNameId);
184

185
    /**
186
     * Retrieves templates by group, class name, class PK and type
187
     */
188
    List<DDMTemplate> getTemplates(long groupId, long classNameId, long classPK, String type);
189
}
190
```
191

192
### Form Instance Management Services
193

194
Services for managing form instances - deployable forms based on structures.
195

196
```java { .api }
197
interface DDMFormInstanceLocalService extends BaseLocalService, PersistedModelLocalService {
198
    /**
199
     * Creates a new form instance
200
     */
201
    DDMFormInstance addFormInstance(
202
        long userId, long groupId, long structureId, Map<Locale, String> nameMap,
203
        Map<Locale, String> descriptionMap, DDMForm ddmForm, DDMFormLayout ddmFormLayout,
204
        DDMFormInstanceSettings settings, ServiceContext serviceContext) 
205
        throws PortalException;
206

207
    /**
208
     * Updates an existing form instance
209
     */
210
    DDMFormInstance updateFormInstance(
211
        long userId, long formInstanceId, Map<Locale, String> nameMap,
212
        Map<Locale, String> descriptionMap, DDMForm ddmForm, DDMFormLayout ddmFormLayout,
213
        DDMFormInstanceSettings settings, ServiceContext serviceContext) 
214
        throws PortalException;
215

216
    /**
217
     * Publishes a form instance making it available for submissions
218
     */
219
    void updateFormInstanceWorkflowStatus(long userId, long formInstanceId, int status,
220
        ServiceContext serviceContext) throws PortalException;
221

222
    /**
223
     * Retrieves form instances by group
224
     */
225
    List<DDMFormInstance> getFormInstances(long groupId);
226

227
    /**
228
     * Searches form instances with pagination
229
     */
230
    BaseModelSearchResult<DDMFormInstance> searchFormInstances(
231
        SearchContext searchContext) throws PortalException;
232
}
233
```
234

235
### Form Record Services
236

237
Services for managing form submissions and their data.
238

239
```java { .api }
240
interface DDMFormInstanceRecordLocalService extends BaseLocalService, PersistedModelLocalService {
241
    /**
242
     * Adds a new form submission record
243
     */
244
    DDMFormInstanceRecord addFormInstanceRecord(
245
        long userId, long groupId, long formInstanceId, DDMFormValues ddmFormValues,
246
        ServiceContext serviceContext) throws PortalException;
247

248
    /**
249
     * Updates an existing form record
250
     */
251
    DDMFormInstanceRecord updateFormInstanceRecord(
252
        long userId, long formInstanceRecordId, DDMFormValues ddmFormValues,
253
        ServiceContext serviceContext) throws PortalException;
254

255
    /**
256
     * Updates form record status (e.g., draft, approved)
257
     */
258
    DDMFormInstanceRecord updateStatus(
259
        long userId, long formInstanceRecordId, int status, 
260
        ServiceContext serviceContext) throws PortalException;
261

262
    /**
263
     * Retrieves form records by form instance
264
     */
265
    List<DDMFormInstanceRecord> getFormInstanceRecords(long formInstanceId);
266

267
    /**
268
     * Retrieves form records with pagination
269
     */
270
    List<DDMFormInstanceRecord> getFormInstanceRecords(
271
        long formInstanceId, int status, int start, int end,
272
        OrderByComparator<DDMFormInstanceRecord> orderByComparator);
273

274
    /**
275
     * Exports form records to various formats
276
     */
277
    byte[] getFormInstanceRecordsCSV(long formInstanceId, int status) throws PortalException;
278
}
279
```
280

281
### Data Provider Services
282

283
Services for managing external data providers that populate form field options.
284

285
```java { .api }
286
interface DDMDataProviderInstanceLocalService extends BaseLocalService, PersistedModelLocalService {
287
    /**
288
     * Adds a new data provider instance
289
     */
290
    DDMDataProviderInstance addDataProviderInstance(
291
        long userId, long groupId, Map<Locale, String> nameMap,
292
        Map<Locale, String> descriptionMap, DDMForm ddmForm, String type,
293
        ServiceContext serviceContext) throws PortalException;
294

295
    /**
296
     * Updates an existing data provider instance
297
     */
298
    DDMDataProviderInstance updateDataProviderInstance(
299
        long userId, long dataProviderInstanceId, Map<Locale, String> nameMap,
300
        Map<Locale, String> descriptionMap, DDMForm ddmForm, String type,
301
        ServiceContext serviceContext) throws PortalException;
302

303
    /**
304
     * Fetches data from a data provider
305
     */
306
    DDMDataProviderResponse getData(DDMDataProviderRequest ddmDataProviderRequest)
307
        throws PortalException;
308

309
    /**
310
     * Retrieves data provider instances by group and type
311
     */
312
    List<DDMDataProviderInstance> getDataProviderInstances(long groupId, String type);
313
}
314
```
315

316
## Usage Examples
317

318
### Creating a Complete Form Workflow
319

320
```java
321
@Component
322
public class FormCreationExample {
323
    
324
    @Reference
325
    private DDMStructureLocalService structureLocalService;
326
    
327
    @Reference
328
    private DDMFormInstanceLocalService formInstanceLocalService;
329
    
330
    @Reference
331
    private DDMFormInstanceRecordLocalService recordLocalService;
332
    
333
    public void createCompleteForm(long groupId, long userId) throws PortalException {
334
        ServiceContext serviceContext = new ServiceContext();
335
        serviceContext.setScopeGroupId(groupId);
336
        
337
        // 1. Create a structure with form definition
338
        DDMForm ddmForm = createSampleForm();
339
        DDMFormLayout ddmFormLayout = DDMFormLayout.getDefaultDDMFormLayout(ddmForm);
340
        
341
        Map<Locale, String> nameMap = Collections.singletonMap(Locale.US, "Contact Form");
342
        Map<Locale, String> descriptionMap = Collections.singletonMap(Locale.US, "Customer contact form");
343
        
344
        DDMStructure structure = structureLocalService.addStructure(
345
            userId, groupId, 
346
            DDMStructureConstants.DEFAULT_PARENT_STRUCTURE_ID,
347
            PortalUtil.getClassNameId(DDMContent.class),
348
            null, // auto-generate structure key
349
            nameMap, descriptionMap, ddmForm, ddmFormLayout,
350
            "json", DDMStructureConstants.TYPE_DEFAULT, serviceContext
351
        );
352
        
353
        // 2. Create form instance from structure
354
        DDMFormInstanceSettings settings = new DDMFormInstanceSettings();
355
        settings.setRequireAuthentication(false);
356
        settings.setStorageType("json");
357
        
358
        DDMFormInstance formInstance = formInstanceLocalService.addFormInstance(
359
            userId, groupId, structure.getStructureId(),
360
            nameMap, descriptionMap, ddmForm, ddmFormLayout,
361
            settings, serviceContext
362
        );
363
        
364
        // 3. Publish the form
365
        formInstanceLocalService.updateFormInstanceWorkflowStatus(
366
            userId, formInstance.getFormInstanceId(), 
367
            WorkflowConstants.STATUS_APPROVED, serviceContext
368
        );
369
        
370
        // 4. Add a sample submission
371
        DDMFormValues formValues = createSampleSubmission(ddmForm);
372
        recordLocalService.addFormInstanceRecord(
373
            userId, groupId, formInstance.getFormInstanceId(),
374
            formValues, serviceContext
375
        );
376
    }
377
    
378
    private DDMForm createSampleForm() {
379
        DDMForm ddmForm = new DDMForm();
380
        ddmForm.setDefaultLocale(Locale.US);
381
        ddmForm.addAvailableLocale(Locale.US);
382
        
383
        // Name field
384
        DDMFormField nameField = new DDMFormField("name", "text");
385
        nameField.setLabel(new LocalizedValue(Locale.US, "Full Name"));
386
        nameField.setRequired(true);
387
        ddmForm.addDDMFormField(nameField);
388
        
389
        // Email field
390
        DDMFormField emailField = new DDMFormField("email", "text");
391
        emailField.setLabel(new LocalizedValue(Locale.US, "Email Address"));
392
        emailField.setRequired(true);
393
        emailField.setDataType("email");
394
        ddmForm.addDDMFormField(emailField);
395
        
396
        // Message field
397
        DDMFormField messageField = new DDMFormField("message", "textarea");
398
        messageField.setLabel(new LocalizedValue(Locale.US, "Message"));
399
        messageField.setRequired(false);
400
        ddmForm.addDDMFormField(messageField);
401
        
402
        return ddmForm;
403
    }
404
}
405
```
406

407
### Querying and Exporting Form Data
408

409
```java
410
@Component
411
public class FormDataExportExample {
412
    
413
    @Reference
414
    private DDMFormInstanceRecordLocalService recordLocalService;
415
    
416
    public void exportFormSubmissions(long formInstanceId) throws PortalException {
417
        // Get all approved form records
418
        List<DDMFormInstanceRecord> records = recordLocalService.getFormInstanceRecords(
419
            formInstanceId, WorkflowConstants.STATUS_APPROVED, 
420
            QueryUtil.ALL_POS, QueryUtil.ALL_POS, null
421
        );
422
        
423
        // Process each submission
424
        for (DDMFormInstanceRecord record : records) {
425
            DDMFormValues formValues = record.getDDMFormValues();
426
            processFormSubmission(record, formValues);
427
        }
428
        
429
        // Export to CSV
430
        byte[] csvData = recordLocalService.getFormInstanceRecordsCSV(
431
            formInstanceId, WorkflowConstants.STATUS_APPROVED
432
        );
433
        
434
        // Save or stream the CSV data
435
        saveCSVData(csvData, "form-submissions.csv");
436
    }
437
    
438
    private void processFormSubmission(DDMFormInstanceRecord record, DDMFormValues formValues) {
439
        Map<String, List<DDMFormFieldValue>> fieldValuesMap = formValues.getDDMFormFieldValuesMap();
440
        
441
        // Extract specific field values
442
        String name = getFieldValue(fieldValuesMap, "name");
443
        String email = getFieldValue(fieldValuesMap, "email");
444
        String message = getFieldValue(fieldValuesMap, "message");
445
        
446
        System.out.printf("Submission %d: %s (%s) - %s%n", 
447
            record.getFormInstanceRecordId(), name, email, message);
448
    }
449
    
450
    private String getFieldValue(Map<String, List<DDMFormFieldValue>> fieldValuesMap, String fieldName) {
451
        List<DDMFormFieldValue> fieldValues = fieldValuesMap.get(fieldName);
452
        if (fieldValues != null && !fieldValues.isEmpty()) {
453
            Value value = fieldValues.get(0).getValue();
454
            return value.getString(Locale.getDefault());
455
        }
456
        return "";
457
    }
458
}
459
```
460

461
## Types
462

463
### Core Data Transfer Objects
464

465
```java { .api }
466
class DDMFormValues {
467
    Map<String, List<DDMFormFieldValue>> getDDMFormFieldValuesMap();
468
    void setDDMFormFieldValues(List<DDMFormFieldValue> ddmFormFieldValues);
469
    void setDefaultLocale(Locale defaultLocale);
470
    void setAvailableLocales(Set<Locale> availableLocales);
471
}
472

473
class DDMFormFieldValue {
474
    String getName();
475
    Value getValue();
476
    String getInstanceId();
477
    List<DDMFormFieldValue> getNestedDDMFormFieldValues();
478
}
479

480
class DDMForm {
481
    Set<Locale> getAvailableLocales();
482
    Locale getDefaultLocale();
483
    List<DDMFormField> getDDMFormFields();
484
    Map<String, DDMFormField> getDDMFormFieldsMap(boolean includeNestedFields);
485
}
486

487
class DDMFormField {
488
    String getName();
489
    String getType();
490
    String getDataType();
491
    LocalizedValue getLabel();
492
    LocalizedValue getTip();
493
    boolean isRequired();
494
    boolean isRepeatable();
495
    Map<String, Object> getProperties();
496
}
497

498
class DDMFormLayout {
499
    List<DDMFormLayoutPage> getDDMFormLayoutPages();
500
    Locale getDefaultLocale();
501
    Set<Locale> getAvailableLocales();
502
}
503

504
class ServiceContext {
505
    void setScopeGroupId(long scopeGroupId);
506
    void setWorkflowAction(int workflowAction);
507
    void setAttribute(String name, Serializable value);
508
}
509
```