# User Interface (UI)

Zuar Runner's user interface (UI) allows users to create/edit jobs and perform many
administrative tasks.

To access Zuar Runner's user interface, you'll need the following information: 

- The URL of your Zuar Runner instance.
- A Zuar Runner admin login.

See your Zuar Runner administrator for these items.

## Left Sidebar (Navigation Menu)

Zuar Runner's **navigation menu** appears on the left sidebar when you login with an
admin user.

.. image:: assets/user-interface-1.png
   :alt: Zuar Runner's left sidebar navigation

Use this menu to navigate to different areas of Zuar Runner:

- **Stage** - All jobs/sequences tagged with `stage`.
- **Swimlanes** - Visual representation of job run history.
- **Graph** - Visual representation of the relationships between jobs.
- **Database** - Information related to Zuar Runner’s internal PostgreSQL database.
- **Source** - Quick links to all jobs for a particular source.
- **Jobs** - Manage Zuar Runner jobs.
- **History** - Review job run history.
- **Files** - Manage and download files stored on the Zuar Runner instance file system.
- **Credentials** - Manage stored credentials.
- **Settings** - Configuration options.

More details about these sections can be found below.

### Left Sidebar on Smaller Screens

On smaller screens (e.g. mobile), the left sidebar is collapsed into an icon
in the upper-left, next to the Zuar Runner logo. Click the icon to display/hide the
sidebar:

.. image:: assets/user-interface-2.png
   :alt: Mobile browser menu icon

### + Add Job Button

The **+ Add Job** button at the bottom of the left sidebar allows you to
create new items from anywhere in Zuar Runner.

.. image:: assets/user-interface-3.png
   :alt: Zuar Runner's Add button on the bottom of the left sidebar

If you'd like to create something other than a job, click the **^** on the
right side of the button to add any of the following:

- **Credentials**
- **File**
- **Navigation**
- **Sequence** 

## Top Navigation Bar

.. image:: assets/user-interface-4.png
   :alt: Zuar Runner's top navigation

Along the top of the screen, Zuar Runner displays the following: 

- **Zuar Runner logo** - Anywhere in Zuar Runner click the logo to return to the
  **Stage**. In mobile mode, the sidebar display/hide icon is displayed in
  this area.
- **Metrics** - Zuar Runner displays the following statistics: 
    - **Running jobs**: number of jobs being currently executed.
    - **Total jobs**: number of jobs found under **Jobs** (including disabled jobs).
    - **Total runs**: the number of job executions Zuar Runner has attempted. 
    - **Ok Runs**: the percentage of jobs completed with a **Status** of `Successful`.
- **?** (Help): Provides access to this documentation, the Zuar Community, and Zuar Support.  
- **Logout**: Click to end your Zuar Runner session and return to the login screen.

## Stage

.. image:: assets/user-interface-5.png
   :alt: Zuar Runner Stage

The Stage serves as a customizable "homepage" that presents your most
important sequences and jobs as soon as you login.

The Stage presents a view of all of the jobs that are tagged with `stage`. If
you tag a job with `stage` the job will appear in this space automatically.

This can be used as a workspace for current projects, or as a place to collect
jobs that you visit often. The Stage is a convenient place to put jobs that
are important to you.

The Stage is often the first thing you see when logging in to Zuar Runner. At any
time, you can navigate directly to the Stage by clicking Stage on the left
sidebar or the Zuar Runner logo.

.. warning:: 

    Until you tag a job or sequence with the word stage, all of your jobs and sequences will show up on the stage

## Swimlanes

.. image:: assets/user-interface-6.png
   :alt: Zuar Runner Swimlanes

The Swimlanes page displays the history of job runs in a Gantt chart. You can
use the Swimlanes page to get an overview of job runs, or get information that
may help understand why something went wrong. 

You can use filters to focus on:

- Job **status** (running/success/failure)
- Job **type**
- **Tags**
- **Ran during**: job execution start

The Gantt chart provides many insights:

- Job start and end times
- Job durations
- Job concurrency
- Jobs are color-coded to indicate **status**
- Hover over the job run bar to see more detail

Quick navigation: 

- Click the name of a job on the left to go directly to the job.
- Click a job run's bar in the chart to be taken to the job run details page.

## Graph

.. image:: assets/user-interface-7.png
   :alt: Zuar Runner Graph

A place to visually see job and sequence relationships and job status. There
are a variety of graph layout types available. There are also quick links to
navigate straight to a specific job or sequence.

You can use filters to focus on:

- Job **status** (running/success/failure)
- Job **type**
- **Tags**
- **Ran during**: job execution start

