Planon Connect for Kone

Introduction

KONE is a global powerhouse transforming how people move through buildings and cities. From manufacturing elevators and escalators to pioneering smart urban mobility and sustainability, KONE shapes urban life through innovation, safety, and environmental responsibility.

Planon Connect for KONE provides the feasibility of integrating both KONE and Planon systems to synchronize the services orders between the systems.

Prerequisites

Environment

This solution is designed to work with Planon Live L119 and above.

Constraints

The app is based on below constraints

  • The app currently supports only one way synchronization ie from KONE to Planon

  • The customer has access to KONE portal to create Application and webhooks

  • The reactive orders created in Planon are sent to KONE via email using notifications

  • The mapping between Planon Assets and KONE equipment is already in place.

Required free BOs & free fields

The app requires below free fields

  1. Business Object BaseAsset

    1. 1 Free String field to store the KONE equipment number
  2. Business Object BaseOrder

    1. 1 Free String field to store KONE Service Order Number

    2. 1 Free field of type CodesCode field to store KONE Service Order Type.

Assumptions

NA

Features

Handle Unplanned (Reactive) Orders

One of the key features of the application is its ability to manage updates for reactive service orders.

Reactive orders are created in two ways.

  • Reactive Orders created in Planon

  • Reactive Orders (call outs) created at KONE

When a reactive order is created in Planon, it has to be shared with the KONE team via email for further processing. Once KONE creates corresponding service orders in their system, updates related to those orders such as status changes or completion details are communicated back to Planon through webhook integration.

The other case, where reactive orders created in KONE are sent to Planon via the webhook integration which are then created in Planon. Further updates to these orders are also sent to Planon.

These updates are seamlessly applied to the respective orders in Planon, ensuring that both systems remain synchronized and up to date.

Handle Planned Orders

KONE also manages planned maintenance tasks, which are sent to Planon via webhook integration. When a planned maintenance order is created in KONE, it is transmitted to Planon and registered as a new service order.

Subsequent updates from the KONE system such as revised schedules, technician assignments, or work completion are communicated via webhooks and applied to the relevant orders in Planon.

Get Service Report

KONE publishes a service report of the completed order. The app now supports to get this service report from KONE and stores it on a communication log for the corresponding order.

How does it work?

This chapter provides a technical description of the features above.

Handling Orders

Any new orders or updates to the existing orders are sent to Planon through webhook integration.

In order to receive updates via webhook, the comes with a POST endpoint which will be configured on webhook. This endpoint receives the json message and sends to the Planon Event Connector which are handled indendenlty.

Below is the endpoint

<Planon Base URL>/sdk/platform/jaxrs/planonsoftware/apps/connectforkone/module/webhook/order

Authentication to Planon endpoint:

To authenticate with Planon endpoint, a custom authorization header has to be sent along with the POST call.

Header key: Authorization

Header value: PLANONKEY accesskey=<Access Key generated for the integration user>

Sample body received

{
    "data": {
        "serviceOrderNumber": "9ABE41986336",
        "customerPurchaseOrderNumber": "",
        "equipmentNumber": "44414120",
        "actualArrivalDateTime": "2025-07-14T07:56:52",
        "finishedDateTime": "2025-07-12T18:18:47",
        "jobDescription": "Fermatorsturing defect na algemene stroomonderbreking in de regio.",
        "serviceOrderType": "YSM2",
        "serviceOrderTypeDesc": "Unplanned Service Order with Contract",
        "orderStatus": "On Site",
        "description": "105  Buiten dienst op niveau met gesloten deur",
        "commentsForCustomer": "The elevator is operational again",
        "descriptionOfWork": "On 14/07/2025 1:54 p.m., Upon arrival, our engineer noted that your installation was working. After analyzing the failure, our engineer began cleaning the bottom of the pit of your installation. The component concerned was part of the cabin electrification.",
        "workOrderPlannedStartDate": "2025-07-14T10:08:08"
    },
    "id": "71fee4f4-34bc-46e9-b7b7-620faf1a50e3",
    "time": "2023-09-09T04:42:51.893Z",
    "type": "com.kone.equipment.serviceorder.v2",
    "equipmentId": "ken:42069879",
    "clientid": "e2b5a2aa-71d1-4bea-b340-9d85f8d88c29",
    "source":
"http://dev.kone.com/webhook/765b2708-7036-4d1e-964e-cbd2b8d3fdaa",
    "specversion": "1.0"
}

The data received via the endpoint is pushed to event connector creating inbound raw messages and inbound messages. Once the inbound raw message is created, the endpoint returns success response.

The processing of data into Planon is processed via the event connector. The PaaP component called Processor gets the necessary information from the message received and process the data as per the logic defined.

