HelloID-Conn-Prov-Target-Planon-Order

⚠️ Warning
Note that this connector is "a work in progress" and therefore not ready to use in your production environment.

⚠️ Warning
This connector has not been tested on a Planon environment. Therefore, changes might have to be made according to your environment.

⚠️ Warning
Before using this connector, make sure the necessary Planon WSDL's are available. See: WSDL specifications

ℹ️ Information
This repository contains the connector and configuration code only. The implementer is responsible to acquire the connection details such as username, password, certificate, etc. You might even need to sign a contract or agreement with the supplier before implementing this connector. Please contact the client's application manager to coordinate the connector requirements.

Table of contents

• HelloID-Conn-Prov-Target-Planon-Order
  • Table of contents
  • Introduction
  • Getting started
    • Connection settings
    • LifeCycle events
    • Prerequisites
    • Remarks
      • No user provisioning
      • GetPerson not yet available
      • Pre-Emptive authentication
      • WSDL specifications
  • Getting help
  • HelloID docs

Introduction

HelloID-Conn-Prov-Target-Planon is a target connector. Planon offers web services APIs that allow developers to access and integrate the functionality with other applications and systems.

The Planon API uses a WSDL / SOAP architecture. A WSDL (Web Services Description Language) is an XML-based language that is used for describing the functionality of a web service. A WSDL file defines the methods that are exposed by the web service, along with the data types that are used by those methods and the messages that are exchanged between the web service and its clients.

Getting started

Connection settings

The following settings are required to connect to the API.

Setting	Description	Mandatory
UserName	The UserName to connect to the Planon webservice	Yes
Password	The Password to connect to the Planon webservice	Yes
BaseUrl	The URL to the Planon webservice Example: https://{environment}/nyx/services	Yes
OrderCodesJSONFile	The path to a file with StandardOrderCode the required permissions And example can be found in the asset folder	Yes

LifeCycle events

The following lifecycle events are available:

Event	Description	Notes
create.ps1	Correlates an account	ws:GetPerson
grant.ps1	Creates an order	umr:MaakOrder
permissions.ps1	Retrieves a list of order codes	Requires a file in JSON format containing standard user codes

Prerequisites

❗ Note that, this connector has not been tested on a Planon environment. Changes might have to be made according to your environment.

❗ Contact your Planon consultant to verify that the necessary WSDL's are available.

• A JSON file containing the standard order Codes.
• URL to the Planon webservice
• The UmraOrders and SDWWebServices WSDL's available.

Remarks

No user provisioning

The sole purpose of this connector is to automatically create Planon orders. It cannot be used for user provisioning.

GetPerson not yet available

Both the create.ps1 and grant.ps1 will need to retrieve the user account from Planon. The create.ps1 for account correlation, the grant.ps1 because the order send to Planon must contain the EmployeeId or PersonnelNumber.

Because the connector is based on documentation, the XML response for a GetPerson call to Planon is unclear. Therefore, this part is currently not developed and not available in the connector.

The PowerShell code below can be used to retrieve a person from Planon.

$UserName   = ''
$Password   = ''
$BaseUrl    = ''
$ExternalId = ''

$pair = "$($UserName):$($Password)"
$b64Encoded = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes($pair))
$headers = [system.collections.generic.dictionary[string, string]]::new()
$headers.add('Authorization', "Basic $b64Encoded")

$body = @"
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://www.tempsdw.org/SDWWebServices/v1/ws">
    <soapenv:Body>
        <ws:GetPerson>
            <code>$ExternalId</code>
        </ws:GetPerson>
    </soapenv:Body>
</soapenv:Envelope>
"@

$splatParams = @{
    Uri         = "$($BaseUrl)/SDWWebServices.SDWWebServicesSOAP"
    Method      = 'POST'
    Headers     = $headers
    Body        = $body
    ContentType = 'application/text+xml; charset=utf-8'
}
Invoke-RestMethod @splatParams

Pre-Emptive authentication

Planon requires Pre-Emptive authentication. Which means that, the outgoing request must contain the authorization header with the username:password in a base64 encoded string.

WSDL specifications

The connector uses the following WSDL specifications:

WSDL	Description
UmraOrders	To create, update and retrieves order(s)
SDWWebServices	To retrieve and correlate a user account

Before using this connector, contact your Planon consultant to verify the WSDL's listed above are available.

Getting help

For more information on how to configure a HelloID PowerShell connector, please refer to our documentation pages

If you need help, feel free to ask questions on our forum

HelloID docs

The official HelloID documentation can be found at: https://docs.helloid.com/