¶ The StUF-ZKN Integration
JOIN Case and Document is able to exchange case and document information with connected applications through the interface Case and Document Services. In most cases this concerns a process application in the back office. Consider, for example, permit or WMO applications.
The interface is an implementation of the Business and Document Services as specified by VNG-Realisatie.
The functionality of this interface is described on this page
¶ Messaging possibilities
For the exchange of this data, Decos offers a messaging service based on the interface specification “Case and document services” version 1.1, as specified by KING (see documentation reference II). In practice, this interface is referred to by the abbreviation “zs-dms”.
For additional functionality on this interface, Decos offers support for various messages from the StUF-ZKN standard version 3.10, established by KING in 2010 (see documentation reference I). These messages are referred to in this document as “regular” StUF-Zaken messages. Both functionalities (zs-dms and regular StUF-ZKN) are part of the JOIN StUF-ZKN integration.
In summary, there are 3 types of messages:
- Case and document services
- Regular asynchronous StUF-ZKN messages
- Regular synchronous StUF-ZKN messages
¶ Asynchronous and Synchronous
The JOIN StUF-ZKN integration offers asynchronous and synchronous messaging services. The main difference between the two variants is the moment of feedback (response).
- An asynchronous messaging service only confirms the correct receipt of a request.
- A synchronous messaging service confirms the correct processing of a request.
An asynchronous messaging service generally provides better performance due to its fast acknowledgment and is suitable for requests where an end user does not have to wait for the request to be processed.
A synchronous messaging service is less likely to respond because the request must be processed first. This type of request is suitable if the end user or the application needs the result of the request before the process can continue.
¶ Use in practice
For all traffic in the direction of JOIN Case & Document from a back office application (chapters 2 to 6), the messages from the Case and Document services are recommended. These services offer a message set of asynchronous and synchronous messages that is tailored to link with a back office application.
Traffic from JOIN Business & Document towards a back office application (chapter 7) is not specified in the Case and Document services. Regular asynchronous StUF-ZKN messages are recommended for this.
Regular synchronous StUF-ZKN messages are not recommended at all for communication with a back office application. There are applications, such as a scanning solution for which this form of reporting can be of practical use. Chapters 2 to 6 do indicate with which synchronous message the relevant scenario can be executed.
¶ Authorization
This authorization is based on the StUF sender data, whereby the organization name and application name must correspond with the settings in the StUF-ZKN integration. During the connection phase, this data is coordinated between Decos and a third party.
This application name is also registered in JOIN Case & Document with one or more case types by means of adding and linking so-called external applications in Zaaktypen.nl. This can be independently configured by the application manager of JOIN Case & Document and can therefore be changed during the use of the StUF-ZKN integration without the intervention of Decos.
After these settings it is possible for this party to add cases of this case type (s) to JOIN Case & Document. These settings apply immediately to all incoming messages from this party.
Being allowed to add a case in Decos does not necessarily mean that this application is also a customer of goods or that it also handles these cases. The purchasing / handling application of the case can also be set in Zaaktypen.nl. More about this in chapter 7.
¶ Add Items
The StUF-ZKN integration of JOIN Case & Document offers the possibility to receive StUF-ZKN messages from third-party applications about new cases that are added to the JOIN Case & Document business warehouse. This chapter describes the functionalities and possible messages. See Chapter 8 for information about the data that can be exchanged in this scenario.
¶ Functionality
When the services, which the StUF-ZKN integration supports for adding cases, receive a message, processing will go through the following steps.
First of all, it is checked whether the sending application is known to the integration on the basis of the control data. If the application is not known, an error response will follow. It is then checked whether the sending application has access to the case type indicated in the message. If the sending application does not have access, an internal processing error or an error response follows, depending on the messaging service used. If the sending application has access to the specified case type, the new case is registered under this case type.
¶ Case identification
The Case Identifier consists of a text value of 40 characters. The identification is a globally unique code and serves as a means of communication in the internal StUF messages about the case in question. A case also has a characteristic and is the legible case number that is used in communication with citizens and employees. The case identifier is sent in the outgoing messages from Decos, described in chapter 7.
By default, the StUF-ZKN integration generates the globally unique code for the “GenerateCaseIdentification_Du02” response message. However, it is also possible to make an actual case reservation in the case system where the case characteristic can be returned as identification in the “generateCaseIdentification_Du02” response message. This can be useful for applications that do not know the difference between a case identification and case characteristic.
¶ Case type code
The case type code is a unique code that belongs to the case type as it is available in Zaaktypen.nl and JOIN Case & Document. This case type code must be known and matched in both applications.
¶ Linking / creating address records
The integration will attempt, based on the data on citizens and / or organizations in the case addition, to make a link with the relevant data from the basic data source, using the StUF-BG integration through an external collection. If this is unsuccessful, the integration will attempt to link the entry from an internal collection in JOIN Case & Document. If this data cannot be found in this collection either, the integration itself will create an address registration in the internal collection, using the data from the case addition message (see Chapter 10 - Address Data).
¶ Link BAG locations
Based on the location data in the case addition, the integration will attempt to link to the appropriate data from the source for BAG locations.
¶ Messages
In addition to the messages from the Case and document services for adding cases to the business warehouse, the integration also offers a synchronous (zakLk02) service based on regular StUF-ZKN messages. The use of these services has been discouraged since the introduction of the Case and Document Services.
¶ Case and Document Services
Before a case can be offered to JOIN Case & Document, a case identification must first be requested from the business warehouse by means of the “Generate CaseIdentification_Di02” message. The “generateCaseIdentification_Du02” response contains the case identification.
After that, the processing of the “createZaak_Lk01” message will lead to the registration of all case data.
| Message | Answer | Wrong | |
|---|---|---|---|
| 1 | generateCauseIdentification_Di02 | generateCauseIdentification_Du02 | Fo02 Message |
| 2 | createZaak_Lk01 | Bv03 Message | Fo03 Message |
¶ In sync
When using regular synchronous StUF-ZKN message traffic, an identification does not have to be generated first. The “zakLk02” message can be presented without identification. If the case has been successfully registered, a “Bv02Bericht” response will follow with the case identification generated by the system and containing the case reference.
| Message | Answer | Wrong | |
|---|---|---|---|
| 1 | bagLk02 | Bv02 Message | Fo02 Message |
¶ Change case
Decos supports the receipt and processing of change messages on business. These are “bag” messages with transaction type W (change). This chapter describes the functionalities and possible messages. See Chapter 8 for a complete overview of all data that can be exchanged in this scenario.
¶ Functionality
When the services that support the StUF-ZKN integration receive a message for changes to cases, processing of the following steps will go through.
First of all, it is checked whether the sending application is known to the integration on the basis of the control data. If the application is not known, an error response will follow. If the application is known, the case is looked up in the case system based on the case identification. It is then checked whether the sending application has access to the case type associated with this case. If the sending application does not have access, an internal processing error or an error response follows, depending on the messaging service used. If the sending application has access to the linked case type, it is checked whether the case has been handled. If the case is settled, an internal processing error or an error response will follow, depending on the messaging service used. If the case has not yet been settled, the change from the message will be implemented.
¶ Case handling and result
As soon as an end date has been entered, the case will be closed in JOIN Case & Document. After that, it is no longer possible to make changes to this case.
As soon as a result is entered, the end date is automatically filled in. With a result, the case is expected to be closed.
It is possible to reopen the case from a message. A change message must be sent in which the end date is explicitly cleared. After that it is again possible to send other changes.
¶ Change of case type not possible
Changing a case type code later is not supported by JOIN Case & Document. Based on a case type, work processes are started and lead times are calculated. The consequences of changing a case type cannot be predicted and are therefore not supported. If the case type is not correctly supplied to JOIN Case & Document, because it contains, for example, the wrong case type, the case will have to be handled manually. This sets the status to “completed” and the result to “expired”. Then a new case must be created with the correct case type.
¶ Unable to delete items
Deleting cases, messages with transaction type V (delete) towards Decos is not supported. In the case of a delete message, it is not known what consequences this will have for the current application and should always be carried out manually. (In both applications, the case must be deleted, if there is no other option).
An alternative to deleting cases is to set the status to “completed” and the result to “expired” with an explanation as to why the case has been deleted.
¶ Linking / Creating address records
The functionality for linking and creating address registrations for case changes is the same as for additions (see 2.1.3 - Linking / creating address registrations). Existing address links are always left intact.
¶ Link BAG locations
The integration will attempt to link to the appropriate data from the source for BAG locations based on the location data in the case changes. Existing BAG location links are always left intact.
¶ Messages
¶ Case and Document Services
The Case and Document Services has two messages for updating case data; A message specifically for updating the case status (updateZaakstatus_Lk01) and a message for updating other case data (updateZaak_Lk01). In practice, it often happens that a connected application also passes on the case status by means of the “updateZaak_Lk01” message.
¶ Updating status
| Message | Answer | Wrong | |
|---|---|---|---|
| 1 | updateJobstatus_Lk01 | Bv03 Message | Fo03 Message |
¶ Bijwerken zaakgegevens
| Message | Answer | Wrong | |
|---|---|---|---|
| 1 | updateZaak_Lk01 | Bv03 Message | Fo03 Message |
¶ Synchroon
| Message | Answer | Wrong | |
|---|---|---|---|
| 1 | bagLk02 | Bv02 Message | Fo02 Message |
If the change to the case has been successfully implemented, a ‘Bv02Bericht’ will follow. By default, this message contains the following information:
-
Case identification
-
Case characteristic
¶ Add documents to a case
Decos supports receiving so-called “edc” messages (Single Document) about new documents that can be registered with a case. These are messages with mutation type T (addition). See Chapter 9 for a complete overview of all data that can be exchanged in this scenario
¶ Functionality
A document addition contains a mandatory reference to the case to which the document must be added. When a document message is received, the corresponding case will be searched first. It is then checked whether the sending application has access to the case type associated with this case. If the sending application does not have access to the linked case type, an internal processing error or an error response follows, depending on the messaging service used.
If the sending application has access to the linked case, the document is added to this case.
¶ Document identification
The DocumentIdentification consists of a text field of 40 characters. The identification is a unique code and serves as a means of communication in the internal StUF messages about the relevant document. A document also has a Decos mark and is the legible document number that is used in communication with citizens and employees. The Decos feature is sent in the outgoing messages from Decos, described in chapter 7.
¶ Request document data
It is possible to request document data from Decos in advance, before the physical file is added in the node “content”. To this end, a “attachZaakdocumentToe_Lk01” message (with identification) or an edcLk02 message (possibly without identification) can be sent to Decos. Based on the related case and the document type (dct. Description), a document registration is already created in Decos. On the basis of the change messages from JOIN Case & Document (see chapter 7), the additional features such as Document reference and barcode are provided and the content of the document can be added to Decos later with a change message.
¶ Messages
¶ Business and Document Services
Within the standard Case and document services it is specified that a sending application first requests a document identification from the case system by means of the “generateDocumentIdentification_Di02” message. The “generateDocumentIdentification_Du02” response contains the generated identification of the document.
| Message | Answer | Wrong | |
|---|---|---|---|
| 1 | generateDocumentIdentification_Di02 | generateDocumentIdentification_Di02 | Fo02 Message |
| 2 | addBaseDocumentToe_Lk01 | Bv03 Message | Fo03 Message |
In sync
Regular synchronous StUF ZKN message can also be used to add a document. Based on the edcLk02 message, a “Fo02 message” with an error message or a “Bv02 Message” with a confirmation of the registration of the document in JOIN Case & Document follows. In the Bv02Message, among other things, the EDC identification is sent directly. In this synchronous service, it is not mandatory to first request a document identification from Decos, such as with the Case and document services.
| Message | Answer | Wrong | |
|---|---|---|---|
| 1 | bagLk02 | Bv02 Message | Fo02 Message |
The response of the Bv02Message contains the following data as standard:
-
Document identification
-
Document reference
-
Document Decos barcode
After that, the actual document is offered by means of the “attachZaakdocumentToe_Lk01” message.
¶ Change document
Decos supports the receipt and processing of change messages on documents. These are “edc” messages with transaction type W (change).
¶ Functionality
A document change message always contains the mandatory document identification element. A.d.h.v. the document identifier first looks up the linked case. It is then checked whether the sending application has access to the case type associated with this case and whether this application is therefore authorized to perform the document modification. If the sending application does not have access to the linked case type, an internal processing error or an error response follows, depending on the messaging service used.
If the sending application has access, the document change will be made.
The connected application can make a document change in various ways. The Case and Document Services describe two methods for changing document metadata or document content. In addition, it is possible to implement the change by means of a regular synchronous StUF-ZKN message. Finally, there is the option of directly opening the document registration in JOIN Case & Document via a link to the registration.
¶ Check-out, check-in (Zs-DMS)
With these services, the connected application is able to check out a document registration in JOIN Case & Document. The document is checked out in JOIN Case & Document by a system user belonging to the connection. After that, the document can be checked in again with adjustments or the check-out can be canceled.
¶ Instant update
The connected Zs-DMS application can also immediately perform a document update without first checking out the document. This is only possible if the application itself has kept a copy of the document.
A document update can also be sent directly through the synchronous web service.
¶ Link
The connected application can also open a file via a direct link to the file registration behind the document registration in JOIN Case & Document. This link can be obtained through question-answer messages (see Chapter 6). The document is then opened via the JOIN Client components. Edits to the document are written back to JOIN Case & Document by means of these components. This functionality falls outside the scope of the StUF-ZKN integration.
i 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.
¶ Delete messages
The JOIN StUF-ZKN integration does not support document delete messages. The Case and Document Services do not include a message specification for a delete message. The messaging services for regular asynchronous and synchronous document messages govern with an error response to “edc” notifications of transaction type “V”.
¶ Messages
¶ Case and Document Services
The Case and Document Services has two methods for changing a document:
- Via the check-out, check-in method
- Instant update
¶ Check-out, check-in
| Message | Answer | Wrong | |
|---|---|---|---|
| 1 | [giveEdit Business Document_Di02] | giveEdit Business Document_Du02 | Fo02 Message |
| 2a | updateZaakdocument_Di02 | Bv02 Message | Fo02 Message |
| 2b | cancelCheckout_Di02 | Bv02 Message | Fo02 Message |
¶ Direct
| Message | Answer | Wrong | |
|---|---|---|---|
| 1 | updateZaakdocument_Di02 | Bv02 Message | Fo02 Message |
¶ In sync
| Message | Answer | Wrong | |
|---|---|---|---|
| 1 | edcLk02 | Bv02 Message | Fo02 Message |
¶ Request information about case and documents
Decos offers an AnswerQuestion service, with which it is possible to ask a question to JOIN Case & Document with the aim of requesting the details of a specific case and / or document. The Case or document identification can be obtained using the addition messages of cases previously sent (see Chapter 2).
¶ Functionality
¶ Case details with document information
This service makes it possible to request information about a case, based on the case identification. The case identification was previously obtained when adding the case itself. Or by receiving and processing a notification about a new case from JOIN Case & Document.
The answer of a case question can return the status and other case details of a particular case (giveZaakstatus_Lv01 and giveZaakdetails_Lv01). It is also possible to request a list of linked case documents (giveLijstZaakdocumenten_Lv01). The document identifiers of these documents are shown in the response message. These identifications can then be used to retrieve the file contents per document.
In JOIN Case & Document it is possible to save multiple files with one document registration. This service takes this into account. The document identifiers returned are the unique data of each file in this registry. The metadata provided on the basis of the question is composed of the document and file records.
In addition, outside of the StUF Cases standard, it is possible to go directly to the correct case via a hyperlink to JOIN Case & Document and to start Decos with this case as the starting screen. In this way, a user can also view the list of documents as recorded in Decos. In order to be able to use this hyperlink to a case, additional (deep link) functionality must be realized within JOIN Case & Document.
¶ Document questions
This service makes it possible to ask a question to JOIN Case & Document with the aim of requesting the details and the content of a document in order to view it. Only one message is supported within this service: giveZaakdocumentRead_Lv01. The document identifier, required in this message, can be obtained by using one of the identifiers from the response to the message “giveListZaakdocumenten_Lv01”, described in the previous paragraph.
This message returns the metadata, hyperlink, and file contents of the document with the appropriate document identifier.
If the intention is to open a document in order to then modify it, this document must be requested with the message “give Business document edit_Di02” (see chapter 5 - Changing the document).
¶ Messages
The question messages as specified in the case and document services offer sufficient functionality for any connected back office application. The use of regular StUF-ZKN question messages in combination with back office applications are therefore no longer described in this document.
¶ Case and Document Services
There are various messages within the case and document services for requesting information from JOIN Case & Document:
Request case status
| Message | Message | Wrong | |
|---|---|---|---|
| 1 | [giveZaakstatus_Lv01] | [giveZaakstatus_Lv01] | Fo02 Message |
Request case details
| Message | Answer | Wrong | |
|---|---|---|---|
| 1 | [giveZaakdetails_Lv01] | bagLa01 | Fo02 Message |
Request list of linked case documents
| Message | Answer | Wrong | |
|---|---|---|---|
| 1 | [giveListZaakdocumenten_Lv01] | bagLa01 | Fo02 Message |
Request case document
| Message | Answer | Wrong | |
|---|---|---|---|
| 1 | [giveZaakdocumentRead_Lv01] | edcLa01 | Fo02 Message |
¶ Notifications from JOIN Business & Document
Notifications (notifications) about matters and documents can be sent to customers from JOIN Business & Document. These customers can be back office as well as front office suppliers.
¶ Functionality
The information sent in these messages about a case and a document is described in Chapters 8 and 9.
¶ Subscription service
In JOIN Case & Document you can indicate which cases (of which case type) should be sent to a back office application. A back office application has a subscription to items of a specific business type.
By default, all mutations in cases and documents of these case types are actively sent to the connected back office application. It can be set that mutations that come from the connected application itself are not sent again to the same application. This is discussed and set up during the configuration of the link.
¶ Notification receipt and processing
Based on the functionalities that a back office has, these messages can be stored or accepted for inspection. It is also possible to request case and document information from Decos on the basis of these notifications and receive the current status in this way. See chapter 620 for this.
¶ Conditions for sending notification
A case report is sent when the following conditions are met:
- Identification, start date, registration date, description and status are filled in
- Case is of the correct case type (back office is customer)
- Relationship with person or organization as initiator has been established.
- For a person, the person must contain a valid value such as BSN.
¶ Messages
The messages can be presented synchronously or asynchronously and therefore expect from the back office a StUF-Zaken receiving station for zakLk01 and edcLk01 or zakLk02 and edcLk02 messages. (These services are not described in the Standard for Case and Document Services). The use of synchronous outgoing notifications is hardly used in practice. Virtually all the descending connected applications support the reception of asynchronous notifications.
Additions and changes to items or documents
The StUF-ZKN integration keeps track of which items have been sent to which application and whether the application has processed this message correctly. A message about a case that has not previously been sent to a back office is an Addition message (processing type T). Any change subsequently made to the item is a change to this item (processing type W). The same principle applies to documents. Not every affiliated application processes the messages sent by JOIN Zaak & Document. However, the application must acknowledge every asynchronous notification sent with a “Bv03Bericht” response.
Removal of items or documents
When a case or document is removed from JOIN Case & Document, a removal message is sent to the customer. It is up to the customer to determine how this will be dealt with. Not every affiliated application processes the messages sent by JOIN Zaak & Document. However, the application must acknowledge every asynchronous notification sent with a “Bv03Bericht” response.
Filter outgoing messages by source
By default, every change in a case or document is submitted to the purchasing system for notification. However, this same system can also be the initiator of the mutation. This can create a so-called “loop” of messages. It is possible to filter messages in the outgoing message flow. These settings ensure that some sources (the back office itself, an OLO message, etc.) do not lead to an add or change message to a back office.
Case Notice
| Message | Answer | Wrong | |
|---|---|---|---|
| 1 | bagLk01 | Bv03 Message | Fo03 Message |
¶ Asynchronous document (edc) notification
| Message | Answer | Wrong | |
|---|---|---|---|
| 1 | edcLk01 | Bv03 Message | Fo03 Message |
The messages that are sent about new or changed documents are sent according to the information stated in chapter 9. However, the “content” field will not be filled, but the “link” field and the “identification” will be. With the help of this data, the document content can be called up by means of the services from chapter 6. In addition, the document can be opened directly from JOIN Case & Document by calling the hyperlink from the “link” field.
i 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.
¶ Data Case
This chapter describes all data that is exchanged in incoming and outgoing messages at case level. The first paragraph lists the data from the message. In the following sections more information is given about the processing of the data from the available fields in JOIN Case & Document.
¶ Data in message
| Field description | Note | V/O |
|---|---|---|
| identification | Unique identification of the case as registered in JOIN Case & Document | v * |
| Description | Description of the case | v |
| explanation | Explanation of the case description | o |
| Characteristic | Reference code from another application | o |
| Source | Application name of the broadcaster | o |
| Case level | Indicates whether this is a major or partial matter | o |
| Partial case indication | Indicates whether this case is part of another case | o |
| Isvan ZAKZKT | Relationship with the case type | v * |
| Description | Case type description | |
| code | Case type code | |
| Start date | Date on which the case is started | v |
| End date | End date of the case (optional, empty at start) | o |
| Registration date | Date the case was registered | v |
| End date Scheduled | Date the case is scheduled to end (may be left blank) | o |
| Deadline End Date | Date by which the case must be settled at the latest according to the legal term (may be left empty) | o |
| Result Description | Description of the result of the case (empty at the start) | o |
| Result explanation | Possible explanation of the result (optional, empty at the start) | o |
| ZAKSTT serial number | Status of the case | O |
| ZAKSTT description | Status of the case | O |
| ZAKSTT.date status set | Date the status was set | O |
| Refers to ZAKOBJ | Relationship with a business object | O |
| Addressable Object designation | An address can be added within the relationship with an object. In Decos, this address is then stored as a text field in the appropriate location field. | O |
| AOA | If you have a BAG link, the authentic object will also be linked. | |
| Public space | A public space can be added within the relationship with an object. In Decos, this public space is then stored as a text field in the appropriate location field. | O |
| OPR | ||
| has as Initiator | Relationship with the initiator of the case - the applicant | V |
| ZAKBRTINI | ||
| has as Delegate | Relationship with the agent of the case | o |
| ZAKBRTGMC | ||
| has as Stakeholder ZAKBRTBLH | Relationship with the stakeholder of the case | o |
| has as other involved parties ZAKBRTOVR | Relationship with other parties involved in the case | o |
| Natural person | Information about the relationship - a BSN is sufficient | - |
| NPS.inp.bsn | The following Natural Person fields are stored in the business warehouse when it is not possible to create the relationship with a citizen from the data warehouse. | |
| Last name | ||
| Prefix Gender Name | ||
| Initials | ||
| First names | ||
| Gender Designation | ||
| Residence address details | ||
| Place of residence name | ||
| Street name | ||
| Postal Code | ||
| House number | ||
| HouseLetter | ||
| HouseNumberAddition | ||
| Not natural person NNP.inn.nnpId | Information about the relationship - a Chamber of Commerce is sufficient | - |
| The following fields of an Not Natural Person are stored in the business warehouse when it is not possible to create the relationship with an organization from the data warehouse. | ||
| Registered name | ||
| visiting address | ||
| City name | ||
| Street name | ||
| Postal Code | ||
| House number | ||
| HouseLetter | ||
| House number Addition | ||
| Establishment | Information about the relationship - a location number is sufficient | - |
| VES location number | The following fields of a location are stored in the business warehouse when it is not possible to create the relationship with an organization from the data warehouse. | |
| Trade name | ||
| visiting address | ||
| City name | ||
| Street name | ||
| Postal Code | ||
| House number | ||
| HouseLetter | ||
| House number Addition | ||
| Operated by ZAKBRTUTV | Relationship with the executor of the case - employee or organizational unit | o |
| Responsible for ZAKBTRVRA | Relationship with the person responsible for the business - employee or organizational unit | o |
| Collaborator | Details of the employee handling the case. | - |
| MDW | The following fields are processed: | |
| Identification | ||
| Initials | ||
| Surname prefix | ||
| Last name | ||
| Organizational unit | Details of the organizational unit handling the case. | - |
| OEH | The following fields are processed: | |
| Identification | ||
| Name | ||
| Has ZAKZAKDEL as a sub-case | Relationship with one or more sub-cases | o |
| BAG identification | The identifiers of the sub-cases in this case are entered here. | o |
¶ Generic case data
| JZD Field | Internal field | Connect property | StUF |
|---|---|---|---|
| Case identification | ExternalId | identification | |
| Case characteristic | MARK | [Uniek veld] | characteristic / characteristic |
| Description of case | SUBJECT1 | Description | Description |
| Case start date | DOCUMENT_DATE | StartDate | start date |
| Case settled | PROCESSED | IsProcessed | - |
| Date of settlement | DATE5 | EndDate | end date |
| Date registration | DateCreated | registration date |
¶ Case identification
The case identification is used within the integration to uniquely identify a case. This information is not visible in the user interface of JOIN Case & Document.
The connected application can generate an identification by means of the “GenerateCommissionIdentification_Di02” service.
¶ Case characteristic
The case attribute cannot be written by an attached application. The value of this field is used in messaging as follows:
<ZKN:kenmerk> <ZKN:kenmerk>[Zaak kenmerk]</ZKN:kenmerk> <ZKN:bron>[Instelling ‘Standaard bron’]</ZKN:bron> </ZKN:kenmerk>
If the setting “Use case characteristic as case identification” is enabled, the value is also used in the StUF node:
<ZKN:identificatie>[Zaak kenmerk]</ZKN:identificatie>
¶ Case description
The description of the case is limited to 80 characters within StUF. For outgoing notifications, the case description is truncated to this. The description is a mandatory value for an outgoing notification.
<ZKN:omschrijving>[Omschrijving zaak]</ZKN:omschrijving>
¶ Case start date
The case start date contains the DATE () macro by default. As a result, when creating a case, today’s date is automatically entered as the start date if this is not specified in the incoming StUF message.
<ZKN:startdatum>[Startdatum zaak]</ZKN:startdatum>
¶ Case closed
This field is automatically checked when the case receives a filled due date. There is no separate field for this state within StUF.
¶ Date of settlement
The date of settlement is determined by a macro “DATE (PROCESSED)” when the case is not handled by the StUF-ZKN interface.
<ZKN:einddatum>[Datum afhandeling]</ZKN:einddatum>
¶ Date registration
There is no field in the item profile for the registration date. This date is available as a hidden Connect property and is used for the following StUF node:
<ZKN:registratiedatum>[Datum registratie]</ZKN:registratiedatum>
¶ 8.3. Case type specific data
| JZD Field | Internal field | Connect property | StUF |
|---|---|---|---|
| Current practitioner | TEXT5 | Handler | has As Executive (ZAKBTRUTV) |
| Status | TITLE | Status | has (ZAKSTT) |
| Expected end date (service standard) | DATE1 | DesiredEndDate | End date Scheduled |
| Expected end date (legal) | DATE2 | MaximumEndDate | deadline |
| Result | FUNCTION | Result | result |
| Source | PHONE2 | MarkSource | characteristic / source |
| External case characteristic | COUNTRY | IntakeID | characteristic / characteristic |
| Responsible back office | TEXT1 | ResponsiblePerson | hasAs Responsible (ZAKBTRVRA) |
| Feedback | EMAIL 3 | FeedBack | - |
| Remarks to case / explanation | MEMO | Explanation | explanation |
¶ Current practitioner
The practitioner can be assigned by the back office application via StUF-ZKN if he / she has the role “Practitioner” as an external application in Zaaktypen.nl. The practitioner cannot then be entered manually in JOIN Case & Document.
The practitioner can be an employee or an organizational unit (department).
¶ Collaborator
The practitioner is saved in JOIN Case & Document as:
<voorletters>. <voorvoegselAchternaam> <achternaam> [<identificatie>] <ZKN:heeftAlsUitvoerende StUF:entiteittype="ZAKBTRUTV" StUF:verwerkingssoort="T"> <ZKN:gerelateerde> <ZKN:medewerker StUF:entiteittype="MDW" StUF:verwerkingssoort="T"> <ZKN:identificatie>001</ZKN:identificatie> <ZKN:achternaam>Boer</ZKN:achternaam> <ZKN:voorletters>J</ZKN:voorletters> <ZKN:voorvoegselAchternaam>de</ZKN:voorvoegselAchternaam> </ZKN:medewerker> </ZKN:gerelateerde> </ZKN:heeftAlsUitvoerende>
¶ Organizational unit
Details of the organizational unit handling the case.
The following fields are processed:
- Identification
- Name
<ZKN:heeftAlsUitvoerende StUF:entiteittype="ZAKBTRUTV" StUF:verwerkingssoort="T"> <ZKN:gerelateerde> <ZKN:organisatorischeEenheid StUF:entiteittype="OEH" StUF:verwerkingssoort="T"> <ZKN:identificatie>008</ZKN:identificatie> <ZKN:naam>Afdeling ruimte</ZKN:naam> </ZKN:organisatorischeEenheid> </ZKN:gerelateerde> </ZKN:heeftAlsUitvoerende>
¶ Status
The possible statuses must be coordinated with the back office application. JOIN Case & Document only has a status description and a status sequence number. The status code that is entered in the outgoing message is the status description truncated to 8 characters.
<ZKN:heeft StUF:entiteittype="ZAKSTT" StUF:verwerkingssoort="T"> <ZKN:gerelateerde StUF:entiteittype="STT" StUF:verwerkingssoort="T">| <ZKN:zkt.code>[Zaaktype code]</ZKN:zkt.code> <ZKN:zkt.omschrijving>[Zaaktype naam]</ZKN:zkt.omschrijving> <ZKN:volgnummer>[Volgnummer status]</ZKN:volgnummer> <ZKN:code>[Status omschrijving, afgekapt tot 8 tekens]</ZKN:code> <ZKN:omschrijving>[Status omschrijving]</ZKN:omschrijving> <ZKN:ingangsdatumObject>20140101</ZKN:ingangsdatumObject> </ZKN:gerelateerde> <ZKN:toelichting>[Status omschrijving]</ZKN:toelichting> <ZKN:datumStatusGezet>[Datum vandaag]</ZKN:datumStatusGezet> </ZKN:heeft>
With question-answer to a case, in addition to the above status information, it is also indicated whether the current status is the latest status:
<ZKN:heeft StUF:entiteittype="ZAKSTT"> ... <ZKN:indicatieLaatsteStatus>[J/N]</ZKN:indicatieLaatsteStatus> </ZKN:heeft>
¶ Expected end date (service standard)
The “expected end date (service standard)” can be set by the back office application via StUF-ZKN when it has the role “Handler” as an external application in Zaaktypen.nl. If the back office application does not provide a value, JOIN Case & Document calculates a value based on the set ‘Service standard treatment’.
<ZKN:einddatumGepland>[Verwachte einddatum (servicenorm)]</ZKN:einddatumGepland>
¶ Expected end date (legal)
The “expected end date (legal)” can be set by the back office application via StUF-ZKN when it has the role “Practitioner” as an external application in Zaaktypen.nl. If the back office application does not provide a value, JOIN Case & Document calculates a value based on the set ‘Processing time’.
<ZKN:uiterlijkeEinddatum>[Verwachte einddatum (wettelijk)]</ZKN:uiterlijkeEinddatum>
¶ Result
The possible results must be coordinated with the back office application. JOIN Case & Document has no explanation of the result. That is why the explanation in outgoing messages is filled with the result description.
<ZKN:resultaat> <ZKN:omschrijving>[Resultaat]</ZKN:omschrijving> <ZKN:toelichting>[Resultaat]</ZKN:toelichting> </ZKN:resultaat>
¶ Source and External Case Reference
The “Source” and “External case characteristic” fields are used to store the value that the interface receives for within an attribute node that is not its own characteristic. For example, an application can control the following:
<ZKN:kenmerk> <ZKN:kenmerk>Z/16/101546</ZKN:kenmerk> <ZKN:bron>DecosD5</ZKN:bron> </ZKN:kenmerk> <ZKN:kenmerk> <ZKN:kenmerk>Z-HZ_WABO-2015-000045</ZKN:kenmerk> <ZKN:bron>Squit XO</ZKN:bron> </ZKN:kenmerk>
In this case, the value “Z-HZ_WABO-2015-000045” is stored in the “External Case Attribute” field and the “SquitXO” value “is stored in the” Source "field.
A maximum of 2 characteristics are always stopped in outgoing notifications. The own characteristic and the external characteristic. In the absence of an external characteristic and source, only the own characteristic is filled.
¶ Responsible back office
The responsible back office can be set by the back office application via StUF-ZKN. The responsible back office cannot be entered manually in JOIN Case & Document.
The person responsible for a case can be an employee or an organizational unit (department).
¶ Collaborator
Details of the employee handling the case.
The following fields are processed:
- Identification
- Initials
- Surname prefix
- Last name
The responsible back office is written in JOIN Case & Document as:
<voorletters>. <voorvoegselAchternaam> <achternaam>
[<identificatie>] <ZKN:heeftAlsVerantwoordelijke StUF:entiteittype="ZAKBTRVRA" StUF:verwerkingssoort="T"> <ZKN:gerelateerde> <ZKN:medewerker StUF:entiteittype="MDW" StUF:verwerkingssoort="T"> <ZKN:identificatie>002</ZKN:identificatie> <ZKN:achternaam>Vries</ZKN:achternaam> <ZKN:voorletters>M</ZKN:voorletters> <ZKN:voorvoegselAchternaam>de</ZKN:voorvoegselAchternaam> </ZKN:medewerker> </ZKN:gerelateerde> </ZKN:heeftAlsVerantwoordelijke>
¶ Organizational unit
Details of the organizational unit handling the case.
The following fields are processed:
- Identification
- Name
<ZKN:heeftAlsVerantwoordelijke StUF:entiteittype="ZAKBTRVRA" StUF:verwerkingssoort="T"> <ZKN:gerelateerde> <ZKN:organisatorischeEenheid StUF:entiteittype="OEH" StUF:verwerkingssoort="T"> <ZKN:identificatie>008</ZKN:identificatie> <ZKN:naam>Afdeling ruimte</ZKN:naam> </ZKN:organisatorischeEenheid> </ZKN:gerelateerde> </ZKN:heeftAlsVerantwoordelijke>
¶ Feedback
The “Feedback” field is filled with the last response that the interface received when sending a notification. Possible values are:
- Bv02 confirmation received from BackOffice
- Bv03 confirmation received from BackOffice
- Unknown Error Occured
¶ Explanation
The explanation may be a maximum of 1000 characters long within StUF. The “memo” field of JOIN Case & Document has no maximum length. In outgoing messages, the field is therefore truncated to 1000 characters.
<ZKN:toelichting>[Toelichting]</ZKN:toelichting>
¶ Additional data
The fields for this data are not added by default to an item profile generated by a Zaaktypen.nl, but may be useful for some implementations.
| JZD Field | Internal field | Connect property | StUF |
|---|---|---|---|
| Substance indication | BOL7 | SubCase | See description |
| Handling organization | SALUTATION | OrganizationCode | See description |
| Location | TEXT8 | Location | See description |
¶ Substitute indication
This field can be used to indicate that it is a partial business. The back office application can indicate this in the StUF message by filling the following StUF nodes:
| case level | 01-Mar | 1 = Main business, 2 = Sub-business, 3 = Sub-business |
|---|---|---|
| Sub-cases Indication | Y / N | The indication of whether a CASE is being handled in sub-cases. |
| extraElement: idPartMissOf | String | Identification of the related essential |
¶ For instance:
<ZKN:zaakniveau>2</ZKN:zaakniveau> <ZKN:deelzakenIndicatie>J</ZKN:deelzakenIndicatie> <StUF:extraElementen> <StUF:extraElement naam="isDeelZaakVan">Z/16/101545</StUF:extraElement> </StUF:extraElementen>
For instance:
<ZKN:zaakniveau>2</ZKN:zaakniveau> <ZKN:deelzakenIndicatie>J</ZKN:deelzakenIndicatie> <StUF:extraElementen> <StUF:extraElement naam="isDeelZaakVan">Z/16/101545</StUF:extraElement> </StUF:extraElementen>
¶ Handling organization
This field is filled with the handling organization. The possible values must be coordinated for all connected back office applications.
For incoming notifications, the value taken from the “administration” node is taken from the message control data, which is sent to JOIN Case & Document to create / update the case.
For outgoing notifications, the value from the field is put in the “organization” node of the “receiver” control data when the connection in the interface is configured with multiple organization codes. When 1 organization code is configured for the connection, the value from the field is put in the “administration” node of the “recipient” control data.
Example control data incoming notification:
<StUF:zender> <StUF:organisatie>Gemeente X</StUF:organisatie> <StUF:applicatie>GWS4ALL</StUF:applicatie> </StUF:zender> <StUF:ontvanger> <StUF:organisatie>Decos</StUF:organisatie> <StUF:applicatie>JOINZD</StUF:applicatie> <StUF:administratie>Gemeente X</StUF:administratie> </StUF:ontvanger>
Example control data of outgoing notification with multiple set organization codes:
<StUF:zender> <StUF:organisatie>Decos</StUF:organisatie> <StUF:applicatie>JOINZD</StUF:applicatie> <StUF:administratie>Gemeente X</StUF:administratie> </StUF:zender> <StUF:ontvanger> <StUF:organisatie>Gemeente X</StUF:organisatie> <StUF:applicatie>GWS4ALL</StUF:applicatie> </StUF:ontvanger>
Example control data of outgoing notification with 1 set organization code:
<StUF:zender> <StUF:organisatie>Decos</StUF:organisatie> <StUF:applicatie>JOINZD</StUF:applicatie> <StUF:administratie>Gemeente X</StUF:administratie> </StUF:zender> <StUF:ontvanger> <StUF:organisatie>Centric</StUF:organisatie> <StUF:applicatie>GWS4ALL</StUF:applicatie> <StUF:administratie>Gemeente X</StUF:administratie> </StUF:ontvanger>
¶ Location
The connected application has the option of sending the entities ‘addressable object’ (AOA) and ‘public space’ (OPR) as entities to which the case relates.
The data from these entities is translated by the link into a textual representation in the ‘Location’ field.
If this field is added as an extra feature from Zaaktypen.nl, it is unpredictable which TEXT field will be used. Make sure that the field mapped in Connect is the same TEXT field for all case types linked to StUF-Zaken.
¶ Addressable object
The following data can be processed for an addressable object:
<ZKN:heeftBetrekkingOp stuf:entiteittype="ZAKOBJ" stuf:verwerkingssoort="T"> <ZKN:gerelateerde> <ZKN:adres stuf:entiteittype="AOA" stuf:verwerkingssoort="T"> <BG:identificatie stuf:noValue="waardeOnbekend" xsi:nil="true"/> <BG:authentiek stuf:metagegeven="true">N</BG:authentiek> <BG:wpl.woonplaatsNaam>Noordwijk</BG:wpl.woonplaatsNaam> <BG:gor.openbareRuimteNaam>Huygenstraat</BG:gor.openbareRuimteNaam> <BG:huisnummer>30</BG:huisnummer> <BG:huisletter>A</BG:huisletter> <BG:huisnummertoevoeging>Bis</BG:huisnummertoevoeging> <BG:postcode>2201DK</BG:postcode> </ZKN:adres> </ZKN:gerelateerde> </ZKN:heeftBetrekkingOp>
Resultaat in JOIN Zaak & Document:
When a BAG connection has been realized, an addressable object can be linked to the case by the StUF-ZKN integration.
Public space
The following data can be processed from a public space:
<ZKN: Relates To StUF: entity type = "ZAKOBJ" StUF: processing type = "T"> <ZKN: related> <ZKN: publicSpace stuf: entity type = "OPR" stuf: processing type = "T"> <BG: identifier stuf: noValue = "valueUnknown" xsi: nil = "true" /> <BG: authentic stuf: metadata = "true"> N </ BG: authentic> <BG: wpl.residenceName> Noordwijk </BG:wpl.residenceName> <BG: gor.publicSpaceName> Huygenstraat </BG:gor.publicSpaceName> </ ZKN: public space> </ ZKN: related> </ ZKN: Relates To>
Result in JOIN Case & Document:
¶ Data Document
Within JOIN Case & Document we make a distinction between a document registration and a file registration. The StUF standard only knows the entity ‘Single document’ (EDC) in which document metadata and file content are linked to each other. For this reason, every linked file in JOIN Case & Document is visible via the StUF-ZKN integration as an EDC entity. This entity contains data from both the document registration and the file registration.
¶ Data in message
| Field description | Note | V / O |
|---|---|---|
| identification | Unique identification of the document in JOIN Case & Document. | v |
| dct description | Document type description as defined in the case type catalog | O |
| Creation date | Date the document was created | v |
| Date of receipt | Date the document was received (optional) | O |
| Title | Brief description of the document | v |
| Format | The format of the document (file format) | O |
| Language | The language of the document | O |
| Description | Detailed description of the document (optional) | O |
| Status | Status of the document. | O |
| Shipment date | Date the document was sent. (optional) | O |
| confidential Designation | Confidentiality notice according to StUF-ZKN (is automatically filled by Decos from the document type, can be overwritten by the back office for deviating indication) | O |
| Author | Author of the document | O |
| Content | Base64 content of the document | O |
| extraElement: attribute | JOIN Document attribute | O |
| extraElement: barcode | JOIN Document barcode | O |
| Is relevant for EDCZAK BAG identification | Relationship with the Good: Unique identification of the case as registered in JOIN Case & Document. This can be both the identification and the decos case characteristic. | v |
¶ Generic document data
| JZD Field | Internal field | Connect property | StUF |
|---|---|---|---|
| Document identification | ExternalId | identification | |
| Document type | BOOKNAME | DocumentType | dct description |
| Topic | SUBJECT1 | Subject | title |
| Date of document | DOCUMENT_DATE | DocumentDate | creation date |
| Characteristic | MARK | Mark | document attribute |
| Barcode | BARCODE | Barcode | barcode |
| Author | TEXT5 | Author | Author |
| File extension | - | format | |
| Language | - | language | |
| Audience | BOL9 | IsPublished | confidential Designation |
| Link to registration | EntityUrl | Link |
¶ Document identification
The document identifier is used within the integration to uniquely identify a document. This information is not visible in the user interface of JOIN Case & Document.
The connected application can generate an identification using the ‘generateDocumentIdentification_Di02’ service.
<ZKN:identificatie>123465f612f5-c372-4f49-8bbd-f2cec6fde54a</ZKN:identificatie>
¶ Document type
The document type of the document. The textual value of this element must exactly match the document type description.
<ZKN:dct.omschrijving>Ontvangstbevestiging</ZKN:dct.omschrijving>
¶ Topic
The subject of the document. This value is exchanged in the ‘title’ field in the message traffic.
<ZKN:titel>Aanvragen vergunning</ZKN:titel>
¶ Date of document
The creation date of the document.
<ZKN:creatiedatum>20150902</ZKN:creatiedatum>
¶ Feature and barcode
The characteristic of a document as registered in Decos is always mentioned in an extra element part of a StUF document message. A message sent from Decos therefore always contains the EDC identification as a unique identifying and internally used field and contains the readable document reference and barcode of Decos for correspondence about this document.
<StUF:extraElementen> <StUF:extraElement naam="documentkenmerk">D-12354</StUF:extraElement> <StUF:extraElement naam="barcode">Z0006CD16F8</StUF:extraElement> </StUF:extraElementen>
The barcode can be placed on a letter using the Decos Barcode font.
¶ Author
The author is the originator of the document and is saved as a free text field. This information is not passed on by every application.
<ZKN:auteur>Jan Jansen</ZKN:auteur>
¶ File extension
The file extension is automatically populated with the current extension of the file in outgoing notifications or reply messages.
<ZKN:formaat>.txt</ZKN:formaat>
With incoming EDC notifications, any value entered is ignored and the complete file name from the relevant attribute from the content node is used to create the file.
¶ Language
The language of the document is filled with ‘NL’ by default in outgoing notifications or reply messages.
<ZKN:taal>NL</ZKN:taal>
In case of incoming EDC notifications, any value entered is ignored.
¶ Audience
This BOL field is mapped to the confidentiality indication. When the BOL field is checked, the confidentiality indication will be filled with the term ‘Public’. When the BOL field is unchecked, the confidentiality indication is filled with the term ‘Confidential’.
<ZKN:vertrouwelijkAanduiding>VERTROUWELIJK</ZKN:vertrouwelijkAanduiding>
¶ Link to registration
This field contains a direct link to the registration in JOIN Case & Document in all outgoing notifications and response messages.
<ZKN:link>http://jzd/aspx/item.aspx?I=FA88CDC619514176AF0B1EF73B819A27</ZKN:link>
i In case of incoming EDC notifications, any value entered will be ignored.
¶ Document type specific document data
| JZD Field | Internal field | Connect property | StUF |
|---|---|---|---|
| Date of receipt | DATE8 | DateReceived | receipt date |
| Date sent | DATE7 | DateSent | shipment date |
¶ Date of receipt
The receipt date of the document.
<ZKN:ontvangstdatum>20160405</ZKN:ontvangstdatum>
¶ Date sent
The date sent of the document.
<ZKN:verzenddatum>20160405</ZKN:verzenddatum>
¶ File registration information
| JZD Field | Internal field | Connect property | StUF |
|---|---|---|---|
| Description | TEXT1 | File.Description | Description |
| File content | - | Content |
¶ Description
The description / description of the document. This value is written at the file level as a file description.
<ZKN:beschrijving>Beschrijving van het document</ZKN:beschrijving>
¶ File content
The file content is only returned from JOIN Case & Document to a connected application by means of the response message to an EDC question message. Outgoing EDC notices do not include the file content.
When incoming EDC notifications contain file content, the file in JOIN Case & Document will be updated with this updated content. When versioning is enabled, a new version is created.
<ZKN:inhoud StUF:bestandsnaam="test.txt">aG9pIGRlY29z</ZKN:inhoud>
¶ Data Addresses
The StUF-Business integration is able to create address registrations of citizens and / or organizations and / or link them to a case registration.
JOIN Case & Document links the addresses directly to the source in the data warehouse, using the StUF-BG integration (basic data) when a BSN or branch number is available. If this is not the case, the details of the person or company will be placed in a separate non-authentic address collection and related to the case.
¶ Data in message
Various data relating to citizens or organizations can be exchanged in the message. The integration uses different address roles for this.
| has as initiator ZAKBRTINI | Relationship with the initiator of the case - the applicant (address role ‘Initiator’) |
|---|---|
| has as Agent ZAKBRTGMC | Relationship with the representative of the case (address role ‘Authorized representative’) |
| has ZAKBRTBLH as the interested party | Relationship with the interested party of the case (address role ‘Interested party’) |
| has As Other Involved ZAKBRTOVR | Relationship with other parties involved in the case (address role ‘Other’) |
| Natural person NPS.inp.bsn | Information about the relationship - a BSN is sufficient to make a link with an existing address. The following Natural Person fields are stored in the business warehouse when it is not possible to create the relationship with a citizen from the data warehouse. BSN Last name Prefix Gender Name Initials First names Gender Designation Residence address details Place of residence name Street name Postal Code House number HouseLetter HouseNumberAddition |
| Not natural person NNP.inn.nnpId | Information about the relation - an nnp Id (RSIN / SofiNumber) is sufficient to be able to make a link with an existing address. The following fields of an Not Natural Person are stored in the business warehouse when it is not possible to create the relationship with an organization from the data warehouse. Nnp.Id (RSIN / SofiNumber) Registered name visiting address City name Street name Postal Code House number HouseLetter House number Addition |
| Establishment VES location number | Information about the relationship - a location number is sufficient to be able to make a link with an existing address. The following fields of a location are stored in the business warehouse when it is not possible to create the relationship with an organization from the data warehouse. Establishment number Trade name visiting address City name Street name Postal Code House number HouseLetter House number Addition |
| Organizational unit OEH | |
| Collaborator MDW |
From version 2020.9, organizations / social activities have support for a Chamber of Commerce number (Trade register number). The used entities NNP and VES do not have a standard field for a Chamber of Commerce number. In practice, some affiliated suppliers use the Nnp.Id for the Chamber of Commerce number.
¶ Address data
How the data of an address are processed in JOIN Case & Document is described in the functional description of the StUF-BG integration.