Difference between revisions of "App-data vocabulary"

Latest revision as of 22:25, 10 May 2012

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

Vocabulary used by TemplateContext to describe:

• Metadata used to create a connection to a website (see WebsiteFacade)
• CDE Scripts to be executed by the Higgins Browser Extension's Connection Data Engine
• JavaScript to be invoked by the browser extension either on the page the browser user is currently looking at, or in a background thread.

Used by Template vocabulary. Part of the Persona Data Model 2.0

Files

• Most recently published
• SVN source: app-data.owl

UML Overview

Classes

AppParams

An AppParams instance is the value of an AppData's params attribute. It is a set of attributes and values used to initialize the app. Note: these attribute/values are combined with those derived from the AppData's entityParam.

CDEScript

A Connector Data Engine script. The data is a JSON document consumed by the engine. If necessary the engine is completely or partially replaced by customJS.

• 0..1 customJS
• 1..1 data
• 1..1 format
• 0..1 skos:prefLabel
• 1..1 version
• 1..1 scriptId (only on DataSyncScripts)

CDEScript SubClasses:

• MailingList:
  • Subscribe: Subscribes the user to the site's email list. Doesn't create an account.
  • Unsubscribe: Unsubscribes the user to the site's mailing list.
• Account:
  • ChangeEmail: Change the user's email address at this site in cases where the this email address is also their login id.
  • ChangeEmailOnly: Change the user's email address in their account at this site while preserving their current userid (which may be an email address) and password.
  • ChangeEmailPW: Change the user's email address at this site when the email address is the user's account id. It also changes the user's password.
  • IsLoggedIn: Determine if user is logged in.
  • IsLoggedOut: Determine if user is logged out.
  • Login: Script to auto-login the user at this site.
  • Logout: Script to log out the user at this site.
  • Register: Register the user at this site.
  • RegisterHI: Register the user at this site in cases where Human Intelligence is required and thus the script requires assistance from the user.
  • ResetPW: Reset the user's password.
  • UserIdExists: Tests if the reason for a register failure was that the userid (e.g. email) already exists.
• DataSyncScripts: Scripts that sync user data to/from the PDS. Unlike other script types, there may be more than one instance. For this reason these scripts have unique scriptId identifiers.
  • Fill: Script that attempts to fill any non-login form.
  • Scrape: Script that attempts to scrape non-login related data (e.g. by hooking the formSubmit URL).
  • Push: A script that is triggered by the PDS app when the user changes a field in the PDS app's connection page. The script applies the change that the user just made on the connection page to the website.

JavaScript

Description of a JavaScript application to be executed in the user's browser by the browser extension.

• 0..1 skos:prefLabel
• 1..1 version
• 1..1 code

ManagedJS

Description of a JavaScript application fetched from an external service and executed in the user's browser by the browser extension.

• subClassOf: JavaScript
• 1..1 appId
• 1..1 description
• 1..1 eventHandlerURL
• 1..1 adminURL
• 1..1 serviceType
• 1..1 serviceURL
• 0..N hbxFunctionsEnabled

Overlay

JavaScript app that does web augmentation as an overlay to the current page the user is looking at in their browser.

• subClassOf: ManagedJS
• 0..N sites
• 0..1 params
• 0..N entityParam

WebsiteFacade

A participant context that has local JavaScript running in the background or the foreground that scrapes & fills an external website.

• subClassOf: template:Participant
• 0..1 emailAsUserId
• 0..1 emailConfirmEmailChange
• 0..1 login
• 1..1 loginMethod
• 0..1 registration
• 0..N script

WebsiteFacade Attributes

changeEmail

View-builder structure that defines the attributes required to change the user's email (and login userid) after having successfully logged in.

• domain: WebsiteFacade
• value: view-builder:Group

emailAsUserId

If true, for this organization's website the userid is an email to which the organization will send emails.

• domain: WebsiteFacade
• value: xsd:boolean

emailConfirmEmailChange

If true, this organization's website sends an email to the user's old email address requiring them to confirm a change to their email profile attribute.

• domain: WebsiteFacade
• value: xsd:boolean

loginMethod

Login method(s) used by this organization's website.

• domain: WebsiteFacade
• value: one of ("un-pw" , "none")

login

View-builder structure that defines the attributes required to login to this site.

• domain: WebsiteFacade
• value: view-builder:Group

register

View-builder structure that defines the attributes required to register with this site.

• domain: WebsiteFacade
• value: view-builder:Group

subscribe

View-builder structure that defines the attributes required to subscribe to the site's mailing list.

• domain: WebsiteFacade
• value: view-builder:Group

CDEScript Attributes

customJS

For sites where the general purpose CDE won't work, use this JavaScript.

• domain: CDEScript
• value: JavaScript

data

Connector Data Engine script (JSON document).

• domain: CDEScript
• value: xsd:string

format

The format of the CDE script itself.

