Skip to content

Commit

Permalink
Add files via upload
Browse files Browse the repository at this point in the history
  • Loading branch information
@MarkMulderTeec2
MarkMulderTeec2 authored May 23, 2024
1 parent da30380 commit 5afd224
Showing 1 changed file with 2 additions and 343 deletions.
345 changes: 2 additions & 343 deletions docs/visi1.7/VISI.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15335,347 +15335,6 @@ message. To prevent this, it has been stated that in
2. enumeration (UserDefinedTYpe) non-ascii characters must be displayed
correctly

# 1.8 additions

All issues have been described by their respective number in
https://github.com/nl-digigo/visi/issues/\<nr\>

## Theme 1: Special Fields

### Sequence fields (#50)

UDT met format (geen vaste naam)\
velden die uit psb komen worden in software geregeld\
Voorstel schrijven voor raamwerk standaard.\

<figure id="lst:Volgnummer">
<pre><code> &lt;UserDefinedType id=&quot;Udt_transaction_sequence&quot;&gt;
&lt;description&gt;Transaction Sequence&lt;/description&gt;
&lt;state&gt;active&lt;/state&gt;
&lt;dateLamu&gt;2024-04-05T00:00:00&lt;/dateLamu&gt;
&lt;userLamu&gt;xyz&lt;/userLamu&gt;
&lt;baseType&gt;SEQUENCE&lt;/baseType&gt;
&lt;xsdRestriction&gt;&amp;lt;xs:pattern value=&quot;{organisation.id:3}_{sequence_x:08}&quot;/&amp;gt;&lt;/xsdRestriction&gt;
&lt;/UserDefinedType&gt;</code></pre>
<figcaption>Sequence user-defined type</figcaption>
</figure>

A sequence is a way to assign increasing numbers to a field. The
xsdRestriction field is used to define the format of the sequence
number. {variable} can be used in the pattern value to target the known
information A list of supported variables is listed below.

