HelloID-Conn-Prov-Target-Pynter

Important

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-Pynter
  • Table of contents
  • Introduction
  • Getting started
    • Connection settings
    • Correlation configuration
    • Available lifecycle actions
    • Field mapping
  • Remarks
    • Permissions
    • Namespace
    • Dynamic SOAP envelope derived from fieldMapping
      • Example SOAP envelope for GetPersonByExternalId
    • Required fields when updating
      • Compare logic within the update lifecycle action
  • Development resources
    • SOAP methods
  • Getting help
  • HelloID docs

Introduction

HelloID-Conn-Prov-Target-Pynter is a target connector. Pynter provides a set of SOAP APIs that allow you to programmatically interact with its data. These APIs use XML-based requests and responses, following the SOAP protocol for structured communication.

Supported features

The following features are available:

Feature	Supported	Actions	Remarks
Account Lifecycle	✅	Create, Update, Enable, Disable
Permissions	✅	Grant, Revoke	All available accountlevels except 'User', cause this a default accountlevel
Resources	❌	-
Entitlement Import: Accounts	✅	-
Entitlement Import: Permissions	✅	-	All available accountlevels except 'User', cause this a default accountlevel

Getting started

HelloID Agent

Warning

Currently it is necessary to use a HelloID agent. Due to issues with a specific issuer of the root certificate used by the webservice, the connector doesn't work with the HelloID cloud.

Session concurrency

Within each event the Pynter endpoints expect the complete account object. Therefore to ensure that events do not interfere with each other, it's necessary to set concurrent actions to 1 for the connector.

Connection settings

The following settings are required to connect to the API.

Setting	Description	Mandatory
UserName	The UserName to connect to the API	Yes
Password	The Password to connect to the API	Yes
BaseUrl	The URL to the API	Yes

Correlation configuration

The correlation configuration is used to specify which properties will be used to match an existing account within Pynter to a person in HelloID.

Setting	Value
Enable correlation	True
Person correlation field	ExternalId
Account correlation field	ExternalIdentifier

Tip

For more information on correlation, please refer to our correlation documentation pages.

Available lifecycle actions

The following lifecycle actions are available:

Action	Description
create.ps1	Creates a new account.
delete.ps1	Removes an existing account entitlement. Account in target won't be deleted.
disable.ps1	Disables an account, preventing access without permanent removal.
enable.ps1	Enables an account, granting access.
update.ps1	Updates the attributes of an account.
grantPermission.ps1	Sets the accountlevel for an account.
revokePermission.ps1	Revokes the accountlevel of an account and sets it to default 'User'.
import.ps1	Imports existing entitlements for configured entitlements in business rules.
importPermission.ps1	Imports existing permission entitlements for configured entitlements in business rules
configuration.json	Contains the connection settings and general configuration for the connector.
fieldMapping.json	Defines mappings between person fields and target system person account fields.

Field mapping

The field mapping can be imported by using the fieldMapping.json file.

Remarks

Permissions

Warning

Be aware only one accountlevel can be assigned, so business rules must be set up so users can only get one accountlevel. If a user falls within the conditions of multiple business rules the last granted entitlement will determine the accountlevel.

Namespace

Currently the function New-PynterSoapXmlBody uses a default namespace which is set to: http://tempuri.org/. This value is usually reserved for development environemts only. For production environments, the value of the namespace might be subject to change. Make sure to verify and update this accordingly during the first implementation.

Dynamic SOAP envelope derived from fieldMapping

The New-PynterSoapXmlBody function is responsible for creating the SOAP envelope. It takes two parameters:

• SOAPMethod – Defines the specific SOAP method being called.
• Parameters – Contains the key-value pairs for the SOAP body, derived from actionContext.Data or the correlation configuration.

Since actionContext.Data dynamically provides the parameter names and values, this function allows full flexibility in constructing the SOAP envelope. You can easily extend actionContext.Data with additional fields, as long as the names match the expected SOAP method parameters.

Example SOAP envelope for GetPersonByExternalId

Consider the following PowerShell code:

$splatGetPersonByExternalIdXmlBody = @{
    SoapMethod = 'GetPersonByExternalId'
    Parameters = @{ externalId = '123456' }
}
New-PynterSoapXmlBody @splatGetPersonByExternalIdXmlBody

This will result in the following SOAP envelope:

<soap12: Envelope xmlns: xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns  : xsd="http://www.w3.org/2001/XMLSchema"
xmlns  : soap12="http://www.w3.org/2003/05/soap-envelope">
<soap12: Body>
        <GetPersonByExternalId xmlns = "http://tempuri.org/">
            <username>MyUserName</username>
            <password>MyPassword</password>
            <externalId>123456</externalId>
        </GetPersonByExternalId>
</soap12: Body>
</soap12: Envelope>

• username and password are automatically derived from actionContext.Configuration, ensuring authentication.
• externalId is a dynamic input and specified in the -Parameters parameter.

Required fields when updating

The fields: FirstName, FamilyName, ExternalIdentifier, and Email must always be provided when updating an account (or performing operations like enabling, disabling, or deleting an account). The values send back are the ones that come from the $correlatedAccount' object.

Compare logic within the update lifecycle action

The update lifecycle action does contain our standard compare logic. However, contrary to the documentation, its worth to note that; even though properties are compared and changed properties are logged, ALL properties will be updated.

Development resources

SOAP methods

The following endpoints are used by the connector

SOAP method	Documentation URI	Lifecycle actions
GetPersonByExternalId	Retrieve user information	create,update,enable,disable,delete
CreatePerson	Create user account	create
UpdatePerson	Update user account	update,enable,disable,delete

Getting help

Tip

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

Tip

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/