Using the TeamDynamix People Import Utility

This article assumes that you have already read through and understand the Related Article named Using the TDWebApi People Import API to sync users between your organization and TeamDynamix (ID 4191). If you have reached this article without reading article 4191, it is strongly recommended to go back and read article 4191 first.

Overview

The TeamDynamix People Import Utility is a .NET command-line program which can:

  1. Watch a specified folder for "pending" files to submit to the TeamDynamix Web API for processing. Files are submitted to /api/people/import endpoint.
  2. Move files successfully submitted to the TeamDynamix Web API to the specified "submitted" directory.
  3. Move files which could not be submitted to the TeamDynamix Web API to the specified "failed" directory.
  4. Logs all activity to a logfile.log file for later review. Logs are generated in the directory where the utility is located. Log files will rollover at 5MB and a total of 5 (rolling) log files will be preserved.

This utility essentially helps to facilitate submitting files to the TeamDynamix /api/people/import endpoint. It does not actually process the imports or provide status updates on the import jobs later. Its only function is to post files from the "pending" directory to the TeamDynamix API for later processing by the import processors. You can read more details about how the imports received by the API are actually processed in the Related Article about how to sync your organization's users with TeamDynamix.

Suggested Implementation Steps and Reading Plan For New Clients

  1.  Read the Table of Contents (TOC) sections #1-4.
  2.  Download, unblock and extract the appropriate utility zip file (outline in TOC item #3).
  3.  Read TOC section #6.
  4.  Create folders on your server for pending upload files (-pendingDirectory), successfully submitted files (-submittedDirectory) and failed to upload files (-failedDirectory) based on the example in TOC item #6 flags. Replace the example paths with the actual paths you want these folders to reside.
  5.  Refer to TOC item #6 usage examples for how to run the utility manually before you might have it configured in a scheduler utility.
  6.  Read TOC section #6 Scheduling the Utility subsection for information about how to schedule the utility to run regularly. This requires usages of a scheduling utility like Windows Task Scheduler.
  7.  For information about how files are processed, how to format import files, and more info about the import process in general, refer to TOC section #7.

What This Article Will Not Cover

This article is not a guide for the following things:

  • How to generate customer user/people data to sync. That is the responsibility of the client to programmatically create and maintain. 
  • What data is expected/supported by the people import, or the format of columns/headers in the data file. This is outlined in the Related Article named Using the TDWebApi People Import API to sync users between your organization and TeamDynamix (ID 4191).
  • How the People Import Utility API works, processes data, and other specific details about the import. This is outlined in the Related Article named Using the TDWebApi People Import API to sync users between your organization and TeamDynamix (ID 4191).
  • How to troubleshoot issues with customer server command-line/terminal syntax.
  • How to troubleshoot issues with customer server scheduler systems.
  • How to troubleshoot database connectivity issues (if using the direct database options).
  • How to troubleshoot SQL query syntax or errors (if using the direct database options).

Table of Contents

  1. Minimum Server Requirements
  2. TeamDynamix Version Support
  3. How to Obtain the Utility
  4. Supported File Types
  5. Breaking Changes
  6. Usage and Scheduling
  7. API Processing Details

Minimum Server Requirements

The following minimum server requirements need to be met to run this utility:

  • A Windows computer/server with the ability to utilize TLS 1.2 or TLS 1.3 for outbound web requests on port 443 (https; secure)
  • A Windows computer/server with the ability to utilize one of the supported TLS 1.2 or TLS 1.3 cipher suites listed in our SSL Labs report:
    https://www.ssllabs.com/ssltest/analyze.html?d=solutions.teamdynamix.com
  • .NET Framework 4.7
  • At least 2GB of RAM and a dual core CPU

TeamDynamix Version Support

Use the following application download from the Files section based upon your TeamDynamix version:

  • 10.3 and up - TeamDynamix People Import Utility 3.1.0.zip
  • 9.0-10.2 - TeamDynamix People Import Utility 2.0.1.zip

How to Obtain the Utility

Download the TeamDynamix People Import Utility 3.1.X.zip file from the Attachments section. Unblock the .zip file and extract it to the location you wish it to run from.

Be sure to unblock the .zip file after downloading it or you may run into file access issues when using it! This requires opening the file's Properties dialog and choosing to unblock the file if it shows as blocked.

Supported File Types

The utility supports all of the following file types:

  • XLSX
  • XLS
  • CSV Comma delimited only. Semicolon, pipe, tab or other delimiters are not supported.

If the utility encounters CSV or XLS files, it will attempt to convert them to XLSX files for submission to the TeamDynamix Web API (as the API only accepts XLSX files). If the files can be successfully converted to XLSX, the XLSX file will be submitted to the API and then both files will be moved to the specified "submitted" or "failed" directory. Converted files will be named OriginalFileName_converted.xlsx.

Files with no extensions or which are not included in the list of allowed file types are not supported.

Breaking Changes

  • Version 3.0.0
    • The notifyEmailAddress flag was renamed to notifyEmailAddresses to support multiple notification email addresses. If you do not update the flag name in your commands, notify email addresses will not be sent up to the API properly! Should you still need to use the 2.0.1 version of the utility, be sure to use the singular notifyEmailAddress flag.

Usage and Scheduling

Command-line switches

The utility has the following command-line switches available for usage which are always applicable.

Please note that any switch marked as New for VERSION is only available starting in the utility marked as compatible for that TeamDynamix version. They will not be available in previous versions of the utility. For example, switches that are new for 10.3 are only available in the 3.1 utility designated for versions 10.3 and up. They will not work in the 2.0 utility designated for versions 9.0 - 10.2.
Always applicable switches

-u, --apiBaseUrl
Required.
The base URL to the TeamDynamix Web API (typically ending with "/TDWebApi/"). Be sure to use your organization's custom domain URL for best results.

SaaS Production Example: https://yourTeamDynamixDomain/TDWebApi/
SaaS Sandbox Example: https://yourTeamDynamixDomain/SBTDWebApi/
Install (On-Prem) Example: https://yourUrlToTDWebServer/TDWebApi/

-b, --apiBeid
Required.
The TeamDynamix Web Services BEID value. This is found in the TDAdmin application organization details page. In this page, there is a Security box which shows the Web Services BEID value if you have the Admin permission to Add BE Administrators. You will need to generate a web services key and enabled key-based services for this value to appear.

-w, --apiWebServicesKey
Required.
The TeamDynamix Web Services Key value for an Admin Service Account. This is found in the TDAdmin application organization details page. In this page, there is a Security box which shows the Admin Service Accounts section if you have the Admin permission to Add BE Administrators. You will need to have at least one active admin service account to get a web services key (create or activate one if necessary). Get the Web Services Key value from the desired admin service account to use for this value.

-p, --pendingDirectory
Required. Do not include a trailing \ at the end of the folder path or you will see an Invalid Arguments error!
A Pending directory for this utility to look for new files to send to the TeamDynamix People Import API. Any file found will be submitted to the /TDWebApi/api/people/import endpoint and then moved to the Submitted directory. Valid file types include .csv, .xls and .xlsx. Files of type .csv or .xls will be converted to .xlsx by this utility and then the converted file will be posted to the API. When a conversion happens, both the original and converted files will be moved to the Submitted or Failed directory after submission to the TeamDynamix Web API.

Example: C:\TeamDynamix\PeopleImports\Pending

-s, --submittedDirectory
Required. Do not include a trailing \ at the end of the folder path or you will see an Invalid Arguments error!
A Submitted directory for the utility to move files to after it successfully submits them to the TeamDynamix Web API for processing.

Example: C:\TeamDynamix\PeopleImports\Submitted

-f, --failedDirectory
Required. Do not include a trailing \ at the end of the folder path or you will see an Invalid Arguments error!
A Failed directory for the utility to move files to if the submission to the TeamDynamix Web API fails. Files will be moved to this directory when an unsupported file type is detected in the Pending directory, if a .csv or .xls file cannot be converted to a .xlsx file for some reason, if authentication to the API fails or the actual POST to /TDWebApi/api/people/import/ fails. If a file is moved to the Failed directory, you can check the logfile.log file for more details about the reason for failure.

Example: C:\TeamDynamix\PeopleImports\Failed

-n, --notifyEmailAddresses
Changed for 10.3
The email address(es) to notify after people imports are processed server-side. To specify multiple values, use a comma as the separator. Notifications will be sent out after processing regardless of whether or not the job is successful or not. Please note that this setting is not for notifying the specified addresses that an upload is posted. It is for after the import is processed by TeamDynamix.

The long name for this switch was previously --notifyEmailAddress since the API only supported a single notify email address. As of TeamDynamix version 10.3, the API supports multiple alert email addresses, so the switch long name was renamed to reflect this.

--batchSize
The row threshold at which to automatically split files. A value of 0 or lower means that no file splitting will occur. A value greater than 0 means to split files in the pending directory into separate smaller files with a batch size of the value specified. In direct database connection mode, a value greater than 0 means to transform the query results into multiple files based upon the specified batch size. The default value is 0 (no batching).

-i, --allowIsActiveChanges
New for 10.3
Whether or not to allow changes to user active status or not. This option only applies to updates for existing user records. If records have to be created, all created records will be set as active. Excluding this flag will equate to a false value for this option.

-r, --allowSecurityRoleChanges
New for 10.3
Whether or not to allow changes to user security roles. This option is specifically for updates to existing user records. Excluding this flag will equate to a false value for this option.

-a, --allowApplicationChanges
New for 10.3
Whether or not to allow changes to application access. This option is specifically for updates to existing user records of type User. Excluding this flag will equate to a false value for this option.

-v, --verifyAndFixXlsxReadErrors
New for 11.4
Occasionally, when a native .xlsx file is passed to the utility which needs no conversion or file splitting (batching), errors are encountered during server-side processing related to Bad signature (X) at position Y exceptions. If, and only if, you are experiencing this issue, you may need to opt into this flag. When enabled, the utility will attempt to open the .xlsx file for reading. If this action fails, it will re-save the file before submitting to the API to correct read errors. If the re-saved file still cannot be read, it will be moved to the Failed directory with an appropriate message logged. This flag can be used in conjunction with the --batchSize flag for cases where the incoming file is not large enough to split. Again, only use this flag if you are experiencing this issue as it does incur heavier resource usage.

-t, --testMode
Run this application in test mode. Test mode will validate  your API information to ensure that authentication works. Files will not actually be posted to the TeamDynamix API though. Instead, they will be moved to the directory specified as the Submitted directory. If the processor detects a .csv or .xls file, the file will still be converted to .xlsx in test mode. Simply including the -t flag will turn on test mode. To run in non-test mode, do not include the -t flag.

-h, --help
Display the help screen.

Example Usage

To run the utility, navigate to the extracted files and call TeamDynamix.ApiUtility.PeopleImporter.exe via the Windows Command Prompt with an account that has Read/Write permissions on the "pending", "submitted" and "failed" directories.

View the Help Menu
TeamDynamix.ApiUtility.PeopleImporter.exe -h or TeamDynamix.ApiUtility.PeopleImporter.exe --help

Run in Test Mode

TeamDynamix.ApiUtility.PeopleImporter.exe -u "https://yourTeamDynamixDomain/TDWebApi/" -b "00000000-0000-0000-0000-000000000000" -w "00000000-0000-0000-0000-000000000000" -p "C:\TeamDynamix\PeopleImports\Pending" -s "C:\TeamDynamix\PeopleImports\Submitted" -f "C:\TeamDynamix\PeopleImports\Failed" -n "user1@example.edu,user2@example.edu" -irat

Run in Non-Test Mode
To opt into all of the new people import options added in TeamDynamix version 10.3, be sure include -ira in your command as shown in the example below. If you do not wish to enable these options yet, remove -ira from your command before running it.

TeamDynamix.ApiUtility.PeopleImporter.exe -u "https://yourTeamDynamixDomain/TDWebApi/" -b "00000000-0000-0000-0000-000000000000" -w "00000000-0000-0000-0000-000000000000" -p "C:\TeamDynamix\PeopleImports\Pending" -s "C:\TeamDynamix\PeopleImports\Submitted" -f "C:\TeamDynamix\PeopleImports\Failed" -n "user1@example.edu,user2@example.edu" -ira

The utility has the following database-related command-line switches.

Database-related switches

Scheduling the Utility

To run the utility on a schedule, use Windows Task Scheduler (or a similar scheduler utility) to run the program with the appropriate arguments (command-line switches) and on the desired schedule. Be sure to run your task as an account which will have Read/Write permissions on the "pending", "submitted" and "failed" directories or the utility may receive file access errors.

API Processing Details

To read more details about how the submitted files are processed by the TeamDynamix API, read the Related Article about how to sync your organization's users with TeamDynamix.

100% helpful - 8 reviews
Print Article