🧩Extensions

Learn how to write your own extensions.

Writing extensions for WrangleBot is very simple and only requires a text editor to get started.

We recommend using an IDE such as Visual Studio Code, WebStorm or at the very least a text editor with syntax highlighting such as Sublime.

Choosing your Extension

WrangleBot supports two extension types: hooks and endpoints

Hook

Whenever WrangleBot does something, it fires events, these events contain data, that you can act on.

Example Use Cases:

• You want to send information to a third party whenver a MetaFile is ingested.

• You want to copy or transcode files directly after a Copy Task was completed.

• You want to send reports to a Slack channel.

Endpoint

An endpoint acts as any other endpoint on the API, you can call it via /api/v1/your-endpoint/ using any curl or http request.

Example Use Cases:

• You want to post or modify data that is coming from another source of truth.

• You want to run custom workflows, but don't want to have the logic on your side.

• You want to add custom functionality, i.e. Business Logic.

Adding your Extension

Start by creating a folder called custom in your wranglebot folder in your user home folder, i.e. /Users/axelrothe/wranglebot/

Within this folder, create another folder and give it a unique name. This will be your extension root folder.

Add your extension folder inside your custom folder

Create one or both folders, for hooks and endpoints and create a .js file, the name should reflect the script functionality, i.e. create-new-project.js

Create your extension files and place them in the correct folder.

Hook

Hooks are written in NodeJS using the CommonJS dialect.

module.exports = {
  name: "example-external-hook",
  description: "An example hook that is external to the bot",
  version: "0.0.1",
  events: ["notification"],
  handler: async (event, data, wranglebot) => {
    const libs = await wranglebot.query.library.many().fetch();

    console.log(`There are currently ${libs.length} libraries loaded.`);
  },
};

property	description
name : string	give your extension a name that you can use reference console logs in log.txt
description : string	describe your extension and what it is for. This will be used to display the current running extensions.
version : string	the version number. must adhere to semantic versioning
events : string[]	the id's of the events to listen to. It's possible to listen to multiple events per Hook, though it might be easier to write a hook per event.
handler : Function	The handler expects a Promise to be returned. To do this you can either use the async or Promise syntax. event : string // the event id data : any // see event return value wranglebot : WrangleBot // current instance

Endpoints

Endpoints are written in NodeJS using the CommonJS dialect.

module.exports = {
  method: "get",
  requiredRole: ["admin", "maintainer", "contributor"],
  url: "/example/01",
  handler: async (request, result, wranglebot, server) => {
  
    const libs = await wranglebot.query.library.many().fetch();
 
    return {
      status: 200, 
      result: `There are currently ${libs.length} libraries loaded.`
    }
  },
};

Property	Description
method : string	Must be either get, put, post, notify, patch or delete. This defines the REST endpoints method.
requiredRole : string[]	An array of all roles that can have access to this endpoint. If you leave this property blank it will default to any registered user. Possible Roles are: admin, maintainer, contributor, curator
url : string	The URI to the endpoint. You can define parameters by using the : operator, e.g. /custom-endpoint/:paramA/:paramB You can then query those parameters with request.params. const { paramA, paramB } = request.params; To get the body of a POST or PUT request, you use request.body
handler : async Function	The handler expects a Promise to be returned. To do this you can either use the async or Promise syntax. The handler will catch your Errors and return a generic Error to the user. The log will offer better insight into what went wrong. request : Request //use to get params, body and auth result : Result, //the result object, best left alone wranglebot : WrangleBot, //current instance server : RESTServer //Http Server You must return a valid RouteResult, as defined below. You can use any valid 3-digit HTTP Error Code. // @define RouteResult { status: number, // e.g. 200 OK, 404 NOT FOUND, 400 BAD REQUEST result: any // your result }

Importing Third Party Libraries

WrangleBot extensions currently do not support automatic importing of libraries via the node_module folder. You will need to directly require the script.

//instead of 
const thirdparty = require('mythirdpartylib');
// do
const thirdparty = require('./node_modules/mythirdpartylib/dist/index.js')

Sharing your Creations

We'd love to hear about your extensions and how you implemented them. You can share them with an active community over at our Discord Server and get feedback and recognition 👍