The systematic consumption of Knowledge

Willful ignorance

Plugins of all kinds are largely ignorant of each other. pushbullet doesn’t know how the facts learned by youtube look like; in order for it to work, the user has to configure it so that it will get the right values from the right fields and concatenate them to form meaningful messages.

Similarly, transmission doesn’t know where the link to a torrent will be, nor will it search for it. rarbgLookup won’t ever try to guess how to put together a meaningful search term.

This is by design.

Templating

In order to generate messages, links, file paths and anything else that might be needed to make plugins work together, templates need to be written. Here’s what a template looks like:

‘The field “youtube:video:link” contains the value {{youtube:video:link}}’

If this template is applied to the fact shown in the previous chapter, the result will be this:

‘The field “youtube:video:link” contains the value https://www.youtube.com/watch?v=eWEJb_3IFBw’

The full docs of the templating system are on the egeria-temple project’s page, but here’s the part you need if all you care about is learning how to write templates.

A template is a single string that contains zero or more tokens. Text present between tokens won’t be changed. “Rendering” a template means replacing all tokens in it with a string of characters.

In a template, “||” and ”!!” are reserved sequences. “|||”, “||||” and so on are all illegal. The same goes for ”!!” and ”!!!”, ”!!!!” and so on. It’s OK if those sequences are part of the value that will be rendered, but they must not appear in the template itself.

A token is written like this: {{PRE||FIELD!!FORMAT||POST}}

The order of the various elements must be respected:

PRE is a string that will precede the value if the value is not null.

FIELD is a field of the fact being processed and resolves to wahtever value is present in that field. The value could be null.

FORMAT is the format that will be used to format the FIELD if and only if such value is a Date. It will be ignored otherwise.

POST is a string that will be appended to the value if the value is not null.

PRE, FORMAT and POST are optional. If the value is a Date, the default FORMAT is ‘YYYYMMDD’ (e.g. “20151124”).

FIELD is mandatory, but it doesn’t have to exist on data. If it’s null, undefined or empty, the entire token will be replaced by an empty string, meaning that PRE and POST will not be rendered either.

Malformed tokens will remain untouched in the final output.

The smallest token you can possibly write is {{fieldName}}. The biggest is {{On day ||happeningDate!!DD-MM-YYYY|| something happened}}.

Now let’s look again at the pushbullet configuration from the first example that appears in this guide:

{
    plugin: 'pushbullet',
    configuration: {
        identity: 'pbMyName',
        tag: "some pushbullet tag",
        mode: "link",
        title: "{{youtube:channel:title}} - {{youtube:video:publishedAt!!MM/DD/YYYY}} - {{youtube:video:title}}",
        body: "{{youtube:video:description}}"
    }
}

The parameters title and body will apply their templates to any fact sent to pushbullet. The results, if the fact is the one learned by youtube that we saw earlier, will be this:

// value generated by the template assigned to “title”:

‘Previously Recorded - 03/31/2016 - Batman V Superman Discussion (SPOILERS)’

// value generated by the template assigned to “body”:

‘From the March 30th stream, we talk about Batman V Superman at length. – Watch live at https://www.twitch.tv/previouslyrecorded_live.’

To know how to configure plugins properly you can refer to their documentation. It will tell you what you can configure, which parameter will accept templates and what the resulting value will be used for. The documentation of plugins that can learn new facts or add to them will tell you what fields will be available and what they contain.

Remember that something like 'This is a template' is also a valid template; it will always output 'This is a template' regardless of what fact it’s applied to. Think of it as a constant. Moreover, '' is also a valid template that will always output an empty string.

Private information

A number of services require their users to authenticate before they let them access the data. Egeria has a simple system by which it can learn and remember how to authenticate with various services on behalf of the user. This is set up through egeriactl auth <type> [credentials...].

When setting up authentication, always run egeriactl from a console within a graphical environment with a working browser. All OSes are supported. This is necessary because of how modern authentication works.

A few services such as Google may require you to create an API app. This documentation will help you do that.

How plugins can be addressed: plugin paths

Once the configuration is complete, a way is needed to address different plugins or different tasks. For each instance of a plugin, a path is assigned:

<task name>/<plugin name>/<instance number>

In the following example:

{   system: {},
    tasks: [{
        name: 'test',
        chain: [{
            plugin: 'youtube',
            configuration: {...}
        }, {
            plugin: 'youtube',
            configuration: {...}
        }, {
            plugin: 'filter',
            configuration: {...}
        }, {
            plugin: 'youtubeDownloader',
            configuration: {...}
        }],
    }]
}

The paths are:

  • test/youtube/0
  • test/youtube/1
  • test/filter/0
  • test/youtubeDownloader/0

The instance number always respects the order set by the user. yuotube/0 will always be the first youtube plugin that appears inside the task configuration and youtube/1 will always be the second.