Merge pull request #312 from adobe-apiplatform/v2

prepare for v2.3rc2 build

Author: adobeDan

RELEASE_NOTES.md

@@ -1,13 +1,17 @@
 # Release Notes for User Sync Tool Version 2.3
 
-These notes apply to v2.3rc1 of 2017-11-20.
+These notes apply to v2.3rc2 of 2017-12-03.
 
 ## New Features
 
 User Sync can now connect to Okta enterprise directories.  Create an Okta configuration and use the new `--connector okta` command-line argument to select that connector.  See [the docs](https://adobe-apiplatform.github.io/user-sync.py/en/user-manual/advanced_configuration.html#the-okta-connector) for details.
 
 There is a new command-line argument `--connector` for specifying whether to get directory information via LDAP file, by reading a CSV file, or via the Okta connector.  The default connector is `ldap`.  For CSV users, who formerly had to specify their input source with the `--users` argument, this optional argument offers the chance to specify `--users mapped` or `--users group ...` (since the CSV input can be specified with `--connector`).  See [the docs](https://adobe-apiplatform.github.io/user-sync.py/en/user-manual/command_parameters.html) for details.
 
+[#292](https://github.com/adobe-apiplatform/user-sync.py/issues/292) You can now specify the log file name as well as the log file directory in your configuration file.  The name is specified by giving a Python format string which, when applied to a Python `datetime` value at the start of the run, produces the name of the log file.  The default value of this string is backwards-compatible with prior User Sync behavior.  See [the docs](https://adobe-apiplatform.github.io/user-sync.py/en/user-manual/configuring_user_sync_tool.html#configure-logging) for details.
+
+[#299](https://github.com/adobe-apiplatform/user-sync.py/issues/299) You can now use an `invocation_defaults` section to specify desired values for command-line arguments in the main configuration file.  This can make it a lot easier to repeat runs with a stable set of arguments, even when running interactively rather than from a script.  The sample main configuration file specifies the configuration parameters to use as well as the syntax for specifying values.  See [the docs](https://adobe-apiplatform.github.io/user-sync.py/en/user-manual/command_parameters.html) for full details.
+
 ## Bug Fixes
 
 [#305](https://github.com/adobe-apiplatform/user-sync.py/issues/305) General issues with Okta connector.

docs/en/FAQ/index.md

@@ -123,7 +123,7 @@ User Sync is an open source python project.  Users can build for any OS platform
 
 ### Has this been tested on python 3.5?
 
-User Sync has been run successfully on Python 3.x, but most of our use and testing is on Python 2.7 so you may discover problems, and we only provide builds on Python 2.7.  Feel free to report problems (and contribute fixes) to the open source site at https://github.com/adobe-apiplatform/user-sync.py.
+User Sync has been run successfully on Python 3.x.  We started development with 2.7 but most work is now on the Python 3.6.x series and Python 3 builds are available for recent releases.  Feel free to report problems (and contribute fixes) to the open source site at https://github.com/adobe-apiplatform/user-sync.py.
 
 ### If something changes in the API (new field in creating users, for example ) how will the update  be applied to the user sync tool?
 

docs/en/success-guide/command_line_options.md

@@ -21,7 +21,8 @@ The command line for user sync selects the set of users to be processed, specifi
 |   `--users group "g1,g2,g3"`  |    The named directory groups are used to form the user selection. <br>Users that are members of any of the groups are included.  |
 |   `--users mapped`  |    The same as `--users group g1,g2,g3,...`, where `g1,g2,g3,...` are all the directory groups specified in the configuration file group mapping.|
 |   `--users file f`  |    The file f is read to form the selected set of users.  The LDAP directory is not used in this case. |
-|   `--user-filter pattern`    |  Can be combined with the above options to further filter and reduce the user selection. <br>`pattern` is a string in Python regular expression format.  <br>The user name must match the pattern in order to be included.  <br>Writing patterns can be somewhat of an art.  See examples below or refer to the Python documentation [here](https://docs.python.org/2/library/re.html). |
+|   `--user-filter pattern`    |  Can be combined with the above options to further filter and reduce the user selection. <br>`pattern` is a string in Python regular expression format.  <br>The user name must match the pattern in order to be included.  <br>Writing patterns can be somewhat of an art.  See examples below or refer to the Python documentation [here for Python 2.x](https://docs.python.org/2/library/re.html) and [here for Python 3.x](https://docs.python.org/3/library/re.html). |
+{: .bordertablestyle }
 
 
 If all users listed in the directory are to be synced to Adobe, use `--users all`.  If only some users, you can limit the set by altering the LDAP query in the `connector-ldap.yml` configuration file (and use `--users all`), or you can limit the users to those in specific groups (by using --users group).  You can combine either of these with a `--user-filter pattern` to further limit the selected set of users to be synced.
@@ -51,7 +52,7 @@ Note that only the users returned by the directory query and filter are consider
 |   `--adobe-only-user-action remove`  |    Adobe account to remain but licenses, group memberships, and listing in the Adobe Admin console are removed   |
 |   `--adobe-only-user-action delete`  |    Adobe account to be deleted: remove from<br>Adobe product configurations and user groups; account deleted and all storage and settings freed. |
 |   `--adobe-only-user-action write-file f.csv`    |  No action to be taken on the account.  User name written to file for later action. |
-
+{: .bordertablestyle }
 
 
 

docs/en/success-guide/install_sync.md

@@ -12,17 +12,26 @@ nav_order: 270
 
 Once you have access to the server where User Sync will run, pick a directory where you will install and operate User Sync.
 
-On Windows, you will need to install Python.  As of this writing, version 2.7.13 is recommended.  Windows and Python need to be 64 bit versions.
+On Windows, you will need to install Python.  As of this writing, version 3.6.x is recommended.  Windows and Python need to be 64 bit versions.
+
+On Windows, you also are very likely to need to set an environment variable PEX\_ROOT to C:\\pex.  This is needed to work around Windows pathname length limits.
+
+Note: Setting PEX\_ROOT may not be necessary if:
+
+- You are running Windows 10
+- You are running Python 3.6 or later, 64 bit version (also called X86-64, for AMD64), and
+- You have enabled the long pathname support in Windows 10 as described in the Maximum Path Length Limitation section of this [Microsoft Dev Note](https://msdn.microsoft.com/en-us/library/windows/desktop/aa365247%28v=vs.85%29.aspx?#maxpath). You can also enable long pathname support by pressing the button in the Python Windows executable installer (in the final dialog box, when installation finishes) that performs this action.
+
+If these conditions are met, you can run without setting PEX\_ROOT.
 
-On Windows, you also are very likely to need to set an environment variable PEX_ROOT to C:\user_sync\.pex.  This is needed to work around Windows pathname length limits.
 
 Initial steps:
 
 ☐ Setup a user and file directory for installing and running sync.  For example, we'll create a folder /home/user_sync/user_sync_tool and a user user_sync.  On Windows an example would be C:\Users\user_sync\user_sync_tool.
 
-☐ Windows only: set the environment variable **PEX\_ROOT** to **C:\user_sync\.pex**.
+☐ Windows only: set the environment variable **PEX\_ROOT** to **C:\pex**. (But see note above.)
 
-☐ Windows only: Install python 2.7.13 (or later in the 2.7 series), 64 bit. 
+☐ Windows only: Install python 3.6.2 (or later in the 3.6 series), 64 bit. 
 
 The next few sections show the installation process.
 
@@ -38,7 +47,9 @@ Select “release”
 
 ☐ 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.
+☐ Decide whether you will run Python 2.x or 3.x (recommended) and download that version of User Sync.  You need to install the corresponding version of Python on your server.
+
+☐ 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 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.