X-Git-Url: http://jsfdemo.indexdata.com/?a=blobdiff_plain;f=doc%2Flibrary-configuration.txt;h=040bf738cef46788b904f438ffbdbf10ff63954c;hb=851a7c7eb7aebfb6d0b2d756b4377d8e325efd3f;hp=311c3b0bd16cdc844a784dfa3f707f4b02193aeb;hpb=8871d5d24f00a1ec36b58334b703701b3c9183fa;p=mkws-moved-to-github.git

diff --git a/doc/library-configuration.txt b/doc/library-configuration.txt
index 311c3b0..040bf73 100644
--- a/doc/library-configuration.txt
+++ b/doc/library-configuration.txt
@@ -17,43 +17,42 @@ available targets to use.
 1. Maintaining the library
 --------------------------
 
-### and so that a library of targets
-is available, maintained using an instance of MKAdmin (often
-http://mkc-admin.indexdata.com/console/)
-
-
-2. Choosing targets from the library
-------------------------------------
-
-MKWS applications can choose what subset of the library's targets to
-use, by means of several alternative settings on individual widgets or
-in the mkws_config structure:
-
-* targets -- contains a Pazpar2 targets string, typically of the form
-  "pz:id=" or "pz:id~" followed by a pipe-separated list of low-level
-  target IDs.
-
-  At present, these IDs can take one of two forms, depending on the
-  configuration of the Service Proxy being used: they may be based on
-  ZURLs, so a typical value would be something like:
-	pz:id=josiah.brown.edu:210/innopac|lui.indexdata.com:8080/solr4/select?fq=database:4902
-  Or they may be UDBs, so a typical value would be something like:
-	pz:id=brown|artstor
-
-* targetfilter -- contains a CQL query which is used to find relevant
-  targets from the relvant library. For example,
-	udb==Google_Images
-  Or
-	categories=news
-
-* target -- contains a single UDB, that of the sole target to be
-  used. For example
-	Google_Images
-  This is merely syntactic sugar for "targetfilter" with the query
-	udb==NAME
-
-
-3. Authenticating onto the library
+The service proxy accesses sets of targets that are known as
+"libraries". In general, each customer will have their own library,
+though some standard libraries may be shared between many customers --
+for example, a library containing all open-access academic journals.
+A library can also contain other configuration information, including
+the set of categories by which targets are classified for the library.
+
+Libraries are maintained using MKAdmin (MasterKey
+Admin). Specifically, those used by MKWS are generally maintained on
+the "MKC Admin" installation at
+	http://mkx-admin.indexdata.com/console/
+
+In general, Index Data will create a library for each customer, then
+give the customer a username/password pair that they can use to enter
+MKAdmin and administrate that library.
+
+Once logged in, customers can select which targets to include (from
+the list of several thousand that MKAdmin knows about), and make
+customer-specific modifications -- e.g. overriding the titles of the
+targets.
+
+Most importantly, customers' administrators can add authentication
+credentials that the Service Proxy will used on their behalf when
+accessing subscription resources. Note that IT IS THEN CRUICIAL TO
+SECURE THE LIBRARY FROM USE BY UNAUTHORISED CLIENTS, otherwise the
+customer's paid subscriptions will be exploited.
+
+Access to libraries is managed by creating one or more "User Access"
+records in MKAdmin, under the tab of that name. Each of these records
+provides a combination of credentials and other data that allow an
+incoming MKWS client to be identified as having legitimate access to
+the library. The authentication process, described below, works by
+searching for a matching User Access record.
+
+
+2. Authenticating onto the library
 ----------------------------------
 
 Some MKWS applications will be content to use the default library with
@@ -126,3 +125,35 @@ Once such a library has been set up, and access to it established,
 target selection within the set that it makes available can be done
 using the mechanisms above.
 
+
+3. Choosing targets from the library
+------------------------------------
+
+MKWS applications can choose what subset of the library's targets to
+use, by means of several alternative settings on individual widgets or
+in the mkws_config structure:
+
+* targets -- contains a Pazpar2 targets string, typically of the form
+  "pz:id=" or "pz:id~" followed by a pipe-separated list of low-level
+  target IDs.
+
+  At present, these IDs can take one of two forms, depending on the
+  configuration of the Service Proxy being used: they may be based on
+  ZURLs, so a typical value would be something like:
+	pz:id=josiah.brown.edu:210/innopac|lui.indexdata.com:8080/solr4/select?fq=database:4902
+  Or they may be UDBs, so a typical value would be something like:
+	pz:id=brown|artstor
+
+* targetfilter -- contains a CQL query which is used to find relevant
+  targets from the relvant library. For example,
+	udb==Google_Images
+  Or
+	categories=news
+
+* target -- contains a single UDB, that of the sole target to be
+  used. For example
+	Google_Images
+  This is merely syntactic sugar for "targetfilter" with the query
+	udb==NAME
+
+