IT Pro: How to read users from Active Directory on-premises

You can read users from Active Directory on-prem automatically, and then you do not need to add/update users manually in Xink.

When new users are created in your Active Directory, they are automatically added to your Xink EMPLOYEE list. 

It's all automatic, so hires and fires are reflected in Xink as soon as they're updated in your on-premise AD.
This is the easiest way for IT to maintain email signature information like name, mobile number, title etc. 

To try it out, you can start by running ADExport from your domain-joined PC. 

When successfully seeing users exported into Xink, you can always move it to a server and set it up as a scheduled task in a production environment. 

You can add additional information you may not want to maintain in AD, like LinkedIn, Twitter, headshots, Skype, etc.

Show examples

What exactly is exported?

ADExport is completely safe to run. Check out these bald facts about ADExport:

• ADExport does not make any changes to your AD.
• ADExport only reads data.
• ADExport cannot write or update any data anywhere in your AD.
• ADExport does not grab any passwords.
• ADExport exports only the data for a user you instruct to export (Preferences > Fields).
• ADExport means “Active Directory Export”, which again means “export of data from AD” — no import or updates.
• ADExport doesn’t export anything else but user information — no schema information or anything deeper is exported.

System requirements

• Windows PC or a Windows Server connected to the domain you plan to export users from.
• Unique email addresses not used in other Xink accounts are imported. 
  
• Latest .NET Service Pack. 
• Port 443 (HTTPS) enabled.
  Your antivirus software might prevent the file from running on your server, so you might need to allow the executable to run and access the internet through port 443.

• Make sure that all users you want to export have email addresses.

• DO NOT RUN the ADExport tool in Domain Controllers. Just use any domain-joined Windows PC.
  Only users with a primary SMTP email address will be exported to Xink portal:
  

Your Step-by-step Guide to Xink AD Export

Log into your Xink account > Click your name on the upper right - click on Preferences:

Go to Integration - Click Active Directory on the left-hand side - Download Export Tool and save in your file system.
It is a single file, and no installation is needed.

Create an API User

Assign permission to the newly created API user. The user must have an “Automated Employee Data Push” Permission. 

Finally, set up EMSADExport (Xink ADExport tool) to run daily through windows task scheduler on domain-joined PC (e.g. an application server, file server, etc.) You can choose your schedule depending on how often you want it to update data from your AD.

Before you read data from your Active Directory, scroll down to learn about the different switches and examples later in this guide.
Then, when you're ready, run the file manually to start with so you know it exports as expected before you schedule it to run on your server.

Start on your Windows domain PC. If you only need to export a group of users within your Active directory (e.g OU or AD group) then apply one of the switches described below (use the examples later in this guide).

How to run 'emsadexport' to export user contact details from your Active Directory on-prem to Xink Employees

You can run the file as: 

• .BAT, 
• .CMD or 
• Command Prompt, where you browse to the directory where you have saved it:
  

Export Switches

The export tool comes with a number of switches you can use. 

The switch can be added anywhere after the emsadexport file name.

The user and secret switch include your API username and API account. The result of this switch is that your AD data ends up in your Xink account.  

P.S. You always need to include the /secret switch when exporting

/user:"YourAPIAccount@SRV" /secret:"YourAPIAccountPassword"

Export only users who belong to a specific OU.

Users in sub-OUs are pulled.

Exports only users who belong to a certain group (both security groups and distribution groups are supported). 

The value of the switch is the group name from Active Directory (not the OU name).

Users in sub-groups (nested) are not pulled.

P.S: If the group contains blank space in the name, you need to write the Group name in quotes. 

Example: The Group name is 'Sales North America' so your switch will be /group:"Sales North America".

P.S.S: Reading from groups is much slower than reading from OUs. 

By default TLS 1.3 is enforced. This switch uses TLS 1.2

This switch removes users not included in the export. 

E.g. your Xink account has 100 users and next time it found only 2 users to export, then these 2 users will remain. All others will be deleted in Xink.  

C:\emsadexport.exe /user:"YourAPIAccount@SRV" /secret:"YourAPIAccountPassword" /remove+

This switch supports your own custom AD names if you have an AD with the extended schema.  Learn more. 

C:\emsadexport.exe /user:"YourAPIAccount@SRV" /secret:"YourAPIAccountPassword"  /field:ATTRIBUTE1 /field:ATTRIBUTE2 

You can enable LDAP over SSL (LDAPS) by using this switch.

When adding this switch nothing will actually be exported to your Xink account. It will display the users who will be included in the export. This switch is often used in connection with the initial setup to make sure that only a minor selection of users will be exported. Remember to remove the switch when you actually want to export the users.

