Adioso Agent Creates events

The Adioso Agent will tell you the minimum airline prices between a pair of cities, and within a certain period of time.

The currency is USD. Please make sure that the difference between start_date and end_date is less than 150 days. You will need to contact Adioso for a username and password.


Aftership Agent Creates events

The Aftership agent allows you to track your shipment from aftership and emit them into events.

To be able to use the Aftership API, you need to generate an API Key. You need a paying plan to use their tracking feature.

You can use this agent to retrieve tracking data.

Provide the path for the API endpoint that you’d like to hit. For example, for all active packages, enter trackings (see https://www.aftership.com/docs/api/4/trackings), for a specific package, use trackings/SLUG/TRACKING_NUMBER and replace SLUG with a courier code and TRACKING_NUMBER with the tracking number. You can request last checkpoint of a package by providing last_checkpoint/SLUG/TRACKING_NUMBER instead.

You can get a list of courier information here https://www.aftership.com/courier

Required Options:

  • api_key - YOUR_API_KEY.
  • path request and its full path

Algorithmia Agent Creates events Receives events Dry runs huginn_algorithmia_agent

The AlgoritmiaAgent runs algorithms from Algorithmia.

You need to register an account before using this Agent.

The created event will have the output from Algorithmia in the result key. To merge incoming Events with the result, use merge for the mode key.


Attribute Difference Agent Creates events Receives events

The Attribute Difference Agent receives events and emits a new event with the difference or change of a specific attribute in comparison to the previous event received.

path specifies the JSON path of the attribute to be used from the event.

output specifies the new attribute name that will be created on the original payload and it will contain the difference or change.

method specifies if it should be…

  • percentage_change eg. Previous value was 160, new value is 116. Percentage change is -27.5
  • decimal_difference eg. Previous value was 5.5, new value is 15.2. Difference is 9.7
  • integer_difference eg. Previous value was 50, new value is 40. Difference is -10

decimal_precision defaults to 3, but you can override this if you want.

expected_update_period_in_days is used to determine if the Agent is working.

The resulting event will be a copy of the received event with the difference or change added as an extra attribute. If you use the percentage_change the attribute will be formatted as such {{attribute}}_change, otherwise it will be {{attribute}}_diff.

All configuration options will be liquid interpolated based on the incoming event.


Basecamp Agent Creates events 37signals

The Basecamp Agent checks a Basecamp project for new Events

To be able to use this Agent you need to authenticate with 37signals in the Services section first.


Bigquery Agent Creates events Receives events Dry runs huginn_bigquery_agent

The Bigquery Agent queries Google BigQuery. This is not a free service and requires a Google Cloud account.

This agent relies on service accounts for authentication, rather than oauth.

Setup:

  1. Visit the google api console
  2. Use your existing project (or create a new one)
  3. APIs & Auth -> Enable BigQuery
  4. Credentials -> Create new Client ID -> Service Account
  5. Download the JSON keyfile and either save it to a path, ie: /home/huginn/Huginn-5d12345678cd.json, or copy the value of private_key from the file.
  6. Grant that service account access to the BigQuery datasets and tables you want to query.

The JSON keyfile you downloaded earlier should look like this:

{
  "type": "service_account",
  "project_id": "huginn-123123",
  "private_key_id": "6d6b476fc6ccdb31e0f171991e5528bb396ffbe4",
  "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
  "client_email": "huginn@huginn-123123.iam.gserviceaccount.com",
  "client_id": "123123...123123",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://accounts.google.com/o/oauth2/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/huginn%40huginn-123123.iam.gserviceaccount.com"
}

Agent Configuration:

project_id - The id of the Google Cloud project.

query - The BigQuery query to run. Liquid formatting is supported to run queries based on receiving events.

use_legacy - Whether or not to use BigQuery legacy SQL or standard SQL. (Defaults to false)

max - Maximum number of rows to return. Defaults to unlimited, but results are always limited to 10 MB.

timeout - How long to wait for query to complete (in ms). Defaults to 10000.

event_per_row - Whether to create one Event per row returned, or one event with all rows as results. Defaults to false.

Authorization

keyfile - (String) The path (relative to where Huginn is running) to the JSON keyfile downloaded in step 5 above.

Alternately, keyfile can be a hash:

keyfile private_key - The private key (value of private_key from the downloaded file). Liquid formatting is supported if you want to use a Credential. (E.g., {% credential google-bigquery-key %})

keyfile client_email - The value of client_email from the downloaded file. Same as the service account email.


Boxcar Agent Receives events

The Boxcar agent sends push notifications to iPhone.

To be able to use the Boxcar end-user API, you need your Access Token. The access token is available on general “Settings” screen of Boxcar iOS app or from Boxcar Web Inbox settings page.

Please provide your access token in the user_credentials option. If you’d like to use a credential, set the user_credentials option to {% credential CREDENTIAL_NAME %}.

Options:

  • user_credentials - Boxcar access token.
  • title - Title of the message.
  • body - Body of the message.
  • source_name - Name of the source of the message. Set to Huginn by default.
  • icon_url - URL to the icon.
  • sound - Sound to be played for the notification. Set to ‘bird-1’ by default.

Change Detector Agent Creates events Receives events

The Change Detector Agent receives a stream of events and emits a new event when a property of the received event changes.

property specifies a Liquid template that expands to the property to be watched, where you can use a variable last_property for the last property value. If you want to detect a new lowest price, try this: {% assign drop = last_property | minus: price %}{% if last_property == blank or drop > 0 %}{{ price | default: last_property }}{% else %}{{ last_property }}{% endif %}

expected_update_period_in_days is used to determine if the Agent is working.

The resulting event will be a copy of the received event.


Commander Agent Receives events Controls agents

The Commander Agent is triggered by schedule or an incoming event, and commands other agents (“targets”) to run, disable, configure, or enable themselves.

Action types

Set action to one of the action types below:

  • run: Target Agents are run when this agent is triggered.

  • disable: Target Agents are disabled (if not) when this agent is triggered.

  • enable: Target Agents are enabled (if not) when this agent is triggered.

  • configure: Target Agents have their options updated with the contents of configure_options.

Here’s a tip: you can use Liquid templating to dynamically determine the action type. For example:

  • To create a CommanderAgent that receives an event from a WeatherAgent every morning to kick an agent flow that is only useful in a nice weather, try this: {% if conditions contains 'Sunny' or conditions contains 'Cloudy' %} run{% endif %}

  • Likewise, if you have a scheduled agent flow specially crafted for rainy days, try this: {% if conditions contains 'Rain' %}enable{% else %}disabled{% endif %}

  • If you want to update a WeatherAgent based on a UserLocationAgent, you could use 'action': 'configure' and set ‘configure_options’ to { 'location': '{{_location_.latlng}}' }.

  • In templating, you can use the variable target to refer to each target agent, which has the following attributes: name, options, sources, type, url, id, disabled, memory, controllers, schedule, keep_events_for, propagate_immediately, working, receivers, and control_targets.

Targets

Select Agents that you want to control from this CommanderAgent.


Csv Agent Creates events Receives events Consumes file pointer

The CsvAgent parses or serializes CSV data. When parsing, events can either be emitted for the entire CSV, or one per row.

Set mode to parse to parse CSV from incoming event, when set to serialize the agent serilizes the data of events to CSV.

Universal options

Specify the separator which is used to seperate the fields from each other (default is ,).

data_key sets the key which contains the serialized CSV or parsed CSV data in emitted events.

Parsing

If use_fields is set to a comma seperated string and the CSV file contains field headers the agent will only extract the specified fields.

output determines wheather one event per row is emitted or one event that includes all the rows.

Set with_header to true if first line of the CSV file are field names.

This agent can consume a ‘file pointer’ event from the following agents with no additional configuration: S3Agent, FtpsiteAgent, LocalFileAgent. Read more about the concept in the wiki.

When receiving the CSV data in a regular event use JSONPath to select the path in data_path. data_path is only used when the received event does not contain a ‘file pointer’.

Serializing

If use_fields is set to a comma seperated string and the first received event has a object at the specified data_path the generated CSV will only include the given fields.

Set with_header to true to include a field header in the CSV.

Use JSONPath in data_path to select with part of the received events should be serialized.


Data Output Agent Receives events

The Data Output Agent outputs received events as either RSS or JSON. Use it to output a public or private stream of Huginn data.

This Agent will output data at:

https:///users/1/web_requests/:id/:secret.xml

where :secret is one of the allowed secrets specified in your options and the extension can be xml or json.

You can setup multiple secrets so that you can individually authorize external systems to access your Huginn data.

Options:

  • secrets - An array of tokens that the requestor must provide for light-weight authentication.
  • expected_receive_period_in_days - How often you expect data to be received by this Agent from other Agents.
  • template - A JSON object representing a mapping between item output keys and incoming event values. Use Liquid to format the values. Values of the link, title, description and icon keys will be put into the <channel> section of RSS output. Value of the self key will be used as URL for this feed itself, which is useful when you serve it via reverse proxy. The item key will be repeated for every Event. The pubDate key for each item will have the creation time of the Event unless given.
  • events_to_show - The number of events to output in RSS or JSON. (default: 40)
  • ttl - A value for the <ttl> element in RSS output. (default: 60)
  • ns_media - Add yahoo media namespace in output xml
  • ns_itunes - Add itunes compatible namespace in output xml
  • rss_content_type - Content-Type for RSS output (default: application/rss+xml, application/rdf+xml;q=0.8, application/atom+xml;q=0.6, application/xml;q=0.4, text/xml;q=0.4)
  • response_headers - An object with any custom response headers. (example: {"Access-Control-Allow-Origin": "*"})
  • push_hubs - Set to a list of PubSubHubbub endpoints you want to publish an update to every time this agent receives an event. (default: none) Popular hubs include Superfeedr and Google. Note that publishing updates will make your feed URL known to the public, so if you want to keep it secret, set up a reverse proxy to serve your feed via a safe URL and specify it in template.self.

If you’d like to output RSS tags with attributes, such as enclosure, use something like the following in your template:

"enclosure": {
  "_attributes": {
    "url": "{{media_url}}",
    "length": "1234456789",
    "type": "audio/mpeg"
  }
},
"another_tag": {
  "_attributes": {
    "key": "value",
    "another_key": "another_value"
  },
  "_contents": "tag contents (can be an object for nesting)"
}

Ordering events

To specify the order of events, set events_order to an array of sort keys, each of which looks like either expression or [expression, type, descending], as described as follows:

  • expression is a Liquid template to generate a string to be used as sort key.

  • type (optional) is one of string (default), number and time, which specifies how to evaluate expression for comparison.

  • descending (optional) is a boolean value to determine if comparison should be done in descending (reverse) order, which defaults to false.

Sort keys listed earlier take precedence over ones listed later. For example, if you want to sort articles by the date and then by the author, specify [["{{date}}", "time"], "{{author}}"].

Sorting is done stably, so even if all events have the same set of sort key values the original order is retained. Also, a special Liquid variable _index_ is provided, which contains the zero-based index number of each event, which means you can exactly reverse the order of events by specifying [["{{_index_}}", "number", true]].

DataOutputAgent will select the last events_to_show entries of its received events sorted in the order specified by events_order, which is defaulted to the event creation time. So, if you have multiple source agents that may create many events in a run, you may want to either increase events_to_show to have a larger “window”, or specify the events_order option to an appropriate value (like date_published) so events from various sources are properly mixed in the resulted feed.

There is also an option events_list_order that only controls the order of events listed in the final output, without attempting to maintain a total order of received events. It has the same format as events_order and is defaulted to [["{{_index_}}","number",true]] so the selected events are listed in reverse order like most popular RSS feeds list their articles.

Liquid Templating

In Liquid templating, the following variable is available:

  • events: An array of events being output, sorted in the given order, up to events_to_show in number. For example, if source events contain a site title in the site_title key, you can refer to it in template.title by putting {{events.first.site_title}}.

De Duplication Agent Creates events Receives events

The De-duplication Agent receives a stream of events and remits the event if it is not a duplicate.

property the value that should be used to determine the uniqueness of the event (empty to use the whole payload)

lookback amount of past Events to compare the value to (0 for unlimited)

expected_update_period_in_days is used to determine if the Agent is working.


Delay Agent Creates events Receives events

The DelayAgent stores received Events and emits copies of them on a schedule. Use this as a buffer or queue of Events.

max_events should be set to the maximum number of events that you’d like to hold in the buffer. When this number is reached, new events will either be ignored, or will displace the oldest event already in the buffer, depending on whether you set keep to newest or oldest.

expected_receive_period_in_days is used to determine if the Agent is working. Set it to the maximum number of days that you anticipate passing without this Agent receiving an incoming Event.

max_emitted_events is used to limit the number of the maximum events which should be created. If you omit this DelayAgent will create events for every event stored in the memory.


Digest Agent Creates events Receives events

The Digest Agent collects any Events sent to it and emits them as a single event.

The resulting Event will have a payload message of message. You can use liquid templating in the message, have a look at the Wiki for details.

Set expected_receive_period_in_days to the maximum amount of time that you’d expect to pass between Events being received by this Agent.

If retained_events is set to 0 (the default), all received events are cleared after a digest is sent. Set retained_events to a value larger than 0 to keep a certain number of events around on a rolling basis to re-send in future digests.

For instance, say retained_events is set to 3 and the Agent has received Events 5, 4, and 3. When a digest is sent, Events 5, 4, and 3 are retained for a future digest. After Event 6 is received, the next digest will contain Events 6, 5, and 4.


Dkt Clustering Agent Creates events Receives events Consumes file pointer Dry runs huginn_dkt_curation_agents

The DktClusteringAgent clusters the input document collection. The document collection first has to be converted to a set of vectors.

The Agent expects the input in this particular format and then proceeds to find clusters in this input data. The output contains information on the number of clusters found and specific values for the found clusters.

The Agent accepts all configuration options of the /e-clustering/generateClusters endpoint as of september 2016, have a look at the offical documentation if you need additional information

All Agent configuration options are interpolated using Liquid in the context of the received event.

url allows to customize the endpoint of the API when hosting the DKT services elswhere.

body use Liquid templating to specify the input .arff file. See http://www.cs.waikato.ac.nz/ml/weka/arff.html for an explanation of this format.

language language of the source data

algorithm: the algorithm to be used during clustering. Currently EM and Kmeans are supported.

merge set to true to retain the received payload and update it with the extracted result

result_key when present the emitted Event data will be nested inside the specified key

When receiving a file pointer:

body will be ignored and the contents of the received file will be send instead.

This agent can consume a ‘file pointer’ event from the following agents with no additional configuration: S3Agent, FtpsiteAgent, LocalFileAgent. Read more about the concept in the wiki.


Dkt Document Classification Agent Creates events Receives events Dry runs huginn_dkt_curation_agents

The DktDocumentClassificationAgent determines the class of a given text using the DKT API.

The different available classes depend on the model that is used (see next section).

The Agent accepts all configuration options of the /e-documentclassification endpoint as of march 2016, have a look at the offical documentation if you need additional information

All Agent configuration options are interpolated using Liquid in the context of the received event.

url allows to customize the endpoint of the API when hosting the DKT services elswhere.

input use Liquid templating to specify the data to be send to the API.

informat specify the content-type of the data in body

outformat requested RDF serialization format of the output

language language of the source data

modelName the model that is used for text classification. There are some models available:

  • 3pc: model generated using the data provided by 3pc (Mendelsohn letters) and their categories.
  • condat_types: model generated using the data provided by Condat and the types associated to every document.
  • condat_categories: model generated using the data provided by Condat and the categories associated to every document.
  • kreuzwerker_categories: model generated using the data provided by Kreuzwerker and the categories associated to every document.
  • kreuzwerker_subcategories: model generated using the data provided by Kreuzwerker and the subcategories associated to every document.
  • kreuzwerker_topics: model generated using the data provided by Kreuzwerker and the topics associated to every document.

modelPath [optional] this parameter is only used is other location for models is used inside the server. This parameter has been meant for local installation of the service.

merge set to true to retain the received payload and update it with the extracted result

result_key when present the emitted Event data will be nested inside the specified key


Dkt Document Storage Query Agent Creates events Receives events Dry runs huginn_dkt_curation_agents

The DktDocumentStorageQueryAgent queres the DKT Document Storage for the contents or status of a collection.

The Agent accepts all configuration options of the /document-storage/collections endpoint as of september 2016, have a look at the offical documentation if you need additional information

All Agent configuration options are interpolated using Liquid in the context of the received event.

url allows to customize the endpoint of the API when hosting the DKT services elswhere (not including the collection_name).

collection_name Name of the collection.

mode:documents returns all documents of the collection, status returns the status of the collection

merge set to true to retain the received payload and update it with the extracted result

result_key when present the emitted Event data will be nested inside the specified key


Dkt Document Storage Store Agent Creates events Receives events Consumes file pointer Dry runs huginn_dkt_curation_agents

The DktDocumentStorageStoreAgent uploads documents to the DKT platform. Each uploaded document will also processed by a series of Natural Language Processing services, the results will be stored in the e-Sesame triple store.

The Agent accepts all configuration options of the /document-storage/collections endpoint as of september 2016, have a look at the offical documentation if you need additional information

All Agent configuration options are interpolated using Liquid in the context of the received event.

url allows to customize the endpoint of the API when hosting the DKT services elswhere (not including the collection_name).

body use Liquid templating to specify data to upload.

collection_name Name of the collection.

file_name Name of the file uploaded.

merge set to true to retain the received payload and update it with the extracted result

result_key when present the emitted Event data will be nested inside the specified key

When receiving a file pointer:

content_type and file_name can optionally be used to override the file name and content-type of the received file.

This agent can consume a ‘file pointer’ event from the following agents with no additional configuration: S3Agent, FtpsiteAgent, LocalFileAgent. Read more about the concept in the wiki.


Dkt Logging Agent Creates events Receives events Dry runs huginn_dkt_curation_agents

The DktLoggingAgent registers information related to user actions using the DKT API.

The Agent accepts all configuration options of the /e-logging endpoint as of september 2016, have a look at the offical documentation if you need additional information.

All Agent configuration options are interpolated using Liquid in the context of the received event.

url allows to customize the endpoint of the API when hosting the DKT services elswhere.

serviceType: defines if the logging information is stored in a file (file) or in a database (database).

loggingServiceName: is only needed for file serviceType. In the case of database, this field is ignored.

create: defines if the logging service has to be created in case it does not exists. It is only needed for file serviceType. In the case of database, this field is ignored.

user: the user that generates the logging information.

interactionType: type of the interaction. Currently there are five possible values: feedback (FEEDBACK), usage (USAGE), RELEVANCE (RELEVANCE), ERROR (ERROR) and  general (GENERAL).

objectId: unique identification of the object that receives the relevance judgment.

relevanceValue: the value of the relevance judgment. There are five possible values: veryirrelevant, irrelevant, neutrum, relevant and veryrelevant.

value: a specific value associated with the interaction.

errorId: unique identification of the error.

errorType: the type of the error has not been defined for now, but it can be something like: BadRequestException, EmptyInputArgument, etc.

additionalInformation: additional text associated with the interaction.

merge set to true to retain the received payload and update it with the extracted result

result_key when present the emitted Event data will be nested inside the specified key


Dkt Ner Agent Creates events Receives events Dry runs huginn_dkt_curation_agents

The DktNerAgent (DKT Named Entity Recognition) enriches text content with entities gathered from various datasets using the DKT API.

The Agent accepts all configuration options of the /e-nlp/namedEntityRecognition endpoint as of september 2016, have a look at the offical documentation if you need additional information

All Agent configuration options are interpolated using Liquid in the context of the received event.

url allows to customize the endpoint of the API when hosting the DKT services elswhere.

body use Liquid templating to specify the data to be send to the API.

body_format specify the content-type of the data in body

outformat requested RDF serialization format of the output

language language of the source data

analysis: The type of analysis to perform. Specify ner for performing NER based on a trained model. Specify dict to perform NER based on an uploaded dictionary. Specify temp to perform NER for temporal expressions.

mode: Works for the ner analysis only. Possible values are spot (for entity spotting only), link (for entity linking only, e.g. looking up the entity label on DBPedia to retrieve a URI) or all (for both).

models: Specify the model to be used for performing the analysis. Use ‘manual input’ to specify multiple models in a comma separated list.

merge set to true to retain the received payload and update it with the extracted result

result_key when present the emitted Event data will be nested inside the specified key


Dkt Sesame Retrieve Agent Creates events Receives events Dry runs huginn_dkt_curation_agents

The DktSesameRetrieveAgent retrieves semantic information from a triple storage system using the DKT API.

The Agent accepts all configuration options of the /e-sesame/retrieveData endpoint as of september 2016, have a look at the offical documentation if you need additional information.

All Agent configuration options are interpolated using Liquid in the context of the received event.

url allows to customize the endpoint of the API when hosting the DKT services elswhere.

storageName: name of the sesame (triple storage) where the information must be stored.

storagePath: (optional) path of the sesame (triple storage) where the information must be stored.

inputDataType: parameter that specifies the format in which the query is provided to the service. It can have four different values: NIF, entity, sparql or triple.

merge set to true to retain the received payload and update it with the extracted result

result_key when present the emitted Event data will be nested inside the specified key

If the inputDataType is NIF, entity or sparql:

input: use Liquid templating to specify the data to be send to the API.

body_format specify the content-type of the data in input

If the inputDataType is triple: the service will retrieve triples that fit one or more of the following elements:

subject: subject of the triple.

predicate: predicate of the triple.

object: object of the triple.

outformat requested RDF serialization format of the output


Dkt Sesame Store Agent Creates events Receives events Dry runs huginn_dkt_curation_agents

The DktSesameStoreAgent stores semantic information in a triple storage system using the DKT API.

The Agent accepts all configuration options of the /e-sesame/storeData endpoint as of september 2016, have a look at the offical documentation if you need additional information.

All Agent configuration options are interpolated using Liquid in the context of the received event.

url allows to customize the endpoint of the API when hosting the DKT services elswhere.

storageName: name of the sesame (triple storage) where the information must be stored.

storagePath: path of the sesame (triple storage) where the information must be stored, set it to /opt/tmp/storage/sesameStorage/

storageCreate: boolean value defining if the repository has to be created.

inputDataFormat: parameter that specifies the format in which the information is provided to the service. It can have three different values: body, or triple.

merge set to true to retain the received payload and update it with the extracted result

result_key when present the emitted Event data will be nested inside the specified key

If the inputDataFormat is body:

body use Liquid templating to specify the data to be send to the API.

inputDataMimeType: in case that the service is receiving a string, this parameter specifies the mime type of the string (text/turtle, application/rdf+xml or application/ld+json).

If the inputDataFormat is triple: the information to be stored is given as a triple defined by its three properties:

subject: subject of the triple.

predicate: predicate of the triple.

object: object of the triple.


Dkt Smt Agent Creates events Receives events Dry runs huginn_dkt_curation_agents

The DktSmtAgent performs Statistical Machine Translation using the DKT API.

The Agent accepts all configuration options of the /e-emt endpoint as of september 2016, have a look at the offical documentation if you need additional information

All Agent configuration options are interpolated using Liquid in the context of the received event.

url allows to customize the endpoint of the API when hosting the DKT services elswhere.

body use Liquid templating to specify the data to be send to the API.

body_format specify the content-type of the data in body

outformat requested RDF serialization format of the output

source-lang: The language of the input text.

target-lang: The language of the output text.

Note, the current implementation translates in the following four directions:

German to English
English to German
Spanish to English
English to Spanish

merge set to true to retain the received payload and update it with the extracted result

result_key when present the emitted Event data will be nested inside the specified key


Dkt Topic Modelling Agent Creates events Receives events Dry runs huginn_dkt_curation_agents

The DktTopicModellingAgent determines the topic of a given text using the DKT API.

A set of documents is used by Mallet to train a topic modelling model. It clusters the terms into the documents to model the ‘topics’, so each ‘topic’ is defined as the terms (words) that are included in the corresponding ‘topic’ (cluster).

The Agent accepts all configuration options of the /e-topicmodelling endpoint as of march 2016, have a look at the offical documentation if you need additional information

Al Agent configuration options are interpolated using Liquid in the context of the received event.

url allows to customize the endpoint of the API when hosting the DKT services elswhere.

input use Liquid templating to specify the data to be send to the API.

informat specify the content-type of the data in body

outformat requested RDF serialization format of the output

language language of the source data

modelName the model that is used for topic modelling. There are some models available:

  • 3pc: model generated using the data provided by 3pc (Mendehlson letters).
  • condat: model generated using the data provided by Condat.
  • kreuzwerker: model generated using the data provided by Kreuzwerker.

modelPath [optional] this parameter is only used is other location for models is used inside the server. This parameter has been meant for local installation of the service.

merge set to true to retain the received payload and update it with the extracted result

result_key when present the emitted Event data will be nested inside the specified key


Dropbox File Url Agent Creates events Receives events Dry runs Dropbox oauth2

The DropboxFileUrlAgent is used to work with Dropbox. It takes a file path (or multiple files paths) and emits events with either temporary links or permanent links.

Include the dropbox-api and omniauth-dropbox gems in your Gemfile and set DROPBOX_OAUTH_KEY and DROPBOX_OAUTH_SECRET in your environment to use Dropbox Agents.

The incoming event payload needs to have a paths key, with a comma-separated list of files you want the URL for. For example:

{
  "paths": "first/path, second/path"
}

TIP: You can use the Event Formatting Agent to format events before they come in. Here’s an example configuration for formatting an event coming out of a Dropbox Watch Agent:

{
  "instructions": {
    "paths": "{{ added | map: 'path' | join: ',' }}"
  },
  "matchers": [],
  "mode": "clean"
}

An example of usage would be to watch a specific Dropbox directory (with the DropboxWatchAgent) and get the URLs for the added or updated files. You could then, for example, send emails with those links.

Set link_type to 'temporary' if you want temporary links, or to 'permanent' for permanent ones.


Dropbox Save Agent Creates events Receives events Consumes file pointer Dropbox oauth2 huginn_dropbox_save_agent

Add a Agent description here


Dropbox Watch Agent Creates events Dropbox oauth2

The Dropbox Watch Agent watches the given dir_to_watch and emits events with the detected changes.

Include the dropbox-api and omniauth-dropbox gems in your Gemfile and set DROPBOX_OAUTH_KEY and DROPBOX_OAUTH_SECRET in your environment to use Dropbox Agents.


Email Agent Receives events

The Email Agent sends any events it receives via email immediately.

You can specify the email’s subject line by providing a subject option, which can contain Liquid formatting. E.g., you could provide "Huginn email" to set a simple subject, or {{subject}} to use the subject key from the incoming Event.

By default, the email body will contain an optional headline, followed by a listing of the Events’ keys.

You can customize the email body by including the optional body param. Like the subject, the body can be a simple message or a Liquid template. You could send only the Event’s some_text field with a body set to {{ some_text }}. The body can contain simple HTML and will be sanitized. Note that when using body, it will be wrapped with <html> and <body> tags, so you do not need to add these yourself.

You can specify one or more recipients for the email, or skip the option in order to send the email to your account’s default email address.

You can provide a from address for the email, or leave it blank to default to the value of EMAIL_FROM_ADDRESS (``).

You can provide a content_type for the email and specify text/plain or text/html to be sent. If you do not specify content_type, then the recipient email server will determine the correct rendering.

Set expected_receive_period_in_days to the maximum amount of time that you’d expect to pass between Events being received by this Agent.


Email Digest Agent Receives events

The Email Digest Agent collects any Events sent to it and sends them all via email when scheduled. The number of used events also relies on the Keep events option of the emitting Agent, meaning that if events expire before this agent is scheduled to run, they will not appear in the email.

By default, the will have a subject and an optional headline before listing the Events. If the Events’ payloads contain a message, that will be highlighted, otherwise everything in their payloads will be shown.

You can specify one or more recipients for the email, or skip the option in order to send the email to your account’s default email address.

You can provide a from address for the email, or leave it blank to default to the value of EMAIL_FROM_ADDRESS (``).

You can provide a content_type for the email and specify text/plain or text/html to be sent. If you do not specify content_type, then the recipient email server will determine the correct rendering.

Set expected_receive_period_in_days to the maximum amount of time that you’d expect to pass between Events being received by this Agent.


Event Formatting Agent Creates events Receives events Dry runs

The Event Formatting Agent allows you to format incoming Events, adding new fields as needed.

For example, here is a possible Event:

{
  "high": {
    "celsius": "18",
    "fahreinheit": "64"
  },
  "date": {
    "epoch": "1357959600",
    "pretty": "10:00 PM EST on January 11, 2013"
  },
  "conditions": "Rain showers",
  "data": "This is some data"
}

You may want to send this event to another Agent, for example a Twilio Agent, which expects a message key. You can use an Event Formatting Agent’s instructions setting to do this in the following way:

"instructions": {
  "message": "Today's conditions look like {{conditions}} with a high temperature of {{high.celsius}} degrees Celsius.",
  "subject": "{{data}}",
  "created_at": "{{created_at}}"
}

Names here like conditions, high and data refer to the corresponding values in the Event hash.

The special key created_at refers to the timestamp of the Event, which can be reformatted by the date filter, like {{created_at | date:"at %I:%M %p" }}.

The upstream agent of each received event is accessible via the key agent, which has the following attributes: name, options, sources, type, url, id, disabled, memory, controllers, schedule, keep_events_for, propagate_immediately, working, receivers, control_targets.

Have a look at the Wiki to learn more about liquid templating.

Events generated by this possible Event Formatting Agent will look like:

{
  "message": "Today's conditions look like Rain showers with a high temperature of 18 degrees Celsius.",
  "subject": "This is some data"
}

In matchers setting you can perform regular expression matching against contents of events and expand the match data for use in instructions setting. Here is an example:

{
  "matchers": [
    {
      "path": "{{date.pretty}}",
      "regexp": "\A(?<time>\d\d:\d\d [AP]M [A-Z]+)",
      "to": "pretty_date"
    }
  ]
}

This virtually merges the following hash into the original event hash:

"pretty_date": {
  "time": "10:00 PM EST",
  "0": "10:00 PM EST on January 11, 2013"
  "1": "10:00 PM EST"
}

So you can use it in instructions like this:

"instructions": {
  "message": "Today's conditions look like {{conditions}} with a high temperature of {{high.celsius}} degrees Celsius according to the forecast at {{pretty_date.time}}.",
  "subject": "{{data}}"
}

If you want to retain original contents of events and only add new keys, then set mode to merge, otherwise set it to clean.

To CGI escape output (for example when creating a link), use the Liquid uri_escape filter, like so:

{
  "message": "A peak was on Twitter in {{group_by}}.  Search: https://twitter.com/search?q={{group_by | uri_escape}}"
}

Evernote Agent Creates events Receives events Evernote

The Evernote Agent connects with a user’s Evernote note store.

Visit Evernote to set up an Evernote app and receive an api key and secret. Store these in the Evernote environment variables in the .env file. You will also need to create a Sandbox account to use during development.

Next, you’ll need to authenticate with Evernote in the Services section.

Options:

  • mode - Two possible values:

    • update Based on events it receives, the agent will create notes or update notes with the same title and notebook

    • read On a schedule, it will generate events containing data for newly added or updated notes

  • include_xhtml_content - Set to true to include the content in ENML (Evernote Markup Language) of the note

  • note

    • When mode is update the parameters of note are the attributes of the note to be added/edited. To edit a note, both title and notebook must be set.

      For example, to add the tags ‘comic’ and ‘CS’ to a note titled ‘xkcd Survey’ in the notebook ‘xkcd’, use:

      "notes": {
        "title": "xkcd Survey",
        "content": "",
        "notebook": "xkcd",
        "tagNames": "comic, CS"
      }
      

      If a note with the above title and notebook did note exist already, one would be created.

    • When mode is read the values are search parameters. Note: The content parameter is not used for searching. Setting title only filters notes whose titles contain title as a substring, not as the exact title.

      For example, to find all notes with tag ‘CS’ in the notebook ‘xkcd’, use:

      "notes": {
        "title": "",
        "content": "",
        "notebook": "xkcd",
        "tagNames": "CS"
      }
      

File Url Agent Creates events Receives events Emits file pointer Dry runs huginn_file_url_agent

The File URL agent takes a url and emits an event with a file_pointer. Optionally, you can merge


Flickr Agent Creates events Flickr huginn_flickr_agent

Checks the Flickr feed of the provided user and creates an event for each upload.

Set FLICKR_OAUTH_KEY and FLICKR_OAUTH_SECRET in your environment to use Flickr agents.

To be able to use this Agent you need to authenticate with Flickr in the Services section first.

You must also provide the username of the Flickr user–use me if you would like to retrieve your favorites. number refers to the number of latest favorites to monitor and history refers to the number of favorites that will be held in memory.

Set expected_update_period_in_days to the maximum amount of time that you’d expect to pass between Events being created by this Agent.

Set starting_at to the date/time (eg. Mon Jun 02 00:38:12 +0000 2014) you want to start receiving favorites from (default: agent’s created_at)


Flickr Favorites Agent Creates events Flickr huginn_flickr_agent

The Flickr Favorites agent retrieves the favorites list of a specified Flickr user.

Set FLICKR_OAUTH_KEY and FLICKR_OAUTH_SECRET in your environment to use Flickr agents.

To be able to use this Agent you need to authenticate with Flickr in the Services section first.

You must also provide the username of the Flickr user–use me if you would like to retrieve your favorites. number refers to the number of latest favorites to monitor and history refers to the number of favorites that will be held in memory.

Set expected_update_period_in_days to the maximum amount of time that you’d expect to pass between Events being created by this Agent.

Set starting_at to the date/time (eg. Mon Jun 02 00:38:12 +0000 2014) you want to start receiving favorites from (default: agent’s created_at)


Freme Explore Agent Creates events Receives events Dry runs huginn_freme_enrichment_agents

The FremeExploreAgent can retrieve description of a resource from a given endpoint. The endpoint can be SPARQL or Linked Data Fragments endpoint.

The Agent accepts all configuration options of the /e-link/explore endpoint as of September 2016, have a look at the offical documentation if you need additional information.

All Agent configuration options are interpolated using Liquid in the context of the received event.

base_url allows to customize the API server when hosting the FREME services elswhere.

auth_token can be set to access private filters, datasets, templates or pipelines (depending on the agent).

outformat requested RDF serialization format of the output (required), CSV is only supported when using a filter.

resource a URI of the resource which should be described (required).

endpoint a URL of the endpoint which should be used to retrieve info about the resource.

endpoint_type the type of the endpoint (required).

filter allows to post-process the results using a pre-configured SPARQL filter. Check the official documentation for details.

merge set to true to retain the received payload and update it with the extracted result

result_key when present the emitted Event data will be nested inside the specified key


Freme Filter Agent Creates events Receives events Dry runs huginn_freme_enrichment_agents

The FremeFilterAgent allows to execute a certain filter against a RDF graph sent as post body or as value of the NIF input parameter. For more information and a list of available filters, see the Simply FREME output using SPARQL filters article.

The Agent accepts all configuration options of the /toolbox/convert/documents endpoint as of September 2016, have a look at the offical documentation if you need additional information.

All Agent configuration options are interpolated using Liquid in the context of the received event.

base_url allows to customize the API server when hosting the FREME services elswhere.

auth_token can be set to access private filters, datasets, templates or pipelines (depending on the agent).

body use Liquid templating to specify the data to be send to the API.

body_format specify the content-type of the data in body

outformat requested RDF serialization format of the output

name name of filter to execute against, the official documentation has a list of all available filters.

merge set to true to retain the received payload and update it with the extracted result

result_key when present the emitted Event data will be nested inside the specified key


Freme Link Agent Creates events Receives events Dry runs huginn_freme_enrichment_agents

The FremeLinkAgent accepts a NIF document (with annotated entities) and performs enrichment with pre-defined templates.

The Agent accepts all configuration options of the /e-link/documents endpoint as of September 2016, have a look at the offical documentation if you need additional information.

The templates contain fields marked between three at-signs @@@field-name@@@. If a user, while calling the enrichment endpoint specifies an unknown parameter (not from the list above), then the values of that unknown parameters will be used to replace with the corresponding field in the query template.

All Agent configuration options are interpolated using Liquid in the context of the received event.

base_url allows to customize the API server when hosting the FREME services elsewhere.

auth_token can be set to access private filters, datasets, templates or pipelines (depending on the agent).

body use Liquid templating to specify the data to be send to the API.

body_format specify the content-type of the data in body

outformat requested RDF serialization format of the output, CSV is only supported when using a filter

templateid the ID of the template to be used for enrichment, the official documentation has a list of all available templates.

filter allows to post-process the results using a pre-configured SPARQL filter. Check the official documentation for details.

merge set to true to retain the received payload and update it with the extracted result

result_key when present the emitted Event data will be nested inside the specified key


Freme Ner Agent Creates events Receives events Dry runs huginn_freme_enrichment_agents

The FremeNerAgent (Freme Named Entity Recognition) enriches text content with entities gathered from various datasets by the DBPedia-Spotlight Engine. The service accepts plaintext or text sent as NIF document. The text of the nif:isString property (attached to the nif:Context document) will be used for processing.

The Agent accepts all configuration options of the /e-entity/freme-ner/documents endpoint as of September 2016, have a look at the official documentation if you need additional information

All Agent configuration options are interpolated using Liquid in the context of the received event.

base_url allows to customize the API server when hosting the FREME services elsewhere.

auth_token can be set to access private filters, datasets, templates or pipelines (depending on the agent).

body use Liquid templating to specify the data to be send to the API.

body_format specify the content-type of the data in body

outformat requested RDF serialization format of the output, CSV is only supported when using a filter

prefix controls the url of rdf resources generated from plaintext. Has default value “http://freme-project.eu/”.

language language of the source data

dataset indicates the dataset used for entity linking which includes a list of entities and associated labels.

mode This parameter allows to produce only partly results of named entity recognition. This can speed up computation time. Spotting and classification are relatively fast operations, whereas linking is a computationally expensive operation. When “link” is given as the parameter and the given “informat” or “Content-Type” is NIF, this service expects NIF data with entity mentions, i.e. anchorOf, beginIndex, endIndex etc. are given and it does only entity linking. When “link” is given as the parameter and the given “informat” or “Content-Type” is plain text, this service interprets the entire input as a single Entity and does entity linking for that specific entity. Note that “all” is equivalent to “spot,link,classify”. The order of the modes are irrelevant, i.e. “spot,link,classify” is equivalent to “spot,classify,link”.

domain Takes as input a domain ID, and it only returns entities from this domain. The domain IDs are from the TaaS domain classification system. For example, the sports domain is identified with the TaaS-2007 ID. Note that the IDs are case-sensitive. More information about the domain parameter in FREME NER knowledge-base.

types Takes as input list of one or more entity types separated by a comma. The types are URLs of ontology classes and they should be encoded. The result is a list of extracted entities with these types. More information about the types parameter in FREME NER knowledge-base.

linkingMethod is a configurable parameter that can be used to choose preferred entity linking method. Depending on dataset and the content you want to process, one linking might provide better results than other. While one approach could aim at higher recall, the other might target higher precision. So far, you can choose between following linking approaches:

numLinks Using the numLinks parameter one can specify the maximum number of links to be assigned to an entity. By default only one link is returned. The maximum possible number for this parameter is 5.

filter allows to post-process the results using a pre-configured SPARQL filter. Check the official documentation for details.

merge set to true to retain the received payload and update it with the extracted result

result_key when present the emitted Event data will be nested inside the specified key


Freme Nif Converter Agent Creates events Receives events Consumes file pointer Dry runs huginn_freme_enrichment_agents

The FremeNifConcerterAgent allows to convert plain text, a document in any format supported by e-Internalisation or in the RDF formats supported by FREME into a NIF document with the RDF serialisation format specified by the accept header.

The Agent accepts all configuration options of the /toolbox/nif-converter endpoint as of September 2016, have a look at the offical documentation if you need additional information.

All Agent configuration options are interpolated using Liquid in the context of the received event.

base_url allows to customize the API server when hosting the FREME services elswhere.

outformat requested RDF serialization format of the output

body_format specify the content-type of the data in body

body use Liquid templating to specify the data to be send to the API.

merge set to true to retain the received payload and update it with the extracted result

result_key when present the emitted Event data will be nested inside the specified key

When receiving a file pointer:

body and body_format will be ignored and the received file will be converted using Apache Tika.

This agent can consume a ‘file pointer’ event from the following agents with no additional configuration: S3Agent, FtpsiteAgent, LocalFileAgent. Read more about the concept in the wiki.


Freme Pipeline Agent Creates events Receives events Dry runs huginn_freme_enrichment_agents

The FremePipelineAgent allows to send a pipeline request to the FREME API.

The Agent accepts all configuration options of the /pipelining/chain endpoint as of September 2016, have a look at the offical documentation if you need additional information.

All Agent configuration options are interpolated using Liquid in the context of the received event.

base_url allows to customize the API server when hosting the FREME services elswhere.

auth_token can be set to access private filters, datasets, templates or pipelines (depending on the agent).

template When selecting a pipeline-template, body will be used as the input for the pipeline chain.

body_format specify the content-type of the data in body (only used when a template is selected)

body use Liquid templating to specify the data to be send to the API.

stats If true, adds timing statistics to the response: total duration of the pipeline and duration of each service called in the pipeline (in milliseconds).

useI18n If false, enforces to not use e-Internalization, even if Content-Type header is one of the possible e-Internalization formats. For any othe value, e-Internalization will be used, if possible.

merge set to true to retain the received payload and update it with the extracted result

result_key when present the emitted Event data will be nested inside the specified key


Freme Spotlight Agent Creates events Receives events Dry runs huginn_freme_enrichment_agents

The FremeFilterAgent enriches text content with entities gathered from various datasets by the DBPedia-Spotlight Engine.

The Agent accepts all configuration options of the /e-entity/dbpedia-spotlight/documents endpoint as of September 2016, have a look at the offical documentation if you need additional information.

All Agent configuration options are interpolated using Liquid in the context of the received event.

base_url allows to customize the API server when hosting the FREME services elswhere.

auth_token can be set to access private filters, datasets, templates or pipelines (depending on the agent).

body use Liquid templating to specify the data to be send to the API.

body_format specify the content-type of the data in body

outformat requested RDF serialization format of the output, CSV is only supported when using a filter

prefix controls the url of rdf resources generated from plaintext. Has default value “http://freme-project.eu/”.

numLinks The number of links from a knowledge base returned for each entity. Note that for some entities it might returned less links than requested. This might be due to the low number of links available. The maximum number of links that can be returned is 5.

language language of the source data

confidence Setting a high confidence threshold instructs DBpedia Spotlight to avoid incorrect annotations as much as possible at the risk of losing some correct ones. A confidence value of 0.7 will eliminate 70% of incorrectly disambiguated test cases. The range of the confidence parameter is between 0 and 1. Default is 0.3.

filter allows to post-process the results using a pre-configured SPARQL filter. Check the official documentation for details.

merge set to true to retain the received payload and update it with the extracted result

result_key when present the emitted Event data will be nested inside the specified key


Freme Terminology Agent Creates events Receives events Dry runs huginn_freme_enrichment_agents

The FremeTerminologyAgent annotate text with terminology information using Tilde Terminology service.

The Agent accepts all configuration options of the /e-terminology/tilde endpoint as of September 2016, have a look at the offical documentation if you need additional information

All Agent configuration options are interpolated using Liquid in the context of the received event.

base_url allows to customize the API server when hosting the FREME services elswhere.

auth_token can be set to access private filters, datasets, templates or pipelines (depending on the agent).

body use Liquid templating to specify the data to be send to the API.

body_format specify the content-type of the data in body

outformat requested RDF serialization format of the output, CSV is only supported when using a filter

prefix controls the url of rdf resources generated from plaintext. Has default value “http://freme-project.eu/”.

source_lang source language, e.g. “de”,”en”. Language of submitted text. A list of supported language codes is here.

target_lang target language, e.g. “de”, “en”. Language for targeted terms. A list of supported language codes is here.

collection collection id from https://term.tilde.com portal. If filled then annotates only with terms from that collection

mode Whether the result must contain full terminology information or only term annotations with references to the full information

domain If given - it filters out by domain proposed terms. Available domains here: https://term.tilde.com/domains (should pass just ID, eg, TaaS-1001, that means Agriculture)

key A private key to access private and not publicly available translation systems. Key can be created by contacting Tilde team. Optional, if omitted then translates with public systems

filter allows to post-process the results using a pre-configured SPARQL filter. Check the official documentation for details.

merge set to true to retain the received payload and update it with the extracted result

result_key when present the emitted Event data will be nested inside the specified key


Freme Translation Agent Creates events Receives events Dry runs huginn_freme_enrichment_agents

The FremeTranslationAgent translates text using Tilde Translation service.

The Agent accepts all configuration options of the /e-translation/tilde endpoint as of September 2016, have a look at the offical documentation if you need additional information

All Agent configuration options are interpolated using Liquid in the context of the received event.

base_url allows to customize the API server when hosting the FREME services elswhere.

auth_token can be set to access private filters, datasets, templates or pipelines (depending on the agent).

body use Liquid templating to specify the data to be send to the API.

body_format specify the content-type of the data in body

outformat requested RDF serialization format of the output, CSV is only supported when using a filter

source_lang source language, e.g. “en”. A list of available language pairs is here.

target_lang target language, e.g. “de”. A list of available language pairs is here.

key A private key to access private and not publicly available translation systems. Key can be created by contacting Tilde team. Optional, if omitted then translates with public systems

domain specify domain of translation system. List of supported domains and language pairs can be found here.

system select translation system by ID [an alternative to source, target language and domain selection]. ID of public translation system can be retrieved at https://services.tilde.com/translationsystems or private system ID can be found at portal http://tilde.com/mt with authentication [optional, if omitted then source and target languages and also domain parameters are used]

filter allows to post-process the results using a pre-configured SPARQL filter. Check the official documentation for details.

merge set to true to retain the received payload and update it with the extracted result

result_key when present the emitted Event data will be nested inside the specified key


Freme Xslt Converter Agent Creates events Receives events Dry runs huginn_freme_enrichment_agents

The FremeXsltConverterAgent allows to transform a XML or HTML document with a certain XSLT converter using the FREME API.

The Agent accepts all configuration options of the /toolbox/xslt-converter/documents endpoint as of September 2016, have a look at the offical documentation abd the Input transformation with XSLT article if you need additional information.

All Agent configuration options are interpolated using Liquid in the context of the received event.

base_url allows to customize the API server when hosting the FREME services elswhere.

auth_token can be set to access private filters, datasets, templates or pipelines (depending on the agent).

body use Liquid templating to specify the data to be send to the API.

body_format specify the content-type of the data in body

outformat requested format of the output

name name of filter to execute against, the official documentation has a list of all available filters.

merge set to true to retain the received payload and update it with the extracted result

result_key when present the emitted Event data will be nested inside the specified key


Ftpsite Agent Creates events Receives events Emits file pointer

The Ftp Site Agent checks an FTP site and creates Events based on newly uploaded files in a directory. When receiving events it creates files on the configured FTP server.

mode must be present and either read or write, in read mode the agent checks the FTP site for changed files, with write it writes received events to a file on the server.

Universal options

Specify a url that represents a directory of an FTP site to watch, and a list of patterns to match against file names.

Login credentials can be included in url if authentication is required: ftp://username:password@ftp.example.com/path. Liquid formatting is supported as well: ftp://{% credential ftp_credentials %}@ftp.example.com/

Optionally specify the encoding of the files you want to read/write in force_encoding, by default UTF-8 is used.

Reading

Only files with a last modification time later than the after value, if specifed, are emitted as event.

Writing

Specify the filename to use in filename, Liquid interpolation is possible to change the name per event.

Use Liquid templating in data to specify which part of the received event should be written.

This agent only emits a ‘file pointer’, not the data inside the files, the following agents can consume the created events: CsvAgent, PostAgent, ReadFileAgent. Read more about the concept in the wiki.


Gap Detector Agent Creates events Receives events

The Gap Detector Agent will watch for holes or gaps in a stream of incoming Events and generate “no data alerts”.

The value_path value is a JSONPath to a value of interest. If either this value is empty, or no Events are received, during window_duration_in_days, an Event will be created with a payload of message.


Github Notifications Agent Creates events Dry runs huginn_github_notifications_agent

The GithubNotificationsAgent fetches your notifications from Github.

You need to create a personal access token to use this, only the notifications scope is necessary.

To emit all new notifications as a single event, change events to single. The event key will be notifications.

To fetch all (unread) notifications, change last_modified to false. Default behaviour is to only fetch notifications that are updated since last run.

More options might be added for the API.

This agent also adds two more fields to subject in the response, url_web and repo_name. These are for convenience, if you want to link to the updated resource for example. "subject": { "url_web": "https://github.com/joenas/huginn_github_notifications/pull/1234", "repo_name": "joenas/huginn_github_notifications" }


Google Calendar Publish Agent Creates events Receives events

The Google Calendar Publish Agent creates events on your Google Calendar.

This agent relies on service accounts, rather than oauth.

Setup:

  1. Visit the google api console
  2. New project -> Huginn
  3. APIs & Auth -> Enable google calendar
  4. Credentials -> Create new Client ID -> Service Account
  5. Download the JSON keyfile and save it to a path, ie: /home/huginn/Huginn-5d12345678cd.json. Or open that file and copy the private_key.
  6. Grant access via google calendar UI to the service account email address for each calendar you wish to manage. For a whole google apps domain, you can delegate authority

An earlier version of Huginn used PKCS12 key files to authenticate. This will no longer work, you should generate a new JSON format keyfile, that will look something like:

{
  "type": "service_account",
  "project_id": "huginn-123123",
  "private_key_id": "6d6b476fc6ccdb31e0f171991e5528bb396ffbe4",
  "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
  "client_email": "huginn-calendar@huginn-123123.iam.gserviceaccount.com",
  "client_id": "123123...123123",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://accounts.google.com/o/oauth2/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/huginn-calendar%40huginn-123123.iam.gserviceaccount.com"
}

Agent Configuration:

calendar_id - The id the calendar you want to publish to. Typically your google account email address. Liquid formatting (e.g. {{ cal_id }}) is allowed here in order to extract the calendar_id from the incoming event.

google A hash of configuration options for the agent.

google service_account_email - The authorised service account email address.

google key_file OR google key - The path to the JSON key file above, or the key itself (the value of private_key). Liquid formatting is supported if you want to use a Credential. (E.g., {% credential google_key %})

Set expected_update_period_in_days to the maximum amount of time that you’d expect to pass between Events being created by this Agent.

Use it with a trigger agent to shape your payload!

A hash of event details. See the Google Calendar API docs

The prior version Google’s API expected keys like dateTime but in the latest version they expect snake case keys like date_time.

Example payload for trigger agent:

{
  "message": {
    "visibility": "default",
    "summary": "Awesome event",
    "description": "An example event with text. Pro tip: DateTimes are in RFC3339",
    "start": {
      "date_time": "2017-06-30T17:00:00-05:00"
    },
    "end": {
      "date_time": "2017-06-30T18:00:00-05:00"
    }
  }
}

Google Translation Agent Creates events Receives events

The Translation Agent will attempt to translate text between natural languages.

Services are provided using Google Translate. You can sign up to get google_api_key which is required to use this agent. The service is not free.

To use credentials for the google_api_key use the liquid credential tag like so {% credential google-api-key %}

to must be filled with a translator language code.

from is the language translated from. If it’s not specified, the API will attempt to detect the source language automatically and return it within the response.

Specify what you would like to translate in content field, you can use Liquid specify which part of the payload you want to translate.

expected_receive_period_in_days is the maximum number of days you would allow to pass between events.


Growl Agent Receives events Dry runs

The Growl Agent sends any events it receives to a Growl GNTP server immediately.

The option message, which will hold the body of the growl notification, and the subject option, which will have the headline of the Growl notification are required. All other options are optional. When callback_url is set to a URL clicking on the notification will open the link in your default browser.

Set expected_receive_period_in_days to the maximum amount of time that you’d expect to pass between Events being received by this Agent.

Have a look at the Wiki to learn more about liquid templating.


Hipchat Agent Receives events

The Hipchat Agent sends messages to a Hipchat Room

To authenticate you need to set the auth_token, you can get one at your Hipchat Group Admin page which you can find here:

https://yoursubdomain.hipchat.com/admin/api

Change the room_name to the name of the room you want to send notifications to.

You can provide a username and a message. If you want to use mentions change format to “text” (details).

If you want your message to notify the room members change notify to “True”.

Modify the background color of your message via the color attribute (one of “yellow”, “red”, “green”, “purple”, “gray”, or “random”)

Have a look at the Wiki to learn more about liquid templating.


Http Status Agent Creates events Receives events Dry runs

The HttpStatusAgent will check a url and emit the resulting HTTP status code with the time that it waited for a reply. Additionally, it will optionally emit the value of one or more specified headers.

Specify a Url and the Http Status Agent will produce an event with the HTTP status code. If you specify one or more Headers to save (comma-delimited) as well, that header or headers’ value(s) will be included in the event.

The disable redirect follow option causes the Agent to not follow HTTP redirects. For example, setting this to true will cause an agent that receives a 301 redirect to http://yahoo.com to return a status of 301 instead of following the redirect and returning 200.

The changes only option causes the Agent to report an event only when the status changes. If set to false, an event will be created for every check. If set to true, an event will only be created when the status changes (like if your site goes from 200 to 500).


Human Task Agent Creates events Receives events

The Human Task Agent is used to create Human Intelligence Tasks (HITs) on Mechanical Turk.

HITs can be created in response to events, or on a schedule. Set trigger_on to either schedule or event.

Schedule

The schedule of this Agent is how often it should check for completed HITs, NOT how often to submit one. To configure how often a new HIT should be submitted when in schedule mode, set submission_period to a number of hours.

Example

If created with an event, all HIT fields can contain interpolated values via liquid templating. For example, if the incoming event was a Twitter event, you could make a HITT to rate its sentiment like this:

{
  "expected_receive_period_in_days": 2,
  "trigger_on": "event",
  "hit": {
    "assignments": 1,
    "title": "Sentiment evaluation",
    "description": "Please rate the sentiment of this message: '{{message}}'",
    "reward": 0.05,
    "lifetime_in_seconds": "3600",
    "questions": [
      {
        "type": "selection",
        "key": "sentiment",
        "name": "Sentiment",
        "required": "true",
        "question": "Please select the best sentiment value:",
        "selections": [
          { "key": "happy", "text": "Happy" },
          { "key": "sad", "text": "Sad" },
          { "key": "neutral", "text": "Neutral" }
        ]
      },
      {
        "type": "free_text",
        "key": "feedback",
        "name": "Have any feedback for us?",
        "required": "false",
        "question": "Feedback",
        "default": "Type here...",
        "min_length": "2",
        "max_length": "2000"
      }
    ]
  }
}

As you can see, you configure the created HIT with the hit option. Required fields are title, which is the title of the created HIT, description, which is the description of the HIT, and questions which is an array of questions. Questions can be of type selection or free_text. Both types require the key, name, required, type, and question configuration options. Additionally, selection requires a selections array of options, each of which contain key and text. For free_text, the special configuration options are all optional, and are default, min_length, and max_length.

By default, all answers are emitted in a single event. If you’d like separate events for each answer, set separate_answers to true.

Combining answers

There are a couple of ways to combine HITs that have multiple assignments, all of which involve setting combination_mode at the top level.

Taking the majority

Option 1: if all of your questions are of type selection, you can set combination_mode to take_majority. This will cause the Agent to automatically select the majority vote for each question across all assignments and return it as majority_answer. If all selections are numeric, an average_answer will also be generated.

Option 2: you can have the Agent ask additional human workers to rank the assignments and return the most highly ranked answer. To do this, set combination_mode to poll and provide a poll_options object. Here is an example:

{
  "trigger_on": "schedule",
  "submission_period": 12,
  "combination_mode": "poll",
  "poll_options": {
    "title": "Take a poll about some jokes",
    "instructions": "Please rank these jokes from most funny (5) to least funny (1)",
    "assignments": 3,
    "row_template": "{{joke}}"
  },
  "hit": {
    "assignments": 5,
    "title": "Tell a joke",
    "description": "Please tell me a joke",
    "reward": 0.05,
    "lifetime_in_seconds": "3600",
    "questions": [
      {
        "type": "free_text",
        "key": "joke",
        "name": "Your joke",
        "required": "true",
        "question": "Joke",
        "min_length": "2",
        "max_length": "2000"
      }
    ]
  }
}

Resulting events will have the original answers, as well as the poll results, and a field called best_answer that contains the best answer as determined by the poll. (Note that separate_answers won’t work when doing a poll.)

Other settings

lifetime_in_seconds is the number of seconds a HIT is left on Amazon before it’s automatically closed. The default is 1 day.

As with most Agents, expected_receive_period_in_days is required if trigger_on is set to event.


Imap Folder Agent Creates events Dry runs

The Imap Folder Agent checks an IMAP server in specified folders and creates Events based on new mails found since the last run. In the first visit to a folder, this agent only checks for the initial status and does not create events.

Specify an IMAP server to connect with host, and set ssl to true if the server supports IMAP over SSL. Specify port if you need to connect to a port other than standard (143 or 993 depending on the ssl value).

Specify login credentials in username and password.

List the names of folders to check in folders.

To narrow mails by conditions, build a conditions hash with the following keys:

  • subject
  • body Specify a regular expression to match against the decoded subject/body of each mail.

    Use the (?i) directive for case-insensitive search. For example, a pattern (?i)alert will match “alert”, “Alert”or “ALERT”. You can also make only a part of a pattern to work case-insensitively: Re: (?i:alert) will match either “Re: Alert” or “Re: alert”, but not “RE: alert”.

    When a mail has multiple non-attachment text parts, they are prioritized according to the mime_types option (which see below) and the first part that matches a “body” pattern, if specified, will be chosen as the “body” value in a created event.

    Named captures will appear in the “matches” hash in a created event.

  • from, to, cc Specify a shell glob pattern string that is matched against mail addresses extracted from the corresponding header values of each mail.

    Patterns match addresses in case insensitive manner.

    Multiple pattern strings can be specified in an array, in which case a mail is selected if any of the patterns matches. (i.e. patterns are OR’d)

  • mime_types Specify an array of MIME types to tell which non-attachment part of a mail among its text/* parts should be used as mail body. The default value is ['text/plain', 'text/enriched', 'text/html'].

  • is_unread Setting this to true or false means only mails that is marked as unread or read respectively, are selected.

    If this key is unspecified or set to null, it is ignored.

  • has_attachment

    Setting this to true or false means only mails that does or does not have an attachment are selected.

    If this key is unspecified or set to null, it is ignored.

Set mark_as_read to true to mark found mails as read.

Set include_raw_mail to true to add a raw_mail value to each created event, which contains a Base64-encoded blob in the “RFC822” format defined in the IMAP4 standard. Note that while the result of Base64 encoding will be LF-terminated, its raw content will often be CRLF-terminated because of the nature of the e-mail protocols and formats. The primary use case for a raw mail blob is to pass to a Shell Command Agent with a command like openssl enc -d -base64 | tr -d ' ' | procmail -Yf-.

Each agent instance memorizes the highest UID of mails that are found in the last run for each watched folder, so even if you change a set of conditions so that it matches mails that are missed previously, or if you alter the flag status of already found mails, they will not show up as new events.

Also, in order to avoid duplicated notification it keeps a list of Message-Id’s of 100 most recent mails, so if multiple mails of the same Message-Id are found, you will only see one event out of them.


Jabber Agent Creates events Receives events

The Jabber Agent will send any events it receives to your Jabber/XMPP IM account.

Specify the jabber_server and jabber_port for your Jabber server.

The message is sent from jabber_sender to jaber_receiver. This message can contain any keys found in the source’s payload, escaped using double curly braces. ex: "News Story: {{title}}: {{url}}"

When connect_to_receiver is set to true, the JabberAgent will emit an event for every message it receives.

Have a look at the Wiki to learn more about liquid templating.


Java Script Agent Creates events Receives events Dry runs

The JavaScript Agent allows you to write code in JavaScript that can create and receive events. If other Agents aren’t meeting your needs, try this one!

You can put code in the code option, or put your code in a Credential and reference it from code with credential:<name> (recommended).

You can implement Agent.check and Agent.receive as you see fit. The following methods will be available on Agent in the JavaScript environment:

  • this.createEvent(payload)
  • this.incomingEvents() (the returned event objects will each have a payload property)
  • this.memory()
  • this.memory(key)
  • this.memory(keyToSet, valueToSet)
  • this.setMemory(object) (replaces the Agent’s memory with the provided object)
  • this.deleteKey(key) (deletes a key from memory and returns the value)
  • this.credential(name)
  • this.credential(name, valueToSet)
  • this.options()
  • this.options(key)
  • this.log(message)
  • this.error(message)
  • this.escapeHtml(htmlToEscape)
  • this.unescapeHtml(htmlToUnescape)

Jira Agent Creates events

The Jira Agent subscribes to Jira issue updates.

  • jira_url specifies the full URL of the jira installation, including https://
  • jql is an optional Jira Query Language-based filter to limit the flow of events. See JQL Docs for details.
  • username and password are optional, and may need to be specified if your Jira instance is read-protected
  • timeout is an optional parameter that specifies how long the request processing may take in minutes.

The agent does periodic queries and emits the events containing the updated issues in JSON format.

NOTE: upon the first execution, the agent will fetch everything available by the JQL query. So if it’s not desirable, limit the jql query by date.


Json Api Agent Creates events Receives events Dry runs huginn_jsonapi_agent

Agent communicates with api.

url – api url

method – must be ‘post’, ‘get’, ‘put’, ‘delete’, or ‘patch’

payloadLiquid-interpolated data will be send to carprice-api.

emit_events – emit result as event

merge_event – merge result with incoming event

extract – sub-hashes specify JSONPaths to the values that you care about. Option can be skipped, causing the full JSON response to be returned.


Json Parse Agent Creates events Receives events Dry runs

The JSON Parse Agent parses a JSON string and emits the data in a new event or merge with with the original event.

data is the JSON to parse. Use Liquid templating to specify the JSON string.

data_key sets the key which contains the parsed JSON data in emitted events

mode determines whether create a new clean event or merge old payload with new values (default: clean)


Lifx Pulse Lights Agent Receives events Lifx huginn_lifx_agents

Performs a pulse effect by quickly flashing your LIFX lights between the given colors.

To be able to use this Agent you need to authenticate with LIFX in the Services section first.

Read more about the LIFX HTTP API


Lifx Toggle Lights Agent Receives events Lifx huginn_lifx_agents

Turn off your LIFX lights if any of them are on, or turn them on if they are all off. All lights matched by the selector will share the same power state after this action. Physically powered off lights are ignored.

To be able to use this Agent you need to authenticate with LIFX in the Services section first.

Read more about the LIFX HTTP API


Liquid Output Agent Receives events

The Liquid Output Agent outputs events through a Liquid template you provide. Use it to create a HTML page, or a json feed, or anything else that can be rendered as a string from your stream of Huginn data.

This Agent will output data at:

https:///users/1/web_requests/:id/:secret.any_extension

where :secret is the secret specified in your options. You can use any extension you wish.

Options:

  • secret - A token that the requestor must provide for light-weight authentication.
  • expected_receive_period_in_days - How often you expect data to be received by this Agent from other Agents.
  • content - The content to display when someone requests this page.
  • mime_type - The mime type to use when someone requests this page.
  • response_headers - An object with any custom response headers. (example: {"Access-Control-Allow-Origin": "*"})
  • mode - The behavior that determines what data is passed to the Liquid template.
  • event_limit - A limit applied to the events passed to a template when in “Last X events” mode. Can be a count like “1”, or an amount of time like “1 day” or “5 minutes”.

Liquid Templating

The content you provide will be run as a Liquid template. The data from the last event received will be used when processing the Liquid template.

Modes

Merge events

The data for incoming events will be merged. So if two events come in like this:

{ 'a' => 'b', 'c' => 'd'} { 'a' => 'bb', 'e' => 'f'}

The final result will be:

{ 'a' => 'bb', 'c' => 'd', 'e' => 'f'}

This merged version will be passed to the Liquid template.

Last event in

The data from the last event will be passed to the template.

Last X events

All of the events received by this agent will be passed to the template as the events array.

The number of events can be controlled via the event_limit option. If event_limit is an integer X, the last X events will be passed to the template. If event_limit is an integer with a unit of measure like “1 day” or “5 minutes” or “9 years”, a date filter will be applied to the events passed to the template. If no event_limit is provided, then all of the events for the agent will be passed to the template.

For performance, the maximum event_limit allowed is 1000.


Local File Agent Creates events Receives events Emits file pointer

The LocalFileAgent can watch a file/directory for changes or emit an event for every file in that directory. When receiving an event it writes the received data into a file.

mode determines if the agent is emitting events for (changed) files or writing received event data to disk.

Reading

When watch is set to true the LocalFileAgent will watch the specified path for changes, the schedule is ignored and the file system is watched continuously. An event will be emitted for every detected change.

When watch is set to false the agent will emit an event for every file in the directory on each scheduled run.

This agent only emits a ‘file pointer’, not the data inside the files, the following agents can consume the created events: CsvAgent, PostAgent, ReadFileAgent. Read more about the concept in the wiki.

Writing

Every event will be writting into a file at path, Liquid interpolation is possible to change the path per event.

When append is true the received data will be appended to the file.

Use Liquid templating in data to specify which part of the received event should be written.

Warning: This type of Agent can read and write any file the user that runs the Huginn server has access to, and is currently disabled. Only enable this Agent if you trust everyone using your Huginn installation. You can enable this Agent in your .env file by setting ENABLE_INSECURE_AGENTS to true.


Manual Event Agent Creates events

The Manual Event Agent is used to manually create Events for testing or other purposes.

Do not set options for this Agent. Instead, connect it to other Agents and create Events using the UI provided on this Agent’s Summary page.


Moves Agent Creates events huginn_moves_agent

The Moves Agent pulls location data from your Moves app.


Moves Current Location Agent Creates events Moves huginn_moves_agent

The Moves Current Location agent pulls the most recent location from your Moves app.

Set MOVES_OAUTH_KEY and MOVES_OAUTH_SECRET in your environment to use Moves agents.

To be able to use this Agent you need to authenticate with Moves in the Services section first.


Mqtt Agent Creates events Receives events

The MQTT Agent allows both publication and subscription to an MQTT topic.

MQTT is a generic transport protocol for machine to machine communication.

You can do things like:

Simply choose a topic (think email subject line) to publish/listen to, and configure your service.

It’s easy to setup your own broker or connect to a cloud service

Hints: Many services run mqtts (mqtt over SSL) often with a custom certificate.

You’ll want to download their cert and install it locally, specifying the certificate_path configuration.

Example configuration:

{
  'uri' => 'mqtts://user:pass@localhost:8883'
  'ssl' => :TLSv1,
  'ca_file' => './ca.pem',
  'cert_file' => './client.crt',
  'key_file' => './client.key',
  'topic' => 'huginn'
}

Subscribe to CloCkWeRX’s TheThingSystem instance (thethingsystem.com), where temperature and other events are being published.

{
  'uri' => 'mqtt://kcqlmkgx:sVNoccqwvXxE@m10.cloudmqtt.com:13858',
  'topic' => 'the_thing_system/demo'
}

Subscribe to all topics

{
  'uri' => 'mqtt://kcqlmkgx:sVNoccqwvXxE@m10.cloudmqtt.com:13858',
  'topic' => '/#'
}

Find out more detail on subscription wildcards


Mysql2 Agent Creates events Receives events Dry runs huginn_mysql2_agent

Run custom mysql query

connection_url:

– from credentials:

{% credential mysql_connection %}

– from string:

mysql2://user:pass@localhost/database

sql – custom sql query

select id, title from mytable where ... order by limit 30

merge_event – merge result with incoming event


Naive Bayes Agent Creates events Receives events Dry runs huginn_naive_bayes_agent

The Naive Bayes Agent uses incoming Events from certain sources as a training set for Naive Bayes Machine Learning. Then it classifies Events from other sources and adds category tags to them accordingly.

All incoming events should have these two fields in their payloads, likely via the Event Formatting or Javascript Agent:

  • nb_content for the content used for classification, space separated.
  • nb_cats for the classification categories, space separated.

If nb_cats is empty or contains =class, then the content from nb_content will be classified according to the training data. The categories will be added to nb_cats and then a new event is created with that payload.

However, if nb_cats is already populated, then the content from nb_content will be used as training data for the categories listed in nb_cats. For instance, say nb_cats consists of trees. Then nb_content will be used as training data for the category trees. The data is saved to the agent memory.

Data in nb_content can be cleaned before classification. If strip_punctuation is set to true, the text in nb_content is stripped of punctuation before it is sent to the classifier. The changes are not saved to nb_content but will affect the Agent’s saved training data.

Content can also be “stemmed”, reducing words to their base, by setting stem to true. Stemming will reduce “epistemology”, “epistemologies”, and “epistemological” all to “epistemolog”. See here for the implementation used. Again, changes are not saved to nb_content but will affect the Agent’s saved training data.

When an event is received for classification, the Naive Bayes Agent will assign a value between 0 and 1 representing the likelihood that it falls under a category. The min_value option lets you choose the minimum threshold that must be reached before the event is labeled with that category. If min_value is set to 1, then the event is labeled with whichever category has the highest value.

The option propagate_training_events lets you choose whether the training events are emitted along with the classified events. If it is set to false, then no new event will be created from events that already had categories when they were received.

To load trained data into an agent’s memory, create a Manual Agent with nb_cats : =loadYML and nb_content : your-well-formed-training-data-here. Use the text input box, not the form view, by clicking “Toggle View” when inputting your training data else whitespace errors occur in the YML. Then submit this to your Naive Bayes Agent.

Advanced Naive Bayes Features

Only works if the nbayes dependency was installed from Github, version => .1.2. Rubygems is still .1.1

Be carefull with these functions: see the documentation linked below.

If a category has a - in front of it, eg. -trees, then the category trees will be UNtrained according to that content.

Low frequency words that increase processing time and may overfit - tokens with a count less than x (measured by summing across all classes) - can be removed: Set nb_cats : =purgeTokens and nb_content : integer-value.

Categories can be similarly deleted by nb_cats : =delCat and nb_content : categories to delete.

See the NBayes ruby gem and this blog post for more information about the Naive Bayes implementation used here.


Pdf Info Agent Creates events Receives events

The PDF Info Agent returns the metadata contained within a given PDF file, using HyPDF.

In order for this agent to work, you need to have HyPDF running and configured.

It works by acting on events that contain a key url in their payload, and runs the pdfinfo command on them.


Peak Detector Agent Creates events Receives events

The Peak Detector Agent will watch for peaks in an event stream. When a peak is detected, the resulting Event will have a payload message of message. You can include extractions in the message, for example: I saw a bar of: {{foo.bar}}, have a look at the Wiki for details.

The value_path value is a JSONPath to the value of interest. group_by_path is a JSONPath that will be used to group values, if present.

Set expected_receive_period_in_days to the maximum amount of time that you’d expect to pass between Events being received by this Agent.

You may set window_duration_in_days to change the default memory window length of 14 days, min_peak_spacing_in_days to change the default minimum peak spacing of 2 days (peaks closer together will be ignored), and std_multiple to change the default standard deviation threshold multiple of 3.

You may set min_events for the minimal number of accumulated events before the agent starts detecting.

You may set search_url to point to something else than Twitter search, using the URI Template syntax defined in RFC 6570. Default value is https://twitter.com/search?q={q} where {q} will be replaced with group name.


Phantom Js Cloud Agent Creates events Receives events Dry runs

This Agent generates PhantomJs Cloud URLs that can be used to render JavaScript-heavy webpages for content extraction.

URLs generated by this Agent are formulated in accordance with the PhantomJs Cloud API. The generated URLs can then be supplied to a Website Agent to fetch and parse the content.

Sign up to get an api key, and add it in Huginn credentials.

Please see the Huginn Wiki for more info.

Options:

  • Api key - PhantomJs Cloud API Key credential stored in Huginn
  • Url - The url to render
  • Mode - Create a new clean event or merge old payload with new values (default: clean)
  • Render type - Render as html or plain text without html tags (default: html)
  • Output as json - Return the page conents and metadata as a JSON object (default: false)
  • Ignore images - Skip loading of inlined images (default: false)
  • Url agent - A custom User-Agent name (default: Huginn - https://github.com/huginn/huginn)
  • Wait interval - Milliseconds to delay rendering after the last resource is finished loading. This is useful in case there are any AJAX requests or animations that need to finish up. This can safely be set to 0 if you know there are no AJAX or animations you need to wait for (default: 1000ms)

As this agent only provides a limited subset of the most commonly used options, you can follow this guide to make full use of additional options PhantomJsCloud provides.


Post Agent Creates events Receives events Consumes file pointer Dry runs

A Post Agent receives events from other agents (or runs periodically), merges those events with the Liquid-interpolated contents of payload, and sends the results as POST (or GET) requests to a specified url. To skip merging in the incoming event, but still send the interpolated payload, set no_merge to true.

The post_url field must specify where you would like to send requests. Please include the URI scheme (http or https).

The method used can be any of get, post, put, patch, and delete.

By default, non-GETs will be sent with form encoding (application/x-www-form-urlencoded).

Change content_type to json to send JSON instead.

Change content_type to xml to send XML, where the name of the root element may be specified using xml_root, defaulting to post.

When content_type contains a MIME type, and payload is a string, its interpolated value will be sent as a string in the HTTP request’s body and the request’s Content-Type HTTP header will be set to content_type. When payload is a string no_merge has to be set to true.

If emit_events is set to true, the server response will be emitted as an Event and can be fed to a WebsiteAgent for parsing (using its data_from_event and type options). No data processing will be attempted by this Agent, so the Event’s “body” value will always be raw text. The Event will also have a “headers” hash and a “status” integer value.

If output_mode is set to merge, the emitted Event will be merged into the original contents of the received Event.

Set event_headers_style to one of the following values to normalize the keys of “headers” for downstream agents’ convenience:

  • capitalized (default) - Header names are capitalized; e.g. “Content-Type”
  • downcased - Header names are downcased; e.g. “content-type”
  • snakecased - Header names are snakecased; e.g. “content_type”
  • raw - Backward compatibility option to leave them unmodified from what the underlying HTTP library returns.

Other Options:

  • headers - When present, it should be a hash of headers to send with the request.
  • basic_auth - Specify HTTP basic auth parameters: "username:password", or ["username", "password"].
  • disable_ssl_verification - Set to true to disable ssl verification.
  • user_agent - A custom User-Agent name (default: “Faraday v0.12.1”).

This agent can consume a ‘file pointer’ event from the following agents with no additional configuration: S3Agent, FtpsiteAgent, LocalFileAgent. Read more about the concept in the wiki.

When receiving a file_pointer the request will be sent with multipart encoding (multipart/form-data) and content_type is ignored. upload_key can be used to specify the parameter in which the file will be sent, it defaults to file.


Public Transport Agent Creates events

The Public Transport Request Agent generates Events based on NextBus GPS transit predictions.

Specify the following user settings:

  • agency (string)
  • stops (array)
  • alert_window_in_minutes (integer)

First, select an agency by visiting http://www.nextbus.com/predictor/adaAgency.jsp and finding your transit system. Once you find it, copy the part of the URL after ?a=. For example, for the San Francisco MUNI system, you would end up on http://www.nextbus.com/predictor/adaDirection.jsp?a=sf-muni and copy “sf-muni”. Put that into this Agent’s agency setting.

Next, find the stop tags that you care about.

Select your destination and lets use the n-judah route. The link should be http://www.nextbus.com/predictor/adaStop.jsp?a=sf-muni&r=N Once you find it, copy the part of the URL after r=.

The link may not work, but we’re just trying to get the part after the r=, so even if it gives an error, continue to the next step.

To find the tags for the sf-muni system, for the N route, visit this URL: http://webservices.nextbus.com/service/publicXMLFeed?command=routeConfig&a=sf-muni&r=N

The tags are listed as tag=”1234”. Copy that number and add the route before it, separated by a pipe ‘|’ symbol. Once you have one or more tags from that page, add them to this Agent’s stop list. E.g,

agency: "sf-muni"
stops: ["N|5221", "N|5215"]

Remember to pick the appropriate stop, which will have different tags for in-bound and out-bound.

This Agent will generate predictions by requesting a URL similar to the following:

http://webservices.nextbus.com/service/publicXMLFeed?command=predictionsForMultiStops&a=sf-muni&stops=N|5221&stops=N|5215

Finally, set the arrival window that you’re interested in. E.g., 5 minutes. Events will be created by the agent anytime a new train or bus comes into that time window.

alert_window_in_minutes: 5

Pushbullet Agent Receives events

The Pushbullet agent sends pushes to a pushbullet device

To authenticate you need to either the api_key or create a pushbullet_api_key credential, you can find yours at your account page:

https://www.pushbullet.com/account

If you do not select an existing device, Huginn will create a new one with the name ‘Huginn’.

To push to all of your devices, select All Devices from the devices list.

You have to provide a message type which has to be note, link, or address. The message types checklist, and file are not supported at the moment.

Depending on the message type you can use additional fields:

  • note: title and body
  • link: title, body, and url
  • address: name, and address

In every value of the options hash you can use the liquid templating, learn more about it at the Wiki.


Pushover Agent Receives events

The Pushover Agent receives and collects events and sends them via push notification to a user/group.

You need a Pushover API Token: https://pushover.net/apps/build

  • token: your application’s API token
  • user: the user or group key (not e-mail address).
  • expected_receive_period_in_days: is maximum number of days that you would expect to pass between events being received by this agent.

The following options are all Liquid templates whose evaluated values will be posted to the Pushover API. Only the message parameter is required, and if it is blank API call is omitted.

Pushover API has a 512 Character Limit including title. message will be truncated.

  • message - your message (required)
  • device - your user’s device name to send the message directly to that device, rather than all of the user’s devices
  • title or subject - your notification’s title
  • url - a supplementary URL to show with your message - 512 Character Limit
  • url_title - a title for your supplementary URL, otherwise just the URL is shown - 100 Character Limit
  • timestamp - a Unix timestamp of your message’s date and time to display to the user, rather than the time your message is received by the Pushover API.
  • priority - send as -1 to always send as a quiet notification, 0 is default, 1 to display as high-priority and bypass the user’s quiet hours, or 2 for emergency priority: Please read Pushover Docs on Emergency Priority
  • sound - the name of one of the sounds supported by device clients to override the user’s default sound choice. See PushOver docs for sound options.
  • retry - Required for emergency priority - Specifies how often (in seconds) the Pushover servers will send the same notification to the user. Minimum value: 30
  • expire - Required for emergency priority - Specifies how many seconds your notification will continue to be retried for (every retry seconds). Maximum value: 86400
  • html - set to true to have Pushover’s apps display the message content as HTML

Readability Agent Creates events Receives events Dry runs huginn_readability_agent

The Readability Agent extracts the primary readable content of a website.

data HTML to use in the extraction process, use Liquid formatting to select data from incoming events.

tags comma separated list of HTML tags to sanitize

remove_empty_nodes remove <p> tags that have no text content; also removes <p> tags that contain only images

attributes comma separated whitelist of allowed HTML tag attributes

blacklist CSS selector of elements to explicitly remove

whitelist CSS selector of elements to explicitly scope to

result_key sets the key which contains the the extracted information.

merge set to true to retain the received payload and update it with the extracted result

clean_output Removes \t charcters and duplicate new lines from the output when set to true.

Liquid formatting can be used in all options.


Read File Agent Creates events Receives events Consumes file pointer

The ReadFileAgent takes events from FileHandling agents, reads the file, and emits the contents as a string.

data_key specifies the key of the emitted event which contains the file contents.

This agent can consume a ‘file pointer’ event from the following agents with no additional configuration: S3Agent, FtpsiteAgent, LocalFileAgent. Read more about the concept in the wiki.


Rss Agent Creates events Dry runs

The RSS Agent consumes RSS feeds and emits events when they change.

This agent, using Feedjira as a base, can parse various types of RSS and Atom feeds and has some special handlers for FeedBurner, iTunes RSS, and so on. However, supported fields are limited by its general and abstract nature. For complex feeds with additional field types, we recommend using a WebsiteAgent. See this example.

If you want to output an RSS feed, use the DataOutputAgent.

Options:

  • url - The URL of the RSS feed (an array of URLs can also be used; items with identical guids across feeds will be considered duplicates).
  • include_feed_info - Set to true to include feed information in each event.
  • clean - Set to true to sanitize description and content as HTML fragments, removing unknown/unsafe elements and attributes.
  • expected_update_period_in_days - How often you expect this RSS feed to change. If more than this amount of time passes without an update, the Agent will mark itself as not working.
  • headers - When present, it should be a hash of headers to send with the request.
  • basic_auth - Specify HTTP basic auth parameters: "username:password", or ["username", "password"].
  • disable_ssl_verification - Set to true to disable ssl verification.
  • disable_url_encoding - Set to true to disable url encoding.
  • force_encoding - Set force_encoding to an encoding name if the website is known to respond with a missing, invalid or wrong charset in the Content-Type header. Note that a text content without a charset is taken as encoded in UTF-8 (not ISO-8859-1).
  • user_agent - A custom User-Agent name (default: “Faraday v0.12.1”).
  • max_events_per_run - Limit number of events created (items parsed) per run for feed.
  • remembered_id_count - Number of IDs to keep track of and avoid re-emitting (default: 500).

Ordering Events

To specify the order of events created in each run, set events_order to an array of sort keys, each of which looks like either expression or [expression, type, descending], as described as follows:

  • expression is a Liquid template to generate a string to be used as sort key.

  • type (optional) is one of string (default), number and time, which specifies how to evaluate expression for comparison.

  • descending (optional) is a boolean value to determine if comparison should be done in descending (reverse) order, which defaults to false.

Sort keys listed earlier take precedence over ones listed later. For example, if you want to sort articles by the date and then by the author, specify [["{{date}}", "time"], "{{author}}"].

Sorting is done stably, so even if all events have the same set of sort key values the original order is retained. Also, a special Liquid variable _index_ is provided, which contains the zero-based index number of each event, which means you can exactly reverse the order of events by specifying [["{{_index_}}", "number", true]].

If the include_sort_info option is set, each created event will have a sort_info key whose value is a hash containing the following keys:

  • position: 1-based index of each event after the sort
  • count: Total number of events sorted

In this Agent, the default value for events_order is [["{{date_published}}","time"],["{{last_updated}}","time"]].


S3 Agent Creates events Receives events Emits file pointer

The S3Agent can watch a bucket for changes or emit an event for every file in that bucket. When receiving events, it writes the data into a file on S3.

mode must be present and either read or write, in read mode the agent checks the S3 bucket for changed files, with write it writes received events to a file in the bucket.

Universal options

To use credentials for the access_key and access_key_secret use the liquid credential tag like so {% credential name-of-credential %}

Select the region in which the bucket was created.

Reading

When watch is set to true the S3Agent will watch the specified bucket for changes. An event will be emitted for every detected change.

When watch is set to false the agent will emit an event for every file in the bucket on each sheduled run.

This agent only emits a ‘file pointer’, not the data inside the files, the following agents can consume the created events: CsvAgent, PostAgent, ReadFileAgent. Read more about the concept in the wiki.

Writing

Specify the filename to use in filename, Liquid interpolation is possible to change the name per event.

Use Liquid templating in data to specify which part of the received event should be written.


Scheduler Agent Controls agents

The Scheduler Agent periodically takes an action on target Agents according to a user-defined schedule.

Action types

Set action to one of the action types below:

  • run: Target Agents are run at intervals, except for those disabled.

  • disable: Target Agents are disabled (if not) at intervals.

  • enable: Target Agents are enabled (if not) at intervals.

Targets

Select Agents that you want to run periodically by this SchedulerAgent.

Schedule

Set schedule to a schedule specification in the cron format. For example:

  • 0 22 * * 1-5: every day of the week at 22:00 (10pm)

  • */10 8-11 * * *: every 10 minutes from 8:00 to and not including 12:00

This variant has several extensions as explained below.

Timezones

You can optionally specify a timezone (default: Pacific Time (US & Canada)) after the day-of-week field using the labels in the tz database

  • 0 22 * * 1-5 Europe/Paris: every day of the week when it’s 22:00 in Paris

  • 0 22 * * 1-5 Etc/GMT+2: every day of the week when it’s 22:00 in GMT+2

Seconds

You can optionally specify seconds before the minute field.

  • */30 * * * * *: every 30 seconds

Only multiples of fifteen are allowed as values for the seconds field, i.e. */15, */30, 15,45 etc.

Last day of month

L signifies “last day of month” in day-of-month.

  • 0 22 L * *: every month on the last day at 22:00

Weekday names

You can use three letter names instead of numbers in the weekdays field.

  • 0 22 * * Sat,Sun: every Saturday and Sunday, at 22:00

Nth weekday of the month

You can specify “nth weekday of the month” like this.

  • 0 22 * * Sun#1,Sun#2: every first and second Sunday of the month, at 22:00

  • 0 22 * * Sun#L1: every last Sunday of the month, at 22:00


Sentiment Agent Creates events Receives events

The Sentiment Agent generates good-bad (psychological valence or happiness index), active-passive (arousal), and strong-weak (dominance) score. It will output a value between 1 and 9. It will only work on English content.

Make sure the content this agent is analyzing is of sufficient length to get respectable results.

Provide a JSONPath in content field where content is residing and set expected_receive_period_in_days to the maximum number of days you would allow to be passed between events being received by this agent.


Shell Command Agent Creates events Receives events Dry runs

The Shell Command Agent will execute commands on your local system, returning the output.

command specifies the command (either a shell command line string or an array of command line arguments) to be executed, and path will tell ShellCommandAgent in what directory to run this command. The content of stdin will be fed to the command via the standard input.

expected_update_period_in_days is used to determine if the Agent is working.

ShellCommandAgent can also act upon received events. When receiving an event, this Agent’s options can interpolate values from the incoming event. For example, your command could be defined as {{cmd}}, in which case the event’s cmd property would be used.

The resulting event will contain the command which was executed, the path it was executed under, the exit_status of the command, the errors, and the actual output. ShellCommandAgent will not log an error if the result implies that something went wrong.

If unbundle is set to true, the command is run in a clean environment, outside of Huginn’s bundler context.

If suppress_on_failure is set to true, no event is emitted when exit_status is not zero.

If suppress_on_empty_output is set to true, no event is emitted when output is empty.

Warning: This type of Agent runs arbitrary commands on your system, and is currently disabled. Only enable this Agent if you trust everyone using your Huginn installation. You can enable this Agent in your .env file by setting ENABLE_INSECURE_AGENTS to true.


Slack Agent Receives events

The Slack Agent lets you receive events and send notifications to Slack.

To get started, you will first need to configure an incoming webhook.

  • Go to https://my.slack.com/services/new/incoming-webhook, choose a default channel and add the integration.

Your webhook URL will look like: https://hooks.slack.com/services/some/random/characters

Once the webhook has been configured, it can be used to post to other channels or direct to team members. To send a private message to team member, use their @username as the channel. Messages can be formatted using Liquid.

Finally, you can set a custom icon for this webhook in icon, either as emoji or an URL to an image. Leaving this field blank will use the default icon for a webhook.


Slackbot Agent Creates events Receives events huginn_slackbot_agent

This agent instanciate a slack bot and send messages.

Generate a slack bot token here, and put into a credential called slack_bot_token

To send messages, just fill the options as a documented here

The bot needs to be in channel to send messages in it.


Stubhub Agent Creates events

The StubHub Agent creates an event for a given StubHub Event.

It can be used to track how many tickets are available for the event and the minimum and maximum price. All that is required is that you paste in the url from the actual event, e.g. https://www.stubhub.com/outside-lands-music-festival-tickets/outside-lands-music-festival-3-day-pass-san-francisco-golden-gate-park-polo-fields-8-8-2014-9020701/


Telegram Agent Receives events Dry runs

The Telegram Agent receives and collects events and sends them via Telegram.

It is assumed that events have either a text, photo, audio, document or video key. You can use the EventFormattingAgent if your event does not provide these keys.

The value of text key is sent as a plain text message. You can also tell Telegram how to parse the message with parse_mode, set to either html or markdown. The value of photo, audio, document and video keys should be a url whose contents will be sent to you.

Setup

  • Obtain an auth_token by creating a new bot.
  • If you would like to send messages to a public channel:
    • Add your bot to the channel as an administrator
  • If you would like to send messages to a group:
    • Add the bot to the group
  • If you would like to send messages privately to yourself:
    • Open a conservation with the bot by visiting https://telegram.me/YourHuginnBot
  • Send a message to the bot, group or channel.
  • Select the chat_id from the dropdown.

Options

  • caption: caption for a media content (0-200 characters)
  • disable_notification: send a message silently in a channel
  • disable_web_page_preview: disable link previews for links in a text message
  • long_message: truncate (default) or split text messages and captions that exceed Telegram API limits. Markdown and HTML tags can’t span across messages and, if not opened or closed properly, will render as plain text.
  • parse_mode: parse policy of a text message

See the official Telegram Bot API documentation for detailed info.


Text Summary Agent Creates events Receives events Dry runs huginn_text_summary_agent

The Text Summary Agent creates a summary of the provided text using the epitome gem

data text to summarize, use Liquid formatting construct the text based on the incoming event.

length when mode is percentage (in decimal form) the summary length will be at most the configured percentage of the orignal text, if mode is sentences the summary will be X sentences long.

threshold is a value between 0.1 and 0.3, but 0.2 is considered to give the best results (and thus the default value).

merge set to true to retain the received payload and update it with the extracted result

result_key sets the key which contains the the extracted information.

Liquid formatting can be used in all options.


Todoist Agent Receives events huginn_todoist_agent

The Todoist Agent creates items on your Todoist.

To authenticate you need to either set api_token or provide a credential named todoist_api_token to your Todoist API token. You can find it within the Todoist web frontend from “Gear Menu” > Todoist Settings > Account tab.

Change content to whatever the new Todoist item should tell. You can use liquid templating to include parts from the incoming event in the new item. Have a look at the Wiki to learn more about liquid templating.

In order to set a due date provide a date_string (which may contain all date string features supported by Todoist).

project_id is the ID of the project to add the item to. Leave blank for INBOX.

labels is a comma-seperated list of label IDs (or blank for no labels).

prority is an integer from 1 to 4. Where 1 means lowest (natural) priority and 4 highest. Defaults to natural priority (aka 1).


Todoist Close Item Agent Receives events huginn_todoist_agent

The Todoist Close Item Agent closes items on your Todoist.

To authenticate you need to either set api_token or provide a credential named todoist_api_token to your Todoist API token. You can find it within the Todoist web frontend from “Gear Menu” > Todoist Settings > Account tab.

Change id to whatever the ID of the item you would want to be closed is. You can also route query results from “Todoist Query Agent” to this agent and interpolate it using {{ id }} to close all items included in the search result.


Todoist Query Agent Creates events huginn_todoist_agent

The Todoist Query Agent allows to search items on your Todoist.

To authenticate you need to either set api_token or provide a credential named todoist_api_token to your Todoist API token. You can find it within the Todoist web frontend from “Gear Menu” > Todoist Settings > Account tab.

Change query to the Todoist filter expression you’d like to be carried out.

The mode option allows to control what information is emitted. With the default value of items an event is emitted for every item that matches the search result. And consequently no event is emitted if no items match the query. With count the agent always emits a single event, that just tells the number of matched items.


Transmission Agent Creates events Receives events Dry runs huginn_transmission_agent

Add a Agent description here


Transport Opendata Creates events Dry runs huginn_transport_opendata

Connects to the transport.opendata.ch API and checks currently available connections between two defined cities for the timestamp the request is sent.


Trigger Agent Creates events Receives events Dry runs

The Trigger Agent will watch for a specific value in an Event payload.

The rules array contains hashes of path, value, and type. The path value is a dotted path through a hash in JSONPaths syntax. For simple events, this is usually just the name of the field you want, like ‘text’ for the text key of the event.

The type can be one of regex, !regex, field<value, field<=value, field==value, field!=value, field>=value, field>value, and not in and compares with the value. Note that regex patterns are matched case insensitively. If you want case sensitive matching, prefix your pattern with (?-i).

The value can be a single value or an array of values. In the case of an array, all items must be strings, and if one or more values match, then the rule matches. Note: avoid using field!=value with arrays, you should use not in instead.

By default, all rules must match for the Agent to trigger. You can switch this so that only one rule must match by setting must_match to 1.

The resulting Event will have a payload message of message. You can use liquid templating in the `message, have a look at the Wiki for details.

Set keep_event to true if you’d like to re-emit the incoming event, optionally merged with ‘message’ when provided.

Set expected_receive_period_in_days to the maximum amount of time that you’d expect to pass between Events being received by this Agent.


Tumblr Likes Agent Creates events Receives events Tumblr

The Tumblr Likes Agent checks for liked Tumblr posts from a specific blog.

To be able to use this Agent you need to authenticate with Tumblr in the Services section first.

Required fields:

blog_name The Tumblr URL you’re querying (e.g. “staff.tumblr.com”)

Set expected_update_period_in_days to the maximum amount of time that you’d expect to pass between Events being created by this Agent.


Tumblr Publish Agent Creates events Receives events Tumblr

The Tumblr Publish Agent publishes Tumblr posts from the events it receives.

To be able to use this Agent you need to authenticate with Tumblr in the Services section first.

Required fields:

blog_name Your Tumblr URL (e.g. “mustardhamsters.tumblr.com”)

post_type One of [text, photo, quote, link, chat, audio, video, reblog]


You may leave any of the following optional fields blank. Including a field not allowed for the specified post_type will cause a failure.

Any post type

  • state published, draft, queue, private
  • tags Comma-separated tags for this post
  • tweet off, text for tweet
  • date GMT date and time of the post as a string
  • format html, markdown
  • slug short text summary at end of the post URL

Text title body

Photo caption link source

Quote quote source

Link title url description

Chat title conversation

Audio caption external_url

Video caption embed

Reblog id reblog_key comment


Full information on field options

Set expected_update_period_in_days to the maximum amount of time that you’d expect to pass between Events being created by this Agent.


Twilio Agent Receives events

The Twilio Agent receives and collects events and sends them via text message (up to 160 characters) or gives you a call when scheduled.

It is assumed that events have a message, text, or sms key, the value of which is sent as the content of the text message/call. You can use the EventFormattingAgent if your event does not provide these keys.

Set receiver_cell to the number to receive text messages/call and sender_cell to the number sending them.

expected_receive_period_in_days is maximum number of days that you would expect to pass between events being received by this agent.

If you would like to receive calls, set receive_call to true. In this case, server_url must be set to the URL of your Huginn installation (probably “https://”), which must be web-accessible. Be sure to set http/https correctly.


Twilio Receive Text Agent Creates events

The Twilio Receive Text Agent receives text messages from Twilio and emits them as events.

In order to create events with this agent, configure Twilio to send POST requests to:

https:///users/1/web_requests/:id/sms-endpoint

The placeholder symbols above will be replaced by their values once the agent is saved.

Options:

  • server_url must be set to the URL of your Huginn installation (probably “https://”), which must be web-accessible. Be sure to set http/https correctly.

  • account_sid and auth_token are your Twilio account credentials. auth_token must be the primary auth token for your Twilio accout.

  • If reply_text is set, it’s contents will be sent back as a confirmation text.

  • expected_receive_period_in_days - How often you expect to receive events this way. Used to determine if the agent is working.


Twitter Action Agent Creates events Receives events Twitter

The Twitter Action Agent is able to retweet or favorite tweets from the events it receives.

Set TWITTER_OAUTH_KEY and TWITTER_OAUTH_SECRET in your environment to use Twitter Agents.

It expects to consume events generated by twitter agents where the payload is a hash of tweet information. The existing TwitterStreamAgent is one example of a valid event producer for this Agent.

To be able to use this Agent you need to authenticate with Twitter in the Services section first.

Set expected_receive_period_in_days to the maximum amount of time that you’d expect to pass between Events being received by this Agent. Set retweet to either true or false. Set favorite to either true or false. Set emit_error_events to true to emit an Event when the action failed, otherwise the action will be retried.


Twitter Favorites Creates events Twitter

The Twitter Favorites List Agent follows the favorites list of a specified Twitter user.

Set TWITTER_OAUTH_KEY and TWITTER_OAUTH_SECRET in your environment to use Twitter Agents.

To be able to use this Agent you need to authenticate with Twitter in the Services section first.

You must also provide the username of the Twitter user, number of latest tweets to monitor and `history’ as number of tweets that will be held in memory.

Set expected_update_period_in_days to the maximum amount of time that you’d expect to pass between Events being created by this Agent.

Set starting_at to the date/time (eg. Mon Jun 02 00:38:12 +0000 2014) you want to start receiving tweets from (default: agent’s created_at)


Twitter Publish Agent Creates events Receives events Twitter

The Twitter Publish Agent publishes tweets from the events it receives.

Set TWITTER_OAUTH_KEY and TWITTER_OAUTH_SECRET in your environment to use Twitter Agents.

To be able to use this Agent you need to authenticate with Twitter in the Services section first.

You must also specify a message parameter, you can use Liquid to format the message.

Set expected_update_period_in_days to the maximum amount of time that you’d expect to pass between Events being created by this Agent.


Twitter Search Agent Creates events Twitter

The Twitter Search Agent performs and emits the results of a specified Twitter search.

Set TWITTER_OAUTH_KEY and TWITTER_OAUTH_SECRET in your environment to use Twitter Agents.

If you want realtime data from Twitter about frequent terms, you should definitely use the Twitter Stream Agent instead.

To be able to use this Agent you need to authenticate with Twitter in the Services section first.

You must provide the desired search.

Set result_type to specify which type of search results you would prefer to receive. Options are “mixed”, “recent”, and “popular”. (default: mixed)

Set max_results to limit the amount of results to retrieve per run(default: 500. The API rate limit is ~18,000 per 15 minutes. Click here to learn more about rate limits.

Set expected_update_period_in_days to the maximum amount of time that you’d expect to pass between Events being created by this Agent.

Set starting_at to the date/time (eg. Mon Jun 02 00:38:12 +0000 2014) you want to start receiving tweets from (default: agent’s created_at)


Twitter Stream Agent Creates events Twitter

The Twitter Stream Agent follows the Twitter stream in real time, watching for certain keywords, or filters, that you provide.

Set TWITTER_OAUTH_KEY and TWITTER_OAUTH_SECRET in your environment to use Twitter Agents.

To follow the Twitter stream, provide an array of filters. Multiple words in a filter must all show up in a tweet, but are independent of order. If you provide an array instead of a filter, the first entry will be considered primary and any additional values will be treated as aliases.

To be able to use this Agent you need to authenticate with Twitter in the Services section first.

Set expected_update_period_in_days to the maximum amount of time that you’d expect to pass between Events being created by this Agent.

generate should be either events or counts. If set to counts, it will output event summaries whenever the Agent is scheduled.


Twitter User Agent Creates events Twitter

The Twitter User Agent either follows the timeline of a specific Twitter user or follows your own home timeline including both your tweets and tweets from people whom you are following.

Set TWITTER_OAUTH_KEY and TWITTER_OAUTH_SECRET in your environment to use Twitter Agents.

To be able to use this Agent you need to authenticate with Twitter in the Services section first.

To follow a Twitter user set choose_home_time_line to false and provide the username.

To follow your own home timeline set choose_home_time_line to true.

Set include_retweets to false to not include retweets (default: true)

Set exclude_replies to true to exclude replies (default: false)

Set expected_update_period_in_days to the maximum amount of time that you’d expect to pass between Events being created by this Agent.

Set starting_at to the date/time (eg. Mon Jun 02 00:38:12 +0000 2014) you want to start receiving tweets from (default: agent’s created_at)


Unique Agent Creates events Receives events huginn_unique_agent

The UniqueAgent receives a stream of events and remits the event if it is not a duplicate.

property the value that should be used to determine the uniqueness of the event (empty to use the whole payload)

lookback amount of past Events to compare the value to (0 for unlimited)

expected_update_period_in_days is used to determine if the Agent is working.


User Location Agent Creates events Receives events

The User Location Agent creates events based on WebHook POSTS that contain a latitude and longitude. You can use the POSTLocation or PostGPS iOS app to post your location to https:///users/1/update_location/:secret where :secret is specified in your options.

If you want to only keep more precise locations, set max_accuracy to the upper bound, in meters. The default name for this field is accuracy, but you can change this by setting a value for accuracy_field.

If you want to require a certain distance traveled, set min_distance to the minimum distance, in meters. Note that GPS readings and the measurement itself aren’t exact, so don’t rely on this for precision filtering.

To view the locations on a map, set api_key to your Google Maps JavaScript API key.


Weather Agent Creates events

The Weather Agent creates an event for the day’s weather at a given location.

You also must select when you would like to get the weather forecast for using the which_day option, where the number 1 represents today, 2 represents tomorrow and so on. Weather forecast inforation is only returned for at most one week at a time.

The weather forecast information can be provided by either Wunderground or Dark Sky. To choose which service to use, enter either darksky or wunderground.

The location should be:

  • For Wunderground: A US zipcode, or any location that Wunderground supports. To find one, search wunderground.com and copy the location part of the URL. For example, a result for San Francisco gives https://www.wunderground.com/US/CA/San_Francisco.html and London, England gives https://www.wunderground.com/q/zmw:00000.1.03772. The locations in each are US/CA/San_Francisco and zmw:00000.1.03772, respectively.
  • For Dark Sky: location must be a comma-separated string of map co-ordinates (longitude, latitude). For example, San Francisco would be 37.7771,-122.4196.

You must set up an API key for Wunderground in order to use this Agent with Wunderground.

You must set up an API key for Dark Sky in order to use this Agent with Dark Sky.

Set expected_update_period_in_days to the maximum amount of time that you’d expect to pass between Events being created by this Agent.

If you want to see the returned texts in your language, set the language parameter in ISO 639-1 format.


Webhook Agent Creates events

The Webhook Agent will create events by receiving webhooks from any source. In order to create events with this agent, make a POST request to:

https:///users/1/web_requests/:id/:secret

The placeholder symbols above will be replaced by their values once the agent is saved.

Options:

  • secret - A token that the host will provide for authentication.
  • expected_receive_period_in_days - How often you expect to receive events this way. Used to determine if the agent is working.
  • payload_path - JSONPath of the attribute in the POST body to be used as the Event payload. Set to . to return the entire message. If payload_path points to an array, Events will be created for each element.
  • verbs - Comma-separated list of http verbs your agent will accept. For example, “post,get” will enable POST and GET requests. Defaults to “post”.
  • response - The response message to the request. Defaults to ‘Event Created’.
  • response_headers - An object with any custom response headers. (example: {"Access-Control-Allow-Origin": "*"})
  • code - The response code to the request. Defaults to ‘201’. If the code is ‘301’ or ‘302’ the request will automatically be redirected to the url defined in “response”.
  • recaptcha_secret - Setting this to a reCAPTCHA “secret” key makes your agent verify incoming requests with reCAPTCHA. Don’t forget to embed a reCAPTCHA snippet including your “site” key in the originating form(s).
  • recaptcha_send_remote_addr - Set this to true if your server is properly configured to set REMOTE_ADDR to the IP address of each visitor (instead of that of a proxy server).

Website Agent Creates events Receives events Dry runs

The Website Agent scrapes a website, XML document, or JSON feed and creates Events based on the results.

Specify a url and select a mode for when to create Events based on the scraped data, either all, on_change, or merge (if fetching based on an Event, see below).

The url option can be a single url, or an array of urls (for example, for multiple pages with the exact same structure but different content to scrape).

The WebsiteAgent can also scrape based on incoming events.

  • Set the url_from_event option to a Liquid template to generate the url to access based on the Event. (To fetch the url in the Event’s url key, for example, set url_from_event to {{ url }}.)
  • Alternatively, set data_from_event to a Liquid template to use data directly without fetching any URL. (For example, set it to {{ html }} to use HTML contained in the html key of the incoming Event.)
  • If you specify merge for the mode option, Huginn will retain the old payload and update it with new values.

Supported Document Types

The type value can be xml, html, json, or text.

To tell the Agent how to parse the content, specify extract as a hash with keys naming the extractions and values of hashes.

Note that for all of the formats, whatever you extract MUST have the same number of matches for each extractor except when it has repeat set to true. E.g., if you’re extracting rows, all extractors must match all rows. For generating CSS selectors, something like SelectorGadget may be helpful.

For extractors with hidden set to true, they will be excluded from the payloads of events created by the Agent, but can be used and interpolated in the template option explained below.

For extractors with repeat set to true, their first matches will be included in all extracts. This is useful such as when you want to include the title of a page in all events created from the page.

Scraping HTML and XML

When parsing HTML or XML, these sub-hashes specify how each extraction should be done. The Agent first selects a node set from the document for each extraction key by evaluating either a CSS selector in css or an XPath expression in xpath. It then evaluates an XPath expression in value (default: .) on each node in the node set, converting the result into a string. Here’s an example:

"extract": {
  "url": { "css": "#comic img", "value": "@src" },
  "title": { "css": "#comic img", "value": "@title" },
  "body_text": { "css": "div.main", "value": "string(.)" },
  "page_title": { "css": "title", "value": "string(.)", "repeat": true }
} or
"extract": {
  "url": { "xpath": "//*[@class="blog-item"]/a/@href", "value": "."
  "title": { "xpath": "//*[@class="blog-item"]/a", "value": "normalize-space(.)" },
  "description": { "xpath": "//*[@class="blog-item"]/div[0]", "value": "string(.)" }
}

“@attr” is the XPath expression to extract the value of an attribute named attr from a node (such as “@href” from a hyperlink), and string(.) gives a string with all the enclosed text nodes concatenated without entity escaping (such as &amp;). To extract the innerHTML, use ./node(); and to extract the outer HTML, use ..

You can also use XPath functions like normalize-space to strip and squeeze whitespace, substring-after to extract part of a text, and translate to remove commas from formatted numbers, etc. Instead of passing string(.) to these functions, you can just pass . like normalize-space(.) and translate(., ',', '').

Beware that when parsing an XML document (i.e. type is xml) using xpath expressions, all namespaces are stripped from the document unless the top-level option use_namespaces is set to true.

For extraction with array set to true, all matches will be extracted into an array. This is useful when extracting list elements or multiple parts of a website that can only be matched with the same selector.

Scraping JSON

When parsing JSON, these sub-hashes specify JSONPaths to the values that you care about.

Sample incoming event:

{ "results": {
    "data": [
      {
        "title": "Lorem ipsum 1",
        "description": "Aliquam pharetra leo ipsum."
        "price": 8.95
      },
      {
        "title": "Lorem ipsum 2",
        "description": "Suspendisse a pulvinar lacus."
        "price": 12.99
      },
      {
        "title": "Lorem ipsum 3",
        "description": "Praesent ac arcu tellus."
        "price": 8.99
      }
    ]
  }
}

Sample rule:

"extract": {
  "title": { "path": "results.data[*].title" },
  "description": { "path": "results.data[*].description" }
}

In this example the * wildcard character makes the parser to iterate through all items of the data array. Three events will be created as a result.

Sample outgoing events:

[
  {
    "title": "Lorem ipsum 1",
    "description": "Aliquam pharetra leo ipsum."
  },
  {
    "title": "Lorem ipsum 2",
    "description": "Suspendisse a pulvinar lacus."
  },
  {
    "title": "Lorem ipsum 3",
    "description": "Praesent ac arcu tellus."
  }
]

The extract option can be skipped for the JSON type, causing the full JSON response to be returned.

Scraping Text

When parsing text, each sub-hash should contain a regexp and index. Output text is matched against the regular expression repeatedly from the beginning through to the end, collecting a captured group specified by index in each match. Each index should be either an integer or a string name which corresponds to (?<name>...). For example, to parse lines of word: definition, the following should work:

"extract": {
  "word": { "regexp": "^(.+?): (.+)$", "index": 1 },
  "definition": { "regexp": "^(.+?): (.+)$", "index": 2 }
}

Or if you prefer names to numbers for index:

"extract": {
  "word": { "regexp": "^(?<word>.+?): (?<definition>.+)$", "index": "word" },
  "definition": { "regexp": "^(?<word>.+?): (?<definition>.+)$", "index": "definition" }
}

To extract the whole content as one event:

"extract": {
  "content": { "regexp": "\A(?m:.)*\z", "index": 0 }
}

Beware that . does not match the newline character (LF) unless the m flag is in effect, and ^/$ basically match every line beginning/end. See this document to learn the regular expression variant used in this service.

General Options

Can be configured to use HTTP basic auth by including the basic_auth parameter with "username:password", or ["username", "password"].

Set expected_update_period_in_days to the maximum amount of time that you’d expect to pass between Events being created by this Agent. This is only used to set the “working” status.

Set uniqueness_look_back to limit the number of events checked for uniqueness (typically for performance). This defaults to the larger of 200 or 3x the number of detected received results.

Set force_encoding to an encoding name (such as UTF-8 and ISO-8859-1) if the website is known to respond with a missing, invalid, or wrong charset in the Content-Type header. Below are the steps used by Huginn to detect the encoding of fetched content:

  1. If force_encoding is given, that value is used.
  2. If the Content-Type header contains a charset parameter, that value is used.
  3. When type is html or xml, Huginn checks for the presence of a BOM, XML declaration with attribute “encoding”, or an HTML meta tag with charset information, and uses that if found.
  4. Huginn falls back to UTF-8 (not ISO-8859-1).

Set user_agent to a custom User-Agent name if the website does not like the default value (Huginn - https://github.com/huginn/huginn).

The headers field is optional. When present, it should be a hash of headers to send with the request.

Set disable_ssl_verification to true to disable ssl verification.

Set unzip to gzip to inflate the resource using gzip.

Set http_success_codes to an array of status codes (e.g., [404, 422]) to treat HTTP response codes beyond 200 as successes.

If a template option is given, its value must be a hash, whose key-value pairs are interpolated after extraction for each iteration and merged with the payload. In the template, keys of extracted data can be interpolated, and some additional variables are also available as explained in the next section. For example:

"template": {
  "url": "{{ url | to_uri: _response_.url }}",
  "description": "{{ body_text }}",
  "last_modified": "{{ _response_.headers.Last-Modified | date: '%FT%T' }}"
}

In the on_change mode, change is detected based on the resulted event payload after applying this option. If you want to add some keys to each event but ignore any change in them, set mode to all and put a DeDuplicationAgent downstream.

Liquid Templating

In Liquid templating, the following variables are available:

  • _url_: The URL specified to fetch the content from. When parsing data_from_event, this is not set.

  • _response_: A response object with the following keys:

    • status: HTTP status as integer. (Almost always 200) When parsing data_from_event, this is set to the value of the status key in the incoming Event, if it is a number or a string convertible to an integer.

    • headers: Response headers; for example, {{ _response_.headers.Content-Type }} expands to the value of the Content-Type header. Keys are insensitive to cases and -/_. When parsing data_from_event, this is constructed from the value of the headers key in the incoming Event, if it is a hash.

    • url: The final URL of the fetched page, following redirects. When parsing data_from_event, this is set to the value of the url key in the incoming Event. Using this in the template option, you can resolve relative URLs extracted from a document like {{ link | to_uri: _response_.url }} and {{ content | rebase_hrefs: _response_.url }}.

Ordering Events

To specify the order of events created in each run, set events_order to an array of sort keys, each of which looks like either expression or [expression, type, descending], as described as follows:

  • expression is a Liquid template to generate a string to be used as sort key.

  • type (optional) is one of string (default), number and time, which specifies how to evaluate expression for comparison.

  • descending (optional) is a boolean value to determine if comparison should be done in descending (reverse) order, which defaults to false.

Sort keys listed earlier take precedence over ones listed later. For example, if you want to sort articles by the date and then by the author, specify [["{{date}}", "time"], "{{author}}"].

Sorting is done stably, so even if all events have the same set of sort key values the original order is retained. Also, a special Liquid variable _index_ is provided, which contains the zero-based index number of each event, which means you can exactly reverse the order of events by specifying [["{{_index_}}", "number", true]].

If the include_sort_info option is set, each created event will have a sort_info key whose value is a hash containing the following keys:

  • position: 1-based index of each event after the sort
  • count: Total number of events sorted

Website Metadata Agent Creates events Receives events Dry runs huginn_website_metadata_agent

The WebsiteMetadata Agent extracts metadata from HTML. It supports schema.org microdata, embedded JSON-LD and the common meta tag attributes.

data HTML to use in the extraction process, use Liquid formatting to select data from incoming events.

url optionally set the source URL of the provided HTML (without an URL schema.org links can not be extracted properly)

result_key sets the key which contains the the extracted information.

merge set to true to retain the received payload and update it with the extracted result

Liquid formatting can be used in all options.


Weibo Publish Agent Creates events Receives events

The Weibo Publish Agent publishes tweets from the events it receives.

You must first set up a Weibo app and generate an access_token for the user that will be used for posting status updates.

You’ll use that access_token, along with the app_key and app_secret for your Weibo app. You must also include the Weibo User ID (as uid) of the person to publish as.

You must also specify a message_path parameter: a JSONPaths to the value to tweet.

You can also specify a pic_path parameter: a JSONPaths to the picture url to tweet along.

Set expected_update_period_in_days to the maximum amount of time that you’d expect to pass between Events being created by this Agent.


Weibo User Agent Creates events

The Weibo User Agent follows the timeline of a specified Weibo user. It uses this endpoint: http://open.weibo.com/wiki/2/statuses/user_timeline/en

You must first set up a Weibo app and generate an acess_token to authenticate with. Provide that, along with the app_key and app_secret for your Weibo app in the options.

Specify the uid of the Weibo user whose timeline you want to watch.

Set expected_update_period_in_days to the maximum amount of time that you’d expect to pass between Events being created by this Agent.


Witai Agent Creates events Receives events

The wit.ai agent receives events, sends a text query to your wit.ai instance and generates outcome events.

Fill in Server Access Token of your wit.ai instance. Use Liquid to fill query field.

expected_receive_period_in_days is the expected number of days by which agent should receive events. It helps in determining if the agent is working.


Wunderlist Agent Creates events Receives events Wunderlist

The WunderlistAgent creates new Wunderlist tasks based on the incoming event.

Include the omniauth-wunderlist gem in your Gemfile and set WUNDERLIST_OAUTH_KEY and WUNDERLIST_OAUTH_SECRET in your environment to use this Agent

To be able to use this Agent you need to authenticate with Wunderlist in the Services section first.


Xero Agent Creates events Receives events huginn_xero_agent

Create Invoices in Xero based on incoming Events.

See this Agent’s GitHub page for instructions on setting up this Agent to access your Xero data.

All options support Liquid templating.

Options

  • expected_receive_period_in_days - How often you expect data to be received by this Agent from other Agents.
  • due_in_days - The number of days from now when the invoice is due.
  • The options contact_name, contact_phone_number, contact_email, contact_address_line_1, contact_address_line_2, contact_address_city, contact_address_region, contact_address_country, and contact_address_post_code allow setting details for a new contact.
  • You can set an item_path if you’d like to create multiple invoices, one per record at that JSONPath.
  • The options item_description, item_account_code, and item_amount allow configuring of invoice details and can contain Liquid templating, allowing you to make them dynamic based on Event input.