¶ preface
StUF-DCR (document creation services) is based on StUF-ZKN and StUF-BG. It is a message standard for the exchange of the data for the purpose of the document creation process.
The document creation process refers to the merging of templates with registration data. This registration data is retrieved from JOIN; the templates can be created and managed in JOIN, but when templates are created and managed in another package, StUF-DCR takes care of merging data from JOIN Case & Document, the Document Creation Requestor (DCV) with the template of the Document Creation application ( DCA).
StUF-DCR has the advantage that data is transferred one to one. Fewer mistakes are made, because data is not manually retyped; This also makes it possible to work more efficiently, because part of the document creation process is automated.
In addition, the document creation services tie in well with case-oriented working, because the case-related documents can be automatically stored in the case file after creation (via the Case and Document Services).
¶ Conditions
The StUF-DCR messaging service can be deployed if the following preconditions can be met:
- JOIN Case & Document version 6.0.8 and higher
- Decos solution case-oriented working (zaaktypen.nl)
- Availability and accessibility of the StUF-DCR message service of JOIN Case & Document from DCA and vice versa
¶ Operation
This section describes how the interface works.
¶ Document creation
Document creation can take place in three different ways; this can be set per template in the DCA. JOIN Case & Document therefore has no influence on the method used by the DCA for merging a chosen template. The behavior within JOIN Case & document is different for each method.
From the specification Document creation services (see reference document II), two mandatory options to support are described for the merge process. These are the synchronous and asynchronous process. In addition, the specification describes “Optional Variant # 3 - User interaction during creation”. The JOIN StUF-DCR integration also supports this variant.
The three different methods are discussed below.
¶ In sync
The chosen template is immediately merged with the data from JOIN Case & Document. The exchange of StUF messages takes place immediately without the intervention of a user.
- JOIN Case & Document calls on the DCA to start document creation
- The result is immediately reflected in the response of the call
The merged result is opened directly through the JOIN Client components.
To open the document directly from JOIN Case & Document, the Decos Document Control components are required at the user’s workplace and the user also needs Decos editing rights to this document. In addition, JOIN Case & Document must be accessible from the user’s workplace.
¶ Asynchronous (deferred concatenation)
The chosen template is not directly merged with the data of JOIN Case & Document. The merge is interrupted (for example, by the user) and will resume at a later time. A file registration will be created in JOIN, where the “Merge status” will be on Postponed until it is completed from JOIN Case & Document or the DCA. In this case, the StUF message is sent with a delay.
- JOIN Case & Document calls on the DCA to start document creation
- The DCA will only return the status “Received” in the response.
- After the merge, the DCA sends a message with the status “Done” and the file contents of the merged result to the JOIN Case & Document messaging service.
Because it is not predictable for JOIN Case & Document when the merge will be completed, the document will not open automatically when the merge is complete.
¶ User Interface (Optional Variant # 3)
After choosing the template, JOIN Case & Document opens the user interface of the document creation application. Here the user can add data. The template is then merged with both the data from JOIN Case & Document and the completed data. The result is written back to JOIN Case & Document via the asynchronous process.
- JOIN Case & Document calls on the DCA to start document creation
- In the response, the DCA returns the status “Received” and a link to the DCA user interface.
- JOIN Case & Document opens the link to the DCA user interface, after which the user can complete the merge within the DCA application.
- After the merge, the DCA sends a message with the status “Done” and the file contents of the merged result to the JOIN Case & Document messaging service which updates the file registration with this information.
Document creation always takes place from JOIN. The created file is written back from the template application to the file registry in JOIN when the user has finished editing the file.
Because it is not predictable for JOIN Case & Document when the merge will be completed, the document will not open automatically when the merge is complete.
¶ Conditions
In order to make use of this optional variant # 3, the DCA must meet the following preconditions.
- The DCA also supports optional variant # 3.
- The DCA uses a web-based user interface that can be called via a URL (Link).
¶ Combinate Business and Document Services
The Document Creation Services specification (See Reference Document II) describes an "Optional Variant # 1 - Storage by DCA in DMS via Case and Document Services. This variant describes a chain of 3 applications:
- Document creation application (DCA)
- Document creation applicant (DCV)
- Case system and DMS (Zs-DMS)
In this chain JOIN Business & Document is not the DCV, but a back office application assumes this role.
The chain then works as follows:
- DCV sends start message to DCA, DCA only returns the result “Received”.
- DCA stores created documents (without the intervention of DCV) in JOIN Business & Document via the Business and Document services.
- DCA sends message with result “Done” with no file content to DCV
The DCV can use the Business and Document Services to process the created document based on retrieve relevant metadata from JOIN Case & Document. For more information, see the KING and Decos Case and Document Services specification (Reference Documents IV).
¶ Conditions
For this chain to function, a number of preconditions must be met.
- The back office application (DCV) in this chain supports “Extension # 3” of the Document Creation Services specification. (Do not include document.content (ZKN: EDC) in message - deliveryDocumentcreationResultDu02).
- The back office application (DCV) in this chain is able to provide the case identification to the DCA in message 1.
- The document creation application in this chain supports the storage of case documents through the Case and document services.
- The back office application in this chain has already realized a Business and Document Services connection to the JOIN StUF-ZKN integration.
¶ Data exchange
Within the Document Creation services, a number of fields have been specified that both the DCO and the DCV must support (see reference document II). In addition, a number of optional fields are specified in this specification.
¶ data
The JOIN StUF-DCR integration supports the following fields and information. For each information it is indicated whether the DCA is allowed to update the metadata in the result message in JOIN Case & Document (column “T”).
| Field | Description | T | ||
|---|---|---|---|---|
| Parameters | ||||
| template identification | Identificatie van het sjabloon | x | ||
| job identification | Unieke sleutel voor de samenvoegopdracht | x | ||
| Document specification | ||||
| identification | Unieke sleutel voor de bestandsregistratie | x | ||
| yourLetterDate of receipt | Ontvangstdatum | x | ||
| yourLetterDate | Document datum | x | ||
| our reference | Document kenmerk | x | ||
| regarding | Document onderwerp | x | ||
| has.related.stakeholder (ZKN: BTR) | Gegevens gekoppelde betrokkene | x | ||
| Natural person | Indien gekoppelde persoon | x | ||
| inp.bsn | Burger service nummer | x | ||
| last name | Geslachtsnaam van de persoon | x | ||
| initials | Voorletters van de persoon | x | ||
| given names | Voornamen van de persoon | x | ||
| gender designation | Geslachtsaansuiding (‘M’ / ‘V’ / ‘O’) | x | ||
| residence address | Gegevens verblijfsadres | x | ||
| wpl.woonplaatsNaam | Woonplaatsnaam | x | ||
| gor.straatnaam | Straatnaam | x | ||
| aoa.postcode | Postcode | x | ||
| aoa.huisnummer | Huisnummer | x | ||
| aoa.huisletter | Huisletter | x | ||
| aoa.huisnummertoevoeging | Huisnummertoevoeging | x | ||
| Establishment (organization) | Indien gekoppelde vestiging | x | ||
| location number | Vestigingsnummer | x | ||
| trade name | Handelsnaam | x | ||
| residence address | Gegevens verblijfsadres | x | ||
| wpl.woonplaatsNaam | Woonplaatsnaam | x | ||
| gor.straatnaam | Straatnaam | x | ||
| aoa.postcode | Postcode | x | ||
| aoa.huisnummer | Huisnummer | x | ||
| aoa.huisletter | Huisletter | x | ||
| aoa.huisnummertoevoeging | Huisnummertoevoeging | x | ||
| has.related. nature | Aard betrokkene (vast ‘Geadresseerde’) | x | ||
| Relates To Related Case (ZKN: ZAK) | Gekoppelde zaak | x | ||
| identification | Zaak identificatie | x | ||
| Description | Omschrijving | x | ||
| explanation | Toelichting op omschrijving | x | ||
| characteristic | Zaak kenmerk | x | ||
| Start date | Startdatum van de zaak | x | ||
| registration date | Registratiedatum | x | ||
| End date Scheduled | Geplande einddatum (servicenorm) | x | ||
| deadline | Uiterlijke einddatum (wettelijke termijn) | x | ||
| end date | Eindatum van de zaak | x | ||
| isSpecificationof.related.document (ZKN: EDC) | Gegevens van document | |||
| identification | Document identificatie | x | ||
| dct description | Documenttype omschrijving | x | ||
| creation date | Creatiedatum | v | ||
| receipt date | Ontvangstdatum | x | ||
| title | Onderwerp van het document | v | ||
| description | Beschrijving van de bestandsregistratie | v | ||
| link | Link naar de bestandsregistratie in JOIN Z&D | x | ||
| document attribute | Document kenmerk | x | ||
| Free content (see section 2.1) | Decos Barcode | x | ||
| Group “document” | ||||
| Group “folder” | Alle ‘legacy’ itemprofiel velden van gekoppelde documenten | x | ||
| Group “address” | Alle ‘legacy’ itemprofiel velden van gekoppelde dossiers / zaken | x | ||
| Alle ‘legacy’ itemprofiel velden van gekoppelde adressen | x |
¶ Free content
The free content can be used to access data that is outside the standard. The references in the template to the fields in JOIN Case & Document will have to be coordinated by the application managers of the DCA and JOIN Case & Document.
See below an example of the JOIN Case & Document item profile elements “translated” by the integration into the free content structure in the StUF-DCR message.
¶ JOIN Case & Document structure
<ITEM TYPE = "DOCUMENT"> <ITEM_KEY> 123456 </ITEM_KEY> <SEQUENCE> 1 </SEQUENCE> <MARK> D-1 </MARK> <SUBJECT1> Test </SUBJECT1> <ITEMS TYPE = "ADDRESS"> <ITEM> <ITEM_KEY> 234567 </ITEM_KEY> <SEQUENCE> 2 </SEQUENCE> <MARK> A-2 </MARK> <SUBJECT1> Test </SUBJECT1> </ITEM> </ITEMS> </ITEM>
¶ StUF-DCR free content structure
<DCr: FreeContent>
<DCr: group type = “DOCUMENT” xsi: type = “DCr: FreeContentGroup”>
<DCr: element name = “ITEM_KEY” format = “string” xsi: type = “DCr: FreeContentElement-e”> 123456 </ DCr: element>
<DCr: element name = “SEQUENCE” format = “string” xsi: type = “DCr: FreeContentElement-e”> 1 </ DCr: element>
<DCr: element name = “MARK” format = “string” xsi: type = “DCr: FreeContentElement-e”> D-1 </ DCr: element>
<DCr: element name = “SUBJECT1” format = “string” xsi: type = “DCr: FreeContentElement-e”> Test </ DCr: element>
<DCr: group type = “ADDRESS” xsi: type = “DCr: FreeContentGroup”>
<DCr: element name = “ITEM_KEY” format = “string” xsi: type = “DCr: FreeContentElement-e”> 234567 </ DCr: element>
<DCr: element name = “SEQUENCE” format = “string” xsi: type = “DCr: FreeContentElement-e”> 2 </ DCr: element>
<DCr: element name = “MARK” format = “string” xsi: type = “DCr: FreeContentElement-e”> A-2 </ DCr: element>
<DCr: element name = “SUBJECT1” format = “string” xsi: type = “DCr: FreeContentElement-e”> Test </ DCr: element>
</ DCr: group>
</ DCr: group>
</ DCr: FreeContent>
¶ Data collections
The StUF-DCR integration can be connected to 1 collection for business and 1 collection for documents. Partly for this reason, the use of a Zaaktypen.nl device is strongly recommended, as this device works with 1 collection for both entity types.
In addition, 1 collection for natural persons and 1 collection for organizations can be used. It is recommended to use the collections for this data that are connected to the source for the basic data through the JOIN StUF-BG integration.
¶ Use and Furnishing
The templates are created and set up in the DCA. We refer to the supplier of the DCA for an explanation of how to design and set up such templates.
¶ Specify external templates
The template can be entered in Admin under the Application Management> Templates section in admin.
The description is the description of the template that users see when they can select a template.
Furthermore, the file names + extension are entered here in the file name field. The extension to be used for the StUF-DCR templates is always “.dcr”. For example: acknowledgment of receipt.dcr. Entering these file names ensures that StUF-DCR recognizes the template and that this template is opened in the correct application.
A new template is created for each document type up to and including version 6.0.7. For example, if the Licensing document type is associated with two case types, the associated template will be duplicated. From version 6.0.8 the functionality has changed and one and the same template is referenced if it is known in JOIN. It is desirable to have at least 6.0.8 installed.
¶ Authorization
In Admin, the authorization is also arranged per template. By default, each new template is available under each item profile. In the case of a zaaktypen.nl layout, this means that a template is available under each document type.
It is possible to set specifically to which document type a template may be merged.
Under the item profiles tab of a specific template, you indicate under which profile and the associated document type a template may be called up.
Because several document types of the same name can be found under a case document profile, you can tick the option Show the full path to the books, so that it becomes visible which document type is linked to which case type.
In the screenshot below you can see that the option is not checked. It is currently unclear which document type Advice belongs to which case type.
In the screenshot below, the option is checked. The Award letter template is now available with document type Advice that is related to case type Delivery check.
In addition to recording the authorization at the document type level, it is also possible to record an authorization at the user profile level. This indicates which user group can call a template.
¶ Capture standard template
In Zaaktypen.nl you can specify a standard template per entered document type. You do this by entering the description of the template in the Model field.
When the template is known in JOIN (ie when the description is the same), the existing template registration is referred to. If the template is not known, a new template registration is created. The application manager must then link the correct template to the registration. The template then becomes the default template for that document type. This means that the template is selected by default when using the answer button from the work queue, or that the template can be called up during document registration with the letter button.
¶ Merge information
The StUF-DCR integration writes information back to the file registry about the status of the merge. The field “TEXT2” is used for this by default. If desired, this field can be added to the default file item profile. The NUM6 field is used to record the numeric status.
The possible statuses are:
- received (job was received by DCA)
- busy (the job is still running)
- interrupted (means that the job will continue in the future)
- canceled (means that the job will not continue permanently)
- ready (job is completed, document is ready)
- unknown (for other cases)
- error (not allowed in this message)
These statuses are communicated by the DCA to JOIN Case & Document. Not every DCA is able to report all of these statuses.
¶ Start merge
Starting a merge is described in the help page of JOIN Case & Document. The method for calling an external StUF-DCR template is the same as for an internal template. For more information, see the JOIN Case & Document manual for the options for template merging (reference document IV).
¶ Resume merge
You can resume a merge by using the “open file” functions at the various places in JOIN Case & Document, in the case of an unfinished merge. This function causes the merge to resume. For more information, see the JOIN Case & Document manual on opening files (reference document IV).
¶ Error handling
It is possible that the DCA returns an error when calling the document merge. If this error message follows the synchronous call to start or resume the document merge, the error message will be displayed on the user’s screen.
The error message consists of the text “Merge with external template failed:”, supplemented with a textual message that corresponds one to one with the error message received from the DCO.