Loading...
 
Page actions
Print

Fautore API: osaAppReg

Applications are end points between which data is transferred. Both sending and receiving applications must be registered with the POD OCE. The osaAppReg function is the means by which an application registers with an OCE.

Overview

This page details the operation and use of the "osaAppReg" function. Applications are registered with an OCE as data sources and destinations. Applications are registered to provide theOCE administrator(s) options for moving data to and from external applications. Application agents are also registered to the OCE just like applications themselves.

An application must be approved by an authorized administrator before it can be used.

Registration Structure

The application registration data structure is constructed of encoded JSON passed within the "Adjunct":"Data" portion of the master OSA message being used to pass the data to the OCE.

Function: osaAppReg

Source:
All data is provided by registering application. Alternatively, Fautore screens could be developed at a future time for the manual registration of an application.

Example:
This is a decoded JSON data structure extracted from the "Adjunct":"Data" portion of the master OSDS.

Request Example
$json = '{ "Func": "osaAppReg",
      "AppName":     "fauEmail",
      "AppId" : "SMTP:HammersFamousEmailApp",
      "Maintainer": "Technoloy Advocates"
      "CompatibilityDate": "2014-06-22",
      "Description": "Email utility to treat a mail server as a contributing team member",
      "UserName":    "Crazed1",
      "ocePush":     1,
      "AppPull":     0,
      "AppLoc":     "/home/member/fautore/apps/fauEmail/fauEmail.pl",
      "AppSetup":   "/home/member/fautore/apps/fauEmail/fauEmail_su.pl",
      "Multiuser":  1,
      "Computer": "Thor.cichosz.org",
      "Port":     26,
      "AppUser":  "Marvin",
      "AppPass":  "R0bot",
      "Interval": 300,
      "AppVals": [
         {"TechName": "catalog",
           "DispName": "Catalog",
           "DataType": "Str",
           "Length": 42,
           "Value": "Spring"},
         {"TechName": "persKey",
          "DispName": "Personal Key",
          "DataType": "Str",
          "Length": 69,
          "Value": "ajhdfyuqw487qqweiaisfg6480403er"}
       ],
}';

Field Definitions

Below are the field definitions by section.

Main

Top level field definitions

SubField Type Disp Description
AppName string req Descriptive application name, spaces allowed
AppId string opt Application developer supplied key for use in supporting like-application default routing. The first value in this field acts as a categorical designator so that the qMsg will default delivery to any application of the same category. A second, colon separated value specifies the application to which the data should go. The second value can be thought of as the "preferred" application to receive the qMesg data. No field however; can override OCE member instructions for delivery.
Maintainer string req Indicator of person or company responsible for maintaining the app
CompatibilityDate date req Earliest date with which the current app version is compatible
Description string req Info to aid enablement decision by app manager
UserName string req User name of registering member, must verify
ocePush boolean req Flag (0,1) indicating if the OCE pushes data to the Application
AppPull boolean req Flag (0,1) indicating if Application pulls data from OCE
AppSetup string opt This may contain a url or a system path given by the application where a GUI exists for the entry of configuration/operational data particular to that app. Any reference in this field must be within the POD. Any reference outside the POD will trigger a PODEXT error and be ignored.
AppRun string opt This may contain a system path to stop/start/restart the app. If present when the OCE starts or stops etc the app. Thus the app is sync'd to the OCE
Note: this field is optional and only is triggered if an app is approved.
DefVals hash opt Hash of values considered defaults for interfacing with the application.
AppVals array opt Array of additional application specific values.

DefVals

Hash of values considered defaults for interfacing with the application. These are all considered optional because none may be required by some applications. An application that is "pull only" on outbound from the OCE and "push only into the OCE need not have any of these values.

SubField Type Disp Description
AppName string req Descriptive application name, spaces allowed
Computer string opt Host name or IP address of application host
Port int opt Application port number on application host computer
AppUser string opt Application user name on remote computer
AppPass string opt Application user password on remote computer
Interval int opt Polling interval at which application interaction should occur

AppVals

An array of hashes storing custom application defined values for use by the OCE when interacting with the application. Application values are broken into two classes. Each hash element name (referred to as <TechName> in the above "Request Example") is the technical name representing the data and would presumably reference a database field or some other data storage meaningful to the application.

cfg
The configuration class of application values define values that should be passed with every message. These could be things like encryption keys or some other identifying information to help the application be certain it is working with the OCE it is expecting as a form of reverse secondary authentication. Other possibilities could be values for where additional data could be picked up or any other endless number of possibilities.
data
The data class of application values defines data values that can be defined from within the OCE rules for use by the receiving application in data messages. Uses for this capability could, for example, be to inform the receiving application which of several functionalities it supports should process the incoming data. A content management system with a weBLog, Gallery and Forum could use this class of information to define what features should receive the data.
SubField Type Length Disp Description
Class string 4 req Defines whether this is a configuration item or data definition element
DataType string 16 req Data type stored in the dynamic application variable
DispName string 64 req Field name in dynamically created forms
Value string 128 opt Value for application specific field
Length int 4b req Length of dynamic application field

Returns:

The response returned is a 2 field JSON structure:

MsgId:
  • Positive numbers indicate success
  • Negative numbers indicate rejection
  • NULL = Request failure, programmatic error

Mesg:

  • Descriptive text explaining the MsgId

Upon Success:

  • MsgId = 1
  • Mesg = Fautore id for the application reference


Upon Rejection:

  • MsgId = negative reason code (table of codes TBD)
  • Mesg = Text of message describing reason for rejection (i.e. Application already registered for user.)


Upon Failure:

  • NULL

Data Mapping

Data accepted by the osaAppReg function stores it's data as indicated in the below table.

