Skip to content
cloudspark edited this page Jan 11, 2014 · 33 revisions

Pods are federated containers which provide a range of function across a single domain of concern. For example, sending/receiving email would be part of the 'email' pod. Everything Facebook related would be in the 'facebook' pod etc. 'related' means things like authentication management : OAuth, or 3rd party API Tokens, namespaced data sources or file access separated from all other system concerns, contained and self-managed. The methods (actions/emitters) a Pod provides are called Channels. Channels are the methods of a Pod which can be instantiated and arranged into a graph. The export of one channel is pipelined and transformed as the import to another Channel, and these graphs are called 'Bips'.

Installing Pods

From server root :

npm install bip-pod-{pod name}
./tools/pod-install -a {pod name}

Pods are enabled in BipIO automatically during install by creating an entry in the pods section of your config file (config/{environment}.json. Depending on the pod you're installing, it may require further configuration, such as oAuth application keys etc.

Restart the server at your convenience.

Schemas

Pods are collection of similar actions (channels), and each action has its own schema. Schemas tell you a little about the capabilities of a pod and describe the attributes, imports, exports and configs any of its channels have. Schema's use parts of JSON Schema.

Schema sample :

{
  "email": {
    "name": "email",
    "description": "Email",
    "auth": {
      "type": "none",
      "status": "accepted"
    },
    "actions": {
      "smtp_forward": {
        "description": "Send an Email",
        "description_long": "Use to forward email messages to a chosen recipient (requires recipient verification)",
        "auth_required": false,
        "trigger": false,
        "singleton": false,
        "config": {
          "properties": {
            "rcpt_to": {
              "type": "string",
              "description": "Email Address (eg: [email protected])",
              "optional": false,
              "unique": true,
              "validate": [ {
                "pattern": "email",
                "msg": "Invalid Email"
              }]
            }
          }
        },
        "renderers": {
          "verify": {
            "description": "Recipient Verify",
            "description_long": "Verifies this email channel recipient with a secret key sent to their inbox",
            "contentType": "text/html"
          }
        },
        "exports": {
          "properties": {
            "response_code": {
              "description": "SMTP Response Code"
            },
            "response_message": {
              "description": "SMTP Response Message"
            }
          }
        },
        "imports": {
          "properties": {
            "subject": {
              "description": "Message Subject"
            },
            "body_html": {
              "description": "HTML Message Body"
            },
            "body_text": {
              "description": "Text Message Body"
            },
            "reply_to": {
              "description": "Reply To"
            }
          }
        }
      }
    }
  }
}

For some Channels, it makes no sense to have two instances of the same kind present at any time. These channels are marked as singleton. The system doesn't prohibit multiple instances of singleton's, but use this flag as a guide when creating channels in an automated fashion

Describing Pods

To determine which channels are available for a pod, use the rpc

GET /rpc/pod/describe/{pod name}

Channels are created by pointing their action attribute to {pod name}.{action name}. For example, email.smtp_forward :

How To Find an Action

Authentication

OAuth

Issuer Tokens

Creating Pods

A boilerplate sample is contained in the bip-pod repository for reference. This will be updated with more complex examples and can act as a working tutorial for building your own pods.

Clone this wiki locally