• domain: CDEScript
• value: one of ("cde 1.0, "cde 2.0")

scriptId

Uniquely identifies this instance of a DataSyncScript.

• domain: DataSyncScripts
• value: xsd:string

version

A human readable version number.

• domain: CDEScript
• value: xsd:string

JavaScript (and subClasses) Attributes

adminURL

The URL of a admin page to load into PDS portal.

• domain: JavaScript
• value: xsd:anyURI

appId

Uniquely identifies the app within the "developerId" namespace. In other words the combination of the devID and the appId is globally unique. When using Kynetx KNS this is the ruleID with special constraint that this ruleID is globally unique.

• domain: ManagedJS
• value: string

description

A human readable description of the app. Note: If appServer == http(s)://init.kobj.net, then the KNS "describe" API can be used by a context provider implementation to provide this attribute value.

• domain: ManagedJS
• value: string

entityParam

The name of an attribute (e.g. p:postal-code) of a Person within a context associated with this App-data object. The value of this named attribute of the person is used as a parameter to the app-card's app.

• domain: Overlay
• value: URI

eventHandlerURL

The URL of JS that provides specific handlers for certain events in a context’s lifecycle including: onImport, onDelete, onEnable, onDisable, onExport

• domain: ManagedJS
• value: URI

hbxFunctionsEnabled

The list of HBX functions that the JS functions associated with this app-data are allowed to call.

• domain: ManagedJS
• value: string one of: {"delExAttrbutes" , "getExAttributes" , "getSuggestions" , "setExAttributes"}

params

A set of attributes used to initialize the app.

• domain: Overlay
• value: AppParams

serviceURL

The URL of the JS to fetch and execute.

• domain: ManagedJS
• value: URI

serviceType

If value is "kynetx" then the browser extension that will inject the Javascript for this app-card should construct a Kynetx-compatible <script> block and call an initialization URL based on the value of the appService attribute.

• domain: ManagedJS
• value: string whose value is one of ("kynetx", "higgins").

sites

This is not a list of specific URIs, it is a list of strings to match in the domain name part of a URI. So urn:google would fire on maps.google.com, www.google.com, www.googleismyfavoritesite.com. For Kynetx-powered cards (i.e. if appServer = http[s]://init.kobj.net"), the values of this attribute should be dynamically fetched using the 'dispatch' method at URL: [1]<appId>.

• domain: Overlay
• value: string

version

A human readable version of the app. Note: If appServer == http(s)://init.kobj.net, then the Kynetx KNS "describe" API can be used by a context Provider implementation to provide this attribute value.

• domain: JavaScript
• value: string

Related Person attributes

Person attributes consumed by a ManagedJS.

enabledSites

The URLs of sites that the user has enabled the app to run on. Note that this augments the appSites value provided by the app developer which indicates the set of sites the app was designed to run on.

• value: boolean

disabledSites

The URLs of sites that the user has disabled the app from running on.

• value: xsd:anyURI

appEnabled

If true run this app

• value: xsd:anyURI

Example WebsiteFacade template context

Errata: app-data:script attribute should be removed from above

SVN source

ManagedJS Processing Model

Invoking Javascript

The Higgins browser extension is responsible for invoking the app/Javascript for all app-data contexts. This is done three ways. If appJS is not nil, then its value IS the app to invoke. If the appJS is nil, then the appServiceType indicates whether a Kynetx-style KNS invocation should be done or an (as yet undefined) Higgins-style invocation from some Higgins-hosted web service should be done. In the above example the appServiceType = kynetx so a KNS invocation will be done.

App/rule Id parameter

In the non-appJS (i.e. kynetx and/or azigo cases) the appId is required to specify which app (Javascript program) should be run. In the above example the appId (called a rule id by KNS) is "1024".

Before the Javascript is invoked on a given Web page HBX must determine for each AppDataContext if the current page is one that matches one or more card's site list.

Gather parameters to the Javascript

The browser extension and supporting code must implement the following algorithm to gather all necessary parameters to the Javascript function:

• Get the value of all attributes of the entity of the "appParams" attribute of the context object (ignoring rdfs:comment, rdf:label attributes, rdf:type, etc.).
• Get the value of all attributes of the main p:Person entity that are named in the context object's entityParam attribute value(s).

Making parameters/values available to the app (Javascript)

How parameters are inserted varies by service type. Here is how it is done for a "kynetx" serviceType:

var KOBJ_config ={
   "rids"  : ["1024","xyz123"],
   "1024:dataset" : "aaawa",
   "1024:dataset" : "ebates",
   "1024:favorite-song" : "Billy Joel: The Piano Man",
};

This tells kynetx to run rules 1024 and xyz123, and for rule 1024, use dataset=aaawa and dataset=ebates. Note that each appParam value is namespaced by the appId (aka rule id, or rid) to which it is associated.

Links

• Persona Data Model 2.0
• Persona vocabulary