C:\emsadexport.exe /user:"YourAPIAccount@SRV" /secret:"YourAPIAccountPassword" /nd /field:mail /field:displayname /field:telephoneNumber /field:title

This switch will pull user groups from the AD. It does not work when users are pulled from an OU. Learn more in this KB.

C:\emsadexport.exe /user:"YourAPIAccount@SRV" /secret:"YourAPIAccountPassword" /group:"My Test" /ug

Export all users from Active Directory with an email address:

C:\emsadexport.exe /user:"YourAPIAccount@SRV" /secret:"YourAPIAccountPassword"

This command will export users from this OU: 'OU=Users,OU=Company Name,DC=gt,DC=local'.
All other existing users in your Xink account will remain:    

C:\emsadexport.exe /user:"YourAPIAccount@SRV" /secret:"YourAPIAccountPassword" /domain:"OU=Users,OU=Company_1OU,DC=Company_1,DC=internal"

This command will export users from this OU: 'OU=Users,OU=Company Name,DC=gt,DC=local'.
All other existing users in your Xink account will be removed and only the users from this OU will be in your Xink account:    

C:\emsadexport.exe /user:"YourAPIAccount@SRV" /secret:"YourAPIAccountPassword" /domain:"OU=Users,OU=Company_1OU,DC=Company_1,DC=internal" /remove+

 How to find the distinguishedName of an OU:

This command will remove all users except for the users in the group 'Test Group':    

C:\emsadexport.exe /user:"YourAPIAccount@SRV" /secret:"YourAPIAccountPassword" /group:"Test Group" /remove+

This command will update two fields from your extended AD schema (no need to add default AD fields): 

C:\emsadexport.exe /user:"YourAPIAccount@SRV" /secret:"YourAPIAccountPassword" /field:manager /field:generationQualifier

Your enterprise incl. 3 companies; Company_1, Company_2 and Company_3.

You have a group marketing department and you want to collect all employee contact details in one corporate Xink account (with employee data from 3 domains).

You already assigned a role-based login to your group marketing team. 

You export from 3 different domains using the same API Username and Password (across domains):   

C:\emsadexport.exe /user:"YourAPIAccount@SRV" /secret:"YourAPIAccountPassword" /domain:"OU=Users,OU=Company_1OU,DC=Company_1,DC=internal"

C:\emsadexport.exe /user:"YourAPIAccount@SRV" /secret:"YourAPIAccountPassword"  /domain:"OU=Users,OU=Company_2OU,DC=Company_2,DC=internal"

C:\emsadexport.exe /user:"YourAPIAccount@SRV" /secret:"YourAPIAccountPassword"  /domain:"OU=Users,OU=Company_3OU,DC=Company_3,DC=internal"

This command will pull user groups for all users to the field mapped to 'groupCnList': (Learn more)

C:\emsadexport.exe /user:"YourAPIAccount@SRV" /secret:"YourAPIAccountPassword" /ug

This command will write log to C:\Xink:

C:\emsadexport.exe /user:"YourAPIAccount@SRV" /Secret:"YourAPIAccountPassword" > C:\Xink\Xink_log.txt

This command will import one target user and import to https://app.xink.io: 

C:\emsadexport.exe /user:"YourAPIAccount@SRV" /secret:"YourAPIAccountPassword"  /filter:”SAMAccountName=username"

How to map the DirectPhone field to your AD data

When you run AD Export it will update the user's details in Employees menu. 

Per default when you run AD Export all Employee data is updated and you do not need to configure anything else.

DirectPhone field sometimes must be re-mapped as it's not a default field in the AD. 

By default, DirectPhone data is updated from otherTelephone field in the AD. 

Preferences menu > Fields, click the 'gear wheel' and select edit: 

• Property Name is the LDAP name of the field that holds this field information.
• Use 'pager' property name if you store the direct tel. number in pager field in the AD.
  

How to map extensionAttribute fields to Xink fields 

• extensionAttribute1
• extensionAttribute15

How to schedule AD updates on an application server

Example - BAT file for a group which you schedule on a Windows File Server

START emsadexport.exe /user:"YourAPIAccount@SRV" /secret:"YourAPIAccountPassword" /group:"My Test" /remove+

Example - CMD file for a group which you schedule on a Windows File Server

"\\emsadexport.exe" /user:"YourAPIAccount@SRV" /secret:"YourAPIAccountPassword" /group:"My Test" /remove+

How to fix 'Proxy Authentication Required' when behind Proxy Server?

When you authenticate https://e.xink.io and https://e-eu.xink.io, 'Proxy Authentication Required' is gone:

Learn more

IT Pro: How to read groups from Active Directory (AD on-premises and Azure AD).