::: {#tab:Variables for sequences}
Variable part Description
-------------- ------ -------------------------------------------------------------------
sequence_x The name of the sequence that is used for this User Defined Type.
organisation The organisation in the configuration.
id The id of the organisation
project The project

: Variables for sequences
:::

After the variable, a semicolon can be placed to indicate the length of
the previous variable. When the length is preceded by a 0, zeros will
precede the result until the size has been reached, e.g. {number:5}
would give '123' where {number:05} would give '00123'. Whether the
variable is a string or a number doesn't matter for the framework
builder. A variable that contains a period '.' refers to the
sub-variable within that structure. Sequences do not have sub-variables.

Sequences kunnen afhankelijk zijn van wie hem start. Er is dus een
sequence van een organisatie. Dat moet gekoppeld worden aan de sequence
naam.

Sequence definieren in PSB zodat het overgezet kan worden naar een nieuw
project? Prefixen in PSB toevoegen.

Seq in Archive? Beginnen bij 1. Startwaarde in Raamwerk? Seq die niet
bestaat of lager is dan bestaande nummer mag je aanmaken met
startwaarde. Aanpassen van het nummer in software. Logging van het
aanpassen van nummers in de software.

--$>$ Kan er een subsequence op basis van een andere sequence gedaan
worden? Dat een wijziging die niet helemaal goed is een nieuw
versienummer kan hebben. De ophoging zou gaan per bericht types. $<$--

### Reaction Date (#150)

datum waarop het volgende bericht verstuurd moet zijn. Is nu niet in
raamwerk Standaard instelling van aantal dagen vanaf verzenden. Voorstel
schrijven voor raamwerk standaard reactiedatum moet optioneel zijn
(laatste bericht altijd ongewenst)

## Theme 2: DEMO

### DEMO transaction pattern (#60) research

VISI originated from DEMO in the early stages. For acceptance of
implementation some concepts of DEMO were lost. These DEMO concepts
allow for easier and completer modelling of business processes. The
compact DEMO models of the organisation's essence are the base for fully
implementing the business processes with VISI frameworks. With version
1.8, we want to return to the possibility of including complete DEMO
transactions. The option to include the DEMO transaction pattern has
initiated the option to release the 'ping-pong' requirement of the VISI
standard because, in DEMO, some steps in a transaction have message
sequences from the same sender. To explain the concept, we have to
introduce the terms message-from and message-to. A message sent from the
initiator to the executor (with the attribute InitiatorToExecutor =
true) is called message-from. A message that is sent from the executor
to the initiator (InitiatorToExecutor = false) is called message-to.

In VISI, a Mitt can have a previous Message. Another concept is the
reverse term of previous: next. Every previous pointer of message B to
message A has an equivalent next pointer from message A to message B.
Where the first message of a transaction has no previous pointers, the
final message of a transaction has no next pointers. We assume that the
'next' value is calculated out of 'previous' values, and not stored in
the framework.

We need these 'message' and 'next' concepts to clearly state the rules
of the communication protocols 1.7 and 1.8.

For the 1.0-1.7 version protocol, the from and to messages were sent
alternating between the initiator and executor, 'ping-pong'. Currently,
the messages have to comply with the following rules.

- Every transaction starts with a 'from' message.

- Every from-message will have next pointers to to-messages when
having a next pointer.

- Every to-message, when having a next pointer, will have next
pointers to from-messages.

$<$ insert picture to show current communication $>$

For the 1.8 version protocol, the from and to messages can still be sent
alternating, but an alternative is allowed.

- Every transaction starts with a 'from' message.

- All messages except the last message can contain a next message
pointer. VISI has a clear overview of which party in a transaction
is responsible at a certain step in the transaction. To keep
facilitating this, a message with a next message pointer can only
contain a to-message or a from-message, not a mixed variant. See the
left illustration of [112](#fig:visiPattern){reference-type="ref"
reference="fig:visiPattern"}.

- Next pointers (and, therefore, previous pointers) may point to the
same message. This self-reference can *only* be when another next
pointer is pointing to a follow-up message. The last message cannot
only point to itself; otherwise, a loop without escape is created.

Frameworks that do not adhere to these rules will be rejected. In old
versions default handling of behaviour was applied by software vendors,
since this wasn't part of the standard software vendors created their
own solutions. From version 1.8 onwards, we will not accept faults in
the framework. There is no need for a default handling option when the
framework does not comply because it will be rejected. As stated in the
second item above, to retain the clear responsibility order, it is still
only possible for a single side to send a message. While not revoking a
message (see [10.2.2](#sec: Revoke Message){reference-type="ref"
reference="sec: Revoke Message"}), the other side cannot message at the
same time.

In handling the message, this has some consequences. The receiving party
can not handle messages that have a next pointer to the same message
type. The message can only be shown to the receiver but not acted upon.
This enables both parties to stay up to date with the progress of the
transaction. The next message, when the next pointer is the alternate
message type, will replace the last message and then can be handled.
When sending a message, the message that has been handled should stay as
an active message because it needs to be handled again (see
[111](#fig:nextMessageExampleWIP){reference-type="ref"
reference="fig:nextMessageExampleWIP"}). This changes the way people
perceive messages in an inbox style.

![WIP. Next message
example](images/visi next message example WIP.png){#fig:nextMessageExampleWIP
width=".5\\textwidth"}

With this new communication protocol, it is possible to implement the
DEMO [CTP]{acronym-label="CTP" acronym-form="singular+short"}.

$<$Insert CTP image $>$

The [CTP]{acronym-label="CTP" acronym-form="singular+short"} has a
'promise' message, followed by a 'declare' message. These two
to-messages can now be implemented in the communication protocol and in
the handling of messages. This is a possible pattern, but it is not
limited to this use.

![Possible patterns in VISI 1.8](images/VisiDemo4.png){#fig:visiPattern
width="\\textwidth"}

As can be seen in [112](#fig:visiPattern){reference-type="ref"
reference="fig:visiPattern"}, the VISI pattern has expanded. The
to-messages are in blue; the from-messages are in red. The left sequence
of messages will not be accepted because the two next pointers from the
promise go to different message types. The right picture shows the
typical DEMO flow (except the picture says refuse instead of reject),
with two consecutive messages in red. The middle flow shows a way to
model a repeating promise that can be used to update the requesting
organisation on progress. The double promise in the middle picture is
not needed when the promise has a pointer to itself (the image was made
in the 1.6 version of VISI software). This would be represented by an
arrow back to the Mitt itself. Specific updates or progress situations
can be modelled with a self-pointer to the Mitt. Also, forms that need
to be filled in the course of time and completed at a final moment (and
ability to handle the message is sent to the other party) can be
modelled.

![Optional and required
promise](images/VisiDemo2.png){#fig:promiseOptional
width=".5\\textwidth"}

In [113](#fig:promiseOptional){reference-type="ref"
reference="fig:promiseOptional"}, we can see that the promise can be
modelled optional (left) and required (right) in the framework.

promise: graag wel in raamwerk aangeven dat promise erin mag zitten want
raamwerken zonder deze setting willen we kunnen weigeren omdat 2x ini
dezelfde ini to exe willen we dan kunnen afkeuren bij \"normale
raamwerken\"

substransactie invloed beschrijven.

### Revoke Message (#76) {#sec: Revoke Message}

There are special transactions that allow for revokes. The first revoke
transaction has the default ID 'Revoke'. This transaction is linked to
the 'Revoke' role. A start message has a transaction Phase 'revoke'. A
random follow-up message must have the transaction Phase 'allow'. A
random follow-up message must have the transaction Phase 'refuse'. The
three transaction phases, 'revoke', 'allow', and 'refuse', have to have
hard-coded names that are present in every framework. If these phases
are not present, the revoke option is not available. Missing revoke
patterns do not lead to framework rejection.

When a revoke is issued, the user can say to which step the revoke has
to be executed. The allowed steps can be traced in the framework by
finding the previous Mitts with the 'Revoke allowed' set to true. This
information has to be added to the message in a simple element type.

The reasons for revoking the message can be added in complex elements
and need to be addressed to the receiver.

Every Mitt has these extra attributes.

- $<$Revoke allowed$>$ (default: true)\
This is a flag to indicate whether the revoke option has to be
enabled on this Mitt.

- $<$Revoke to Mitt$>$ (default: previous)\
The next message to be handled is, by default, the previous message,
but cases have been found that earlier messages need to be
addressed.

- $<$Revoke Pattern$>$ (default: reference to default revoke
transaction)\
If this option is not given, the revoke with ID revoke is chosen. A
different revoke pattern can be specified in this attribute.

- $<$Revoke Undo Mitt$>$ (default: nothing)\
This is the Mitt that needs to be executed to undo things in case of
a revoke.

Subtransactions that have been started from a message that is revoked
can be revoked by the user itself. These subtransactions can be listed
but need not be automatically cascaded. The steps that have been
executed but will revoked, and now the subtransaction that had been
started are running independently and cannot be used to answer the
revoked message anymore. The flow has been split into two.

When a first message is revoked, an empty transaction is available where
no message is sent. The revoke must allow for a new first message or
cancel everything. How can we cancel a transaction? Is it necessary?

Does a revoke pause the whole transaction? This reduces the simultaneous
messages. What if the revoke and the next step arrive simultaneously?
Which message is leading? The revoke always wins the message flow.

vb: Revoke request met lange transactie en substransacties? Moeten er
voor elk bericht een undo bericht zijn zodat we ook een hele keten
automatisch kunnen intrekken? Is dit te modelleren door mensen en kan de
software dit volgen? Juridisch checken met: Instituut voor bouwrecht:
hoogleeraar Delft: Evelien Bruggeman.

Hoe kun je revoken in de software? Wat is de standaard en wat is
software. Hoe lang mag je na versturen nog een oops doen?

Use case: Kun je een document dat geaccepteerd is vervangen door een
nieuwe versie? Als je dan teruggaat naar een firstmessage, moet je dan
al een nieuwe aanvraag indienen om de revoke te ondersteunen? Kun je het
bericht meesturen als tijdelijke visi attachment en daarna, bij allow,
het bericht alsnog automatisch versturen. Dit is niet verplicht in de
systematiek en wordt te complex om te bewijzen dat het gelijke
berichten.

## Theme 3: VISI export

### archief structuur (#72)

Structuur aanpassen Soap berichten gaan een-op-een het archief in
Controle of het archief correct is (transacties (volgnummer), berichten,
bijlagen in een XML) Controle of visi na inlezen nog hetzelfde is
(checklist)

Sequence opnemen in het archief Extra bestand met sequence nummers van
het raamwerk. JSON.?

### confirmations(#67)

Bevestigingen en Errors ook opslaan in het archief

### mappen (#70)

Berichten moeten een volgnummer hebben om de tijden kwijt te zijn.

bij de issues 72 en 151 staat 'behouden', maar die zijn toch
ramdvoorwaarde om 67 en 70 te kunnen doen? Moeten ze dan niet alle 4 in
1.8 worden opgelost? 15:50

## Theme 4: Promotor

### Nieuwe promotor (#55)

Regels opschrijven die de promotor uitvoert om een XSD te maken XSD is
een makkelijke standaard (maar niet compleet) XSD geeft niet duidelijke
errors Performance is niet goed met XSD vanuit de promotor Een centrale
bericht validator

Door foutmeldingen goed te doen wordt een externe validator overbodig.

Promotor regels uitschrijven.

### raamwerk validator (#10)

Is inmiddels geschreven door TEEC2

### REST (#148)

Communicatie aanpassena aan REST Confirmatie wordt een direct antwoord
op een bericht.

Er zou een rest service moeten zijn die gewoon berichten moet kunnen
ontvangen vanuit software die niet een volledig visi raamwerk
implementeren.

### TestServer

onderzoeken hoe we testen gaan doen onderling met sofware leveranciers.

## Theme 5: Versioning

### Open processes

Ondersteunen van oude raamwerken en de overgang naar nieuwe versies van
het raamwerk

# Index

## Terms defined by this specification
Expand Down Expand Up @@ -15743,7 +15402,7 @@ Role that initiates a transaction.

### Interaction Diagram (Interactiekaart)

See [12.0.25](#glos:VISI-InteractionDiagram){reference-type="ref"
See [11.0.25](#glos:VISI-InteractionDiagram){reference-type="ref"
reference="glos:VISI-InteractionDiagram"}.

### Project Specific Framework (Projectspecifiek raamwerk)
Expand All @@ -15765,7 +15424,7 @@ Promoter is made available by CROW.
### Framework (Raamwerk)

Is used in this context in the sense of 'VISI framework'; see
[12.0.28](#glos:VISI-Framework){reference-type="ref"
[11.0.28](#glos:VISI-Framework){reference-type="ref"
reference="glos:VISI-Framework"}.

### Role Description (Rolbeschrijving)
Expand Down

0 comments on commit 5afd224

Please sign in to comment.