Merge 2.0rc1 sources to master for widespread release.

This will get the docs staged out to the [gihub.io](https://adobe-apiplatform.github.io/user-sync.py/) site.

Author: adobeDan

README.md

@@ -61,76 +61,22 @@ To set up PyCharm for debugging,
 
 # Basic Usage
 
-```
-Adobe Enterprise Dashboard User Sync
-
-optional arguments:
-  -h, --help            show this help message and exit
-  -v, --version         show program's version number and exit
-  -t, --test-mode       run API action calls in test mode (does not execute
-                        changes). Logs what would have been executed.
-  -c, --config-filename filename
-                        main config filename. (default: "user-sync-
-                        config.yml")
-  --users all|file|mapped|group [arg1 ...]
-                        specify the users to be considered for sync. Legal
-                        values are 'all' (the default), 'group name or names'
-                        (one or more specified groups), 'mapped' (all groups
-                        listed in configuration file), 'file f' (a specified
-                        input file).
-  --user-filter pattern
-                        limit the selected set of users that may be examined
-                        for syncing, with the pattern being a regular
-                        expression.
-  --source-filter connector:file
-                        send the file to the specified connector (for example,
-                        --source-filter ldap:foo.yml). This parameter is used
-                        to limit the scope of the LDAP query.
-  --update-user-info    if user information differs between the customer side
-                        and the Adobe side, the Adobe side is updated to
-                        match.
-  --process-groups      if the membership in mapped groups differs between the
-                        customer side and the Adobe side, the group membership
-                        is updated on the Adobe side so that the memberships
-                        in mapped groups matches the customer side.
-  --remove-nonexistent-users
-                        Causes the user sync tool to remove users that exist on
-                        the Adobe side if they are not in the customer side
-                        directory.
-  --generate-remove-list output_path
-                        processing similar to --remove-nonexistent-users
-                        except that rather than performing removals, a file is
-                        generated (with the given pathname) listing users who
-                        would be removed. This file can then be given in the
-                        --remove-list argument in a subsequent run.
-  --remove-list input_path
-                        specifies the file containing the list of users to be
-                        removed. Users on this list are removed from the 
-                        organization on the Adobe side.
-  --delete-nonexistent-users
-                        Causes the user sync tool to delete user accounts on
-                        the Adobe side if they are not in the customer side
-                        directory. Adobe ID user accounts are removed from the
-                        organization, but not deleted.
-  --generate-delete-list output_path
-                        processing similar to --delete-nonexistent-users
-                        except that rather than performing removals, a file is
-                        generated (with the given pathname) listing users who
-                        would be removed. This file can then be given in the
-                        --delete-list argument in a subsequent run.
-  --delete-list input_path
-                        specifies the file containing the list of users to be
-                        deleted. Enterprise and federated users on this list
-                        are deleted on the Adobe side, and Adobe ID users are
-                        removed from the organization but not deleted.
-```
+##User Sync command line
+
+
+| Parameters and argument specifications | Description |
+|------------------------------|------------------|
+| `-h`<br />`--help` | Show this help message and exit.  |
+| `-v`<br />`--version` | Show program's version number and exit.  |
+| `-t`<br />`--test-mode` | Run API action calls in test mode (does not execute changes). Logs what would have been executed.  |
+| `-c` _filename_<br />`--config-filename` _filename_ | The complete path to the main configuration file, absolute or relative to the working folder. Default filename is "user-sync-config.yml" |
+| `--users` `all`<br />`--users` `file` _input_path_<br />`--users` `group` _grp1,grp2_<br />`--users` `mapped` | Specify the users to be selected for sync. The default is `all` meaning all users found in the directory. Specifying `file` means to take input user specifications from the CSV file named by the argument. Specifying `group` interprets the argument as a comma-separated list of groups in the enterprise directory, and only users in those groups are selected. Specifying `mapped` is the same as specifying `group` with all groups listed in the group mapping in the configuration file. This is a very common case where just the users in mapped groups are to be synced.|
+| `--user-filter` _regex\_pattern_ | Limit the set of users that are examined for syncing to those matching a pattern specified with a regular expression. See the [Python regular expression documentation](https://docs.python.org/2/library/re.html) for information on constructing regular expressions in Python. The user name must completely match the regular expression.|
+| `--update-user-info` | When supplied, synchronizes user information. If the information differs between the enterprise directory side and the Adobe side, the Adobe side is updated to match. This includes the firstname and lastname fields. |
+| `--process-groups` | When supplied, synchronizes group membership information. If the membership in mapped groups differs between the enterprise directory side and the Adobe side, the group membership is updated on the Adobe side to match. This includes removal of group membership for Adobe users not listed in the directory side (unless the `--adobe-only-user-action exclude` option is also selected).|
+| `--adobe-only-user-action preserve`<br />`--adobe-only-user-action remove-adobe-groups`<br />`--adobe-only-user-action  remove`<br />`--adobe-only-user-action delete`<br /><br/>`--adobe-only-user-action  write-file`&nbsp;filename<br/><br/>`--adobe-only-user-action  exclude` | When supplied, if user accounts are found on the Adobe side that are not in the directory, take the indicated action.  <br/><br/>`preserve`: no action concerning account deletion is taken. This is the default.  There may still be group membership changes if the `--process-groups` option was specified.<br/><br/>`remove-adobe-groups`: The account is removed from user groups and product configurations, freeing any licenses it held, but is left as an active account in the organization.<br><br/>`remove`: In addition to remove-adobe-groups, the account is also removed from the organization, but is left as an existing account.<br/><br/>`delete`: In addition to the action for remove, the account is deleted if owned by the organization.<br/><br/>`write-file`: the list of user account present on the Adobe side but not in the directory is written to the file indicated.  No other account action is taken.  You can then pass this file to the `--adobe-only-user-list` argument in a subsequent run.<br/><br/>`exclude`: No update of any kind is applied to users found only on the Adobe side.  This is used when doing updates of specific users via a file (--users file f) where only users needing explicit updates are listed in the file and all other users should be left alone.<br/><br>Only permitted actions will be applied.  Accounts of type adobeID are owned by the user so the delete action will do the equivalent of remove.  The same is true of Adobe accounts owned by other organizations. |
+| `adobe-only-user-list` _filename_ | Specifies a file from which a list of users will be read.  This list is used as the definitive list of "Adobe only" user accounts to be acted upon.  One of the `--adobe-only-user-action` directives must also be specified and its action will be applied to user accounts in the list.  The `--users` option is disallowed if this option is present: only account removal actions can be processed.  |
 
 # Configuration
 
-See `examples/example.user-sync-config.yml` for the main configuration template.  The main configuration file user-sync-config.yml must exist in the configuration path.
-
-See `examples/example.dashboard-config.yml` for the dashboard configuration template.  The tool would try and find dashboard-owning-config.yml in the configuration path.
-
-See `examples/example.connector-ldap.yml` for the ldap configuration template.  The main configuration file can be configured to reference this file.
-
-
+See the `examples` directory for sample configuration files of all types.  These sample files include all of the possible options with descriptions of them.

RELEASE_NOTES.md

@@ -1,31 +1,42 @@
 # Release Notes for User Sync Tool Version 1.2
 
-These notes apply to 1.2rc1 of 2017-03-20.z
+These notes apply to 2.0rc1 of 2017-04-03.
+
+## New Arguments & Configuration Syntax
+
+There has been an extensive overhaul of both the configuration file
+syntax and the command-line argument syntax.  See
+[Issue 95](https://github.com/adobe-apiplatform/user-sync.py/issues/95)
+and the [docs](https://adobe-apiplatform.github.io/user-sync.py/)
+for details.
 
 ## New Features
 
 1. You can now exclude dashboard users from being updated or
-   deleted by User Sync. See the
-   [docs](https://adobe-apiplatform.github.io/user-sync.py/) for
-   details.
+deleted by User Sync. See the
+[docs](https://adobe-apiplatform.github.io/user-sync.py/) for
+details.
 2. There is more robust reporting for errors in configuration
-   files.
+files.
 3. The log now reports the User Sync version and gives the
-   details of how it was invoked.
+details of how it was invoked.
 4. You can now create and manage users of all identity types,
-   including Adobe IDs, both when operating from an LDAP
-   directory and from CSV files.
+including Adobe IDs, both when operating from an LDAP
+directory and from CSV files.
 5. You can now distinguish, when a customer directory user is
-   disabled or removed, whether to remove the matching Adobe-side
-   from the organization or also to delete his Adobe user
-   account.
+disabled or removed, whether to remove the matching Adobe-side
+user's product configurations and user groups, to remove the
+user but leave his cloud storage, or to delete his storage as well.
 
 ## Significant Bug Fixes
 
 1. There were many bugs fixed related to managing users of
-   identity types other than Federated ID.
+identity types other than Federated ID.
 2. There were many bugs fixes related to managing group
-   membership of all identity types.
+membership of all identity types.
+3. There was a complete overhaul of how users who have
+adobe group memberships in multiple organizations are
+managed.
 
 ## Changes in Behavior
 
@@ -34,5 +45,39 @@ some had applied only to Federated ID and some to Enterprise ID.
 
 ## Compatibility with Prior Versions
 
-Other than as noted above, existing configuration files and
-should work and have the same behavior.
+All existing configuration files, user input files,
+and command-line scripts will need to be revamped
+to be compatible with the new formats.  Here is a quick
+cheat sheet of what needs to be done:
+
+* replace `dashboard:` with `adobe_users:`
+* replace `directory:` with `directory_users:`
+* add a `connectors:` section under `adobe_users:` similar
+to the one under `directory_users`
+* change `owning` to be `umapi` and put it under `connectors`
+* if you access multiple organizations, remove
+`secondaries`, and put
+all the umapi specifications under `umapi` as a list,
+like this:
+```yaml
+adobe_users:
+  connectors:
+    umapi:
+      - primary-config.yml
+      - org1: org1-config.yml
+      - org2: org2-config.yml
+```
+* change `dashboard_groups` to `adobe_groups`
+* under `limits`, change `max_missing_users` to
+`max_adobe_only_users` and remove all other
+settings
+* if you have an extension, do the following:
+  * remove the per-context: user setting
+  * move all the settings under it to the top level in
+a new file, call it `extension.yaml`
+  * change `extensions` to `extension`, move it into
+the `directory_users` section, and put the relative
+path to the new `extension.yaml` file as its value.
+
+
+

docs/art/user-guide/adobe-to-enterprise-connections.ai

@@ -34,21 +34,22 @@ If you are managing licenses with user sync, include the option `--process-group
 ## Account Deletion
 
 
-There are several command line options that allow you to specify the action to be taken when an Adobe account with no corresponding directory account is found (a “nonexistent” user).
-Note that only the users returned by the directory query and filter are considered as "existing".
+There are several command line options that allow you to specify the action to be taken when an Adobe account with no corresponding directory account is found (an “Adobe only” user).
+Note that only the users returned by the directory query and filter are considered as "existing" in the enterprise directory.  These options range from "completely ignore" to "completely delete" with several possibilities in between.
 
 
 
 | Command line option       ...........| Use when           |
 | ------------- |:-------------| 
-|   None                        |  No action desired on nonexistent users |
-|   `--remove-entitlements-for-nonexistent-users`\* |    Adobe account to remain but licenses and group <br>memberships are removed.  |
-|   `--remove-nonexistent-users`  |    Adobe account to remain but licenses, group memberships, and membership in this org to be removed   |
-|   `--delete-nonexistent-users`  |    Adobe account to be deleted: remove from PLCs and user groups and <br>from the org; account deleted and all storage and settings freed. |
-|   `--generate-remove-list f`    |  No action to be taken on the account.  User name written to file for later action. |
-|   `--generate-delete-list f`    |  No action to be taken on the account.  User name written to file for later action. |
+|   `--adobe-only-user-action exclude`                        |  No action desired on accounts that exist only in Adobe and have no corresponding directory account. Adobe group memberships are not updated even if `--process-groups` is present. |
+|   `--adobe-only-user-action preserve`                        |  No removal or deletion of accounts that exist only in Adobe and have no corresponding directory account. Adobe group memberships are updated if `--process-groups` is present. |
+|   `--adobe-only-user-action remove-adobe-groups` |    Adobe account to remain but licenses and group <br>memberships are removed.  |
+|   `--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. |
+
+
 
-\* These options will be available in a future release.
 
 ## Other Options
 
@@ -61,13 +62,13 @@ Note that only the users returned by the directory query and filter are consider
 
 A few examples:
 
-`user-sync --users all --process-groups --remove-nonexistent-users`
+`user-sync --users all --process-groups --adobe-only-user-action remove`
 
-- Process all users based on config settings, update Adobe group membership, and if there are any users listed in the org that are not in the directory, remove them.
+- Process all users based on config settings, update Adobe group membership, and if there are any Adobe users that are not in the directory, remove them from the Adobe side, freeing any licenses they may have been allocated.  The Adobe account is not deleted so that it can be re-added and/or stored assets recovered.
 
-`user-sync --users file example.users-file.csv --process-groups --remove-nonexistent-users`
+`user-sync --users file users-file.csv --process-groups --adobe-only-user-action remove`
 
-- The file “example.users-file.csv” is read as the master user list. No attempt is made to contact a directory service such as AD or LDAP in this case.
+- The file “users-file.csv” is read as the master user list. No attempt is made to contact a directory service such as AD or LDAP in this case.  Adobe group membership is updated per the information in the file, and any Adobe accounts not listed in the file are removed (see definition of remove, above).
 
 ## Define your command line
 

docs/success-guide/command_line_options.md

@@ -10,21 +10,18 @@ layout: default
 When accounts are disabled or deleted from the directory you often want the corresponding Adobe account removed, but removing the Adobe account may delete assets, settings, etc. that are later needed.  Also, Adobe Id accounts that may be in your organization cannot be deleted because the account belongs to the end user.  However, licenses you granted to the Adobe Id user can be recovered when you want to remove that user from your organization.
 
 
-
-
 Choices available for handling Adobe account deletion via User Sync:
 
   - Take no action.  Account cleanup must be handled manually.
 
   - Generate list of accounts to be deleted, but no action is taken now.  The list can be edited and later used to drive account deletion through User Sync.
 
-  - Recover all licenses given by your org to the account, but leave the account active. *
+  - Recover all licenses given by your org to the account, but leave the account active. (remove-adobe-groups)
 
-  - Recover all licenses and remove from your org, but leave account in existence.
+  - Recover all licenses and remove from your org, but leave account in existence.  (remove)
 
-  - Recover all licenses and delete the account.
+  - Recover all licenses and delete the account.  (delete)
 
-\*  feature coming late March, 2017
 
 Some things to know about account deletion: