Skip to content

New Toezicht Form

Jump to bottom
Riad Abdallah edited this page Dec 8, 2023 · 3 revisions

Description

This page will explain how to add a new form in the Toezicht module of Loket. This form will appear as an option inside the "Type Dossier" dropdown menu. To create the form, we will be using the manage-submission-form-tooling service, so be sure to clone the repo before starting; the link can be found in the #RelevantServices section below.

Toezicht Type Dossier dropdown

Relevant Services

Step-by-Step Guide

Form Structure

We will first start with creating the actual form structure. To make our lives easier, we can use the manage-submission-form-tooling service to help with this task.

Create a folder that contains the new form: manage-submission-form-tooling/formSkeleton/forms/{MY_NEW_FORM_NAME_HERE}/form.ttl In the new form.ttl file, we can start defining the new form.

FieldGroups

fieldGroups:{NFG_UUID} a form:FieldGroup ;
    mu:uuid "{NFG_UUID}" ;
    form:hasField
      ###Opmerking/comment###
      fields:0cdfe85f-ec65-498f-bd26-0ec611967de0,

      ###Bestanden/files###
      fields:c7c5a589-0785-4032-a4bd-ee589add3c39.

The form starts with a new FieldGroup. This new FieldGroup(NFG) should have a new UUID. (replace NFG_UUID by a newly generated uuid). You define fields in the new form under form:hasField. These fields can be custom or pre-made. You can find a list of pre-made field groups in manage-submission-form-tooling/formSkeleton/inputFields/input-fields.ttl. To add a field, simply copy the field URI (e.g.fields:b9d831c5-da21-40d6-aac8-65feb4783d76) and add it under the form:hasField prefix.

ConditionalFieldGroup

After adding all fields to the form, we will add a new ConditionalFieldGroup (NCFG).

fields:{NCFG_UUID} a form:ConditionalFieldGroup ;
  mu:uuid "{NCFG_UUID}";
  form:conditions
    [ a form:SingleCodelistValue ;
      form:grouping form:Bag ;
      sh:path rdf:type ;
      form:conceptScheme <concept-scheme-subject> ;
      form:customValue <custom-value-subject>
    ] ;
  form:hasFieldGroup fieldGroups:{NFG_UUID} .

This new ConditionalFieldGroup (NCFG) will set the conditions as to whom and when to show the form. We are interested in the following prefixes: form:conceptScheme & form:customValue.

form:conceptScheme

