Overview
You can automate user group management with the TeamDynamix User Group Manager utility provided in this KB. This .NET 5.0/6.0 command-line utility will read user group data from all .CSV files in a monitored folder, connect to the TeamDynamix API and then save the new/updated data to the API. Processed files will then be moved to a processed folder. The script matches users based on the TeamDynamix (true) Username field as seen in Admin > Users & Roles > Users > Username column.
This utility is able to support the following use cases. Any use cases not outlined here are not supported.
- Add users to new groups without changing their existing groups.
- This means that any groups included in the spreadsheet for a given user will be appended to their existing group memberships.
- Notes:
- A user will not be removed from any existing groups not in the spreadsheet unless the RemoveAllOtherGroups column is set to True.
- If the spreadsheet includes a group a user is already in, their settings (e.g., IsNotified, IsManager) will be replaced with whatever is in the spreadsheet
- Replace a user's entire set of group memberships with a new set of groups.
- This is facilitated by setting the RemoveAllOtherGroups column to True for a user. This will remove all other groups and only add the user to the groups specified in the spreadsheet.
- Edit the IsNotified and IsManager settings for existing user group memberships.
- This means that if the spreadsheet includes a group that the user is already in, their settings (e.g., IsNotified, IsManager) will be replaced with whatever is in the spreadsheet.
- As this utility works with the TeamDynamix APIs, and there are currently no Groups API endpoints to bulk edit/update existing user group membership settings, edits are facilitated via a bulk removal and then a bulk add operation to properly "edit" settings.
- Log detailed validation exception errors, usually impacting multiple rows, to the specified "errors" directory
- Log 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 20MB and a total of 20 (rolling) log files will be preserved.
The utility works against the live APIs, meaning that all changes are immediate.
Minimum Server Requirements
The following minimum server requirements need to be met to run this utility:
- At least 2GB of RAM and a dual core CPU
- The ability to utilize TLS 1.2 or TLS 1.3 for outbound web requests on port 443 (https; secure)
- 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
- Version-Specific Requirements:
- For the latest version 1.2.0:
- A machine which can run .NET 6.0 or higher.
- .NET 6.0 Runtime or higher.
Install the most basic .NET 6 (or higher) Runtime option, not the SDK, ASP.NET Core Runtime or Desktop Runtime.
Be sure to use the Installers column downloads, not the raw Binaries column downloads!
- For the legacy version 1.1.0 (for .NET 5 compatibility):
- A machine which can run .NET 5.0 or .NET 6.0.
- .NET 5.0 Runtime or .NET 6.0 Runtime
Install the most basic .NET 5 or 6 Runtime option, not the SDK, ASP.NET Core Runtime or Desktop Runtime.
Be sure to use the Installers column downloads, not the raw Binaries column downloads!
TeamDynamix Version Support
The utility will work on all TeamDynamix instances on version 11.3 or higher.
How to Obtain the Utility
Download the TeamDynamix User Group Manager Utility 1.2.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 .csv files in comma-separated format. Semicolons, pipes or any other delimiter are not supported!. Files with no extensions or which are not .csv types are not supported!
Available CSV File Columns
A sample .csv file is included in the Attachments section named importdata.csv. The file contains the following columns:
- Username
Required
The TeamDynamix (true) Username field (as seen in Admin > Users & Roles > Users > Username column) of the user to update groups for.
- PrimaryGroupID
A value in this column or GroupIDs is required
The TeamDynamix group ID to set as the user's primary group. Leave blank or set to 0 when not adding or making changes to primary groups.
- GroupIDs
A value in this column or PrimaryGroupID is required
A comma-separated string of other TeamDynamix group IDs to add to the user.
- IsNotified
This setting is applied to all group IDs in the row. Use multiple rows for a user to set this option differently for different groups.
Whether or not the user will be notified from these groups. Valid values are true or false. Blank values, or not mapping this column, will evaluate to false.
- IsManager
This setting is applied to all group IDs in the row. Use multiple rows for a user to set this option differently for different groups.
Whether or not the user will be manager of these groups. Valid values are true or false. Blank values, or not mapping this column, will evaluate to false.
- RemoveAllOtherGroups
Whether or not to remove all pre-existing group memberships for this user. This controls whether group management operations will act as a "merge/append" action (false value) or a "replace" action (true value). Valid values are true or false. Blank values, or not mapping this column, will evaluate to false.
Usage and Scheduling
Command-line switches
The utility has the following command-line switches available for usage which are always applicable.
-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.
-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.
-m, --monitorFolder
Required. Do not include a trailing \ at the end of the folder path or you will see an Invalid Arguments error!
A Monitor folder for this utility to look for new user group management .csv files in. Any file found will be processed and then moved to the Processed folder. Valid file types include .csv only.
Example: C:\TeamDynamix\UserGroupImports\Monitor
-p, --processedFolder
Required. Do not include a trailing \ at the end of the folder path or you will see an Invalid Arguments error!
A Processed folder for the utility to move files to after it successfully processes them.
Example: C:\TeamDynamix\UserGroupImports\Processed
-e, --errorsFolder
Required. Do not include a trailing \ at the end of the folder path or you will see an Invalid Arguments error!
An Errors folder for the utility to store validation errors in. The Errors folder will be used to log invalid usernames and groups the utility is skipping in .txt files.
Example: C:\TeamDynamix\UserGroupImports\Errors
-v, --verboseLog
Whether or not to use verbose logging to get a more detailed look at each row being saved as files are processed. Excluding this flag will equate to a false value for this option.
-t, --testMode
Run this application in test mode. Test mode will validate that your API information is accurate to ensure that authentication works, that required .csv headers are present, that usernames and group IDs in the .csv file are present and valid, and give a preview of how much data (in how many batches) would be sent to the APIs. File data will not actually be posted to the TeamDynamix API though. Instead, files will be moved to the directory specified as the Processed folder. 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.UserGroupManager.exe (or TeamDynamix.ApiUtility.UserGroupManager.dll for cross-platform) via the appropriate terminal or command prompt for your machine. Be sure to use an account that has Read/Write permissions on the "monitor", "processed" and "errors" folder.
Windows-Specific Examples
View the Help Menu
TeamDynamix.ApiUtility.UserGroupManager.exe -h or TeamDynamix.ApiUtility.UserGroupManager.exe --help
Run in Test Mode
TeamDynamix.ApiUtility.UserGroupManager.exe -u "https://yourTeamDynamixDomain/TDWebApi/" -b "00000000-0000-0000-0000-000000000000" -w "00000000-0000-0000-0000-000000000000" -m "C:\TeamDynamix\GroupImports\Monitor" -p "C:\TeamDynamix\GroupImports\Processed" -e "C:\TeamDynamix\GroupImports\Errors" -t
Run in Non-Test Mode
TeamDynamix.ApiUtility.UserGroupManager.exe -u "https://yourTeamDynamixDomain/TDWebApi/" -b "00000000-0000-0000-0000-000000000000" -w "00000000-0000-0000-0000-000000000000" -m "C:\TeamDynamix\GroupImports\Monitor" -p "C:\TeamDynamix\GroupImports\Processed" -e "C:\TeamDynamix\GroupImports\Errors"
Run in Non-Test Mode with Verbose Logging
TeamDynamix.ApiUtility.UserGroupManager.exe -u "https://yourTeamDynamixDomain/TDWebApi/" -b "00000000-0000-0000-0000-000000000000" -w "00000000-0000-0000-0000-000000000000" -m "C:\TeamDynamix\GroupImports\Monitor" -p "C:\TeamDynamix\GroupImports\Processed" -e "C:\TeamDynamix\GroupImports\Errors" -v
Cross-Platform Examples
View the Help Menu
TeamDynamix.ApiUtility.UserGroupManager.dll -h or TeamDynamix.ApiUtility.UserGroupManager.dll --help
Run in Test Mode
TeamDynamix.ApiUtility.UserGroupManager.dll -u "https://yourTeamDynamixDomain/TDWebApi/" -b "00000000-0000-0000-0000-000000000000" -w "00000000-0000-0000-0000-000000000000" -m "C:\TeamDynamix\GroupImports\Monitor" -p "C:\TeamDynamix\GroupImports\Processed" -e "C:\TeamDynamix\GroupImports\Errors" -t
Run in Non-Test Mode
TeamDynamix.ApiUtility.UserGroupManager.dll -u "https://yourTeamDynamixDomain/TDWebApi/" -b "00000000-0000-0000-0000-000000000000" -w "00000000-0000-0000-0000-000000000000" -m "C:\TeamDynamix\GroupImports\Monitor" -p "C:\TeamDynamix\GroupImports\Processed" -e "C:\TeamDynamix\GroupImports\Errors"
Run in Non-Test Mode with Verbose Logging
TeamDynamix.ApiUtility.UserGroupManager.dll -u "https://yourTeamDynamixDomain/TDWebApi/" -b "00000000-0000-0000-0000-000000000000" -w "00000000-0000-0000-0000-000000000000" -m "C:\TeamDynamix\GroupImports\Monitor" -p "C:\TeamDynamix\GroupImports\Processed" -e "C:\TeamDynamix\GroupImports\Errors" -v
Scheduling the Utility
To run the utility on a schedule, use Windows Task Scheduler (or a similar scheduler utility for non-Windows environments) 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 "monitor", "processed" and "errors" folders or the utility may receive file access errors.