Org.eclipse.higgins.js.pds.client

{{#eclipseproject:technology.higgins|eclipse_custom_style.css}}

Files

• SVN: org.eclipse.higgins.js.pds.connector.common

Design Notes for API additions to this component

Objective

Create a general purpose API that JavaScript programs executed by HBX can use to get and set attributes about the user.

API

getAttributes(agent, rp, audience, attributes, where, onReady)

Enables a JavaScript app to request attributes (e.g user's email address, gender, etc.) about the user. It searches the person graph to find the requested attributes. If it finds multiple, ambiguous values for one or more attributes, it returns nothing (and the "where' parameter must be used to refine the query).

• By setting the value of the authorities = the JavaScript developer's domain (i.e. the "issuer" id of the context associated with this JavaScript) then the caller can force the selector to only read attributes from this context.
• Depending on how the calling JavaScript is written, information about the user may remain local (i.e. within the browser and/or on the user's machine) or it may be transmitted to some external web service. The identity of the calling application and the identity of the "rp" are parameters to this call.
• FUTURE: If the attribute release is not part of (i) an explicit pre-existing connection/relationship with the rp or (ii) an implicit relationship (e.g. form filling when the user is viewing the page) then a UI should be implemented informing the user as to the identity of the agent, the identity of rp (the "next hop" destination if any) and the set of requested (required/optional) attributes and allowing them to give consent to this attribute disclosure.

Parameters:

agent

String identifier of the software agent (e.g. JavaScript program) that is getting the attributes and forwarding them to the rp

rp

String identifier of ultimate attribute data consumer as far as this is known. It is expressed in as detailed a form as possible. If the rp is a website then the string is the website domain (e.g. "staples.com")

audience

FUTURE (ignored for now) - String. Must match either the agent or the rp parameter value or be nil. If not nil, then indicates whether to encrypt tokens for the agent or the rp.

attributes

Set of (attribute, optional, authorities) tuples where: attribute is a URI indicating the attribute type. optional is a boolean (if true then this attribute is desired but not required). authorities FUTURE: (must be nil for now) - a list of domains that are considered by the caller as authoritative WRT this attribute and thus must be used as the source of the attribute, if this list is nil then self asserted values are acceptable. The value of a member of authorities is matched against the issuer of the containing context of the entity.

where 

A set of (attribute, value-expression) tuples where: attribute is the attribute URI of the form <namespace>#localAtt and namespace is the URL of a page (or a set of pages with a consistent schema). if the entire site uses the same schema then the site domain will suffice;value-expression (for now) may be an exact value (e.g. "Alice") or may be a regex that the value must match. In the short term the so-called "regex" is just a string of one or more characters followed by an asterisk (e.g. 2*, or 25*)--meaning that the value of the attribute must start with these characters (e.g. values "290" and "250" will match "2*" and "250" (only) will match "25*")

tokenTypes

A list of token types that are understood by RP. At present this must be a JSon document

onReady

Represents name of a JS event listener. If the value of 'onready' is an empty string, then it executes an synchronous query, otherwise it does an asynchronous query. The result will be passed as a parameter to the function onReady

Returns:

• A set of zero or more tokens (JSon documents at present). Each token encodes multiple (attribute, value(s)) tuples where:
  • Attribute is the attribute URI (note: this will be one of the attribute URIs passed in to this method)
  • Value(s) are the value(s) of the attribute (may be nil, if no values could be found). Each value may be literal or object typed.

IMPLEMENTATION

• context := getConnectionContext(rp) // e.g. http://azigo.com/ptrevithick/staples.com
• person := context + "#me"
• if exists(context) AND person has at least one attribute then
  • template := getTemplate(context); // e.g. http://azigo.com/ptrevithick/template/staples.com
  • Loop: For every triple t in attributes[]:
    • If (t.authority is not nil) then continue looping
    • att := getShortName(t.attribute) // e.g. "bFirstName"
    • attNS := getAttNS(t.attribute) // The namespace of the attribute (e.g. http://staples.com/checkout (the namespace of this page), or http://staples.com (if all forms on staples us a common, consistent universal set of element names))
    • pathset := mapAttribute(att, template, attNS))
    • attributeHolder := getAttributeHolder(person, pathset[0]) // (e.g. the entity that directly holds the vcard:given-name attribute & value) (we are assuming here that pathset.size = 1) (this function will return nil if there is ambiguity)
    • If attributeHolder = nil then continue looping
    • value := read value of attribute att from attributeHolder
    • insert value into a token (each token has a different target entity)
    • remove t from attributes[] //because for this attribute we're done
  • End Loop

@@@@@ the rest of this document is just random, rough notes copied/pasted here from 2 years ago (plz ignore)

1. See if connection context pair for RP already exists. If so skip to step 4
2. Determine candidate entities by a combination of mapping and authority matching
3. Determine best entities from redundant possible target entities
   1. Determine if we need to pop up the selector UI
   2. Pop up selector UI if necessary
   3. Else automatically select best entities
4. Copy attributes from best entities into RP context skipping any ambiguous attributes
5. Read attributes from the RP context, map these attributes, and
6. Return them

setAttribute(agent, domain, attribute, value)

Maps the attribute into the persona data model, determines which existing person and attribute to update (if any) or create (if needed). It only writes to (or creates) person nodes that are specific to the user-to-ip/rp relationship.

Parameters:

agent

ignored

domain

domain of the party providing the attribute value.

attribute

URI of attribute of the form <namespace>#<shortName>. For scraping <namespace> is the URL of the page being scraped (with query parameters removed)

value

literal or object value

Implementation:

• context := getConnectionContext(domain) // e.g. http://azigo.com/ptrevithick/staples.com
• template := getConnectionTemplate(domain) // e.g. http://azigo.com/ptrevithick/template/staples.com

Private Functions

URI getConnectionContext(string domain)

Return:

• http://<servername>/<pdsuser>/domain

URI getConnectionTemplate(string domain)

Return:

• http://<servername>/<pdsuser>/template/domain

string getLocalAtt (URI attribute)

Strip trailing element in the URI and return it. (e.g. if the input was http://staples.com/office/supplies/StaplescheckoutFlow#bFirstName then return "bFirstName").

URI getTemplate (URI context)

Returns value of template attribute of context

ruleSet[] mapAttribute(att, template, class)

Parameters:

att

string - short name of attribute in the original ontology

template

URI of the template context

class

- string name of the p:Person subclass (e.g. "http://staples.com/Office-supplies-StaplesCheckoutFlow")

This routine is the heart of the mapping process. It takes an short name att in one ontology (e.g. the "facebook.com" ontology) and finds an equivalent set of attribute paths in the Persona Data Model. For example it could take facebook's notion of "firstname" and find that this has the same semantics as the PDM's "vcard:given-name" attribute. Thus the string value "Alice" found on some p:Person in some context could be safely copied/used as the value of the "firstname" field on form on a facebook.com web page.

Look for a spin:rule within class such that the attribute map:predicate matches att (e.g. bFirstName). For example here is a match:

     map:nameRule
             [ rdf:type map:rolePathLiteral ;
               map:mappedAtt <http://www.w3.org/2006/vcard/ns#given-name> ;
               map:path <http://www.w3.org/2006/vcard/ns#n> ;
               map:predicate :bFirstName ;
               map:role map:roleParam
             ] ;

Return ruleSet[0] = the above rule (the part in the square brackets).

getSuggestions(attribute, onready)

Note: For privacy reasons this method may only be called by highly trusted JavaScript.

Parameters:

attribute

the attribute type string (HTML form element id)

onready

represents event listener (name of the JS function). if value of 'onready' is empty string, BX does a synchronous request, otherwise BX does an asynchronous request, the result will be passed like parameter to function 'onready'.

JS Example of asynchronous request:

 function onSuggestions(res){
 	//...
 };
 //...
 bx.getSuggestions(attribute, 'onSuggestions');

JS Example of synchronous request:

 res = bx.getSuggestions(attribute, );