Planon Extension - OpenURL

Introduction

This document outlines the specification of the OpenURL App.

The OpenURL app allows users to open an external URL from Planon based on values from selected business object records. The configured URL can contain placeholders that are resolved at runtime using values from the selected business object, referenced business objects, or associated business objects.

This document also describes the installation and configuration of the app, including the required configuration within Planon.

Prerequisites

Environment

This app works for Planon Live L133 and higher.

Constraints

• The action constructs a single URL based on one selected business object..
• The url setting is mandatory.
• URL placeholders must use valid syntax.
• The action must be executed from a business object context.

Required (free) fields

No additional free fields are required.

The app uses existing fields from the configured business object that are referenced in the URL placeholders.

Assumptions

• The default language of messages shown to the user is English.
• Translation keys are available in language.properties.
• The configured URL template is valid.
• The action is executed from a business object with a valid selection.

Features

The purpose of this app is to provide a reusable mechanism for opening external applications from Planon using information from business object records.

Feature 1: Open dynamic URLs

The app introduces a new action that opens an external URL.

The configured URL may contain placeholders that are replaced with values from the selected business object record.

Example:

https://external-app.example/[OrderNumber]

Feature 2: Resolve placeholder values

The app supports resolving values from multiple field types.

Example:

https://external-app.example/orders/[Code]?description=[Description]

Feature 3: Validate URL placeholders

Before constructing the URL, the app validates the configured placeholders.

The following validations are performed:

• Balanced brackets
• Empty placeholders
• Nested placeholders
• Invalid characters in placeholder names
• Duplicate placeholders

If validation fails, processing stops and an error is shown.

Feature 3b: Validate panel show time limit

The panelShowTimeLimit setting is validated before the URL is constructed.

• A negative value is not allowed and results in a validation error.
• A value of 0 opens the URL without displaying the confirmation panel.
• A positive value shows the confirmation panel for that number of seconds before it closes automatically.

Feature 4: Optional field conversion

Optional field conversion can be configured using fieldSettings.

Currently supported conversion:

field.Location.type=gps_rd

This converts GPS coordinates into RD coordinates before replacing the placeholder.

An optional field.<fieldName>.format setting controls how the converted X and Y coordinate values are combined into the resulting string. If not configured, it defaults to %s,%s.

field.Location.format=%s,%s

Feature 5: Empty field validation

When errorOnEmptyFields is enabled, every configured placeholder must resolve to a value.

If one or more placeholders are empty, the app displays a validation message and stops processing.

Feature 6: Error handling

Whenever a validation or runtime error occurs, the app displays a translated error dialog using the configured translation keys.

Solution Approach

This chapter describes the proposed solution.

The app contains a TSI Action responsible for constructing a URL from a configurable template and opening it in the user’s browser.

The TSI Action can be registered on any business object where navigation to an external application is required.

For this implementation the action can be registered on:

• Orders [UsrOrder]
• Any user-defined business object under Orders

Supported placeholder types

Example URL templates

https://external-app.example/orders/[OrderNumber]

https://external-app.example/orders/[OrderNumber]?description=[Description]

https://external-app.example/requestor/[PropertyRef.Code]

How does it work

When the action is executed, the following steps are performed:

1. Read the configured Component Settings.
2. Validate the URL template.
3. Resolve placeholder values from the selected business object.
4. Apply optional field conversions.
5. Validate empty placeholder values.
6. Construct the final URL.
7. Open the generated URL.

Installation

This chapter describes the steps required to install this app on your Planon environment.

Installation Process

There are two ways to install the app:

1. Using the Marketplace
2. Manual installation

Install the app by using the marketplace

In case your environment is configured to use the Planon app store the only thing required to install the app is to add the app license in the AppCenter TSI. Planon will automatically download and install the app.

Manual installation

In case you want to perform a manual installation follow the steps below.

1. Open AppCenter TSI from Planon webclient and click on install from action menu

2. Browse to the .ppk file

3. Click OK to install the app and follow the installation process
4. When the app is successfully installed, the app will appear in the AppCenter

5. Add the app license in Apps TSI

Component Settings

The OpenURL app uses Component Settings.

These settings are configured on the Extended Action in the Field Definer.

Description of settings

Activation

Once the app has been configured, you can activate the app by pressing the Active status transition from the action panel. Always make sure that the required User groups are linked correctly and the Configure action is executed before activating the App.

Planon Configuration

Field definer

1. Log in to Planon ProCenter using the supervisor account (or any account with sufficient rights to UI Configuration).

2. Open the Field definer.

Configure Orders BO

1. Find the business object with system name Orders.

   1. Set the status of the Business Object to Under construction via the action menu.

2. Apply the following steps:

   1. Go to the selection level Details and select the selection step Extended Actions.

   2. Click Add in the action menu and create the action with the following details.

3. Go back to the selection level Business objects.

4. Set the status of the Business Object with system name Orders to Completed via the action menu.

Repeat the above steps for any user-defined business object under Orders where you want to use the OpenURL feature.

Add TSI Action button to layout

1. Navigate to the TSI Layouts.

2. Select the business object Orders and go to the Layouts selection step.

3. Choose the layout in which you want to add the button and set it Under construction by clicking the lock icon.

4. Click Actions in the layout and add the OpenURL action by dragging it into the Actions section.

5. Save the layout and set it to Completed by clicking the open lock.

6. Repeat the above steps for any user-defined business object under Orders where you want to use the OpenURL feature.

Translation keys

Troubleshooting

Error handling

• Errors are recorded in the server logs:
  • Tomcat log for web components
    • Webpages
    • PSS modules
    • Stepview
    • TSI Action
    • JAX-RS webservices
  • Wildfly log for server-side components
    • Business rules
    • Scheduled tasks
    • Workers
    • Event Connector
• UI components (TSI Actions) also display errors in the interface