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.

../_images/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

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

  1. Navigate to Settings on the left hand panel. Learn more about the Settings page.

  2. Click on Configure.

    ../_images/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.

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.

../_images/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.

../_images/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 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}

../_images/jobs__webhooks_api_payload.png

Endpoint: {runner_url}/api/system

../_images/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:

../_images/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.

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

image

Use that URL in the Zuar Runner webhook config:

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

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

../_images/jobs__set_schedule.png

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

../_images/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 logic. To test different CRON schedules, use this helpful tool: https://crontab.guru/

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

../_images/jobs__schedule_cron.png

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

../_images/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 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.

../_images/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:

../_images/jobs__tags_filter.png

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

../_images/jobs__tags_nav.png

Learn more about adding custom navigation in Zuar Runner.

The 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)