////
  // Copyright (c) 2021, 2026 Contributors to the Eclipse Foundation
  //
  // This program and the accompanying materials are made
  // available under the terms of the Eclipse Public License 2.0
  // which is available at https://www.eclipse.org/legal/epl-2.0/
  //
  // SPDX-License-Identifier: EPL-2.0
////

include::_initCommon.adoc[]

== Conformance Check

Conformance checking functionality is used to check whether traces from log files are able to be projected to a certain dispatching.

=== Add Trace Point

Before conducting a conformance check, trace points are supposed to be added to activity specifications. Trace points, logged in _trace_ log files, are used to identify the starting and end points of an event. An example of log file is given below. Each line in a log file contains all the information of time and a trace point.

TIP: By default, log files with an extension `trace` are supported for conformance checking.
A trace file is line based where each line starts with an  instant in UTC (i.e. parsed using https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html#ISO_INSTANT[DateTimeFormatter.ISO_INSTANT^]), followed by comma-space and then the trace point.

---- 
include::{codedir}/tutorial.trace[]
----

In the first line, “TP-0001” is the string identifying the trace point in principle which is unique throughout the entire log files. 

Additionally, there must be a trace point specification, which maps a trace point to either a starting or an end point of a known action. For instance, _TP-0001_ maps to _start claiming Robot_. In order to perform conformance check, trace points are supposed to be added to its related activity specification surrounding an action definition.

---- 
include::{codedir}/tutorial_tp.activity[lines=10..1000]
----

<1> *["TP-0001"]* and *["TP-0002"]* represent starting and end points for claiming a Robot.

=== Conduct Conformance Check

After adding all the trace points to an activity specification, conformance check can be applied upon a dispatching file.

NOTE: Dispatching offset is not supported for conformance check currently.

Right click on a dispatching file and select _Run Conformance Check_. 

image::{imgsdir}/conformance.png[]

Note that in order to obtain a successful conformance check based on the above activity file, the dispatching file look like:
  
---- 
include::{codedir}/tutorial_tp.dispatching[lines=10..1000]
----

Select _trace_ files to run the conformance check, and _Next_.

image::{imgsdir}/conformance_traces.png[]

There are several configurations for conformance check.

image::{imgsdir}/conformance_option.png[]

[horizontal]
Activity dispatching:: Selected, if it activity dispatching occurs multiple times in log files.
Conformance level:: There are three levels for conformance check. +
*Minimal* - only recognized trace points are kept for conformance check. It will pass, as long as it find one valid projection. +
*Claim* - based on minimal level, all trace points for the claimed resources are used for conformance check. +
*Dispatching* - most strict conformance check, it requires all the recognized trace points in log files are perfectly matched, even before claiming and after releasing a resource.

Set conformance check options and _Finish_. The conformance check will be executed.

After the progress is completed, a pop-up will appear to show whether or not it passes the conformance check.

image::{imgsdir}/conformance_pass.png[]

image::{imgsdir}/conformance_failure.png[]

If a conformance check fails, a _petrinet_ file will be generated under the folder  _analysis/conformance_. It is used to diagnose conformance check failure.


In order to open a graphical view of a Petri Net, a new viewpoint needs to be added to the project.

image::{imgsdir}/image29.png[]
image::{imgsdir}/analysis_viewpoint.png[]

TIP: If the Analysis viewpoint is not visible, please restart your Eclipse using menu:File[Restart].

Navigate to a Petri Net model element to open an existing graphical view or right click it to create a new one.

image::{imgsdir}/petri_open.png[]

A graphical view is opened.

image::{imgsdir}/petri_net.png[]

The Petri Net shows how the trace lines are projected upon it.

*Black Bar* - it represents a trace point transition. A green arrow on top indicates this trace point transition has been passed. +
*Gray Bar* - it represents a transition doesn't require a trace point check. +
*Red Bar* - it represents an armed transition with a certain trace point is expected. Usually, it is a place where an error occur. +
*Yellow Circle* - it represents an action as a place. +
*Gray Circle* - it is a place to connect two transitions, if there is no action in between. +
*Blue Token* - it indicates where the conformance check stops.

=== Filter Trace Point
Filtering out irrelevant trace points in log files is not required for conformance check. However, it helps to reconstruct activities manually, especially when the amount of irrelevant trace points is much more than the relevant ones. Before filtering, activity specification should be inserted with trace points.

Right click log files and select _Filter traces_.

image::{imgsdir}/filter_tp.png[]

Select _Activity_ elements which contain all the relevant trace points and continue with _OK_.

image::{imgsdir}/filter_window.png[]

After filtering, selected log files will only keep the trace points which are used in activities.