form:conceptScheme attaches it to another field that is defined as a `conceptScheme``. In this case, we want to make the form appear when it has been selected from the Type Dossier dropdown.

An example is Agenda: In the very first image under #Description, you can see the dropdown values of Type Dossier. The agenda form does not show up by default; you first need to click on it before the whole form appears.

Toezicht Agenda

After Agenda has been selected from the dropdown, the Agenda form appears.

To add our form to the list of Type Dossier, we can just copy/paste the Type Dossier concept-scheme URI:

form:conceptScheme <http://lblod.data.gift/concept-schemes/71e6455e-1204-46a6-abf4-87319f58eaa5> ;

form:customValue

This section needs more information For form:customValue, we want to add a new BesluitDocumentType (NBDT):

form:customValue <https://data.vlaanderen.be/id/concept/BesluitDocumentType/{NBDT_UUID}> ;

Note: we will need the new BesluitDocumentType URI later on to define who can view the new form option.

Generate output

After following the steps above and adding some triples to connect everything together, we should end up with a file that looks like this:

######INSERT_FORM_NAME_HERE_AS_COMMENT######

fieldGroups:{NFG_UUID} a form:FieldGroup ;
  mu:uuid "{NFG_UUID}" ;
  form:hasField
    ###Opmerking/comment###
    fields:0cdfe85f-ec65-498f-bd26-0ec611967de0,

    ###Bestanden/files###
    fields:c7c5a589-0785-4032-a4bd-ee589add3c39 .

fields:0827fafe-ad19-49e1-8b2e-105d2c08a54a form:hasConditionalFieldGroup fields:{NCFG_UUID} .

fields:{NCFG_UUID} a form:ConditionalFieldGroup ;
  mu:uuid "{NCFG_UUID}" ;
  form:conditions
    [ a form:SingleCodelistValue ;
      form:grouping form:Bag ;
      sh:path rdf:type ;
      form:conceptScheme <http://lblod.data.gift/concept-schemes/71e6455e-1204-46a6-abf4-87319f58eaa5> ;
      form:customValue <https://data.vlaanderen.be/id/concept/BesluitDocumentType/{NBDT_UUID}>
    ] ;
  form:hasFieldGroup fieldGroups:{NFG_UUID} .

Important to know:

  • All values in curly brackets {} need to be replaced by newly generated UUID's.
  • Make sure the UUID's match when needed. (e.g. NCFG_UUID must be different from NFG_UUID and must match all other NCFG_UUID fields)
  • the form:conceptScheme value in this case references the Type Dossier dropdown field.

After saving the file, we need to generate the output file. In the root of the manage-submission-form-tooling repo, you will see a build-form.sh shell script. Open the terminal and run it. When the script has finished, you should see a new output.ttl. Save this file as we will use it in the next step.

Integrate form

To integrate the form so we can show it in the app, we will need to move output.ttl to the app-digitaal-loket/config/semantic-forms/ folder. It is highly recommended to prepend the file name by the current date. Enter the following command in your terminal to generate a date string: date +%Y%m%d%H%M%S then rename output.ttl to {GEN_DATE}-form.ttl. Go to the app's docker-compose.yml file and search for the enrich-submission service. Replace the ACTIVE_FORM_FILE env variable to use the new ttl file you added:

  enrich-submission:
    environment:
      ACTIVE_FORM_FILE: "share://semantic-forms/{GEN_DATE}-form.ttl"

Migrations

We need to create some migrations. We will put all migrations in the same file as they are related. Create a new file in the correct folder with the current date prepended and an appropriate name.

File

First, we need to create a migration for a new FileDataObject. For this, we will need the name of the form file (.ttl), the current date and the size of the form file. Add the following to the migration file replacing the placeholders where needed:

PREFIX nfo: <http://www.semanticdesktop.org/ontologies/2007/03/22/nfo#>
PREFIX mu: <http://mu.semte.ch/vocabularies/core/>
PREFIX dct: <http://purl.org/dc/terms/>
PREFIX xsd: <http://www.w3.org/2001/XMLSchema#>
PREFIX dbpedia: <http://dbpedia.org/resource/>
PREFIX dct: <http://purl.org/dc/terms/>
PREFIX ext: <http://mu.semte.ch/vocabularies/ext/>

INSERT DATA{
  GRAPH <http://mu.semte.ch/graphs/public> {
    <share://semantic-forms/{GEN_DATE}-forms.ttl> a nfo:FileDataObject ;
      dct:type              <http://data.lblod.gift/concepts/form-file-type> ;
      mu:uuid               "{NEW_UUID}" ;
      nfo:fileName          "{GEN_DATE}-forms.ttl" ;
      dct:created           "{CURRENT_DATE}"^^xsd:dateTime ;
      dct:modified          "{CURRENT_DATE}"^^xsd:dateTime ;
      dct:format            "text/turtle";
      nfo:fileSize          "{FILE_SIZE}"^^xsd:integer;
      dbpedia:fileExtension "ttl" .
  }
}

{CURRENT_DATE} in the following format: 2021-06-25Z

BesluitDocumentType

In the same file under the `INSERT DATA`` query, we can add the following snippet:

INSERT DATA {
  GRAPH <http://mu.semte.ch/graphs/public> {
    <https://data.vlaanderen.be/id/concept/BesluitDocumentType/{NBDT_UUID}> a <http://www.w3.org/2000/01/rdf-schema#Class>, <http://www.w3.org/2004/02/skos/core#Concept>;
      <http://www.w3.org/2004/02/skos/core#topConceptOf> <https://data.vlaanderen.be/id/conceptscheme/BesluitDocumentType>;
      <http://www.w3.org/2004/02/skos/core#inScheme> <http://lblod.data.gift/concept-schemes/71e6455e-1204-46a6-abf4-87319f58eaa5>, <https://data.vlaanderen.be/id/conceptscheme/BesluitDocumentType>;

      <http://mu.semte.ch/vocabularies/core/uuid> "{NBDT_UUID}";
      <http://lblod.data.gift/vocabularies/besluit/decidableBy> <http://data.vlaanderen.be/id/concept/BestuurseenheidClassificatieCode/{BCC_UUID}>;
      <http://www.w3.org/2004/02/skos/core#prefLabel> "{FORM_NAME}" .
  }
}

First thing to note is that the {NBDT_UUID} value (actually the whole URI) MUST be the same as the one you specified when building the form in the form:customValue subject under form:ConditionalFieldGroup. The same goes for the concept-scheme URI. This does not have a placeholder as the uri of the concept-scheme is the one of Type Dossier. {FORM_NAME} is the label that will appear when opening the Type Dossier dropdown.

There is then the <http://lblod.data.gift/vocabularies/besluit/decidableBy> prefix. This prefix will decide who will be able to see the new form option under the Type Dossier dropdown. You can add as many decidableBy triples as you want. Enter the UUID of the bestuurseenheidClassificatie you want the form to be visible to, and you should see the option appear when logging in as a bestuurseenheid that has that classificatie.

The complete migration file should now look something like this:

PREFIX nfo:     <http://www.semanticdesktop.org/ontologies/2007/03/22/nfo#>
PREFIX mu:      <http://mu.semte.ch/vocabularies/core/>
PREFIX dct:     <http://purl.org/dc/terms/>
PREFIX xsd:     <http://www.w3.org/2001/XMLSchema#>
PREFIX dbpedia: <http://dbpedia.org/resource/>
PREFIX dct:     <http://purl.org/dc/terms/>
PREFIX ext:     <http://mu.semte.ch/vocabularies/ext/>

INSERT DATA{
  GRAPH <http://mu.semte.ch/graphs/public> {
    <share://semantic-forms/{GEN_DATE}-forms.ttl> a nfo:FileDataObject ;
      dct:type              <http://data.lblod.gift/concepts/form-file-type> ;
      mu:uuid               "{NEW_UUID}" ;
      nfo:fileName          "{GEN_DATE}-forms.ttl" ;
      dct:created           "{CURRENT_DATE}"^^xsd:dateTime ;
      dct:modified          "{CURRENT_DATE}"^^xsd:dateTime ;
      dct:format            "text/turtle";
      nfo:fileSize          "{FILE_SIZE}"^^xsd:integer;
      dbpedia:fileExtension "ttl" .
  }
}

;

INSERT DATA {
  GRAPH <http://mu.semte.ch/graphs/public> {
    <https://data.vlaanderen.be/id/concept/BesluitDocumentType/{NBDT_UUID}> a <http://www.w3.org/2000/01/rdf-schema#Class>, <http://www.w3.org/2004/02/skos/core#Concept>;
      <http://www.w3.org/2004/02/skos/core#topConceptOf> <https://data.vlaanderen.be/id/conceptscheme/BesluitDocumentType>;
      <http://www.w3.org/2004/02/skos/core#inScheme> <http://lblod.data.gift/concept-schemes/71e6455e-1204-46a6-abf4-87319f58eaa5>, <https://data.vlaanderen.be/id/conceptscheme/BesluitDocumentType>;

      <http://mu.semte.ch/vocabularies/core/uuid> "{NBDT_UUID}";
      <http://lblod.data.gift/vocabularies/besluit/decidableBy> <http://data.vlaanderen.be/id/concept/BestuurseenheidClassificatieCode/{BCC_UUID}>;
      <http://www.w3.org/2004/02/skos/core#prefLabel> "{FORM_NAME}" .
  }
}

Restart the app, make sure all migrations have run and log in as a bestuurseenheid that has a classificatieCode you specified in the migration file.

Clone this wiki locally