Importing definitions and documents

DynamicsFormsModule supports importing of definitions and documents using json or yaml structures.

Importing a definition

A definition represents groups of fields which define the template for a document, the content of which is stored within a definition version. Creating a definition has two steps, being the creation of the DynamicDefinition and the creation of a corresponding DynamicDefinitionVersion.

In the following sections, we’ll be creating a definition from scratch, including the data set it belongs to.

Creating the data structure

The first thing to do is to have a data structure available to be imported. To do so, we’ll create a yaml file which contains that data structure. This will later on be imported and used to create a DynamicDefinitionVersion

resources/installers/definitions/sample-document.yml
document-definition:
  name: sample-document
  content:
    - id: name
      type: string
    - id: address
      type: fieldset
      fields:
      - id: street
        type: string
      - id: number
        type: number
To learn more about creating a definition, please see the relevant chapters in Designing a document.

Creating an installer

Now that we have the data structure ready, we can create and import our definition. To start off, we’ll create an installer to create the definition.

@Installer(description = "Creates the initial document definitions", phase = InstallerPhase.AfterContextBootstrap)
public class DefinitionInstaller {

}

Next up, before we can import the data structure we’ve created, we need to make sure that we have a definition. To do so, we’ll create a dataset and definition (if necessary), for which we can import the given structure.

Autowired
private DynamicDefinitionDataSetRepository dataSetRepository;

DynamicDefinitionDataSet dataSet = new DynamicDefinitionDataSet();
dataSet.setName( "Samples" );
dataSet.setKey( "samples" );
dataSet = dataSetRepository.save( dataSet );

Now that we have a dataset, we can add definitions to it.

@Autowired
private DynamicDefinitionTypeConfigurationRegistry typeConfigurationRegistry;
@Autowired
private DynamicDefinitionRepoository definitionRepository;

DynamicDefinition definition = DynamicDefinition.builder()
                              .dataSet( dataSet )
                              .type( typeConfigurationRegistry.getbyName(DynamicDefinitionTypes.DOCUMENT)
                              .name( "Sample document" )
                              .key( "sample-document" )
                              .build();
definition = definitionRepository.save( definition );

Next, we can read out the file we’ve created and convert it to a RawDefinition object. Raw definitions are basic building blocks, which will validate whether the provided data structure is correct for a definition of a given type. In this case, we’re defining the structure for a document, so if a RawDefinition is successfully created, we can be sure that the provided definition can be parsed.

@Autowired
private RawDefinitionService rawDefinitionService;

Yaml yaml = new Yaml();
Object raw = yaml.load( new ClassPathResource( "installers/definitions/sample-document.yml" ).getInputStream() );
String convertedToJson = objectMapper.writeValueAsString( raw );
RawDefinition rawDefinition = rawDefinitionService.readRawDefinition( convertedToJson, DynamicDefinitionTypes.DOCUMENT );

Finally, we can create the definition version.

@Autowired
private DynamicDefinitionVersionRepository definitionVersionRepository;

DynamicDefinitionVersion definitionVersion = new DynamicDefinitionVersion();
definitionVersion.setDefinition( definition );
definitionVersion.setPublished( published );
definitionVersion.setRemarks( remarks );
definitionVersion.setVersion( version );
definitionVersion.setDefinitionContent( rawDefinitionService.writeDefinition( rawDefinition ) ); (1)
definitionVersion = definitionVersionRepository.save( definitionVersion );
1 The raw definition is converted to a json structure before it is persisted.

Importing a document