Handling Unplanned (Reactive) Orders

As described in Chapter 3.1, Unplanned orders can start either at Planon or KONE. Below sub chapters provides the details on how these orders are handled.

To differentiate between the Unplanned Orders created at Planon and KONE, we use the below 3 fields from KONE

  1. serviceOrderType €“ Any orders with serviceOrderType as YSM3, YSM4 and YSM6 are considered as unplanned orders
  2. customerPurchaseOrderNumber €“ Orders created at Planon should be mapped with Order Number
  3. serviceOrderNumber €“ A unique number for each order at KONE

Handling orders originating from Planon

The orders created in Planon are sent to KONE via email. This is not part of the app but achieved using configurations. Once the Orders are sent to KONE, KONE team creates those orders in KONE system. The webhook then publishes the updates of the Orders. Below is the logic used to determine if the order is an unplanned one and originating from Planon

  • serviceOrderType : Valid values are YSM3, YSM4 and YSM6
  • customerPurchaseOrderNumber : should contain a value KONE & Planon Field mapping
System Name of Planon FieldKONE API FieldField Type
OrderNumbercustomerPurchaseOrderNumberString
Any free string fieldserviceOrderTypeCodesCodeName
Any free string fieldserviceOrderNumberString
ActualAttendPropertyDateTime (Configurable in settings)actualArrivalDateTimeDateTime
ActualCompletionPropertyDateTime (Configurable in settings)finishedDateTimeDateTime
LastStateChangedDateTimeDate when new status has arrived from KONE
Comment (Configurable in settings)descriptionOfWork + jobDescription + commentsForCustomerString
RefBOStateUserDefinedorderStatus (KONE to Planon Status mapping is configurable)

Handling orders originating from KONE

Sometimes users can directly report to KONE team in case of any failures or issues with elevators. In such cases, unplanned orders originate from KONE which are called as call outs as per KONE terminology.

Below is the criteria to determine if the order is unplanned and originating from KONE

  • serviceOrderType Valid values are YSM3, YSM4 and YSM6
  • customerPurchaseOrderNumber should be empty
  • serviceOrderNumber should contain a value serviceOrderNumber is used as a unique identifier to check for an existing order in Planon. If no order is found with the incoming serviceOrderNumber, a new order is created.

Note: To create an order, the corresponding equipmentNumber should already be mapped to an asset in Planon. If no asset found, creation of order is skipped and further updates are not processed.

KONE & Planon Field mapping

System Name of Planon FieldKONE API FieldField TypeAdditional Comments
DescriptiondescriptionString
OrderNumberAuto Generated by Planon
InventoryItemRefequipmentNumberAsset in Planon is queried using the equipmentNumber
PropertyRefProperty of the Asset
Any free string fieldserviceOrderTypeCodesCodeName
Any free string fieldserviceOrderNumberString
ActualAttendPropertyDateTime (Configurable in settings)actualArrivalDateTimeDateTime
ActualCompletionPropertyDateTimefinishedDateTimeDateTime
LastStateChangedDateTimeDate when new status has arrived from KONE
Comment (Configurable in settings)descriptionOfWork + jobDescription + commentsForCustomerString
OrderGroupRefValue taken from settings of the app
RefBOStateUserDefinedorderStatusKONE to Planon Status mapping is configurable

Handling Planned Orders from KONE

KONE also manages planned maintenance tasks. These are also sent to Planon via the same webhook configured.

Planned orders are differentiated from Unplanned orders based on the KONE API field serviceOrderType

Any order received with serviceOrderType YSM1 or YSM2 are considered as Planned orders.

serviceOrderNumber is used as a unique identifier to check for an existing order in Planon. If no order is found with the incoming serviceOrderNumber, a new order is created.

Note: To create an order, the corresponding equipmentNumber should already be mapped to an asset in Planon. If no asset found, creation of order is skipped and further updates are not processed.

KONE & Planon Field mapping

System Name of Planon FieldKONE API FieldField TypeAdditional Comments
Descriptiondescription
OrderNumberAuto Generated by Planon
InventoryItemRefequipmentNumberAsset in Planon is queried using the equipmentNumber
PropertyRefProperty of the Asset
Any free string fieldserviceOrderTypeCodesCodeName
Any free string fieldserviceOrderNumberString
ActualAttendPropertyDateTime (Configurable in settings)actualArrivalDateTimeDateTime
ActualCompletionPropertyDateTime (Configurable in settings)finishedDateTimeDateTime
PlannedBeginDateTime (Configurable in settings)workOrderPlannedStartDateDateTime
LastStateChangedDateTimeDate when new status has arrived from KONE
Comment (Configurable in settings)descriptionOfWork + jobDescription + commentsForCustomerString
OrderGroupRefValue taken from settings of the app
RefBOStateUserDefinedorderStatusKONE to Planon Status mapping is configurable

