Page Comparison

This article contains the following topics:

Table of Contents

Info

title	Note

This article deals exclusively with how to synchronize user data from other systems via LDAP , and REST and SOAP; to learn how to synchronize user data from Serviceaide Intelligent Service Management and CA Service Desk Manager please refer to Synchronize Users from CA SDM and ISM.

The Sync Utility specifies how to synchronize data on a regular basis from various sources such as Lightweight Directory Access Protocol (LDAP), Representational State Transfer (REST) APIs such as ServiceNow, Cherwell, Freshservice or any other ITSM tools to Luma. The utility is used to import information such as users, groups, group membership and global user attributes. This utility does not import or update passwords in Luma. The synchronization can be scheduled at a recurring interval that is aligns to your organization's needs. When a user is added or updated from a domain, the Sync Utility automatically synchronizes the information with Luma.

...

REST end points with appropriate credentials to pull the data
OS: Windows, UNIX
Latest version of Java (version 8 or later)
Memory: 2 GB minimum
Compatibility with HTTPS secure communications protocol
SOAP end points with appropriate credentials to pull the data
OS: Windows, UNIX
Latest version of Java (version 8 or later)
Memory: 2 GB minimum
Compatibility with HTTPS secure communications protocol
Luma can import contacts and groups from all systems that support REST standards

Verify System Requirements for SOAP API Supported System

Ensure that your system meets the following requirements before running the Sync Utility:

Luma can import contacts and groups from all systems that support SOAP standards

Info

title	Note

Each tenant can configure multiple instances of the Sync Utility by configuring different folder structure and connecting to different sources of information from each end point such as LDAP , and REST and SOAP. Administrators will have the ability to sync the contacts and groups from different sources to a single tenant.

...

The Sync Utility is delivered as a ZIP file. This file contains the utility and supporting files necessary for the process. You can acquire the Sync Utility package by reaching out to the Serviceaide Support through email or the support portal. Specify the subject as require access to the Luma Sync Utility. Once the email is sent or a support ticket is created, the Support team will help you with the request.

...

Info

title	Caution

Do not modify the folder structure of the Sync Utility ZIP folder. Any modifications can result in failure of the synchronization process.

Set up a service account that has permissions to connect to the directory server and run queries.

Configure Files

Sync Utility includes the synctool.properties file in the Install directory \conf folder.

...

Code Block

title	Synctool properties
linenumbers	true

