Saagie jobs

Use these tutorials to create, modify, and run a Saagie job.

1. Create a Saagie job

Together, let’s create the job Scranton Branch Sales in the project Dunder Mifflin Paper Sales.

Let’s assume that:

you’ve completed the tutorial Create a Saagie project where you created the project Dunder Mifflin Paper Sales, and
you’re on a platform where you are authorized to create a job.

1.1. Prepare package

Before creating the job, let’s create the package we’ll need. In this job, we’ll use the technology Python. Therefore, create a Python file called hello-scranton.py.

Open a new file in your preferred text editor.
Copy and paste the following code into the file:
```
print("Hello, Scranton Branch!")
```
Save the file as hello-scranton.py.

Now that you have the file you’ll need, let’s get started.

1.2. Navigate to project and begin creating job

Start by navigating to the example project.

Go to the Projects module from the primary navigation menu.
Go to the Dunder Mifflin Paper Sales project.
Verify that you are on the Jobs homepage (you should land there automatically).
Select the New job button.

1.3. Enter job name and description

Enter the name of your job: Scranton Branch Sales
Enter a description of your job: Fetch paper sales data about the Scranton Branch.
Select the Continue button.

1.4. Choose job type and technology

Next, it’s time to choose the type of job and the technology.

In this example, we’ll create an Extraction job using the technology Python from the repository Dunder Mifflin - URL.

Locate the Extraction category.
Locate the Dunder Mifflin - URL repository.
Select the Python checkbox.

Notice that your selection is indicated at the top of the page: Extraction > Python.
Select the Continue button.

1.5. Configure job

Now let’s configure the technology version, upload your package, and determine your shell command.

For the Python runtime context, choose the stable, recommended Python version 3.6.
Next, select the Choose file button to upload the file we created earlier: hello-scranton.py.
- The Choose file button will change to Change file, and the name and size of the file will appear next to the button. This means your file has been uploaded successfully.
Finally, update the shell command:
- Leave {file} as it is. Saagie will automatically replace it with the path to our uploaded file, hello-scranton.py.
- Delete arg1 and arg2 so that the command will only run our file, but note that the shell command is highly customizable.
Select the Continue button.

1.6. Choose job settings

At this point, you’ve arrived to the final page of job creation. It involves three items: email alerts, release notes, and run type.

1.6.1. Email alerts

Let’s set up an email alert for any time a job fails or is killed.

Select the Enable email alerts for this job checkbox. This will cause more options to open.
In the Job alerts login dropdown box, enter or select your own email address.
- We’ve set ours to send alerts to docs@saagie.com.
Select the Failed and Killed checkboxes.

Refer to the jobs explanation section for a description of each status.

1.6.2. Release notes

Release notes are optional but helpful as jobs evolve.

Select the Add a release note for this job version checkbox. An empty field will appear.
Enter the release note text: This job is a test to show that I can create an awesome Saagie job!

1.6.3. Run type

Almost done! The last step is to configure your run type and finish creating your job. For this job, let’s set up a daily scheduled run.

Select the Scheduled run checkbox.
Choose Shortcut.
Choose @daily.

Notice that a daily run in shortcut mode will run everyday at midnight UTC.
Select the Create job button.

Congratulations, your job is ready to go!

2. Run a job

Now that you’ve created a job on your Saagie platform, let’s try it out!

Let’s assume that you’ve completed the tutorial Create a Saagie job where you created the job Scranton Branch Sales.

You can run jobs manually whenever you need to, even when the job has a scheduled run.

2.1. Navigate to job

Start by navigating to the job.

Go to the Projects module from the primary navigation menu.
Go to the Dunder Mifflin Paper Sales project.
Verify that you are on the Jobs homepage (you should land there automatically). Notice that you can also run jobs from this page.
Go to the Scranton Branch Sales job.

2.2. Run job

Select the Run button located in the secondary navigation panel.

You can run a job from all pages concerning that job: overview, instances, and versions.
After about a minute, refresh your page. (Job run times vary.)
If the job ran successfully, you’ll see a Succeeded badge above the Run button.

Did you notice the changes to the secondary navigation panel after selecting Run?

The status area changes as the job runs.
The Run button became a Stop button.

3. Modify a job’s settings

Together, let’s modify the settings for the job Scranton Branch Sales in the project Dunder Mifflin Paper Sales.

Let’s assume that:

you’ve completed the tutorial Create a Saagie project where you created the project Dunder Mifflin Paper Sales.
you’ve completed the tutorial Create a Saagie job where you created the job Scranton Branch Sales.

3.1. Navigate to job

Start by navigating to the job.

Go to the Projects module from the primary navigation menu.
Go to the Dunder Mifflin Paper Sales project.
Verify that you are on the Jobs homepage (you should land there automatically).
Go to the Scranton Branch Sales job.

