Author: kwright
Date: Mon Jul 1 13:45:29 2013
New Revision: 1498448
URL: http://svn.apache.org/r1498448
Log:
Update end-user documentation to cover mappers. Part of CONNECTORS-743.
Added:
manifoldcf/trunk/site/src/documentation/resources/images/en_US/add-new-mapping-connection-name.PNG
(with props)
manifoldcf/trunk/site/src/documentation/resources/images/en_US/add-new-mapping-connection-type.PNG
(with props)
manifoldcf/trunk/site/src/documentation/resources/images/en_US/authority-prerequisites.PNG
(with props)
manifoldcf/trunk/site/src/documentation/resources/images/en_US/list-mapping-connections.PNG
(with props)
manifoldcf/trunk/site/src/documentation/resources/images/en_US/mapping-prerequisites.PNG
(with props)
manifoldcf/trunk/site/src/documentation/resources/images/en_US/mapping-throttling.PNG
(with props)
manifoldcf/trunk/site/src/documentation/resources/images/en_US/regexp-mapping-status.PNG
(with props)
manifoldcf/trunk/site/src/documentation/resources/images/en_US/regexp-mapping-user-mapping.PNG
(with props)
Modified:
manifoldcf/trunk/site/src/documentation/content/xdocs/en_US/end-user-documentation.xml
manifoldcf/trunk/site/src/documentation/resources/images/en_US/welcome-screen.PNG
Modified:
manifoldcf/trunk/site/src/documentation/content/xdocs/en_US/end-user-documentation.xml
URL:
http://svn.apache.org/viewvc/manifoldcf/trunk/site/src/documentation/content/xdocs/en_US/end-user-documentation.xml?rev=1498448&r1=1498447&r2=1498448&view=diff
==============================================================================
---
manifoldcf/trunk/site/src/documentation/content/xdocs/en_US/end-user-documentation.xml
(original)
+++
manifoldcf/trunk/site/src/documentation/content/xdocs/en_US/end-user-documentation.xml
Mon Jul 1 13:45:29 2013
@@ -84,6 +84,63 @@
If this happens, you will need to correct the problem,
by either fixing your infrastructure, or by editing the connection
configuration appropriately, before the output connection
will work correctly.</p>
</section>
+
+ <section id="mappers">
+ <title>Defining Mapping Connections</title>
+ <p>The Framework UI's left-side menu contains a link for
listing user mapping connections. A user mapping connection is a connection to
a system that understands how to map a user name
+ into a different user name intended for a different
repository. For example, if you want to enforce document security using
LiveLink, but you have only an Active Directory user name,
+ you will need to map the Active Directory user name to
a corresponding LiveLink one, before finding access tokens for it using the
LiveLink Authority.</p>
+ <p>You will not need any user mapping connections if the
authorities that you intend to create can all operate using the same user name,
and that user name is the one that is made available to
+ ManifoldCF's authority servlet at search time.</p>
+ <p>You should define your mapping connections <b>before</b>
setting up your authority connections. Individual authority connections must
specify the mapping connection that precedes it.
+ It's also convenient to define your mapping connections
in the order that you want to process the user name, for the same reason. If
you don't manage to do this right the first time, though,
+ there is no penalty involved if you need to go back and
fix things up.</p>
+ <p>You can create a mapping connection by clicking the "List
User Mapping Connections" link in the left-side navigation menu. When you do
this, the
+ following screen will appear:</p>
+ <br/><br/>
+ <figure src="images/en_US/list-mapping-connections.PNG"
alt="List User Mapping Connections" width="80%"/>
+ <br/><br/>
+ <p>On a freshly created system, there may well be no existing
mapping connections listed. If there are already mapping connections, they
will be listed on this screen, along with links
+ that allow you to view, edit, or delete them. To
create a new mapping connection, click the "Add a new connection" link at the
bottom. The following screen will then appear:</p>
+ <br/><br/>
+ <figure src="images/en_US/add-new-mapping-connection-name.PNG"
alt="Add New User Mapping Connection, specify Name" width="80%"/>
+ <br/><br/>
+ <p>The tabs across the top each present a different view of
your mapping connection. Each tab allows you to edit a different
characteristic of that connection. The exact set of tabs you see
+ depends on the connection type you choose for the
connection.</p>
+ <p>Start by giving your connection a name and a description.
Remember that all mapping connection names must be unique, and cannot be
changed after the connection is defined. The name must be
+ no more than 32 characters long. The description can
be up to 255 characters long. When you are done, click on the "Type" tab. The
Type tab for the connection will then appear:</p>
+ <br/><br/>
+ <figure src="images/en_US/add-new-mapping-connection-type.PNG"
alt="Add New User Mapping Connection, select Type" width="80%"/>
+ <br/><br/>
+ <p>The list of mapping connection types in the pulldown box,
and what they are each called, is determined by your system integrator. The
configuration tabs for each different kind of
+ mapping connection type included with ManifoldCF are
described in separate sections below.</p>
+ <p>After you choose a mapping connection type, click the
"Continue" button at the bottom of the pane. You will then see all the tabs
appropriate for that kind of connection appear, and a
+ "Save" button will also appear at the bottom of the
pane. You <b>must</b> click the "Save" button when you are done in order to
create your connection. If you click "Cancel" instead,
+ the new connection will not be created. (The same
thing will happen if you click on any of the navigation links in the left-hand
pane.)</p>
+ <p>Every mapping connection has a "Prerequisites" tab. This
tab allows you to specify which mapping connection needs to be run before this
one (if any). The tab looks like this:</p>
+ <br/><br/>
+ <figure src="images/en_US/mapping-prerequisites.PNG" alt="User
Mapping Connection Prerequisites" width="80%"/>
+ <br/><br/>
+ <p>Note: It is very important that you do not specify
prerequisites in such a way as to create a loop. To make this easier,
ManifoldCF will not display any user mapping connections in the pulldown
+ which, if selected, would lead to a loop.</p>
+ <p>Every mapping connection has a "Throttling" tab. The tab
looks like this:</p>
+ <br/><br/>
+ <figure src="images/en_US/mapping-throttling.PNG" alt="User
Mapping Connection Throttling" width="80%"/>
+ <br/><br/>
+ <p>On this tab, you can specify only one thing: how many open
connections are allowed at any given time to the system the authority
connection talks with. This restriction helps prevent
+ that system from being overloaded, or in some cases
exceeding its license limitations. Conversely, making this number larger
allows for smaller average search latency. The default
+ value is 10, which may not be optimal for all types of
mapping connections. Please refer to the section of the manual describing your
mapping connection type for more precise
+ recommendations.
+ </p>
+ <p>Please refer to the section of the manual describing your
chosen mapping connection type for a description of the tabs appropriate for
that connection type.</p>
+
+ <p>After you save your connection, a summary screen will be
displayed that describes your connection's configuration. This summary screen
contains a line where the connection's status
+ is displayed. If you did everything correctly, the
message "Connection working" will be displayed as a status. If there was a
problem, you will see a connection-type-specific diagnostic message instead.
+ If this happens, you will need to correct the problem,
by either fixing your infrastructure, or by editing the connection
configuration appropriately, before the mapping connection
+ will work correctly.</p>
+
+ </section>
+
<section id="authorities">
<title>Defining Authority Connections</title>
<p>The Framework UI's left-side menu contains a link for
listing authority connections. An authority connection is a connection to a
system that defines a particular security environment.
@@ -114,7 +171,11 @@
<p>After you choose an authority connection type, click the
"Continue" button at the bottom of the pane. You will then see all the tabs
appropriate for that kind of connection appear, and a
"Save" button will also appear at the bottom of the
pane. You <b>must</b> click the "Save" button when you are done in order to
create your connection. If you click "Cancel" instead, the new connection
will not be created. (The same thing will happen if
you click on any of the navigation links in the left-hand pane.)</p>
- <p>Every authority connection has a "Throttling" tab. The tab
looks like this:</p>
+ <p>Every authority connection has a "Prerequisites" tab. This
tab allows you to specify which mapping connection needs to be run before this
one (if any). The tab looks like this:</p>
+ <br/><br/>
+ <figure src="images/en_US/authority-prerequisites.PNG"
alt="Authority Connection Prerequisites" width="80%"/>
+ <br/><br/>
+ <p>Every authority connection also has a "Throttling" tab.
The tab looks like this:</p>
<br/><br/>
<figure src="images/en_US/authority-throttling.PNG"
alt="Authority Connection Throttling" width="80%"/>
<br/><br/>
@@ -640,7 +701,35 @@ curl -XGET http://localhost:9200/index/_
</section>
</section>
-
+
+ <section id="mappingconnectiontypes">
+ <title>User Mapping Connection Types</title>
+
+ <section id="regexpmapper">
+ <title>Regular Expression User Mapping Connection</title>
+ <p>The Regular Expression user mapping connection type is very
helpful for rote user name conversions of all sorts. For example, it can
easily be configured to map the standard "user@domain" form
+ of an Active Directory user name to (say) a LiveLink
equivalent, e.g. "domain\user". Since many repositories establish such rote
conversions, the Regular Expression user mapping connection
+ type is often all that you will ever need.</p>
+ <br/>
+ <p>A Regular Expression user mapping connection type has one
special tab in the user mapping connection editing screen: "User Mapping". This
+ tab looks like this:</p>
+ <br/><br/>
+ <figure src="images/en_US/regexp-mapping-user-mapping.PNG"
alt="Regexp User Mapping, User Mapping tab" width="80%"/>
+ <br/><br/>
+ <p>The mapping consists of a match expression, which is a
regular expression where parentheses ("(" and ")") mark sections you are
interested in, and a
+ replace string. The sections marked with parentheses
are called "groups" in regular expression parlance. The replace string
consists of constant text plus
+ substitutions of the groups from the match, perhaps
modified. For example, "$(1)" refers to the first group within the match,
while "$(1l)" refers to the first
+ match group mapped to lower case. Similarly, "$(1u)"
refers to the same characters, but mapped to upper case.</p>
+ <p>For example, a match expression of
<code>^(.*)\@([A-Z|a-z|0-9|_|-]*)\.(.*)$</code> with a replace string of
<code>$(2)\$(1l)</code> would convert
+ an Active Directory username of
<code>[email protected]</code> into the user name
+ <code>subdomain\myusername</code>.</p>
+ <p>When you are done, click the "Save" button. When you do, a
connection summary and status screen will be presented, which may look
something like this:</p>
+ <br/><br/>
+ <figure src="images/en_US/regexp-mapping-status.PNG"
alt="Regexp User Mapping Status" width="80%"/>
+ <br/><br/>
+ </section>
+ </section>
+
<section id="authorityconnectiontypes">
<title>Authority Connection Types</title>
Added:
manifoldcf/trunk/site/src/documentation/resources/images/en_US/add-new-mapping-connection-name.PNG
URL:
http://svn.apache.org/viewvc/manifoldcf/trunk/site/src/documentation/resources/images/en_US/add-new-mapping-connection-name.PNG?rev=1498448&view=auto
==============================================================================
Binary file - no diff available.
Propchange:
manifoldcf/trunk/site/src/documentation/resources/images/en_US/add-new-mapping-connection-name.PNG
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added:
manifoldcf/trunk/site/src/documentation/resources/images/en_US/add-new-mapping-connection-type.PNG
URL:
http://svn.apache.org/viewvc/manifoldcf/trunk/site/src/documentation/resources/images/en_US/add-new-mapping-connection-type.PNG?rev=1498448&view=auto
==============================================================================
Binary file - no diff available.
Propchange:
manifoldcf/trunk/site/src/documentation/resources/images/en_US/add-new-mapping-connection-type.PNG
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added:
manifoldcf/trunk/site/src/documentation/resources/images/en_US/authority-prerequisites.PNG
URL:
http://svn.apache.org/viewvc/manifoldcf/trunk/site/src/documentation/resources/images/en_US/authority-prerequisites.PNG?rev=1498448&view=auto
==============================================================================
Binary file - no diff available.
Propchange:
manifoldcf/trunk/site/src/documentation/resources/images/en_US/authority-prerequisites.PNG
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added:
manifoldcf/trunk/site/src/documentation/resources/images/en_US/list-mapping-connections.PNG
URL:
http://svn.apache.org/viewvc/manifoldcf/trunk/site/src/documentation/resources/images/en_US/list-mapping-connections.PNG?rev=1498448&view=auto
==============================================================================
Binary file - no diff available.
Propchange:
manifoldcf/trunk/site/src/documentation/resources/images/en_US/list-mapping-connections.PNG
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added:
manifoldcf/trunk/site/src/documentation/resources/images/en_US/mapping-prerequisites.PNG
URL:
http://svn.apache.org/viewvc/manifoldcf/trunk/site/src/documentation/resources/images/en_US/mapping-prerequisites.PNG?rev=1498448&view=auto
==============================================================================
Binary file - no diff available.
Propchange:
manifoldcf/trunk/site/src/documentation/resources/images/en_US/mapping-prerequisites.PNG
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added:
manifoldcf/trunk/site/src/documentation/resources/images/en_US/mapping-throttling.PNG
URL:
http://svn.apache.org/viewvc/manifoldcf/trunk/site/src/documentation/resources/images/en_US/mapping-throttling.PNG?rev=1498448&view=auto
==============================================================================
Binary file - no diff available.
Propchange:
manifoldcf/trunk/site/src/documentation/resources/images/en_US/mapping-throttling.PNG
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added:
manifoldcf/trunk/site/src/documentation/resources/images/en_US/regexp-mapping-status.PNG
URL:
http://svn.apache.org/viewvc/manifoldcf/trunk/site/src/documentation/resources/images/en_US/regexp-mapping-status.PNG?rev=1498448&view=auto
==============================================================================
Binary file - no diff available.
Propchange:
manifoldcf/trunk/site/src/documentation/resources/images/en_US/regexp-mapping-status.PNG
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added:
manifoldcf/trunk/site/src/documentation/resources/images/en_US/regexp-mapping-user-mapping.PNG
URL:
http://svn.apache.org/viewvc/manifoldcf/trunk/site/src/documentation/resources/images/en_US/regexp-mapping-user-mapping.PNG?rev=1498448&view=auto
==============================================================================
Binary file - no diff available.
Propchange:
manifoldcf/trunk/site/src/documentation/resources/images/en_US/regexp-mapping-user-mapping.PNG
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Modified:
manifoldcf/trunk/site/src/documentation/resources/images/en_US/welcome-screen.PNG
URL:
http://svn.apache.org/viewvc/manifoldcf/trunk/site/src/documentation/resources/images/en_US/welcome-screen.PNG?rev=1498448&r1=1498447&r2=1498448&view=diff
==============================================================================
Binary files - no diff available.
