Fautore API: osaInvite

Send an invitation to connect with an external POD/OCE.

Overview

This page details the operation and use of the "osaInvite" function. The invite process assumes personal interaction before an invite can be extended. The inviting OCE must first be supplied with the address, port and password of the OCE being invited before the invitation can be extended. The workflow being supported is that of one person passing another person the OCE credentials so the receiving party can then extend an inviation to connnect POD environments and begin communications. Think of it as the equivelant of giving someone your phone number and saying, "call me sometime."

Automated registration with online companies could be achieved by the company developing a data entry form to which the site visitor would enter the address, port and password for receiving the invite. The company site would then automatically send an invitation to the site visitor to partake in whatever services or marketing campaigns motivating the request to participate.

Invitation Structure

The OCE connection invitation 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: osaInvite

Source:
The inviting tribe member manually enters credentials provided by the party being invited. The local OCE populates the invitation with specifics for the remote OCE to establish a return connection.

Example:
This is a decoded JSON invitation data structure. Note that the "Adjunct=>Data" field is JSON text being carried as data within the data structure. In a live program the "Adjunct=>Data" field would be JSON decoded into its own data structure.

Full Messge Example
$Invite = { 'msgType' => 'oceOp', 'Private' => '2', 'Summary' => 'Example osaInvite data structure' 'Detail' => 'This is an example osaInvite data structure showing the API call in the "Adjunct=>Data field", 'Source' => { 'Member' => 'Bonnie', 'Key' => '41B13D17D51E24A95B13D17D51E24A95B13D17D51E24A95B13D17D51E24A95B1', 'Coterie' => '1' }, 'Adjunct' => { 'Desc' => 'An example osaInvite API call', 'Data' => '{ "Func" : "osaInvite", "InviteKey" : "54989C1A17189A9A97191A9817189A2D22253EA016AA9F221720161E80A84F18A71A41E80A84F18A71A41E80A84F18A71A41E80A84F18A71A41E80A84F18A71A", "InvitePass" : "SpeakFriendAndEnter", "Computer" : "192.168.42.117", "Port" : 1895, "PodName" : "TekAdvocates" "PodDesc" : "The OCE of the Technology Advocates", "PodManager" : "TekAdvocates", "PodMgrContact" : "Info@TekAdvocates.com" "ReqMembers" : [ { "Login" : "Todd", "fName" : "Todd", "lName" : "Pratkinson", "Pass" : "jest3ME1#&HW", "Email" : "Todd@SomeEmail.org", "About" : "Hard working little brother" }, { "Login" : "Bonnie", "fName" : "Bonnie", "lName" : "Grotsenburger", "Pass" : "G#AJE*64lq82GD", "Email" : "Bonnie@SomeEmail.org", "About" : "Sweetie pie" } ] }' }, };

Field Definitions

The below table defines each data value of the osaInvite API call itself, as stored in the "Adjunct=>Data" field. Refer to the USDS page for an explanation of the complete message structure.

Func
Required,Keyword - Name of API function being called
InviteKey
Required,128 character string (64 hex digit) key used to establish initial invitation encryption. Long term keys are exchanged within the encrypted session.
InvitePass
Required,Unlimited - Pass key provided through real world interaction by the OCE manager being invited. This pass key is used for identification purposes and not stored.
Computer
Required, 64 character sting - Computer reference (IP or FQDN) provided through real world interaction by the OCE manager being invited.

;Port|Optional, 5 digit integer - Computer port reference provided through real world interaction by the OCE manager being invited. Defaults to 1895.

PodName
Required, 60 character string - Human readable identifier for inviting POD.
PodDesc
Required, Unlimited - Human readable description for the inviting POD
PodManager
Required, 60 character string - Human readable reference to person or company responsible for the inviting OCE
PodMgrContact
Required, 254 character - Contact information for the listed POD manager, usually an email address
ReqMembers
Optional, array - List of inviting tribe members being requested for addition as remote members to the OCE being invited to register.
SubField Disp Type Description
Login req string(45) Requested login Id in remote OCE. Login to remote OCE is optionally enabled. This identifier is used primarily to recognize message senders.
fName req string(45) First name of requested OCE member
lName req string(45) Last name of requested OCE member
Pass req string(64) Requested password for requested OCE member
Email opt string(254) Email contact for requested OCE member
About opt text Descriptive text for requested OCE member

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:

  • undef

Data Mapping

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

Main

Data mapping for primary invite data

JSON Table Field Comments
InviteKey Tribe TribeKey Initial encryption key
InvitePass N/A N/A Programmatic value not stored
Computer Tribe IP network identifier for inviting computer (IP or FQDN)
Port Tribe Port Comms port on inviting computer (defaults to 1895)
PodName Tribe TribeName Human readable name for the inviting POD
PodDesc Tribe Description Textual description of inviting POD
PodManager Tribe Owner Individual or company maintaining the POD OCE
PodMgrContact Tribe email Contact information for the inviting POD. Fautore assumes it to be email, that is not however required by the spec.

ReqMembers

Data mapping for requested member data

JSON Table Field Comments
Login User UserName Remote member login
fName User fName Remote member first name
lName User lName Remote member last name
Pass User Password Password for use loging in to remote OCE, if account is enabled for login.
Email User Email Email address for requested member.
About User About Textual description of remote member.

Workflows

The below workflow describes the process for an OCE-toOCE invitation interaction. (One OCE inviting the other to connect)

Personal Invitation

"Invitation" is the process of one OCE inviting another to connect so that messages can be exchanged.


  1. A real world meeting of two people occurs (Tome and Mary)
  2. Tom says he'd like to stay in touch with Mary and she hands him a preprinted card with her OCE FQDN and port listed on the front. Mary has handwritten the current password for Tom to extend an invite to her OCE on the back of the card.
  3. Tom enters the FQDN, port (if other than 1895) and invite password to his OCE.
  4. Tom's OCE sends an osaInvite to Mary's OCE.
  5. Mary's OCE receive's the invite and validates the password received in the invite is correct.
  6. An encrypted connection is set up using the passed InviteKey.
  7. Tom's POD information is stored to Mary's OCE
  8. Mary's OCE acknowledges receipt by passing a success MsgId (1) and a new POD key in the Mesg value.
  9. Tom's OCE creates a new POD key merge's it with Mary's recently returned POD key and stores it as the relationship comms encryption key.
  10. Tom's OCE send Mary's OCE an osaNewKey API call with the key his OCE created by merging with Mary's returned key.
  11. Mary's OCE stores the passed key as being associated with Tom's OCE and return a success MsgId (1) and "Message received" type text "Mesg" value
Complete to This Point
Corporate Invitation

This needs to be finished.