Pods
Pods are federated containers which you string together to do really interesting things.
A single pod is responsible for carrying out all of the functionality of that service, as well as authentication management (OAuth or 3rd party API Tokens), data sources, file access and anything else that you can do by using that service. For example, sending/receiving email would be part of the 'email' pod. Everything Facebook related would be in the 'facebook' pod etc.
By stringing pods together, you can easily create complex workflows that allow you to accomplish what would otherwise take many individual manual steps or wouldn't otherwise be possible. Have a look at what others are doing here!
- Getting Started
- index.js
- Config Options
- Adding Actions
- Constructor
- Schema
- RPC's
- Setup
- Teardown
- Channel Invoker
- Enabling Pods
The methods (actions) a Pod provides are instantiated via the API to create Channels.
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/{environment}.json file. Depending on the pod you're installing, it may require further configuration, such as oAuth application keys etc.
Restart the server at your convenience.
Pods are a collection of grouped actions and each action has its own 'schema'. Schemas tell you about the capabilities of a pod and describe the attributes, imports, exports and configs any of its channels have.
Schema sample :
{
"email": {
"name": "email", // Pod Name
"description": "Email", // Short Description
"description_long" : "Email for Everybody" // Long Description
"auth": { // Authentication requirements
"type": "none", // none|issuer_token|oauth
"status": "accepted", // Auth Status. acceppted|required
"_href" : "", // auth setup url,
"scopes" : [], // oauth : Requested scopes
"authKeys" : [], // oauth : Config keys
"authMap" : { // issuer_token : username/password label map
"password" : "API Token"
}
},
"actions": { // action list
"smtp_forward": { // actio name
"description": "Send an Email", // Action Description
"description_long": "Use to forward email messages to a chosen recipient", // Action Long Description
"trigger": false, // Action is an emitter
"singleton": false, // Action should be singleton
"config": { // Channel Configuration Schema (JSON Schema)
"properties": {
"rcpt_to": {
"type": "string",
"description": "Email Address (eg: [email protected])",
"optional": false,
"unique": true,
"validate": [ {
"pattern": "email",
"msg": "Invalid Email"
}]
}
}
},
"renderers": { // renderer list
"verify": { // renderer name
"description": "Recipient Verify", // description
"description_long": "Verifies this email channel recipient with a secret key sent to their inbox", // long description
"contentType": "text/html" // response content type
}
},
"exports": { // Channel Exports (JSON Schema)
"properties": {
"response_code": {
"description": "SMTP Response Code"
},
"response_message": {
"description": "SMTP Response Message"
}
}
},
"imports": { // Channel Imports (JSON Schema)
"properties": {
"subject": {
"description": "Message Subject"
},
"body_html": {
"description": "HTML Message Body"
},
"body_text": {
"description": "Text Message Body"
},
"reply_to": {
"description": "Reply To"
}
}
}
}
}
}
}
For attributes marked as JSON Schema (config/exports/imports), refer to (http://json-schema.org)
For some actions, it makes no sense to have two instances of the same kind present at any time. These actions 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. As a rule, singletons don't require user config to operate and when a Pod with singletons is enable by a user (via oAuth for instance) - these Channels will be automatically created.
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 :
To use a Pod with a 3rd party provider, and in particular with the case of OAuth, you will need to register your application with the provider so that users can authenticate their accounts for use in your system. ClientID's/Secrets and Callbacks for apps are defined in the config file under the appropriate config section for a pod.
To start the server side oAuth process for a Pod at the Account level for an OAuth enabled pod, the client must call :
/rpc/oauth/{pod name}/auth
Its best to start this process from within a browser. This will negotiate the token for the API authenticated user.
App Registration
Pods requiring OAuth will need to be registered as an 'App' with their target web service. As part of this process, you may be asked to provide a callback URL, which should be :
/rpc/oauth/{pod name}/cb
eg :
http://localhost:5000/rpc/oauth/facebook/cb
'Issuer Tokens' are an abstraction which take a username and/or password for storage and re-use against a single account. It is up to the Pod to implement and the authentication URI will be raised in the Pod schema description (/rpc/describe/pod/{pod name}). The authMap in this structure will label the required fields in the same nomenclature as the Pods provider site. For example, if authMap is :
"authMap" : {
"password" : "API Token"
}
... for 'Zoho', then password is what should be added to _href to set auth for the user.
eg: http://dev-local.bip.io:5000/rpc/issuer_token/zoho/set?password=abc123