Fautore API: osaInvite

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

Fautore API: osaInvite

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.

A real world meeting of two people occurs (Tome and Mary)
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.
Tom enters the FQDN, port (if other than 1895) and invite password to his OCE.
Tom's OCE sends an osaInvite to Mary's OCE.
Mary's OCE receive's the invite and validates the password received in the invite is correct.
An encrypted connection is set up using the passed InviteKey.
Tom's POD information is stored to Mary's OCE
Mary's OCE acknowledges receipt by passing a success MsgId (1) and a new POD key in the Mesg value.
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.
Tom's OCE send Mary's OCE an osaNewKey API call with the key his OCE created by merging with Mary's returned key.
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.