## Database

.. image:: assets/user-interface-8.png
   :alt: Zuar Runner Database

Provides a user interface for Zuar Runner's internal PostgreSQL database showing
previews of its data tables. You can explore Zuar Runner's analytics database with
the ability to drill into schema's and physical tables. Once you've navigated
to a table, you can drop the table with the red **Drop Table** button at the
bottom. *Caution! There is no undo after a table has been dropped.*

## Jobs

.. image:: assets/user-interface-9.png
   :alt: Zuar Runner Jobs

The jobs page is very similar to the Stage but used for searching and
displaying all jobs on the Zuar Runner instance. There are a variety of filters that
can be used for finding specific jobs as well as a search field:

- Job **status** (running/success/failure)
- Job **type**
- **Tags**
- **Ran during**: job execution start

## History

.. image:: assets/user-interface-10.png
   :alt: Zuar Runner History

A history of all job runs on the Zuar Runner instance. Usefully for finding job run
problems or simply viewing the most recently run jobs. You can navigate
directly to jobs and a job status from this page.

You can use filters to focus on:

- Job **status** (running/success/failure)
- Job **type**
- **Tags**
- **Ran during**: job execution start

.. _files:


## Files

.. image:: assets/user-interface-11.png
   :alt: Zuar Runner Files

A built in file explorer for the `/var/mitto/data/` directory on a Zuar Runner
instance. This is generally where flat files are stored prior to being pushed
to a database or scripts can be saved for reference inside of command jobs.

You can find a specific file via the **Search Files** field. 

The following file management operations are available:

- **Upload**: Drag and drop files or click the **Add File** button to upload
  new files. 
- **Download**: Select file(s) using the checkboxes to the left of the
  filename. Click **Download File** button in upper right. Alternatively,
  click the Download icon at the right of the file's row in the list.
- **Delete**: Select file(s) using the checkboxes to the left of the
  filename. Click **Delete File** button in upper right. Alternatively, click
  the Delete icon (trashcan) at the right of the file's row in the list. *Make
  sure you really want to delete - there is no undo!*

.. note:: 

    *Directories* can be added within `/var/mitto/data/` via the Zuar Runner instance shell command line, but will not be visible on the Files page.

## Credentials

.. image:: assets/user-interface-12.png
   :alt: Zuar Runner Credentials

It is best practice to store and encrypt credentials that need to be used
across the Zuar Runner environment. Use this page to add and manage stored
credentials. 

Once stored in the credential manager, credentials are encrypted and can be
referenced across the instance. When credentials need to be updated, update
the stored credential and all jobs referencing that credential will be
updated.

When creating a new credential, choose a **Credential Type** which matches the
service you are connecting to, if available. If a matching Credential Type is
not available, choose Basic or Generic.

.. warning:: 

    Not all credential types can be stored and used in Zuar Runner's credential manager. Ask your Zuar Runner administrator or Zuar about potential limitations.

## Settings

.. image:: assets/user-interface-13.png
   :alt: Zuar Runner Settings

### About Tab

Information about your Zuar Runner environment:

- Zuar Runner Version
- Timezone of the instance
- API Key
- Available hardware resources: CPU, Memory (RAM), Disk Space & Usage breakdown
- Change Password

### Configure Tab

Configure email notifications, enable Job Runner, and add custom navigation items. 

#### Custom Navigation Items

You have the ability to create custom navigation items within the Zuar Runner
sidebar. This can make finding and organizing jobs easier. In general, a
custom navigation item allows you to group jobs by a shared attribute and
easily access these grouped jobs from a menu item.

### Licensing Tab

View license status and connector details, including version. 

## Custom Navigation Items

Custom navigation items within the Zuar Runner sidebar makes finding and organizing
jobs easier. A custom navigation item allows you to group jobs by a shared
attribute (e.g. tag) and easily access these grouped jobs from the sidebar.

To create a new Navigation Item:

1. Click the up arrow `^` next to the **+ Add Job** button and click **Add Navigation**. The Navigation editor also allows you add new items under **Settings** > **Configure**. 

1. Give the navigation item a **Name**

1. Set **Order** to a value that will place the Navigation item on the sidebar where you want it to appear.

1. Choose a relevant **Icon**. 

1. Leave **Type** as `App State`

1. Set **Parent** to `None`, unless you are creating a nested sidebar item. 

1. Set **State name** to `tag` and fill in the Tag field with your desired tag. 

1. Click **Save**.

   .. image:: assets/mitto-ui__custom_nav_item.png
      :alt: Custom navigation item