V2 doc update

docs/success-guide/command_line_options.md

@@ -55,7 +55,7 @@ Note that only the users returned by the directory query and filter are consider
 
 `--test-mode`:  causes User Sync to run through all processing including querying the directory and calling the Adobe User Management APIs to process the request, but no actual action is taken.  No users are created, deleted, or altered.
 
-`--update-user-info`: causes User Sync to check for changes in first name, last name, or email address of users and make updates to the Adobe information if it does not match the directory information.  Specifying this option increases run time so you may not want to include it on each run.
+`--update-user-info`: causes User Sync to check for changes in first name, last name, or email address of users and make updates to the Adobe information if it does not match the directory information.  Specifying this option may increase run time.
 
 
 ## Examples

docs/success-guide/install_sync.md

@@ -32,11 +32,11 @@ Select “release”
 
 ![install2](images/install_release_screen.png)
 
-☐ Download the examples.config.tar.gz, User Sync Guide, and build for your platform, osx, ubuntu, windows, or centos.
+☐ Download the example-configurations.tar.gz, User Sync Guide, and build for your platform, osx, ubuntu, windows, or centos.
 
 ☐ Extract the user-sync (or user-sync.pex) file from the archive and place the file for your OS in the folder.  In our example, this would be /home/user_sync/user_sync_tool/user-sync or C:\Users\user_sync\user_sync_tool\user-sync.pex.
 
-☐ In the examples.config.tar.gz file there is a directory **config files - basic**.  From this folder extract the first 3 files and place in the user_sync_tool folder.  
+☐ In the example-configurations.tar.gz file there is a directory **config files - basic**.  From this folder extract the first 3 files and place in the user_sync_tool folder.  
 
 ☐ Next, rename the 3 config example files by removing the leading "1 ", "2 ", and "3 " from the names.  We will edit these files to create the real User Sync configuration files.
 

docs/success-guide/layout_products.md

@@ -21,11 +21,12 @@ You can use User Sync to manage PC membership and license allocation.  This is o
 
 User Sync helps you manage Adobe product licenses by allowing you to place users into directory groups using the directory system interface or other tools.  Those groups are then mapped to Adobe user groups or PCs.  The mapping is part of the User Sync configuration file.  When User Sync detects that directory users are in one of these mapped groups, the user is added to the corresponding Adobe user group or PC.  Similarly, users in the user group or PC but not in the corresponding directory group are removed from the user group or PC.
 
-☐ Decide if you will manage license allocation using User Sync.  If not, you can skip the remaining steps for now, but you will still need to do them and manually add users to the user groups or PCs later using the Adobe Admin Console. 
+☐ Decide if you will manage license allocation using User Sync.  If not, you can skip the remaining steps; however, before the users you create can access Adobe products, you will need to manually add them to product configurations using the Adobe Admin Console. 
 
-☐ Create the PCs in the Adobe Admin console for the configurations of products and groups of users you will be managing.
+☐ Create the PCs in the Adobe Admin console for the product configurations and groups of users you will be managing.  Add the comment "Managed by User Sync - do not edit" to the description field of the PC.
+
+☐ If you are going to use User Groups to manage product access, you will need to first create the user groups and the product configurations, then you can manage product access by adding each user group to the appropriate product configurations. Add the comment "Managed by User Sync - do not edit" to the description field of the user group.
 
-☐ If you are going to use User Groups, create them and add them to the PC(s) representing product licenses to be issued to members of the user group.
 
 ☐ Draw a diagram of your Adobe organizations, and the products and PCs in each.  Add the directory and directory groups to the picture and show the mapping.  For example:
 

docs/success-guide/scheduling.md

@@ -12,7 +12,7 @@ layout: default
 First, create a batch file with the invocation of user-sync piped to a scan to pull out relevant log entries for a summary.  Create the file run_sync.bat for this with contents like:
 
 	cd user-sync-directory
-	python user-sync.pex --users file example.users-file.csv --process-groups | findstr "==== ----- WARNING ERROR CRITICAL" > temp.file.txt
+	python user-sync.pex --users file example.users-file.csv --process-groups | findstr /I "==== ----- WARNING ERROR CRITICAL Number" > temp.file.txt
 	rem email the contents of temp.file.txt to the user sync administration
 	your-mail-tool –send file temp.file.txt
 
@@ -34,7 +34,8 @@ Note that often when setting up scheduled tasks, commands that work from the com
 First, create a shell script with the invocation of user-sync piped to a scan to pull out relevant log entries for a summary.  Create the file run_sync.sh for this with contents like:
 
 	cd user-sync-directory