Handling Order reports

The service reports for the orders are sent to Planon through webhook integration.

In order to receive updates via webhook, the comes with a POST endpoint which will be configured on webhook. This endpoint receives the json message and sends to the Planon Event Connector which are handled indendenlty.

Below is the endpoint

<Planon Base URL>/sdk/platform/jaxrs/planonsoftware/apps/connectforkone/module/webhook/order/report

Authentication to Planon endpoint:

To authenticate with Planon endpoint, a custom authorization header has to be sent along with the POST call. Header key: Authorization Header value: PLANONKEY accesskey=<Access Key generated for the integration user>

Sample body received

{
   "specversion": "1.0",
   "type": "com.kone.equipment.servicereport.v1",
   "source": "http://dev.kone.com/webhook/765b2708-7036-4d1e-964e-cbd2b8d3fdaa",
   "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
   "time": "2026-11-08T13:00:36.000Z",
   "data": {
      "ken": "10307777",
      "serviceOrderNumber": "7BBE8819756",
      "customerPurchaseOrderNumber": "",
      "serviceReportPdf":"JVBERi0xLjUKJeLjz9MKOCAwIG9iago8PCiUlRU9GCg="
   }
}

The data received through the endpoint is forwarded to the Event Connector, which creates both Inbound Raw Messages and Inbound Messages. The associated file is temporarily stored in a designated Planon location. Once the Inbound Raw Message has been successfully created, the endpoint returns a success response.

The processing of the data within Planon is handled by the Event Connector. A PaaP component called Processor extracts the required information from the received message and retrieves the temporarily stored file.

The retrieved file is then attached as SERVICE_REPORT.pdf to a newly created Communication Log (ComLog) for the corresponding order. The order is identified using the Service Order Number. If no matching order is found, the message is moved to the Failed state.

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.

AppCenter Marketplace Installation

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

AppCenter Installation

  1. Browse to the .ppk file

Browse ppk file

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

Installed App

  1. Add the app license in Apps TSI

Add App License

App Level Configuration

Add module settings

  1. Provide the module settings which are available in the Module Settings section. Here is an example:
  1. Click the Save button after populating the module settings values.

Module Setting details

ParameterExample ValueDescription
konePlanonStatusMapping‘New-UsrOrderReported,Hold-UsrWorkOrderOnHold€™This defines the status mapping between Kone status and Planon order status. Format is Kone Status-System name of Planon status
standardOrderForUnPlannedOrdersUsrOrderStandard Order BO used to create Unplanned Order
standardOrderForPlannedOrdersUsrOrderStandard Order BO used to create Planned order
actualArrivalDateTimeFieldActualAttendPropertyDateTimeThis is the system name of the field on Order to store actualArrivalDateTime from KONE
equipmentNumberFieldFreeString10This is the system name of the field on Asset where KONE Equipment number is stored
finishedDateTimeFieldActualCompletionPropertyDateTimeThis is the system name of the field on Order to store finishedDateTime from KONE
maintenanceDescriptionFieldCommentThis is the system name of the field to store job description, comments for customer on the Order
plannedBeginDateTimeFieldPlannedBeginDateTimeThis is the system name of the field on Order to store Planned Begin Date of Planned Orders from KONE
serviceOrderNumberFieldFreeString14This is the system name of the field to store Service Order Number (A unique id) from KONE
serviceOrderTypeFieldFreeString15This is the system name of the field on Order to store Service Order Type from KONE
comlogTypeForOrderReportUsrCommunicationLogSystem name of the Communication log type to be used for order report
securelyStoreServiceReportYesSet to ‘Yes’ to store the service report PDF in Secure document field on Communication log. Set to ‘No’ to store the service report PDF in Document field on Communication log.

Example settings in view code mode

// Settings for ConnectForKone app

