HelloID-Conn-Prov-Target-ServiceNow

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-ServiceNow
  • Table of contents
  • Introduction
  • Getting started
    • Connection settings
    • Correlation configuration
    • Available lifecycle actions
    • Field mapping
  • Remarks
    • Account validation based on email
    • UTF8 encoding
    • Department, Location, and Manager Fields
  • Development resources
    • API documentation
  • Getting help
  • HelloID docs

Introduction

HelloID-Conn-Prov-Target-ServiceNow is a target connector. ServiceNow is a cloud-based platform that provides various software-as-a-service (SaaS) solutions for enterprise-level service management and IT operations management. It is primarily known for its IT Service Management (ITSM) capabilities, but it offers a wide range of applications and services for various departments within an organization.

Getting started

Connection settings

The following settings are required to connect to the API.

Setting	Description	Mandatory	Example
UserName	The UserName to connect to the ServiceNow API	Yes	-
Password	The Password to connect to the ServiceNow API	Yes	-
BaseUrl	The URL to the ServiceNow environment	Yes	https://{environment}.service-now.com

Correlation configuration

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

Setting	Value
Enable correlation	True
Person correlation field	Accounts.MicrosoftActiveDirectory.UserPrincipalName
Account correlation field	email

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.
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.
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

Account validation based on email

Due to an empty employee_number in a test environment, the account validation for version 1.0.0 of this connector relies on the email address instead.

You can modify it to use a different property, such as employee_number or any other field that suits your requirements.

UTF8 encoding

By default, version 1.0.0 handles UTF-8 encoding. This ensures that data is appropriately encoded. Encoding is handled in both the create and update lifecycle actions.

Department, Location, and Manager Fields

The department, location, and manager fields are linked objects. This means we must ensure they exist in ServiceNow and use the correct sys_id for updates.

• Create: When creating a user, we ensure that the manager, department, and location exist in ServiceNow. If any of these fields do not exist:
  1. A warning is logged.
  2. The property is removed from the JSON payload before submission.
• Update: When updating a user’s department, location, or manager in ServiceNow, we:
  1. Verify if the corresponding values in $correlatedAccount exist and match a unique identifier pattern via a regular expression.
  2. Retrieve the related record from ServiceNow if the conditions are met.
  3. Compare the name field of the retrieved record to the value in $actionContext.Data.
  4. If there’s a discrepancy, update the $actions array with one of the following:
     • UpdateLocation
     • UpdateDepartment
     • UpdateManager

Development resources

API documentation

API documentation can be found on: https://docs.servicenow.com/bundle/utah-api-reference/page/integrate/inbound-rest/concept/c_TableAPI.html

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/