-	./user-sync --users file example.users-file.csv --process-groups |  grep "CRITICAL\\|WARNING\\|ERROR\\|=====\\|-----" | mail -s “Adobe User Sync Report for `date +%F-%a`” Your_admin_mailing_list@example.com
+	./user-sync --users file example.users-file.csv --process-groups |  grep "CRITICAL\\|WARNING\\|ERROR\\|=====\\|-----\\|number of\\|Number of" | mail -s “Adobe User Sync Report for `date +%F-%a`” 
+    Your_admin_mailing_list@example.com
 
 
 You need to fill in your specific User Sync command line options and the email address to which the report should be sent.

docs/success-guide/setup_adobeio.md

@@ -18,7 +18,7 @@ Setup steps are documented.  For complete information about the integration setu
 - Once setup, the Adobe.io console displays all needed values.  You’ll copy these into the user sync configuration file.
 - You'll also need to add the private key file to the User Sync configuration.
 
-☐ Obtain or create a digital signing certificate.  See [insteuctions for certificate creation](https://www.adobe.io/apis/cloudplatform/usermanagement/docs/setup/createcert.html).
+☐ Obtain or create a digital signing certificate.  See [instructions for certificate creation](https://www.adobe.io/apis/cloudplatform/usermanagement/docs/setup/createcert.html).
 
 ☐ Setup an adobe.io integration for each organization you need to access (usually only one).  See Step 2 and 3 on this [page](https://www.adobe.io/apis/cloudplatform/usermanagement/docs/setup.html)
 

docs/success-guide/setup_config_files.md

@@ -28,7 +28,7 @@ In previous steps, you set up a file system directory for the user sync tool Pyt
 
 ### Directory Access Configuration File
 
-If you are driving User Sync from a file, you can skip this step.  Setup a csv file with your entire user list following the "csv inputs - user and remove lists/1 users-file.csv" file example.  This file is in the examples.config.tar.gz download from the release.
+If you are driving User Sync from a file, you can skip setting up connector-ldap.yml and instead create a csv file with your entire user list following the "csv inputs - user and remove lists/1 users-file.csv" file example.  This file is in the example-configurations.tar.gz download from the release.
 
 ☐ Edit the file connector-ldap.yml.  This file has access information to the directory system.  Put in username, password, host, and base_dn values.
 
@@ -43,7 +43,7 @@ If you need a non-default LDAP query to select the desired set of users, it is s
 
 ☐ Edit the connector-umapi.yml.  Put in the information from the adobe.io integration you created earlier.  This would be the org\_id, api\_key, client\_secret, and tech\_acct.
 
-☐ Place the private key file in the user_sync_tool folder The priv\_key\_path config file items is then set to the name of this file.
+☐ Place the private key file in the user_sync_tool folder. The priv\_key\_path config file item is then set to the name of this file.
 
 ![](images/setup_config_umapi.png)
 
@@ -59,7 +59,8 @@ Edit the user-sync-config.yml file.
 	  # example:
 	  # default_country_code: US
 
-If your directory does not list a country for each user, you can set a default country here.  Remove the "# " from the default country code line so it looks like this
+
+☐ If your directory does not list a country for each user, you can set a default country here.  Remove the "# " from the default country code line so it looks like this
 
 	  default_country_code: US
 
@@ -103,7 +104,7 @@ A more realistic example is:
 	  groups:
 	    - directory_group: acrobat_pro_dc
 	      adobe_groups: 
-	        - Default Acrobat Pro DC configuration
+	        - Default Acrobat_Users
 	    - directory_group: all_apps
 	      adobe_groups:
 	        - All Apps
@@ -116,22 +117,22 @@ A more realistic example is:
 
 Limits on deletion prevent accidental account deletion in the event of misconfiguration or some other problem that results in User Sync not getting proper data from the directory system.
 
-☐ If you expect the number of directory users to drop by more than 200 between User Sync runs, then you will need to raise the `max_adobe_only_users` value.  These config file entries are to prevent runaway deletion in case of misconfiguration or other problems.
+☐ If you expect the number of directory users to drop by more than 200 between User Sync runs, then you will need to raise the `max_adobe_only_users` value.  This config file entry prevents runaway deletion in case of misconfiguration or other problems.
 
 	limits:
-	    max_adobe_only_users: 200      # abort if this many directory users disappear
+	    max_adobe_only_users: 200      # abort updates if this many directory users disappear
 
 
 
 #### Delete Protection
 
 If you want to drive account creation and removal through User Sync, and want to manually create a few accounts then you may need this feature to keep User Sync from deleting your manually created accounts.
 
-☐ If you need to use this feature, add lines such as below to the config file at the top level.   To protect users on the Admin Console from updates, create a user group and put the protected users into that group, then list that group as excluded from User Sync processing.  You can also list specific users and/or a pattern that matches specific user names to protect those users.  You can protect users based on their identity type as well.  For example, often User Sync is used only to manage federatedID or enterpriseID user types and you can exclude adobeID type users from management by User Sync.  You only need to include configuration items for exclusions that you wish to use.
+☐ If you need to use this feature, add lines such as below to the config file under adobe_users.   To protect users on the Admin Console from updates, create a user group and put the protected users into that group, then list that group as excluded from User Sync processing.  You can also list specific users and/or a pattern that matches specific user names to protect those users.  You can protect users based on their identity type as well.  For example, often User Sync is used only to manage federatedID or enterpriseID user types and you can exclude adobeID type users from management by User Sync.  You only need to include configuration items for exclusions that you wish to use.
 
 ```YAML
 adobe_users:
-  exclude_groups: 
+  exclude_adobe_groups: 
     - administrators   # Names an Adobe user group or product configuration whose members are not to be altered or removed by User Sync
     - contractors      # You can have more than one group in a list
   exclude_users:
@@ -156,9 +157,10 @@ Note that:
 
 - Directory side users are still created on the Adobe side even if one of the exclude parameters would then exclude the user on the Adobe side from updates in successive runs. That is, these parameters apply only to Adobe users who exist when the Adobe directory is being matched against the customer directory.
 
-- Accounts that would have been removed or updated but were not because of this feature are listed as `info` level log entries.
+- Accounts that would have been removed or updated but were not because of this feature are listed as `debug` level log entries.
 
 - Federated accounts that are not in the directory or are disabled in the directory cannot log in anyway (because login is handled by the ID provider and the user is no longer listed there) even if the account still exists in Adobe.
+- You will likely want to exclude identities of type adobeID because they are usually not listed in the enterprise directory.
 
 
 
@@ -170,7 +172,7 @@ log\_to\_file turns the file log on or off.
 
 Messages can be on one of 5 level of importance and you can choose the lowest importance that will be included for either the file log or standard output log to the console.  The defaults are to produce the file log and to include messages of level "info" or higher.  This is the recommended setting.
 
-☐ Review the settings for logs and make any desired changes.
+☐ Review the settings for logs and make any desired changes.  The recommended log level is info (which is the default).
 
 	logging:
 	  # specifies whether you wish to generate a log file

docs/success-guide/test_run.md

@@ -26,19 +26,19 @@ Give it a try:
 ☐ Next, try a sync limited to a single user and run in test mode.  You need to know the name of some user in your directory.  For example, if the user is bart@example.com, try:
 
 
-	./user-sync -t --users all --user-filter bart@example.com 
+	./user-sync -t --users all --user-filter bart@example.com --adobe-only-user-action exclude
 
-	./user-sync -t --users all --user-filter bart@example.com --process-groups
+	./user-sync -t --users all --user-filter bart@example.com --process-groups --adobe-only-user-action exclude
 
-The first command above will sync only the one user (because of the user filter) which should result in an attempt to create the user.  Because of running in test mode (-t), the run of user-sync will only attempt to create the user and not actually do it.
+The first command above will sync only the one user (because of the user filter) which should result in an attempt to create the user.  Because of running in test mode (-t), the run of user-sync will only attempt to create the user and not actually do it.  The `--adobe-only-user-action exclude` option will prevent updates to any user accounts that already exist in the Adobe organization.
 
 The second command above (with the --process-groups option) will attempt to create the user and add them to any groups that are mapped from the their directory groups.  Again, this is in test mode so no actual action will be taken.  If there are already existing users and the groups have users already added to them, user-sync may attempt to remove them.  If this is the case, skip the next test.  Also, if you are not using directory groups to manage product access, skip the tests that involve --process-groups.
 
 ☐ Next, try a sync limited to a single user and don't run in test mode.  This should actually create the user and add to groups (if mapped). 
 
-	./user-sync --users all --user-filter bart@example.com --process-groups
+	./user-sync --users all --user-filter bart@example.com --process-groups --adobe-only-user-action exclude
 
-	./user-sync --users all --user-filter bart@example.com --process-groups
+	./user-sync --users all --user-filter bart@example.com --process-groups --adobe-only-user-action exclude
 
 ☐ Next, go check on the Adobe Admin Console if the user has appeared and the group memberships have been added.