📜 Event Log to DECLARE JSON Generator

The Event Log to DECLARE JSON Generator is a Rust-based application that processes event logs in XES format to discover underlying process constraints. It first identifies temporal and existential dependencies between activities, constructs a dependency matrix, and then translates this matrix into a DECLARE model, outputting it in a structured JSON format.

This tool offers both an interactive web-based user interface (built with Yew and WebAssembly) for easy experimentation and a command-line interface (CLI) for batch processing and integration into automated workflows.

You can find a live demo of the web application at https://insm-tum.github.io/event-log-to-declare-json/

✨ Features

• Import XES files for process analysis.
• Generate DECLARE models in JSON format based on discovered dependencies from the event log.
• Support for various DECLARE templates: Includes Init, End, RespondedExistence, Coexistence, Response, Precedence, Succession, ChainResponse, ChainSuccession, ChainPrecedence, NotCoexistence, and NotResponse.
• Adjustable thresholds (0.0-1.0) for temporal and existential dependency discovery, allowing fine-tuning of the constraint mining process.
• Interactive web interface for easy file uploading, threshold adjustment, and immediate viewing/copying of the generated DECLARE JSON.
• Command-Line Interface (CLI) for automated conversion of XES logs to DECLARE JSON.

🚀 Repository Overview

├── .github/workflows
│ └── continuous_deployment.yml # GitHub Actions for deploying the web app
├── src
│ ├── declare_translation.rs # Core logic for translating dependency matrix to DECLARE JSON
│ ├── dependency_types # Defines and discovers temporal/existential dependencies (reused)
│ │ ├── dependency.rs
│ │ ├── existential.rs
│ │ └── temporal.rs
│ ├── matrix_generation.rs # Generates dependency matrices from traces (reused)
│ ├── parser.rs # Parses XES files into structured traces (reused)
│ └── main.rs # Entry point for Web UI (Yew) and CLI (Clap)
├── Cargo.toml # Project dependencies and metadata
└── index.html # HTML entry point for the Yew web application

• src/declare_translation.rs: Contains the matrix_to_declare_model() function. This is the core module that applies a set of predefined rules to translate the discovered temporal and existential dependencies (from the matrix) into DECLARE constraints (e.g., Response, Precedence, Coexistence).
• src/matrix_generation.rs: Implements generate_dependency_matrix(), which takes parsed traces and thresholds to build the activity dependency matrix. This matrix serves as the input for the DECLARE translation.
• src/dependency_types/: Modules defining and discovering temporal and existential relationships between activity pairs based on trace occurrences and user-defined thresholds.
• src/parser.rs: Provides parse_into_traces() to read XES files and convert them into a list of activity sequences, which is the basis for dependency discovery.
• src/main.rs: Orchestrates the application, handling CLI arguments via clap or launching the Yew web application for interactive use.
• results/: This directory contains example DECLARE JSON files generated by the tool from various event logs, showcasing the expected output format.

🔧 Prerequisites

• Rust and Cargo: Install from rustup.rs

• Trunk (for Web UI development/local serving): A WASM web application bundler for Rust.

  cargo install trunk
  rustup target add wasm32-unknown-unknown

  🚀 Getting Started

1. Clone the repository

git clone https://github.com/INSM-TUM/event-log-to-declare-json.git
cd event-log-to-declare-json

2. Start the web application (Optional)

If you wish to use the web interface locally:

trunk serve

Then, open your web browser and navigate to http://localhost:8080/automated-process-classification/.

Tips:

• Use trunk serve --open to automatically open in your default browser
• Specify a custom port with trunk serve --port 1234

3. Use the Command-Line Interface (CLI)

The application can be run directly from the command line.

First, ensure the project is built (cargo run will do this automatically):

cargo build --release # Optional, for optimized binary

To run the CLI (examples):

# Using cargo run (compiles if needed):
# To pass arguments to the binary via 'cargo run', use '--'
cargo run -- --file-path path/to/your/log.xes

# Using the compiled binary (from target/release/ after `cargo build --release`):
./target/release/declare_json_generator --file-path path/to/your/log.xes

For a complete list of CLI options and their descriptions:

cargo run -- --help

📋 Usage Guide

Web Interface

1. Upload XES File: Click the "Upload XES File" button (or the input field) and select an .xes file from your local system. The name of the selected file will appear.
2. Set Thresholds (Optional):

• Temporal Threshold (0.0-1.0): Adjust this value to control the sensitivity of temporal dependency detection. A higher value means a temporal relationship must be observed more consistently across traces to be considered. Default is 1.0.
• Existential Threshold (0.0-1.0): Adjust this value for existential dependency detection. Similar to the temporal threshold, it sets the minimum consistency required. Default is 1.0.
• These thresholds should be set before clicking "Process Log". Invalid inputs (outside 0.0-1.0) will highlight the input box in red and disable the process button.

