Fautore Instructions
Fautore instructions define how messages are routed between between Fautore, its registered applications and other OCE environments. Instructions also define what message content should arrive to each
Table of contents
Instruction Access
The abiity to define and modify instructions is available to the Chieftain and all Chiefs in Fautore. This capability can be assigned to other members as well through the Fautore permissions system.
Instruction Structure
An instruction is collectively made up of action criteria, recipients and content definitions. More than one instruction may apply to a single message. Instructions are applied to inbound messages, after being stored to the "Staging" table, to create a queued list of recipients. Content definitions of the instruction are applied to outbound messages as they are constructed.
Instruction Flow
An instruction is defined with concentric granularity. First an instruction itself is defined and in itself carries no routing value. The instruction acts as a container to relating criteria for determining message applicability with a list of recipient intended to receive messages matching criteria. Optionally, message modification instructions can be defined on a per recipient basis after once the recipients are defined.
Action criteria
The action criteria of an instruction is applied to inbound messages as they arrive after being stored to the "Staging" table. The criteria is made up of base message field references
Criteria Status
This table defines each criteria type and it's current development status.
| Type | Status | Description |
|---|---|---|
| Message | Test | Staging table columns used in match data comparisons. Commonly used to define a criteria for what application sent the message, or by whom it was sent. |
| Application | Pending | Application specific field available for match data comparisons. Intended use is to evaluate application specific data, such as "priority" or some such value for message data matching. |
| Function | Design | Function definitions returning boolean to indicate if a match is made. A function might be used to check status of a recipient application application, or if a particular tribe member is logged into an application. |
Criteria functional description
Messages are immediately queued after they are determined to be legitimate as a measure to insure against loss and to allow for future efficiency gains by segregating the instruction processing from the intake function. Once an instruction is queued the it core message data is extracted again from the Staging table and stored in memory. Each instruction is then extracted along with all of its associated criteria. Each defined criterian for the instruction is then pulled and matched to its main instruction definition in a master instruction data structure. The message data is then evaluated against each of the criterian for every instruction.
Instruction Construction
The construction of an instruction is broken into 4 steps.
- Master instruction naming
- Criteria definition for each master instruction
- Recipient assignment to each master instruction
- Data specification for each recipient
Master Instruction Naming
The name of the instruction is defined in a single freeform input field. The name is not the record key and can be changed later. Once a name is entered the data is saved and the workflow proceeds to Criteria definition.
Criteria Definition
The criteria definition is keyed to the master record. All criteria defined for this instruction belongs to the one instruction alone. The name of the instruction should appear on the criteria definition screen for clarity. All criteria possibilities are predefined in the Instruction_Criteria table and should be extracted from that table for screen presentation. This is a major function of the OCE and needs to be made as simple for use as possible. The initial concept is one of loading the available criteria to a view panel on the left side of the window. Each possibility for evaluation would then be available for drag and drop to a panel on the right to indicate it is currently in use. A panel beneath the two drag and drop panels would be populated for the detail definition possibilities for criterion clicked in the right panel. The "IPC_Gui_Name" field should be used for screen presentation of each criteria possibility. The "IPC_Type" is optionally displayed with the criterion name or used to break the criterion into categories on the screen. The "IPC_ref" field is not displayed, but stored in the "Instruction_Criteria" table with the rest of the data associated with the criteria specified in the right panel.
Detail criterion
The detail criterian definition panel is made up of four fields. These fields should appear in a way that all defined criteria can be seen at once with unwanted criteria being easily changed or deleted via the displayed table.
- 1. Data Source
- Field specification as the left operand of the filter data comparison. This data is drawn from the Instruction_Criteria table.
Column Description Example IPC_Gui_Name Name of the element to be used in a comparison as it would be used on the screen. Title IPC_Ref The technical reference location for accessing data in the Fautore application. Staging::msgTitle IPC_Type The categorical type of data element. This is used to define how data is accessed and processed. Message
- 2. Data operator
- The "Data Operator field is an operator defines the data relationship. This should be a dropdown listing all possible operators. Lets stay with the common =, >, <, != for the time being. The resultant selection should be stored to the ACE_Operator field of the Instruction_Criteria table as the literal operator as displayed on the screen.
- 3. Data value
- This is a text entry field for accepting comparative values. Leaving this field empty is acceptable as a way of specifying a match if the passed data value is defined at all.
- 4. Criterian relationship
- Indicates whether this is an "and" or an "or" relationship to the other records. This field is not available for the first criterion, but only for all subsequent criterion defined for the instruction. The literal values of "and" or "or" are stored to the ACE_Rel column of the Instruction_Criteria table for this field.
Criteria Specs
The below table defines the data to be collected via the GUI, from where supporting screen data is collected and to where collected data is saved.
| Field | Type | Descrip Src | Data Dest | Description |
|---|---|---|---|---|
| Criteria | Dropdown | Static Text | N/A | Defines the left hand operand of the criteria definition. |
| Criteria:Label | Dropdown Label | Inst_Poss_Criteria::IPC_Gui_Name | N/A | Displayed label of dropdown |
| Criteria:Value | Dropdown Value | Inst_Poss_Criteria::IPC_Ref | Instruction_Criteria::IC_Ref | Defines value stored when dropdown item is selected. |
| Operator | Dropdown | Static Text | N/A | Defines comparison operator. It may make sense to not label this field, but just let the dropdown values speak for themselves. |
| Operator:Label | Dropdown Label | Static Text | N/A | These literal values =~, =, != <, > |
| Operator:Value | Dropdown Value | Static Text | Instruction_Criteria::IC_Operator | Same value as the label. No translation. |
| Value | Text | Freeform Data Entry | Instruction_Criteria::IC_Value | Defines the right hand operand of the criteria definition. |
| Relationship | Dropdown Value | Static Text | N/A | Determines relationship to other records in the instruction criteria. |
| Relationship:Label | Dropdown Label | Static Text | N/A | Either "and" or "or" literals. It may make sense to not label this field, but just let the dropdown values speak for themselves. |
| Relationship:Value | Dropdown Value | Static Text | Instruction_Criteria::IC_Rel | Same value as the label. No translation. |
Criteria Ordinality
This table illustrates what values for the recipient are required and how the system reacts with or without the value(s). In short all values are optional, but at least one must be defined to have a viable instruction.
| Field | Ordinality | _Detail__ |
|---|---|---|
| Criteria | Required | Must exist to determine message criter to be examined. |
| Operator | Optional | Lack of an operator implies an "exists" relationship of the criteria value being set to anything at all. |
| Value | Optional | Not required if "Operator" is not defined. Required if operator is defined. |
| Relationship | Optional | An "and" relationship between criteria is assumed if undefined. |
Recipient Definition
The Recipient Definition screen ties who should receive the message to the instruction. Recipient definitions are not tied directly to the instruction criteria. The criteria determines only if the instruction applies. All recipients defined in the instruction will receive the message. The name of the instruction should appear on the recipient definition screen for clarity.
The input for the Recipient definition screen is a series of dropdowns, one for each category of recipient. Alternatively one dropdown listing the categories could be selected that would trigger the population of available recipients in that category. The dropdowns should be multi-select. Each selected datum is stored as a single row in the Instruction_Recips table. Another possibility, taking advantage of drag and drop, could be to create a panel of icons for each category and an additional panel for the previously defined Insrtuction. Each category panel would have an icone representing a prospective recipient in each of the categories. The icone would then be dragged from the gategory panels and dropped into the instruction panel.
All defined recipient categories, except "Tribe," are but suggestions to the receiving OCE. The "Tribe value defines to where the message matching the criteria is sent. The default behaviour of the OCE is to deliver a message as requested in all criteria, however an OCE administrator has the ability to modify the routing of a message based on the defined instructions of the recipient OCE.
Recipient Categorie
Recipients can fall into any of several categories that essentially reflect the hierarchy of the Tribe structure. The below table lists the categories, the tables from which the presented data is retrieved and the destination to which the selected data is stored.
| Category | Type | Presentation Src | Data Dest | Description |
|---|---|---|---|---|
| Instruction Key | Hidden | Instruction_Criteria::IC_ID | Instruction_Recips::Inst_IID | The unique instruction key to which the defined recipient is associated. |
| Tribe | Dropdown | Static Text | N/A | Presents a list of tribes for selection. Only data applicable to the selected tribe is in the rest of the categories. |
| Tribe:Label | Dropdown LabelTribe::TribeName | N/A | Displayed label of dropdown | |
| Tribe:Value | Dropdown Value | Tribe::TribeKey | Instruction_Recips::IR_Tribe | Defines value stored when dropdown item is selected. |
| Coterie | Dropdown | Static Text | N/A | Defines coterie to which messages are sent. Currently only Coteries for the local tribe are processes. It is a future consideration to be able to send to remote Coteries. |
| Coterie:Label | Dropdown Label | Coterie::cotName | N/A | Displayed dropdown item name |
| Coterie:Value | Dropdown Value | Coterie::CID | Instruction_Recips::IR_Coterie | Selected dropdown value stored when saved. |
| Application | Dropdown | Static Text | N/A | Identifies application intended to receive message data. |
| Application:Label | Dropdown Label | Application::appName | N/A | Displayed dropdown item name |
| Application:Value | Dropdown Value | Application::appId | Instruction_Recips::IR_Application | Selected dropdown value stored when saved. |
| Group | Dropdown | Static Text | N/A | Defines group to which messages are sent. Currently only groups for the local tribe are processes. It is a future consideration to be able to send to remote groups. |
| Group:Label | Dropdown Label | Group::groupName | N/A | Displayed dropdown item name |
| Group:Value | Dropdown Value | Group::CID | Instruction_Recips::IR_Group | Selected dropdown value stored when saved. |
| Member | Dropdown | Static Text | N/A | Defines Tribe Member to which messages are sent. Remote Tribe Members must be locally registered to receive direct messages. |
| Member:Label | Dropdown Label | User::userName RemoteUser::remName |
N/A | Displayed dropdown item name |
| Member:Value | Dropdown Value | User::userKey RemoteUser::remUID |
Instruction_Recips::IR_Tribe_Member | Selected dropdown value stored when saved. |
| Commons | Dropdown | Static Text | N/A | Defines Commons to which messages are sent. Commons processing not yet developed. |
| Commons:Label | Dropdown Label | TBD | N/A | Displayed dropdown item name |
| Commons:Value | Dropdown Value | TBD | Instruction_Recips::IR_Commons | Selected dropdown value stored when saved. |
| Function | Dropdown | Static Text | N/A | Defines function to be used dure instruction processing. Not yet implemented. The details still need to be worked out. It may be positioned incorrectly in the DB at the moment. |
| Function:Label | Dropdown Label | Fautore::ActFunc->listFuncs() | N/A | Displayed dropdown item name. The information supporting this field will come from a call to the "listFuncs" function of the Fautore:: module once the details are worked out and this capability is fully implemented. |
| Function:Value | Dropdown Value | Fautore::ActFunc->listFuncs() | Instruction_Recips::IR_Function | Selected dropdown value stored when saved.The information supporting this field will come from a call to the "listFuncs" function of the Fautore:: module once the details are worked out and this capability is fully implemented. |
Recipient Ordinality
This table illustrates what values defining the recipient are required and how the system reacts with or without the value(s). In short all values are optional, but at least one must be defined to have a viable instruction. This section is authored from the perspective that dropdown menus are being used for for the presentation screen. If a drag and drop approach is taken the relationships describe below would affect icons available in icon panels rather than menu options available in dropdowns.
| Field | Ordinality | Selected | Absent | Multiselected | Relationships |
|---|---|---|---|---|---|
| Tribe | Optional | All other recipient input fields are constrained to listing only information related to that Tribe | The tribe is defaulted to the local tribe and only recipient information related to the local tribe is available. | Data of other recipient categories related to all selected Tribes are available. | The Tribe category list is the master determinating factor for screen option availability. No other category display to the screen affects what is displayed in the Tribe category. |
| Coterie | Optional | All other recipient input fields are constrained to listing only information related to that Coterie | The presented data in all categories is constrained only by the coterie to which the member currently defining the instruction has access. | Data in other categories are limited to all selected Coteries. | Coteries available for selection are limited to those available to the instruction defining member for the Tribe selected, or permissioned Coteries in local Tribe if no Tribe is selected. |
| Application | Optional | Only members with permission to use the selected application are available in the "Members" category. | All members permissable by Tribe, Coterie and Group categories are available for selection. | Tribe member category list XORs one another. So if Members A,B, and C can use selectec app 1, but only members A and C can use selected app 2, then only A and C will be available in the Members category for selection. | Application limits only Members and Groups based on permissioned access to the selected application(s). Applications listed are constrained by the selected Tribe, and Coterie. No Tribe being selected defaults to local Tribe. |
| Group | Optional | When a group is selected only tribe members associated with that group are listed. | All tribe members accessible to the tribe member defining the instruction, and available within the constraints of selected Tribe and Coterie values, are listed. | Tribe member category list is additive base on the sum of selected groups and the tribe and coterie selections. | The primary function of the Groups categorie is to act as a filter for the members availavailable in the Members category. It also acts as a shortcut to selecting a commonly used group of Members. |
| Members | Optional | Selecting an indivual member is to restrict an instruction's output to the most restricted audience possible, a single member. | The instruction output audience is the entirety of the next larget category of recipients. | All selected members receive the instruction output. | All other recipient categories can be thought of as filters to determining the final list of members to receive the output of message matching the defined instruction criteria. |
Content Definitions
The data to be conatined in outgoing messages can be defined on a per recipient basis. Content definitions can either specify only the content to be included, or it can be specified as what content should be eliminated from a full data set. This means that if a gallery application were to send the photo to the OCE for routing with Title, summary and description, the content definitions of an instruction could be defined so that one recipient would receive the full data set by email, another would receive only the summary by SMS, and another would receive everything except the actual picture.
Content negation has the highest priority when processing content definitions. The full message is assembled with removal of negated data being the last action in this phase of message construction. This measure is taken to aid in minmizing the accidental sending of data through accidental inclusion.
Content detail
The detail content definition screen could operate any of several ways and initial implementation is up to developer judgement. The below examples should be considered starting point ideas to mix and match into reality:
- Direct
- A list of message recipient is available for clicking on the left. With each recipient being clicked a list of available data appears to the right in another panel with checkboxes to indicate whether the data should be included. The information available in the right hand panel is toggle by a radion button to indicate if it is main message data, or application specific data. Clicking the actual data reference provides the ability to choose if the data is included "+" or excluded "-" with included being the default. With the inclusion or exclusion definition is also a field to enter a member defined value that override actual message data content. This value addition can later be enhanced to include conditional replacement with member defined data.
Note: The feature of defining application data to be included or excluded is not complete yet. Current all application specific data is included at all times.
- All Dropdown
- An instruction dropdown is presented and an instruction is selected. A recipient screen in displayed and recipients are selected in a multiselect dropdown. A message attribute screen is presented. A dropdown listing possible core messageMain USDS message values, or, anything outside the "Adjunct" field. values is listed in two dropdowns, one for adding values another to mark values for deletion. Saving this screen without selecting any values will indicate all data values are to be provided in the messages sent to the selected recipients. Upon saving an opportunity to manually input constant values for selected message attributes is offered. A screen of available application attributes will need to be presentde in the future for similar processing as core message attributes once that feature is implemented.
Content Specs
The below table defines the data to be collected via the GUI, from where supporting screen data is collected and to where collected data is saved.
| Field | Type | Descrip Src | Data Dest | Description |
|---|---|---|---|---|
| Recipient | Dropdown | Static Text | N/A | Provides a list of recipients associated with current instruction being processed, not all recipients (unless all recipient are associated with the instruction). |
| Recipient:Label | Dropdown Label | Varied | N/A | Most confining value of the defined values for each defined row. See details page for this value. |
| Recipient:Value | Dropdown Value | Inst_Poss_Criteria::IPC_Ref | Instruction_Criteria::IC_Ref | Defines value stored when dropdown item is selected. |
| Message Data | Dropdown | Static Text | N/A | Lists potential message data elements available for selection to be included/excluded in the message. No selection infers all data to be included. |
| Message Data:Label | Dropdown Label | Inst_Poss_Data::IPD_GUI_Name | N/A | Should reflect a human readable representation of the key stored for the recipient. A manner to disinguish duplicate lables belonging to different PODs (Tribes) should be made available. |
| Message Data:Value | Dropdown Value | Inst_Poss_Data::IPD_Ref | Recipient_Data::RD_Ref | Formatted as {Type}-{TopSeg}::{SubSeg}::{SubSeg}. For example Msg-Object::Title would indicate the the "Title" field of the "Object" message segment. |
| Application Data | Dropdown Value | Static Text | N/A | At the time an application registers with the OCE it can submit application specific data field references that are legitimate to manipulate during, or exclude from, the message transmission. Such fields are referenced through this dropdown. Application inclusions and exclusions do not effect primary message data and vica versa. This means that if only one data field is specified for inclusion in the application data, all data is still included in the primary message unless the primary is specifically manipulated through content definitions. This feature is not yet implemented. |
| Application Data:Label | Dropdown Label | Inst_Poss_Data::IPD_GUI_Name | N/A | This value will be selected from a table of "possible application data" definition criter much like the possible message data definition table. |
| Application Data:Value | Dropdown Value | Inst_Poss_Data::IPD_Ref | Recipient_Data::RD_Ref | Formatted as {Type}-{TopSeg}::{SubSeg}::{SubSeg}. For example App-File::Path would indicate the the "Path" field of the "File" message segment, perhaps of an application that reads files from a specified disk location. |
| Data Disposition | Radio Button | Static Values | Recipient_Data::RD_Disp | Radio buttons that could have labels as simple as "+" and"-" to indicate if the selected data value should be added to, or deleted from the message for the recipient. Plus (+) and minus (-) are the actual values stored to the table for this field as well. |
| Application Data Value | Freeform Text | N/A | Recipient_Data::RD_Value | An optional static value that will be used instead of the content passed to the OCE in the message. |
Content Ordinality
This table illustrates what values for the data definition are required and how the system reacts with or without the value(s).
| Field | Ordinality | _Detail__ |
|---|---|---|
| Instruction | Required | Must be selected to determine the recipients to make available for message data modification. |
| Recipient | Required | Must be selected to determine what recipients message data is being modified. |
| Message Data | Optional | If none selected all data within the message will be made available to the recipient. |
| Application Data | OPtional | If none selected all data within the application defined segment will be made available to the recipient. |
| Disposition | Required | Defaults to "+" |
| Value | Optional | If none entered the message and application data will both be left unmodified when passed to the recipient. If data is entered the specific application or message datato which the value applies will be exchanged for the entered value. |
Default Instructions
In the interest of preventing a build up of dead messages in the OCE cache Fautore implements the concept of "default instructions." An instruction ius defined as being a default by its use of the "Default" column of the "Instruction" table. The "Default" column hold the ID (TID,CID,UID) of the entity for which the Instruction is the default.
The Instruction definition screen has a dropdown field holding the word "None," the word "Tribe," the list of the Coteries for which the logged in member is a Chief, and the login name of the currently logged in member. Any item selected from the dropdown will be stored to the "Instruction" table "default" field as the ID number representing that entity. A selection of "None" will clear the "Default" field of the "instruction" table.
Default Instruction Selection
Default instructions are defined to operate for an individual Tribe Member, All components of a Coterie or for the entire Tribe. The Member default has the highest priority and the Tribe the lowest.
There is no criteria defined for a default instruction in the "Instruction_Criteria" table. Such definitions would be superfluous since a default Instruction is used when no other instructions are found to handle the record, regardless of what criteria is would be defined for the default instruction.
Member
The member default Instruction is defined by the member through the instruction definition screen. In the future a "Set Default Instruction" button could be made available to define an initial instruction that would then be modified by the tribe member as a means of overcome the "blank paper" syndrome.
Coterie
Coterie instructions are defined by Chiefs and the Chieftain through the instruction definition screen. In the future a "Set Default Instruction" button could be made available to define an initial instruction that would then be modified by the tribe member as a means of overcome the "blank paper" syndrome.
Tribe
The tribe default instruction record is inserted at the time of the tribe creation. This record can be changed. This record can be deleted, however a new default record will be created in the place of the default record that was created. The inserted base default tribe instruction is named "<Tribe Name> Default".
/
Default Destination Selection
A default destination is derived as follows:
- Pull default instruction
- Examine instruction for recipient
- Send to recipient and application defined in the "Instruction_Recips" table.
- If an application is defined in the recipient record that application is used as an end point
- If no application exists in the record, or the defined application is unavailable, the recipient Member record is checked for a default application
- If no applictaion is defined at all, or the defined application is unavailable, the message will be written to a log file and a message communicated to the Chieftain.