Merge branch 'doc/example-config-comments' into v2

Author: adorton-adobe

examples/config files - basic/connector-adobe-console.yml

@@ -1,26 +1,19 @@
-# This is a sample configuration file for the Adobe-Console connector.
+# This is a template configuration file for the User Sync Tool UMAPI connector
 #
-# umapi (user management api) is a network protocol served by Adobe that
-# provides management of users in Adobe-hosted enterprise organizations.
-#
-# This sample file contains all of the settable options for this protocol.
-# All of the settings here can be changed.  It is recommended
-# that you make a copy of this file and edit that to match your configuration.
-# While you are at it, you will likely want to remove a lot of this  commentary,
-# in order to enhance the readability of your file.
+# Full documentation here -
+# https://adobe-apiplatform.github.io/user-sync.py/en/user-manual/sync_from_console.html
+
+# --- General Options ---
+# The following options control general UMAPI connector behavior.
+# See https://adobe-apiplatform.github.io/user-sync.py/en/user-manual/sync_from_console.html#configuring-a-connection
 
+# ssl_verify: False
 authentication_method: oauth
+identity_type_filter: all
 
-# (optional) UMAPI server settings (defaults as shown)
-# The host and endpoint settings specify the Adobe endpoints which
-# host the UMAPI services and those which provide authorization.
-# The timeout and retries settings control how much delay (in seconds)
-# can be tolerated in server responses, and also how many times a request
-# that fails due to server timeout or server throttling will be retried.
-# You will *never* need to alter these settings unless you are provided
-# alternate values by Adobe as part of a support engagement.  It is
-# highly recommended that you leave these values commented out
-# so that the default values are guaranteed to be used.
+# --- Server Options ---
+# These generally never need to be changed by most users.
+# See https://adobe-apiplatform.github.io/user-sync.py/en/user-manual/sync_from_console.html#server-settings
 server:
   #host: usermanagement.adobe.io
   #endpoint: /v2/usermanagement
@@ -29,29 +22,16 @@ server:
   #timeout: 120
   #retries: 3
 
-# (required) integration settings
-# You must specify all five of these settings.  Consult the
-# Adobe UMAPI documentation and the Adobe I/O Console to determine
-# the correct settings for your enterprise organization.
+# --- Integration Options ---
+# These options contain the credentials for connecting with the User Management API
+# client_id and client_secret can be stored in plaintext or can be secured (see below)
+# See https://adobe-apiplatform.github.io/user-sync.py/en/user-manual/sync_from_console.html#integration-settings
 integration:
-  org_id: "Org ID goes here"
   client_id: "Client ID goes here"
   client_secret: "Client secret goes here"
+  org_id: "Org ID goes here"
 
-  # (optional) You can store credentials in the operating system credential store
-  # (Windows Credential Manager, Mac Keychain, Linux Freedesktop Secret Service
-  # or KWallet - these will be built into the Linux distribution).
-  # To use this feature, uncomment the following entries and remove the
-  #client_id, and client_secret above.
-  # The actual credential values are placed in the credential store with the
-  # username as the org_id value, and the key name (perhaps called internet
-  # or network address) as one of the values below.
-  #secure_client_id_key: umapi_client_id
-  #secure_client_secret_key: umapi_client_secret
-
-# (optional) identity_type_filter (default value is all)
-# By default, connector will automatically load users from all identity type to be load as directory users.
-# When specify with one of the following value (adobeID, enterpriseID, federatedID)
-# the connector will automatically filter users by the specified identity type.
-identity_type_filter: all
-
+  # NOTE: Credentials can be stored securely with these options
+  # secure_client_id_key: my_client_id
+  # secure_client_secret_key: my_client_secret
+  # See https://adobe-apiplatform.github.io/user-sync.py/en/user-manual/sync_from_console.html#credential-security

examples/config files - basic/connector-csv.yml