3.2. Go to settings

Notice the section on the job’s overview page displaying the current settings: job name, description, run type, and alerts. We will modify some of this information.
Go to Job settings.

You can access a job’s settings from all pages concerning that job: overview, instances, and versions.

3.3. Change name and description

We won’t actually change the name or description of the job, but note that you can change either of these at any time.

3.4. Change email alerts

Alerts are already enabled for this job. However, you’ve realized you need an alert every time this job succeeds, which we didn’t select when creating the job. You also don’t need an alert if the job is killed.

Select the Succeeded checkbox.
Clear the Killed checkbox.
Make no changes to the Failed checkbox.

3.5. Change run type

After some consideration, you’ve realized that a daily run for this job is a bit excessive; a weekly run will do.

However, you’d like that weekly run to be on Mondays instead of Sundays, and at 1:30 am PST instead of midnight UTC.

Scheduled run should already be selected.
Change Shortcut to Simple.
Change the time:
- Don’t change 01.
- Day to Week.
- Change Sunday to Monday.
- Change the first 00 field to 08.
- Change the second 00 field to 30.
- This changed the time from midnight UTC to 8:30 am UTC, which takes into account the time difference between PST and UTC.
Select the Save settings button.

Your settings are completely updated!

4. Upgrade a job

Let’s upgrade the job Scranton Branch Sales in the project Dunder Mifflin Paper Sales.

Let’s assume that:

you’ve completed the tutorial Create a Saagie project where you created the project Dunder Mifflin Paper Sales.
you’ve completed the tutorial Create a Saagie job where you created the job Scranton Branch Sales.

4.1. Prepare new package

We need a slightly different technology file to upgrade this job (for tutorial purposes only).

Open a new file in your preferred text editor.
Copy and paste the following code into the file:
```
print("Hi there, Scranton Branch!")
```
Save the file as hi-scranton.py.

Now that you have the file you’ll need, let’s get started.

4.2. Navigate to job

Start by navigating to the job.

Go to the Projects module from the primary navigation menu.
Go to the Dunder Mifflin Paper Sales project.
Verify that you are on the Jobs homepage (you should land there automatically).
Go to the Scranton Branch Sales job.

4.3. Begin job upgrade

Next, let’s upgrade the job.

Notice some of the information displayed about this job version, specifically the runtime context, package, shell command, and release note. Some of this information will change with the job upgrade, which will pass this job from version 1 to version 2.
Select the Upgrade job button.

You can upgrade a job from all pages concerning that job: overview, instances, and versions.

4.4. Select job upgrades

Keep the recommended Python context.
Upload the new file:
- Select the Change file button.
- Upload the hi-scranton.py file you created earlier.
- Double-check the file name next to the Change file button.
Make no changes to the shell command, as the job for this tutorial is deliberately simple.
Select the Continue button.

4.5. Add a new release note

Finally, let’s add a release note to describe what changed with this upgrade.

Select the Add a release note for this job version checkbox. An empty field will appear.
Enter the release note text: Updated Python file with friendlier language.
Select the Upgrade job button.

On the job’s home screen, it will show Version 2 underneath the title Current version, along with the release note. You can also see the updated Python file.

Focused view of changes made in this upgrade

You’ve now upgraded to a new version of your job. Well done!

5. Move a job

Jobs can be moved, or migrated, from their current project to another project on the same platform.

If a job has been a part of a pipeline at any time, the job can only be moved if that pipeline is deleted.

You have a job to move that is not a part of an existing pipeline.

5.1. Navigate to project

Jobs are moved from the job library page of the job’s current project.

Go to the Projects module from the primary navigation menu.
Go to the Dunder Mifflin Paper Sales project.

5.2. Select job to move

You can move one or multiple jobs at the same time, provided they are moving to the same project and will be the same type of job.

Note that you cannot select a job if it is part of a pipeline.
Select the checkbox next to each job you’d like to move. In this example, we’re moving one job: Rochester Branch Sales.
A box will appear in which we’ll make our next selections.

Move a job to a different project on the same platform

5.3. Choose job’s new project and type

Choose the project to which you’d like to move the job.
- You can move the job to any project you can access that has your job’s technology selected in its settings.
Choose the type of job (processing, extraction, or smart apps). You do not need to choose the same type of job in the target project.
- Categories available will depend on the target project’s settings.
Select the Move button to begin the migration.

5.4. Finish moving the job

Review the text in the confirmation box carefully—moving a job can impact its functionality. Select Cancel if you decide not to move your job.
Select Start Migration to confirm the migration of your job.

After selecting Start Migration, you’ll need to wait for the migration process to finish. Depending on the complexity of the job, this process might take awhile.

Refresh your browser occasionally to check on the progress. If the job is no longer listed on your current screen, that means the migration was successful.