{

   // System name of the field on Order BO to update 'actual­Arrival­Date­Time' from KONE
   "actualArrivalDateTimeField" : "ActualAttendPropertyDateTime",

   // System Name of the field on Asset BO where the equimentNumber from KONE is present
   "equipmentNumberField" : "FreeString10",

   // System name of the field on Order BO to update 'finishedDateTime' from KONE
   "finishedDateTimeField" : "ActualCompletionPropertyDateTime",

   // This defines the status mapping between Kone status and Planon orderstatus. Format is Kone Status-System name of Planon status.Example 'New-UsrWorkOrderReported,Hold-UsrWorkOrderOnHold. Value must be an array of strings.
   "konePlanonStatusMapping" : [ "Hold-UsrWorkOrderOnHold","Assigned-UsrWorkOrderAssigned", "Accepted-UsrWorkOrderAssigned","OnSite-UsrWorkOrderInProgress","Finished-UsrWorkOrderTechnicallyCompleted","Arrived-UsrWorkOrderInProgress" ],

   // System name of the field on Order BO to update 'Description of Work', 'jobDescription' & 'commentsForCustomer' from KONE
   "maintenanceDescriptionField" : "Comment",

   // System name of the field on Order BO to update 'workOrderPlannedStartDate' from KONE
   "plannedBeginDateTimeField" : "PlannedBeginDateTime",

   // System Name of the field on Order BO to store 'serviceOrderNumber' from KONE
   "serviceOrderNumberField" : "FreeString14",

   // System Name of the field on Order BO to store 'serviceOrderType' from KONE
   "serviceOrderTypeField" : "FreeString15",

   // Selected standard order is used to create Order BO in Planon for Kone Planned
   "standardOrderForPlannedOrders" : {
      "primaryKey" : 29
   },

   // Selected standard order is used to create Order BO in Planon for Kone UnPlanned Orders/ Call Outs
   "standardOrderForUnPlannedOrders" : {
      "primaryKey" : 31
   },

   // System name of the Communication log type to be used for order report
   "comlogTypeForOrderReport" : "UsrCommunicationLog",

   // Set to 'Yes' to store the service report PDF in Secure document field on Communication log. Set to 'No' to store the service report PDF in Document field on Communication log.
   "securelyStoreServiceReport" : true

}

App uses Event Connector solution to process data into Planon. So please make sure the app is linked to the User Group that allows to use Event Connector Product definition.

  1. Find/Create a user group that is linked with Event Connector, Json Services and Enterprise API Product Definitions

  2. Go to App centre

  3. Select the app and click on €œLink App User Group€

  4. Select the user group from step 1 and move to In Use section

  5. Click ok

Also, the user for which access key is generated should be linked to this user group.

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.

AppCenter App Activation

Planon Configuration

This chapter describes the required configuration in the application such as adding a TSI Action to field definer / layouts (if applicable) and/or configuring any free fields.

Pick List

A code/descriptive pick list needs to be created and which needs to linked to a field on the Order Business Object.

The picklist should be given the name SERVICE_ORDER_TYPES

The following items should be added to the pick list

CodeDescription
YSM1Planned with Contract
YSM2Planned without Contract
YSM3Unplanned with contract
YSM4Unplanned without contract
YSM6Fixed price repair order

BO BaseOrder (Fields)

Two free fields are required on the Orders to store service order type and service order number from KONE

DescriptionFree field typePlanon field TypePick List
KONE Service Order TypeAny available FreeStringCodesCodeNameSERVICE_ORDER_TYPES
KONE Service Order NumberAny available FreeStringString

BO BaseAsset (Fields)

A free field is required on the Asset to store KONE equipment number

DescriptionFree field typePlanon field Type
KONE Equipment NumberAny available FreeStringString

KONE Configuration

KONE configuration involves the process of configuring the webhook.

Please follow below steps to configure webhook in KONE

  1. Login to KONE API Portal

  2. If there is no active application, create a new application with all the necessary details

  1. Once all the details are provided, the application is saved.

  2. Now Click on Edit action and go to WebHooks section

  1. Create new webhook

  2. Provide the details for the webhook as below

  • Webhook’s name : Any name as per requirement

  • Target Url: <Planon Base url>/sdk/platform/jaxrs/planonsoftware/apps/connectforkone module/webhook/order

  • Contact email: Email of the contact person

  • Customer header: PLANONKEY accesskey=<accesskey generated for a Planon user>

  1. Subscribe to the event Service Info API as below and click on create webhook
  1. Create one more webhook for Order service report with below details
  • Webhook’s name : Any name as per requirement

  • Target Url: <Planon Base url>/sdk/platform/jaxrs/planonsoftware/apps/connectforkone/module/webhook/order/report

  • Contact email: Email of the contact person

  • Customer header: PLANONKEY accesskey=<accesskey generated for a Planon user>

  • Subscribe to event as shown below

Note: The webhook should also be subscribed to specific KONE Equipment Numbers (KENs) such that only the events for the selected equipments are sent to Planon

Troubleshooting

This chapter provides a comprehensive overview of common occurrences and known issues that can serve as a reference when the app is not functioning as anticipated

When no messages are received

  1. Check if Webhook is subscribed

  2. Check if App is active

  3. Check if the access key is valid

  4. Check if app is linked to User group and user for which access key used is also linked to the same user group

  5. Check if the required product definitions are linked to the user group

  6. Any run time errors during creation of inbound raw messages can be found in tomcat log file

  7. Any run time errors during the process of incoming message can be found in wildfly log file