# comment
import-data-system.source-system-name = ADFS
# this can be only supported connection types (REST/SOAP/LDAP) etc
import-data-system.connection-type = LDAP
import-data-system.ldapConfig.admin-user = Administrator@domain.com
import-data-system.ldapConfig.password = xxxxxxxxxx
import-data-system.ldapConfig.global-catalog-server = ldap://xx.xxx.xxx.xxx:xxxx
import-data-system.ldapConfig.domain-controller-server = ldap://xx.xxx.xxx.xxx:xxx
import-data-system.ldapConfig.search-base = OU=USERS,DC=ACME,DC=inc
import-data-system.ldapConfig.search-filter = (&(objectClass=user)(objectClass=person)(objectClass=organizationalPerson))
import-data-system.ldapConfig.response-type = String
# comment
import-export-mapping.import-data-model-key-mapping-with-export-data-model-key = [{\	
	"importDataKey": "",\	
	"exportDataKey": "",\	
	"staticColumn": "true",\	
	"staticColumnName": "Id",\	
	"staticColumnValue": "",\	
	"isTransformationNeeded": "false",\	
	"javascriptImportDataKeyReference": "Id",\	
	"javascriptXformationFunciton": ""\
},\
{\	
	"importDataKey": "title",\	
	"exportDataKey": "Title",\	
	"staticColumn": "false",\	
	"staticColumnName": "",\	
	"staticColumnValue": "",\	
	"isTransformationNeeded": "false",\	
	"javascriptImportDataKeyReference": "title",\	
	"javascriptXformationFunciton": ""\
},\
{\	
	"importDataKey": "givenName",\	
	"exportDataKey": "First Name",\	
	"staticColumn": "false",\	
	"staticColumnName": "",\	
	"staticColumnValue": "",\	
	"isTransformationNeeded": "false",\	
	"javascriptImportDataKeyReference": "firstName",\	
	"javascriptXformationFunciton": ""\
},\
{\	"importDataKey": "givenName",\	
	"exportDataKey": "Middle Name",\	
	"staticColumn": "false",\	
	"staticColumnName": "",\	
	"staticColumnValue": "",\	
	"isTransformationNeeded": "false",\	
	"javascriptImportDataKeyReference": "given Name",\	
	"javascriptXformationFunciton": ""\
},\
{\	
	"importDataKey": "sn",\	
	"exportDataKey": "Last Name",\	
	"staticColumn": "false",\	
	"staticColumnName": "",\	
	"staticColumnValue": "",\	
	"isTransformationNeeded": "false",\	
	"javascriptImportDataKeyReference": "lastName",\	
	"javascriptXformationFunciton": ""\
},\
{\	
	"importDataKey": "givenName",\	
	"exportDataKey": "User Name",\	
	"staticColumn": "false",\	
	"staticColumnName": "",\	
	"staticColumnValue": "",\	
	"isTransformationNeeded": "true",\	
	"javascriptImportDataKeyReference": "userName",\	
	"javascriptXformationFunciton": "function (entity) { return 'usr_' + parseInt((Math.random() * 20), 10) + entity.firstName.replace(/\s+/, '') } "\
},\
{\	
	"importDataKey": "mail",\	
	"exportDataKey": "Email Address",\	
	"staticColumn": "false",\	
	"staticColumnName": "",\	
	"staticColumnValue": "",\	
	"isTransformationNeeded": "false",\	
	"javascriptImportDataKeyReference": "eMail",\	
	"javascriptXformationFunciton": ""\
},\
{\	
	"importDataKey": "mobile",\	
	"exportDataKey": "Phone",\	
	"staticColumn": "false",\	
	"staticColumnName": "",\	
	"staticColumnValue": "",\	
	"isTransformationNeeded": "false",\	
	"javascriptImportDataKeyReference": "phone",\	
	"javascriptXformationFunciton": ""\
},\{\	
	"importDataKey": "dummy",\	
	"exportDataKey": "Role",\	
	"staticColumn": "false",\	
	"staticColumnName": "Role",\	
	"staticColumnValue": "",\	
	"isTransformationNeeded": "true",\	
	"javascriptImportDataKeyReference": "",\	
	"javascriptXformationFunciton": "function(entity) { if (entity.lastName.indexOf('admin') > -1) {return 'Administrator'; } else if (entity.lastName.indexOf('analyst') > -1) {return 'Analyst';} else {return 'Self-service user';}}"\
},\
{\	
	"importDataKey": "",\	
	"exportDataKey": "",\	
	"staticColumn": "true",\	
	"staticColumnName": "Associated Groups",\	
	"staticColumnValue": "G1",\	
	"isTransformationNeeded": "true",\	
	"javascriptImportDataKeyReference": "",\	
	"javascriptXformationFunciton": ""\
}]
export-data-system.target-system-name = LUMA
export-data-system.target-export-format = Excel
export-data-system.exportFileLocation = e:/exportrunner/conf/Template_for_Bulk_Upload.xlsx
export-data-system.exportSheetName = Contacts
export-data-system.connection-type = LUMA
	
export-data-system.luma.base-url = https://xxx
export-data-system.luma.auth-api = /public/tenant/login
export-data-system.luma.export-api = /tenant/@replace.tenantId/contact/upload
export-data-system.luma.userName = admin@xxx.com
export-data-system.luma.password = xxxx
export-data-system.luma.subDomain = xxxx

...