Note:

  • The RegApps table must be populated before the Apps table
  • The RegApps:AppId generated for the application is reused in the Apps table

JSON Table Field Comments
AppName RegApps AppName Straight copy from JSON to table.
Description RegApps Description Straight copy from JSON to table.
UserName RegApps UserName Verified against "User" table before insertion.
AppPush RegApps AppPush Straight copy from JSON to table.
FauPull RegApps FauPull Straight copy from JSON to table.
DefVals - - Pointer to default values for the application. These values are supplied to Tribe Members as defaults when they enroll in application use.
Computer Apps Computer The hostname or IP address of the computer hosting the application. This value must be verified as being within the FOD.
Port Apps Port The port on the host computer by which the application is accessed.
AppUser Apps AppUser Login id used to access the application.
AppPass Apps AppPass Password associated with AppUser. This is a problem point. we need a way to store this information securely, yet still be able to pass it back to the application later n a form it understads.
Interval Apps Interval Number of seconds between iterations of accessing the application.
- Apps User_UID This value is not passed from the application. This is always "default" to indicate this is the default value set for the application. There should always be 1 and only 1 of these records associate with any application.
- Apps RegApps_AppId The unique application id assigned when data was stored to the RegApp table.

Workflows

The below workflows describe the process for registering an aplpication for use with a Fautore Tribe, configuring it for use and configuring it into a Tribe instruction.

Application Registration

Registration is the process of making an application available to Fautore. A registered application is not useable until after it has been configured and activited by a Application ManagerAn application manager is any tribe member with the "Manage Apps" privelege..

  1. Application queries Fautore well known port in the IANA "User Ports" range with a registration request.
  2. Fautore returns Dynamic port address of Registration Service
  3. Application sends registration criteria to Registration Service
  4. Registration service verifies provided TUID exists
  5. Registration service verifies provided password matches for the TUID
  6. Registration service Verifies provided TUID has privileges to register application
  7. Registration service creates Unique Fautore ID (UFID) for application
  8. Registration service creates a record for the application in the "Apps" table
    1. Unique Fautore Identifier (UFID)
    2. Tribe User Id of registering user
    3. AppPush value
    4. FauPull value
    5. Registration date
    6. Default for "Computer" if provided (IP/Hostname)
    7. Default for "Port" if provided
    8. Default for "appUser" if provided
    9. Default for "appPass" if provided
    10. Default for "Interval" if provided
  9. Registration service creates a new record in the "AppSpecs" table for each set of application specific field values provided.

Application Configuration

Once an application is registered with the Tribe it must be configured to function correctly with values specifying how to interact with the remote data source. After configuration is complete the application is then activated (With the click of a checkbox).

  1. Application ManagerAn application manager is any tribe member with the "Manage Apps" privilege. logs into the Tribe.
  2. Application Manager brings up the "Application Management" screen.
  3. Application Management screen presents a list of registered applications and their "Active" status.
    1. Application name is a link to an "Application Detailed Information" screen.
  4. Application Manager clicks link for newly added application.
  5. Fautore builds "Application Detailed Information" screen
    1. Standard fields stored by the tribe are selected from the "Apps" table for the application.
    2. Application specific data descriptors are selected from "AppSpecs"
    3. Any values associated with the application data descriptors are selected from the "AppSpecData" table.
    4. The page is built using the "Apps" data as default for the standard form fields, the "AppSpecs" data to construct the form fields for the application specific data and the data pulled from "AppSpecsData" as the default values for the application specific fields.
  6. Application Manager fills in any missing data and saves the form.
  7. The Application Manager is returned to the "Application Management" screen
  8. Application Manager clicks the "Active" checkbox to activate the application for tribe use
  9. Fautore verifies the parameters of the application access systems only within the Fautore Operational Domain (FOD).
    1. If the "Computer" value for the application is a FQDN the domain name portion must match that of the Tribe FQDN or be "localhost"
    2. If the "Computer" value for the application is an IP address it must fall within the Ethernet IP broadcast mapping for the local LAN.
  10. The application is marked as "active" with a successful FOD verification or an appropriate error is present otherwise.

Application Use

This section is provided for context only. Exact steps for mapping applications to tribe members and activities are yet to be determined.

  1. Coterie Chief selects from active list of applications to enable them for use in their individual Coterie.
  2. Any Tribe member with sufficient privilege for creating instructions accesses the "Instruction Definition" screen.
  3. The "Data Source" section of the screen present fields listing Tribe/Coterie Members, Applications, "RegEx" filter defs for "Summary Content" and "Detail Content," and a "Data Type" pull down that would list values such as "Text," "Images," "Sound" and "Video."
  4. The "Data Destination" section of the screen present fields listing Tribe/Coterie Members, Applications, "RegEx" filter defs for "Summary Content" and "Detail Content," and a "Data Type" pull down that would list values such as "Text," "Images," "Sound" and "Video."
  5. Tribe Member selects an application from the source dropdown
  6. Tribe member selects any additional criteria to narrow down the source trigger.
  7. Tribe member selects an application from the destinations dropdown.
  8. Tribe member select data types to send
  9. Tribe member save rule
  10. Any data placed into the staging area matching the terms of the "source" portion of the rule will be sent to the destination application.



Comments
Seven steps to using the Internet in privacy as a respected Netizen.
  1. Perspective
  2. Search
  3. Email
  4. Social Security
  5. Have Presence
  6. Take Control
  7. Break The Ties

Shoutbox

Steve: Fautore 0.6.0.0 is now released and available to our registered Alpha participants!
Steve: Fautore 5.3.0 is now released and includes dynamically updated stats reporting!
Steve: Fautore 0.5.2.3 FILES.pm patch is up on the site. Thanks for the inputs. Keep it coming. We'll make Fautore a reality together.