3. Process Log: Once a file is selected and thresholds are valid, click the "Process Log" button.
4. View Classification: The application will process the log and display the generated DECLARE model in JSON format in a textarea. You can then copy this JSON for use in other tools, for example declare-js.

Command-Line Interface (CLI)

The CLI is suitable for batch processing or integrating the DECLARE model generation into scripts. The output DECLARE JSON is printed to standard output, allowing for easy redirection to a file.

Basic Classification: To convert an event log to DECLARE JSON with default thresholds (1.0 for both):

cargo run -- --file-path /path/to/your/event_log.xes
# or
# ./target/release/declare_json_generator --file-path /path/to/your/event_log.xes

Specifying Thresholds: You can override the default temporal and existential thresholds:

cargo run -- --file-path log.xes \
             --temporal-threshold 0.85 \
             --existential-threshold 0.90

Getting Help: For a full list of available commands and options:

cargo run -- --help
# or
# ./target/release/matrix_classifier --help

📝 DECLARE Translation Rules

The conversion from the discovered dependency matrix to DECLARE constraints is based on a set of predefined rules implemented in src/declare_translation.rs. Here's a summary:

1. Init(a): If activity a is eventually followed by all other activities b (i.e., a ≺e b for all b != a), and a has a temporal dependency with all other activities.
2. End(a): If activity a is eventually preceded by all other activities b (i.e., b ≺e a for all b != a), and a has a temporal dependency with all other activities.
3. RespondedExistence(a,b): If (a,b) has (-, =>Fwd), meaning no specific temporal dependency, but a implies b existentially.
4. Coexistence(a,b): If (a,b) has (-, <=>Both), meaning no specific temporal dependency, but a and b are existentially equivalent.
5. Response(a,b): If (a,b) has (≺e Fwd, =>Fwd), meaning a is eventually followed by b, and a implies b existentially.
6. Precedence(a,b): If (a,b) has (≺e Fwd, <=Bwd), meaning a is eventually followed by b, and b implies a existentially.
7. Succession(a,b): If (a,b) has (≺e Fwd, <=>Both), meaning a is eventually followed by b, and they are existentially equivalent.
8. ChainResponse(a,b): If (a,b) has (≺d Fwd, =>Fwd), meaning a is directly followed by b, and a implies b existentially.
9. ChainSuccession(a,b): If (a,b) has (≺d Fwd, <=>Both), meaning a is directly followed by b, and they are existentially equivalent.
10. ChainPrecedence(a,b): If (a,b) has (≺d Fwd, <=Bwd), meaning a is directly followed by b, and b implies a existentially.
11. resp_absence(a,b): If (a,b) has (-, NAND), meaning no specific temporal dependency, but a and b have a NAND existential relationship. (Note: The UI/CLI output uses resp_absence as the template name based on the code).
12. NotCoexistence(a,b): If (a,b) has (-, NegatedEquiv), meaning no specific temporal dependency, but a and b have a Negated Equivalence existential relationship.
13. NotResponse(b,a): If the dependency for pair (a,b) is (≻e Bwd, -), meaning b is eventually followed by a (temporal backward for a,b), and there is no existential dependency. The DECLARE constraint is then NotResponse(Target, Activation), which translates to NotResponse(b,a) using the rule's parameters.

(Note: Fwd means Forward, Bwd means Backward, ≺e means eventual precedence, ≺d means direct precedence, ≻e means eventual succession. Existential symbols: => Implication, <=> Equivalence)

📄 Sample Output (DECLARE JSON)

The tool generates DECLARE models in JSON format. Here's a snippet from one of the examples in the results/ directory (results/2.json):

{
  "name": "event-logs/event_log_2_DeclareModel",
  "tasks": [
    { "name": "a" },
    { "name": "b" },
    { "name": "c" },
    { "name": "e" }
  ],
  "constraints": [
    {
      "template": "CoExistence",
      "parameters": [["b"], ["c"]]
    },
    // ... other CoExistence constraints
    {
      "template": "End",
      "parameters": [["e"]]
    },
    {
      "template": "Init",
      "parameters": [["a"]]
    },
    {
      "template": "Precedence",
      "parameters": [["a"], ["e"]]
    },
    // ... other Precedence constraints
    {
      "template": "Succession",
      "parameters": [["a"], ["b"]]
    }
    // ... other constraints
  ]
}

Dependency	Purpose
Yew	Modern Rust framework for front-end web apps using WebAssembly
wasm-bindgen	High-level interactions between Rust and JavaScript
web-sys	Bindings for Web APIs
process_mining	Process mining library for Rust
clap	A popular and feature-rich command Line Argument Parser for Rust.
serde	A framework for serializing and deserializing Rust data structures efficiently.

📜 License

This project is licensed under the MIT License. See the LICENSE file for details.

👏 Acknowledgments

• Thanks to the contributors of the Rust and Yew communities for their support and tools