# Introduction to Jobs

A job in Zuar Runner represents of a unit of work. There are a variety of
different types of jobs, most of which can be found on the Add Jobs
page within the UI.

Each job performs a specific function or set of functions. Jobs can be
run, scheduled, sequenced, tagged, and searched for.

.. image:: assets/intro-jobs-1.png

The most common job types are IO, which handle the input and output of
data, and Sequences which organize, order, and run jobs in series.

.. _notifications:


## Notifications

You can have Zuar Runner notify you on the status of your job.

1. Navigate to **Settings** on the left hand panel. [Learn
   more](/user-interface/settings/#settings) about the **Settings**
   page.
2. Click on **Configure**.

   .. image:: assets/jobs__notification_settings.png

3. The Messaging section is where you set your notifications.

   - **State**: This is where you can either enable or disable notifications.

   - **Recipient(s)**: Enter in the email address of the person(s) that
     will be receiving these notifications. Separate different email
     addresses with a comma. Any email listed in here will receive a
     notification.

   - **Default level**: Choose either *None, All*, or *Errors Only*
     for when you will be notified. With *None*, you will not be
     notified at all for any status of your job. *All* is the exact
     opposite. Choosing this will notify you of any status. *Errors
     Only* will notify you when there is an error in your job
     run. This is turned off by default so you only get
     notifications when you specify it on jobs. 

   - **Templates**: Shows how your notification message is
     encoded. This is an advanced feature. Do not modify this unless
     specified. 

The section below the **Messaging** section is the **Navigation**
section. Learn more about [custom
navigation](/user-interface/custom-navigation/).


## Webhooks

Zuar Runner webhooks can request data from or send data to any URL when a
job starts, completes, succeeds, or fails.

Webhooks can be added to any individual job or sequence in Zuar Runner.

### Add a Webhook to a Job

Click the edit button in the Webhooks section of any job.

.. image:: assets/jobs__webhooks.png

Fill in the form.
.. image:: assets/jobs__webhooks_form.png

#### URL
The URL to send the GET or POST request to.

#### Event

Webhooks can be initiated from four different job event types:

- **JOB_START** - initiate the webhook **when** the job **starts**
- **JOB_COMPLETE** - initiate the webhook **when** the job **completes**
- **JOB_SUCCESS** - initiate the webhook **if** the job **succeeds**
- **JOB_FAILURE** - initiate the webhook **if** the job **fails**

#### Method

- GET - request data from the URL
- POST - send data to the URL

*Typically, you want to send data to another application via a POST.*

#### Content Type

This is the format of the body of the request.

- application/json
- application/x-www-form-urlencoded
- text/plain

The choice here depends on the data format the URL is expecting.

#### Enabled

Check to enable this webhook or uncheck to disable it.

#### Body

This is the body of the request.

.. image:: assets/intro-jobs-5.png

### Editing an Existing Webhook

Click the edit icon next to any existing webhook to edit the webhook.

### Multiple Webhooks on the Same Job

Multiple webhooks can be added to any job in Zuar Runner, enabling complex
use cases and conditional logic.

### Webhooks Data

Data from the [Zuar Runner API](/api/runner/) can be sent in the
body of a webhook.

You can see the available data in the Zuar Runner API endpoints:

Endpoint: `{runner_url}/api/job/{job_id}`

.. image:: assets/jobs__webhooks_api_payload.png

Endpoint: `{runner_url}/api/system`

.. image:: assets/jobs__webhooks_api_system_payload.png

#### Simple Examples:

- `${job['title']}` translates to "Webhooks!"
- `${system['fqdn']}` translates to "stage.zuarbase.net"

#### Complete Example:

This example sends text to a Slack channel.
```
    { 
      "text": "Job Complete!: ${system['fqdn']} - ${job['title']}\nhttps://${system['fqdn']}/#!/job/${job['id']}" 
    }
```
This webhook body translates to:
```
    Job Complete!: stage.zuarbase.net - Webhooks!
    https://stage.zuarbase.net/#!/job/22739
```    

### Webhooks that Interact with Zuar Runner
You can create webhooks that interact directly with Zuar Runner itself. 

For example, one job's webhook can start another job:

.. image:: assets/jobs__webhooks_action.png

Notice the URL:

`http://webapp:7127/v2/jobs/<job_id>/:actions`

And the body:

```
    {
       "action": "START"
    }
```

### Webhooks that Interact with Microsoft Teams

The previous examples have utilized Slack as the receiving
application. Webhooks can be sent to most chat application. You can
create webhooks that interact directly with [Microsoft
Teams](https://learn.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook?tabs=dotnet).

The URL will be the webhook URL obtained from the Teams Channel configuration.

.. image:: assets/jobs__webhooks_teams1.png
   :alt: image

Use that URL in the Zuar Runner webhook config:

.. image:: assets/jobs__webhooks_teams2.png
   :alt: image

THe body of the notification should be structured like the following example in order for Microsoft Teams to accept the alert:
```
    { 
      "text": "Job Failed!: ${system['fqdn']} - ${job['title']}\nhttps://${system['fqdn']}/#!/job/${job['id']}" 
    }
```
.. _scheduling:


## Scheduling

Every Zuar Runner job can be scheduled to run at specific times.

.. image:: assets/jobs__set_schedule.png

On any individual job page, click on the edit button under
**SCHEDULE** to open a modal and set a schedule.

.. image:: assets/jobs__schedule.png

Jobs can be scheduled to to run **daily** at the specified time,
**hourly** on the specified minute (00, 15, 30, 45), **end of** a
specific time (week, month, quarter), as soon as it finishes (on the
next minute) AKA continuously, or to run on any custom schedule using
[CRON](https://en.wikipedia.org/wiki/Cron) logic. To test different
CRON schedules, use this helpful tool:
[https://crontab.guru/](https://crontab.guru/)


For example, run the job at 12:00 AM every Tuesday.

.. image:: assets/jobs__schedule_cron.png

Zuar Runner will attempt to translate your custom schedule on the job page.

.. image:: assets/jobs__schedule_cron_display.png

Jobs are not scheduled by default when they are created.

After you have made your selection, click **Save**. Congratulations!
You have just scheduled your job.

### Zuar Runner Scheduling Best Practices

Generally speaking, you should schedule
[sequences](/jobs/sequences/) of jobs instead of individual
jobs.

Set job schedules that make sense both from a source system
perspective (e.g. consider API limits, etc.) and end user needs
(e.g. do your users really need data refreshed continuously?).

## Tags

Tags are short keywords or keyword phrases associated with jobs. They
help organize jobs in the Zuar Runner UI.

.. image:: assets/jobs__tags.png

Jobs can have zero, one, or multiple tags.

There are several benefits for tagging jobs in Zuar Runner.

### Organization with Tags

Clicking on a tag shows a page with all jobs with that tag.

For example, clicking on the tag `curl` navigates to a page ending in
`/#!/tag/curl`:

.. image:: assets/jobs__tags_filter.png

This `/#!/tag/{tag}` page can be added a custom navigation item:

.. image:: assets/jobs__tags_nav.png

Learn more about adding [custom
navigation](/user-interface/custom-navigation/) in Zuar Runner.

The [Stage](/user-interface/stage/) is a specific example
of this tag and page interaction. Any jobs tagged with `stage` end up
on the Zuar Runner's Stage.

### Searching for Tags

The job search input on multiple pages in the Zuar Runner UI will find jobs
by their tag (as well as other job meta data).

### How to Add a Tag to a Job

Tags can be added to jobs in a number of ways:

- On an individual job's page
- On certain pages where there is a list of jobs (e.g. jobs, stage, any "tags" page)