Deeplinks customizen

Allgemeines

Mit Deeplinks in PLANTA project lassen sich benutzerdefinierte Aktionen direkt über eine URL ausführen. So können Benutzer beispielsweise aus einer E-Mail heraus unmittelbar auf ein verlinktes Modul zugreifen – ganz ohne manuelle Navigation im System.

Technische Implementierung

Voraussetzung

• Erstellung einer benutzerdefinierten Klasse, die von BaseProtocolAction erbt.

Vorgehensweise

• Eine Klasse definieren,

  • hierfür eine Unterklasse von ppms.protocol.BaseProtocolAction erzeugen,

• execute()-Methode implementieren,

• auf URL-Parameter zugreifen,

  • self.path_parameters für Pfadsegmente und

  • self.query_parameters für Query-Strings.

Beispiel

from ppms.protocol import BaseProtocolAction, get_any_module_object

class OpenCustomerModuleAction(BaseProtocolAction):
    def execute(self):
        module = get_any_module_object()
        module.open_module('100000')

Hinweis

• Speichere die Klasse z. B. in customer/protocol.py.

Deeplinks erstellen

Vorgehensweise

• Im Modul Deeplink einen neuen Eintrag erstellen:

  • Aktion auf eine benutzerdefinierte URL setzen (z. B. /special_module),

  • Python-Funktion auf den Pfad zu Ihrer Python-Klasse setzen (z. B. customer.protocol.OpenCustomerModuleAction),

  • Häkchen in der Checkbox Aktiviert setzen,

  • Python-ID definieren, um später auf diesen Deeplink verweisen zu können.

• Nach der Einrichtung öffnet ein Aufruf von <planta-web-client>/special_module das Modul 100000.

Pfad- und Query-Parameter

Information

• PLANTA-Deeplinks unterstützen sowohl Pfadparameter als auch Query-Parameter. Beide können zur Filterung oder zur Navigation in verschachtelten Hierarchien verwendet werden.

Pfadparameter

Details

• Wird verwendet, um hierarchische Ressourcen übersichtlich darzustellen.

• Pfadparameter kann direkt in der Deeplink-URL in spitzen Klammern < > definiert werden:

  • z.B.: project/<pr_id>.

    • Verwendung des RESTful-URL-Designs.

Query-Parameter

Details

• Wird für optionale Filter oder zusätzliche Modifikatoren verwendet.

• Automatische Verfügbarkeit, ohne dass ein Query-Parameter explizit definiert werden muss:

  • z.B.: project/4711?foo=bar

• Die Flexibilität kann auch zu längeren URLs führen.

Fehlerbehandlung

Hinweis

• Wenn ein Benutzer versucht, auf einen nicht existierenden Deeplink zuzugreifen, wird eine Fehlermeldung angezeigt (Textkonstante 002502). Deeplink-Aktionen müssen ungültige Benutzereingaben in ihrer Implementierung entsprechend behandeln.

Deeplink Generator Makro (009DWK)

Information

• Das Makro 009DWK erzeugt dynamisch Deeplinks basierend auf Datensatzwerten.

• Die Konfiguration erfolgt über den Parameter DF-Konfiguration (df_script_settings) mit dem Schlüssel DeeplinkGenerator.

• Es muss entweder python_id (Verweis auf einen Deeplink-Datensatz) oder url (direktes URL-Template) angegeben werden – nicht beides.

• Pfad-Platzhalter werden in path_params, Query-String-Werte in query_params definiert.

• Jeder Parameter enthält entweder field (dynamischer Wert aus aktuellem Datensatz) oder value (statischer Wert).

Konfigurationsbeispiele

Minimales Beispiel (URL-Template)

{
  "DeeplinkGenerator": {
    "url": "/project/<pr_functional>/",
    "path_params": {
      "pr_functional": {
        "field": "fachliche_id"
      }
    }
  }
}

Dynamische und statische Pfadparameter

{
  "DeeplinkGenerator": {
    "url": "/project/<pr_functional>/view/<module>",
    "path_params": {
      "pr_functional": {
        "field": "fachliche_id"
      },
      "module": {
        "value": "terminplan"
      }
    }
  }
}

Query-Parameter

{
  "DeeplinkGenerator": {
    "url": "/booking/<booking_id>/modify",
    "path_params": {
      "booking_id": {
        "field": "uuid"
      }
    },
    "query_params": {
      "hours": {
        "field": "load_act"
      },
      "comment": {
        "value": "Das war ein gutes Meeting"
      }
    }
  }
}

Referenz über python_id

{
  "DeeplinkGenerator": {
    "python_id": "planning_dashboard",
    "path_params": {
      "pr_id": {
        "value": "000008"
      }
    }
  }
}

Bei Verwendung von python_id wird die URL aus dem referenzierten Deeplink-Datensatz ermittelt. Ändert sich die Route, muss nur der Datensatz aktualisiert werden – alle DF-Konfigurationen, die darauf verweisen, bleiben unverändert.

Kombination mit ButtonConfiguration

{
  "ButtonConfiguration": {
    "type": "Primary",
    "size": "Default",
    "content": "IconLabel",
    "danger": false
  },
  "DeeplinkGenerator": {
    "python_id": "planning_dashboard",
    "path_params": {
      "pr_id": {
        "field": "fachliche_id"
      }
    },
    "query_params": {
      "comment": {
        "value": "Das war ein gutes Meeting"
      }
    }
  }
}

Hinweise

Hinweise

• Pfadparameter (< >) müssen korrekt im URL-Template definiert und im Datensatz vorhanden sein, wenn sie dynamisch gelesen werden.

• Query-Parameter eignen sich für optionale oder flexible Werte.

• Das JSON-Format koexistiert mit anderen DF-Konfigurationsabschnitten wie ButtonConfiguration.

• Bei Verwendung von python_id genügt eine Anpassung des Deeplink-Datensatzes, wenn sich die Route ändert.

Deeplink API

Information

• Deeplinks können programmatisch über die Hilfsfunktionen in ppms.protocol.deeplink erzeugt und angezeigt werden.

Modulimport

from ppms.protocol.deeplink import (
    build_deeplink_url,
    copy_deeplink_url,
    build_and_copy_deeplink_url,
)

Verfügbare Funktionen

Beispiel

url = build_deeplink_url(
    python_id="planning_dashboard",
    path_params={"pr_id": "000008"},
    query_params={"tab": "details"},
)
copy_deeplink_url(url)

Implementierungsdetails

DF-Konfiguration des Makros 009DWK

Verarbeitungsreihenfolge beim Parsen der Konfiguration

1. Die Konfiguration wird als JSON geparst.

2. Enthält das JSON-Objekt den Schlüssel DeeplinkGenerator, wird dieser als Deeplink-Konfiguration verwendet.

3. Ist das JSON gültig, enthält aber keinen DeeplinkGenerator-Schlüssel, schlägt das Parsing fehl.

4. Ist der Text kein gültiges JSON, wird auf das Legacy-Zeilenformat zurückgefallen.

Legacy-Zeilenformat

Das ältere zeilenbasierte Format bleibt für Abwärtskompatibilität erhalten:

• Erste Zeile: URL-Template mit Pfad-Platzhaltern oder die python_id eines Deeplink-Datensatzes.

• Nachfolgende nicht-leere Zeilen: Parameter-Zuordnungen gemäß folgender Syntax:

Beispiel: Pfadparameter aus Datenfeld

/project/<pr_functional>/
pr_functional:fachliche_id

Beispiel: Dynamische und statische Query-Daten

/booking/<booking_id>/modify
booking_id:uuid
?hours:load_act
?comment=Das war ein gutes Meeting

Beispiel: Referenz über python_id

planning_dashboard

pr_id=000008