Galaxy Webhooks

name: inverse
layout: true
class: center, middle, inverse

</span></div>

</span></div>

---

# Galaxy Webhooks

<div class="contributors-line">
		Authors: 
<a href="/training-material/hall-of-fame/blankclemens/" class="contributor-badge contributor-blankclemens"><img src="https://avatars.githubusercontent.com/blankclemens?s=27" alt="Avatar">Clemens Blank</a>

<a href="/training-material/hall-of-fame/martenson/" class="contributor-badge contributor-martenson"><img src="https://avatars.githubusercontent.com/martenson?s=27" alt="Avatar">Martin Čech</a>

<a href="/training-material/hall-of-fame/bgruening/" class="contributor-badge contributor-bgruening"><img src="/training-material/assets/images/orcid.png" alt="orcid logo"/><img src="https://avatars.githubusercontent.com/bgruening?s=27" alt="Avatar">Björn Grüning</a>

</div>

<div class="footnote" style="bottom: 8em;"><i class="far fa-calendar" aria-hidden="true"></i><span class="visually-hidden">last_modification</span> Updated: Jul 9, 2021</div>

<div class="footnote" style="bottom: 6em;">

<i class="fas fa-file-alt" aria-hidden="true"></i><span class="visually-hidden">text-document</span><a href="slides-plain.html"> Plain-text slides</a>
</div>

<div class="footnote" style="bottom: 2em;">
    <strong>Tip: </strong>press <kbd>P</kbd> to view the presenter notes
    | <i class="fa fa-arrows" aria-hidden="true"></i><span class="visually-hidden">arrow-keys</span> Use arrow keys to move between slides

</div>

???
Presenter notes contain extra information which might be useful if you intend to use these slides for teaching.

Press `P` again to switch presenter notes off

Press `C` to create a new window where the same presentation will be displayed.
This window is linked to the main window. Changing slides on one will cause the
slide to change on the other.

Useful when presenting.

---

### <i class="far fa-question-circle" aria-hidden="true"></i><span class="visually-hidden">question</span> Questions

- What are Galaxy Webhooks?

- How to create them?

---

### <i class="fas fa-bullseye" aria-hidden="true"></i><span class="visually-hidden">objectives</span> Objectives

- Discover what Galaxy Webhooks are

- Be able to create Webhooks

- Be able to add a Galaxy Webhook in a Galaxy instance

---

### What are Galaxy Webhooks?

A system which can be used to attach new functionalities to predefined entry points in the Galaxy interface.

An accessible way to make isolated customisations to a Galaxy instance.

---

### Entry point: masthead

![A person shaped icon in the Galaxy masthead is being hovered over and the popup reads "Show Username", presumably a custom webhook from a tutorial.](../../images/webhook_masthead.png)

Adds item to the top menu.

---

### Entry point: tool/workflow submission

![Screenshot of Galaxy with the job completion screen shown and a PhD comic image shown below.](../../images/webhook_tool.png)

Shown after tool or workflow execution.

---

### Entry point: tool-menu

Adds an entry to the tool form menu.

---

### Entry point: history-menu

![A section of the history menu is labelled Webhooks and shows a custom menu entry.](../../images/webhook_history.png)

Adds an entry to the history menu.

---

### What is a webhook made of?

- a config file in YAML format: `config/<NAME>.yml`
- optional: A Python helper file with access to the Galaxy `trans` object
  - `helper/__init__.py`
  - provides an API call at `/api/webhooks/<WEBHOOK_NAME>/get_data`
- optional: Additional `JS` and `CSS` code
  - `static/script.js`
  - `static/styles.css`

---

### Example configuration YAML

```yaml
name: trans_object
type:
  - masthead
activate: true

icon: fa-user
tooltip: Show Username

function: >
  $.getJSON("/api/webhooks/trans_object/get_data", function(data) {
    alert('Username: ' + data.username);
  });
```

---

### Definition of the configuration options

Argument | Description
--- | ---
`name` | Name of the Webhook (and API call)
`type` | Entry point. `tool/workflow/masthead/history-menu`. More might be available in future
`activate` | (De-)Activates the Webhook. `true/false`
`icon` | Icon to show for a `masthead` plugin. Full list of available icons [here](https://fontawesome.com/icons)
`tooltip` | Tooltip to show for `masthead` plugins
`function` | JavaScript code to run when `masthead` button is clicked

---

### Example `__init__.py`

```python
def main(trans, webhook):
    if trans.user:
        user = trans.user.username
    else:
        user = 'No user is logged in.'
    return {'username': user}
```

The return value can be read with a call to `/api/webhooks/WEBHOOK_NAME/get_data`
---

### Want to integrate Webhooks in your Galaxy instance?

- Copy your Webhook to your Webhook directory on your Galaxy instance
  - default: `config/plugins/webhooks`
  - configurable via `webhooks_dir` in `galaxy.yml`
- Restart Galaxy. While developing, changes at the `__init__.py` file will be active immediately

---

### Want to contribute?

- Create Webhooks and share them with the world!
  - on the [main Galaxy repository](https://github.com/galaxyproject/galaxy)
- Improve the Webhooks implementation
  - enhance existing entry points
  - add additional ones ...
- Improve the documentation or training material
  - [Documentation](https://docs.galaxyproject.org/en/latest/admin/special_topics/webhooks.html)
  - [Galaxy Training Network](https://training.galaxyproject.org]/training-material)

---

### Developing the Webhooks implementation

- Webhooks initialisation: `lib/galaxy/webhooks/__init__.py`
- JavaScript logic: `client/galaxy/scripts/mvc/webhooks.js`
- Entry points
  - `client/galaxy/scripts/mvc/tool/tool-form.js`
  - `client/galaxy/scripts/mvc/tool/tool-form-composite.js`
  - `client/galaxy/scripts/mvc/history/options-menu.js`
  - `client/galaxy/scripts/layout/menu-js`
- API: `lib/galaxy/webapps/galaxy/api/webhooks.py`
  - `lib/galaxy/webapps/galaxy/buildapp.py`

---
### <i class="fas fa-key" aria-hidden="true"></i><span class="visually-hidden">keypoints</span> Key points

- A Galaxy Webhook provides an easy way to customize the Galaxy UI with plugins

- Right now there are 4 entry points: tool, workflow, masthead, history-menu

- With a minimal amount of code you can extend Galaxy's user-interace.

---

## Thank You!

This material is the result of a collaborative work. Thanks to the [Galaxy Training Network](https://training.galaxyproject.org) and all the contributors!

<a href="/training-material/hall-of-fame/martenson/" class="contributor-badge contributor-martenson"><img src="https://avatars.githubusercontent.com/martenson?s=27" alt="Avatar">Martin Čech</a>

</div>

</div>

<a rel="license" href="https://creativecommons.org/licenses/by/4.0/">
This material is licensed under the Creative Commons Attribution 4.0 International License</a>.