Customize Deeplinks

General

Deep links in PLANTA project allow you to execute user-defined actions directly via URL. For example, users can access a linked module directly from an email—without having to manually navigate the system.

Technical Implementation

Requirement

• Creation of a user-defined class that inherits from BaseProtocolAction.

Procedure

• Define a class by

  • generating a subclass of ppms.protocol.BaseProtocolAction,

• implement the execute() method,

• access URL parameters,

  • self.path_parameters for path segments and

  • self.query_parameters for query strings.

Example

from ppms.protocol import BaseProtocolAction, get_any_module_object

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

Note

• Save the class, e. g. in customer/protocol.py.

Create Deeplinks

Procedure

• Create a new entry in the Deeplink module:

  • Set action to a user-defined URL (e.g. /special_module),

  • Set the Python function to the path to your Python class (e.g. customer.protocol.OpenCustomerModuleAction),

  • Set a checkmark in the Activated checkbox,

  • Define a Python ID to be able to reference this deeplink at a later point.

• After setup, calling up <planta-web-client>/special_module opens module 100000.

Path and Query Parameters

Information

• PLANTA deeplinks support both path parameters and query parameters. Both can be used for filtering or navigating nested hierarchies.

Path Parameter

Details

• Used to clearly display hierarchical resources.

• Path parameters can be defined directly in the deep link URL using angle brackets < >:

  • e.g.: project/<pr_id>.

    • Using the RESTful URL design.

Query Parameter

Details

• Used for optional filters or additional modificators.

• Automatic availability without having to explicitly define a query parameter:

  • e.g.: project/4711?foo=bar

• The flexibility may also lead to longer URLs.

Error Handling

Note

• If a user attempts to access a non-existent deep link, an error message is displayed (text constant 002502). Deeplink actions must treat invalid user input respectively in their implementation.

Deeplink Generator Macro (009DWK)

Information

• The 009DWK macro dynamically creates deeplinks based on record values.

• The configuration is done via the DF configuration parameter (df_script_settings) with the DeeplinkGenerator key.

• Either python_id (reference to a deep link record) or url (direct URL template) must be specified, but not both.

• Path placeholders are defined in path_params, and query string values in query_params.

• Each parameter contains either field (dynamic value from the current record) or value (static value).

Configuration examples

Minimal Example (URL Template)

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

Dynamic and static path parameter

{
  "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"
      }
    }
  }
}

Reference via python_id

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

When using python_id the URL is identified from the referenced deeplink record. If the route changes, only the record needs to be updated; all DF configurations that point this out remain unchanged.

Combination with 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"
      }
    }
  }
}

Notes

Notes

• Path parameters (< >) have to be defined correctly in the URL template and must be existing in the record, if they are read dynamically.

• Query parameters are suitable for optional or flexible values.

• The JSON format coexists with other DF configuration sections like ButtonConfiguration.

• When using python_id, adjusting the deep link record is sufficient if the route changes.

Deeplink API

Information

• Deep links can be generated and displayed programmatically using the auxiliary functions in ppms.protocol.deeplink.

Module import

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

Available functions

Example

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

Implementation details

DF configuration of the 009DWK macro

Processing order when parsing the configuration

1. The configuration is parsed as JSON.

2. If the JSON object contains the key DeeplinkGenerator, it is used as the deeplink configuration.

3. If the JSON is valid but does not contain a DeeplinkGenerator key, parsing fails.

4. If the text is not valid JSON, the system falls back to the legacy line format.

Legacy line format

The older line-based format is retained for backward compatibility:

• First line: URL template with path placeholders or the python_id of a deeplink record.

• Subsequent non-empty lines: Parameter assignments according to the following syntax:

Example: Path parameter from data field

/project/<pr_functional>/
pr_functional:fachliche_id

Example: Dynamic and static query data

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

Example: Reference via python_id

planning_dashboard

pr_id=000008