@@ -1,81 +1,22 @@
-# This is a sample configuration file for the csv connector type.
-#
-# CSV (Comma-Separated Values) is a plain-text spreadsheet format.
-# The main function of this configuration file is to specify how column names
-# in the spreadsheet are mapped to attribute names in the directory.
-#
-# The first line of a CSV file is assumed to be header row with column names.
-# The column names in your spreadsheet can be in any order, and if there are
-# fewer values in a row than there are in the header row, the attributes
-# for the missing columns are given no value.
-#
-# This sample file contains all of the settable options for this format,
-# with each set to its default value.  If the defaults are fine for your
-# application, you can use a copy of this file as-is, or you can omit the csv
-# setting from the connectors in your main User Sync configuration file.
+# This is the configuration template for the CSV connector.
+# For more information, see https://adobe-apiplatform.github.io/user-sync.py/en/user-manual/sync_from_csv.html
+
+# --- Format Options ---
+# These options relate to the CSV file format
+# See https://adobe-apiplatform.github.io/user-sync.py/en/user-manual/sync_from_csv.html#format-options
 
-# (optional) delimiter (no default value)
-# The delimiter is the string that separates columns.  Normally,
-# this is detected automatically from the first line in the file.
-# To set it to a specific value, uncomment this setting:
 #delimiter: ","
+# string_encoding: utf-8
 
-# (optional) string_encoding (default value given below)
-# string_encoding specifies the Unicode string encoding used in the CSV file.
-# All values retrieved from the file are converted to Unicode before being
-# sent to or compared with values on the Adobe side, to avoid encoding issues.
-# The value must be a Python codec name or alias, such as 'latin1' or 'utf-8.
-# See https://docs.python.org/2/library/codecs.html#standard-encodings for details.
-#string_encoding: utf-8
+# --- Column Mapping Options ---
+# These options let you control the column naming scheme of the CSV input file
+# See https://adobe-apiplatform.github.io/user-sync.py/en/user-manual/sync_from_csv.html#column-mapping-options
 
-# (optional) email_column_name (default "email")
-# The column name that contains the user's email address.
-# Values in this column must be valid, unquoted email addresses.
-# A value is required in this column for all users, regardless
-# of their identity type.  For Adobe ID users, all of the other
-# column values are optional.  For Enterprise and Federated ID
-# users, all of the other column values are significant.
 email_column_name: email
-
-# (optional) first_name_column_name (default "firstname")
-# The column name that contains the user's first name (aka given name).
-# Values in this column can be any string
 first_name_column_name: firstname
-
-# (optional) last_name_column_name (default "lastname")
-# The column name that contains the user's last name (aka surname).
-# Values in this column can be any string
 last_name_column_name: lastname
-
-# (optional) country_column_name (default "country")
-# The column name that contains the user's home country.
-# Values in this column must be an ISO-3166 two-letter country code.
 country_column_name: country
-
-# (optional) groups_column_name (default "groups")
-# The column name that contains the user's group memberships.
-# Values in this column must be a comma-separated list of group names.
-# NOTE: Since commas usually separate columns, be sure to surround the
-# entire column value with double quotes, to prevent any embedded commas
-# from being interpreted as column separators.
 groups_column_name: groups
-
-# (optional) identity_type_column_name (default "type")
-# The column name that contains the user's identity type.
-# Values in this column must be adobeID, enterpriseID, or FederatedID.
 identity_type_column_name: type
-
-# (optional) username_column_name (default "username")
-# The column name that contains the user's username (for the Adobe side).
-# Values in this column should not be specified unless the user is of type federatedID
-# and the user's domain is configured for username-based federation.  In all other
-# cases, leave this column blank, and the email will be used for the username.
 username_column_name: username
-
-# (optional) domain_column_name (default "domain")
-# The column name that contains the user's domain.
-# Values in this column should not be specified unless the user is of type federatedID,
-# the user's domain is configured for username-based federation, and there is a value
-# in the username field.  If this field is left blank, the domain part of the email
-# address will be used for the user's domain.
 domain_column_name: domain