PlugIn Project Integration

Overview

Creating connections between projects with code hooks that send data between them.

Structure

PlugIn Schema

• each plugIn is identified by a plugInTag
• ? projects list out which plugInTags connect with each of it's objTypes

ObjType Connection

• a plugIn is expected to connect with one objType
• requests sent to the plugIn must always send an identifier of that objType so the plugIn can identify the connection
• object schema lists which plugInTags can be connected with it's instances

PlugIn Hooks

• ? each plugInTag schema has a list of it's plugInHookTags
• flowStep in flow schema lists which plugInHookTags are invoked from that flowStep
• flowType's may or may not have objType set, and does not have to be the same objType as the plugIn connects to
• any flowStep that has a plugInHookTag must be able to identify an instance of the parent plugIn's objType

submittedBy userId

• submittedBy userId is passed between plugIn projects
• see User_Data_Handling#Per_Project_User_Data

Configuring Connection

• each project has user level RBAC permission for each available plugIn
• if createInstance = false user with permission can send a request to create new connection
• receiving project must have plugIn schema matching initiating project, and createInstance = true
• new base objType instance is created, including RBAC and AccountLimits for the submitted by userId

PlugIn Creates Instance

• both sides of a plugIn have plugIn schema for the other side
• allows the plugIn connection to be bidirectional and use standard plugInHook structure
• in plugIn schema have boolean property createInstance
• when creating the initial connection createInstance = false initiates the request, createInstance = true creates and instance when receiving a request to make new connection

example

• Commerce has ComAcc plugIn and does not create Business instance
• ComAcc has Commerce plugIn and does create ComAccBusiness instance
• ComAcc has Accounting plugIn and does not create ComAccBusiness instance
• Accounting has ComAcc plugIn and does create Organization instance

Connect with Existing Instance

• if initiating project sends request for connection to project where plugIn schema is set to createInstance = false, identifier of existing instance must be sent as well
• setting the createInstance setting on both sides of a plugIn sets whether the plugIn connection is between two existing instances, or an existing instance and create a new instance
• if both sides are createInstance = false user must have permission to create plugIn on both instances

Common Concepts

PlugIn Project

• connects two projects together
• maintains configuration settings that are specific to the connection
• handles flows specific to the connection
• The two connected projects have as little linkage code or data structures as possible, abstract this into the plugin project
• possible that a plugin project could connect multiple projects, eg a logging or analysis plugin

Link Objects

• when object in one project connects with an object in another another project a plugin hook connects to the plugin project which records the per instance links
• required when future flows require knowledge of previous links

Link Configs

• configuration for the plugIn project is handled within the plugIn's own interface
• eg setting which Accounting Accounts connect with which Commerce initiated flows, such as transactions, purchase orders, sales
• plugIn Project has it's own graph with submittedBy, versionData, RBAC etc..

Locking Data

• It might be required that when a plugin connection flows are blocked from proceeding as they can only be initiated from the plugin
• eg once an Accounting Organization is linked to Commerce it might not be possible to add entries directly through the Accounting interface
• can code this into flows where the plugIn hook returns a switch that throws an error in the calling project
• eg: when Accounting Organization is linked to ComAcc add a plugInHook to create Ledger flow which sends request to ComAcc which throws error, because should never get a request from Accounting to create a Ledger, it should come from Commerce

Working documents

PlugIn Project Integration