Parameter Name	Parameter Description	Example Values
ldapConfig.global-catalog-server	Specifies the Domain server and port and is usually the same as the Global Catalog server.	ldap://dcp1s:3268
ldapConfig.admin-user	Specifies the Distinguished Name of the service account to use for connecting to AD and retrieving information.	CN=User\\, Admin, OU=Users, DC=Acme, DC=com
ldapConfig.password	Specifies the password for the service account specified in ldap.bind.user attribute.	XYZ
ldapConfig.search-base	Specifies the file name for the list of Organizational Units (OUs) to be searched against.	ad.search.base.list
ldapConfig.search-filter	Specifies the LDAP filter for retrieving user entries from AD. This does not need to be modified and should work for most organizations.	(&(objectClass=user)(objectClass= person)(objectClass=organization alPerson))
ldapConfig.response-type	This is a system defined template for processing the XML data. This should NOT be modified unless requested by the Support team.	/home/helptwps/dtd/ProcessXM LDocument.dtd
target-system-name	Specifies the target system name, however, the value is hardcoded to Luma.	Luma
target-export-format	Specifies the target export format, which is Excel.	Excel
exportFileLocation	Specify the export file location.	e:/exportrunner/conf/Template_for_Bulk_Upload.xlsx
exportSheetName	Specify the export sheet name.	Contacts
connection-type	Specifies the connection type however, the value is hardcoded to Luma.	Luma
base-url	Specify the base URL of the export.	Staging or Production URL
auth-api	Specify the authorization API, which is hardcoded to /public/tenant/login	/public/tenant/login
export-api	Specifies the export API, which is hardcoded to /tenant/@replace.tenantId/contact/upload.	/tenant/@replace.tenantId/contact/upload
username	Specify the user name.	admin@xxx.com
password	Specify the password to login.
subDomain	Specify the sub domain.

Following are details of the above script:

The supported connection types are REST

, SOAP

and LDAP.
Specify the source details such as
- Admin user's email ID
- Password
- Global catalog server URL
- Domain controller server URL
- Search base
- Search filter
- Response type
The next step is to map the source details with that of Luma. For example, to map the first name of the source data with Luma, specify the following.
- "importDataKey": "givenName",\
  Specify the source column name which is equivalent to the First Name in Luma.
- "exportDataKey": "First Name",\
  Specify the Luma column name which matches the column name to be mapped from the source.
- "staticColumn": "false",\
  If there is a mandatory field in Luma while mapping, however, that column is not available in the source file, then you can specify a static value for the column and specify the staticColumn as true. If the field is available in the source file, then specify it as false.
- "staticColumnName": "",\
  If there is a mandatory field in Luma while mapping, however, that column is not available in the source file, then you can specify the static column name as the standard field name available in Luma.
- "staticColumnValue": "",\
  Specify the static column value as per the staticColumn.
- "isTransformationNeeded": "false",\
  If you need transformation of any function specified in the javascriptxformation function, then specify the value as true, else specify it as false.
- "javascriptImportDataKeyReference": "firstName",\
  Specify an alias name to the importDataKey.
- "javascriptXformationFunciton": ""\
  You can execute a Javascript function to define the value of row for requirements such as string concatenation, truncation or to perform simple logic such as when to choose a user type as

admin

- Administrator or Analyst and so on.

Following is the sample contact sync property file for Freshservice using REST connection:

Code Block

title	Synctool properties
linenumbers	true

# comment
import-data-system.source-system-name = freshservice
# this can be only supported connection types (REST/SOAP/HTTP/LDAP/SQL) etc
import-data-system.connection-type = REST
# comment
import-data-system.http-is-rest = true
# comment
import-data-system.url = https://sample.freshservice.com/api/v2/requesters
# comment
import-data-system.http-method = GET
# comment
import-data-system.auth-type = basic
# comment
import-data-system.auth-token = xxx
# comment
import-data-system.http-headers = [{"headerName":"Content-Type","headerValue":"application/json"}]
# comment
import-data-system.http-url-parameters = [{"parameterName":"Content-Type","parameterValue":"application/json"}]
# comment
import-data-system.http-response-type = JSON# commentimport-data-system.http-response-root-json-path = $['requesters'][*]

...

Versions Compared

Old Version 9

New Version 10

Key

Verify System Requirements for SOAP API Supported System

Configure Files