Case Study 1 - Running a basic job

Problem:

Run a simple PowerShell (.ps1) script on a single machine. The PowerShell file should run daily at 11pm.

Solution:

To complete this task, the following ActiveBatch objects will need to be created: Folder, Execution Queue, Schedule, User Account, Plan and Job. A simple PowerShell script will also need to be created.

The Folder object is used to organize ActiveBatch objects.

The Execution Queue object is needed to establish a relationship between the Job Scheduler and the target Execution Agent ("Agent") machine, which is where the job will run. Every job must be assigned a queue.
The Schedule object is needed since we intend to run the job every day at 11pm.
The User Account object is needed since we need to establish security credentials for the job when it runs on the target Agent system. Every job must be assigned a User Account,
The Job object must be defined so ActiveBatch knows what needs to be run (e.g. the payload - in this case the PowerShell file). For some Job types, you could leave the payload as blank, but realistically, the payload should be configured to create a meaningful job.
The Plan object is where the Job object will be stored. The Plan is discussed more as you go through this case study.

Rather than create each object at the ‘root’ level (root level is the Job Scheduler level); we will create a folder and place all our ‘non-executing’ objects in that folder. Executing objects include Jobs, Job References and Plan, Plan References. Non-executing objects are all other object types.

Note: Please make sure you create the initial folder object, detailed in Case Studies - Getting Started - before you continue with Case Study 1.

Creating a Folder

Before we create our other objects directly related to the Job, we will create a Folder object where the non-executing objects will be placed. This folder will be a subfolder of the previously created UsersGuideCaseStudies folder.

Right-click on the UsersGuideCaseStudies folder (created in the Case Studies - Getting Started section) and select New > Folder. On the General property sheet, enter "Objects" in the Name property. The Label property will auto-populate with the same value. Leave the Label as-is. Click Save and Close. The Objects folder will appear in the Object Navigation Pane as a subfolder of UsersGuideCaseStudies.

Creating an Execution Queue

Next, we need to define an Execution Queue that represents the target Agent system. The purpose of an Execution Queue is to create a layer of abstraction between the actual execution machine and the job.

This abstraction can be very useful. What if the machine name changes that the job should run on? By creating an Execution Queue (that is typically shared by multiple jobs), we can avoid hard-coding the Agent machine on the job itself. Should the machine name change, the update only needs to be done in one place, on the Execution Queue object.

We will right-click on the Objects folder and select New > Queue > Execution Queue.

The property sheets for the New Execution Queue are tabbed in the Main view.

Defining a new execution queue is as simple as naming it and then entering an execution machine in the queue's Machine property. We will name this queue Server1. We have also entered a description for the queue, as depicted in the image above.

Next, click on the Properties tab listed under the General property sheet.

The Machine property is where you associate a machine with the Execution Queue. In this case, we are using local Execution Agent installed on the Job Scheduler system (there is always a local Agent installed on the Scheduler server).

Note: Note: If localhost doesn’t work for your particular machine then use 127.0.0.1 instead.

Notice a button name Directory to the right of the Machine property. Directory refers to Windows Directory Services (either AD or AD LDS), and when clicked, allows you to retrieve a list of published Execution Agent machines. Directory does require that your ActiveBatch Administrator first establish and publish Execution Agent/Machine names to a Directory Service. This feature has many benefits since it immediately reduces your choice of machines to only those where ActiveBatch has been installed. Next, the published name can be much more expressive and descriptive as opposed to a simple host/machine name. That said, since enabling Directory Services is optional, it is possible that this feature will not work for you. If this is the case. use localhost or 127.0.0.1 as indicated above. In summary, the Execution Queue's Machine property identifies the Execution Agent system where the job will run.

We will save exploring the other object categories for a later case study. Click the Save and Close button to create the execution queue. Using the Object Navigation pane, navigate to the Objects folder. Expand it if necessary, to see what is stored inside the folder. You should see something similar to what is depicted in the image below.

First, the queue is colored green. Green is good and denotes that the queue is started and connected to the Agent system. The icon itself also represents a started queue.

As a different example, the icon below for the same queue is not the same as the above image. Observe green is now tan, and there is a lightening bolt in the right hand corner of the icon. This symbolizes the Job Scheduler is not connected to the Execution Agent. Some troubleshooting will need to occur to fix the problem.

Creating a User Account Object

You might wonder why we have decided to create the security credentials for the job first, instead of defining the job and then specifying the security credentials. The reason we define the security credentials first is to demonstrate that these credentials need not be unique to the job. In other words, security credentials can be shared across many jobs (of course, assuming that the security of the object permits that).

The object that holds security credentials is called the User Account object. The User Account object contains the user’s security credentials. The credentials are typically a username and password appropriate to the machine that requires authentication.

The benefit to creating a User Account object is that if the password needs to be changed for a given account, you simply modify the User Account object. Any job object associated with the User Account object would automatically reflect the change. It is important to note that the account does not need to be a Windows username. It all depends on the operating system type that the job will be running on. The User Account object can describe a username/password for any supported operating system platform (e.g. Linux). However, for our case study exercise (since the job is running locally, on the Job Scheduler server) a Windows account must be used.

To create a new User Account object, right-click on the Objects folder and select New > User Account.

The New User Account property sheets are tabbed in the Main view. Enter TrainingAccount in the Name property. Optionally enter the Description. It's a good habit to describe your objects.

Next, click on the Properties tab.

The Credential Type property is "Username/Password". This is the default type. Keep this property as-is. The username and password that represent the User Account object are entered next. Clicking on the right-most button (the ellipsis to the far right of the Username property) causes a Directory Services-based dialog to pop up, in which you can select the account. This account must be a valid Windows account in your Windows environment that will authenticate on the Job Scheduler server, which is where the job will be running. Next, enter the password twice so the system can confirm it was entered correctly.

The “Remember Password” checkbox, if checked, results in an encrypted copy of the username and password to be stored locally on the client machine for convenience. Since we are creating a User Account object that we will be reusing (associating to many jobs) we have no need to remember the password. Since this is the case, the box will remain unchecked.

The Use Standard Authentication checkbox is enabled meaning that a username and password combination will be used for user credential purposes.

We will save exploring the other categories for a later case study and click the Save and Close button to save our new User Account object. It will be added to the Objects folder in the Object Navigation pane.

Creating a Schedule

Now that we have a User Account object established for our job, we will move on and solve the remaining parts of the problem. We know the job must execute at 11pm every day so we need to define a Schedule. A Schedule is an object that generates triggers based on date and, optionally, time. A trigger is a stimulus that causes a job to execute (assuming all requirements have been met – we’ll look at those in later sections).

To define a new schedule, right-click on the Objects folder and select New > Schedule.

The Schedule object Property sheets are tabbed in the Main view. Enter Daily as the Name and Label of the object.

Once again, every ActiveBatch object has several common (General) properties. We have named this Schedule object Daily to be somewhat descriptive.

Click on the Time Specification tab. While we can easily add the 11pm time (by either specifying 23 in the Hours field or as an exact time), we will instead disable the time specification by unchecking the Time Specification checkbox.

Best Practice: Time Specifications, when used as part of the Schedule object, does have its purpose and can be quite useful. That said, it is much better and more flexible to configure the trigger time on the job itself. The reason is because it is much more likely that one or more workflows will operate on the same set of days then at the same time. So if we create a daily schedule with an 11pm start time, it is much more likely that fewer jobs will share the same time (hence the Schedule object can't be shared as much). This means more Schedule objects would need to be created to accommodate all the time variations. This is true when including time in the Schedule object. When the time is set on the job itself, the shareability of the Schedule object is more likely, and you will not have to create as many schedules.

In the above figure the Time Specification property is not checked. This means that this Schedule object will not yield any times. It will only yield dates that we will configure next.

Next, we need to specify the day portion of the date/time trigger. Click on the Day Specification tab, as depicted in the image below.

The default values are what we want, for this case study. As per the above image, the Calendar Type property is "Calendar" the Specification Type property is "Daily", and the Daily Specification property is Every 1 day(s). Keep the default values.

We will save exploring the other categories for a later case study. Therefore, click the Save and Close button to save our new schedule.

This is what you should now see under the Objects folder - the new Schedule object and the other objects created earlier.

Creating the Plan

Just as we defined a Folder named Objects to hold our non-executing objects, and a UsersGuideCaseStudies folder to contain all the objects we define within this User’s Guide, we will apply the same principle to the Job object we need to create.

ActiveBatch supports two (2) types of user-defined containers: Folder and Plan. Both objects are very similar. However, a Folder is only a container. A Plan is both a container as well as an object that can be triggered for execution. Objects that can be triggered for execution are sometimes referred to as ‘instantiated objects’. ActiveBatch supports two (2) types of objects that can be instantiated (or that have instances): Plans and Jobs (and Job/Plan References).

A Plan can have any type of ActiveBatch object placed in it. So do we need to create a Plan to contain one Job? The Best Practice answer is “Yes”. Why? Because in the future we may add additional jobs and create a stream of related jobs. Having all these related jobs within a Plan creates a foundation for the proper organization of objects. As an example, assume you are creating a job to download a file from an FTP server. That is all you want to do - for now. So you create the FTP job and add it to a plan. Later on, you decide you want ActiveBatch to process the downloaded file, then archive the file when done. So you add two more jobs to the plan - process file and archive file. You then set the order the jobs should run in (i.e. Download, Process, Archive). A Plan that started out with 1 job was expanded, and 2 more jobs were added. The Plan is then triggered to start the workflow. While the Plan itself has no payload, it still creates an instance and goes into an executing state while its job are running.

To create a new Plan, right click on the UsersGuideCaseStudies Folder, then select New > Plan.

The Plan's property sheets are tabbed in the Main view. When you look at the left side categories, you may initially be overwhelmed. Don’t be. Very few of the categories and their associated properties are required to create a basic plan. Eventually you will learn about the flexibility those properties offer. But for now we will keep things simple.

Since this Plan will hold the Job object for CaseStudy1, that is what we will name the Plan (as depicted above).

Now, we have not created the Job object yet, but we know the job is supposed to run at 11pm daily. So we can either schedule the job to run at 11pm directly OR we can schedule the Plan to run at 11pm. Triggering the Plan will then cause the job to execute. Typically you should trigger the Plan rather than the job. Plans should be created with the intention of triggering the Plan. Do not use a Plan for storage purposes only. Use the folder object for that.

To associate the Schedule object (Daily) with our Plan, click on the Plan's Triggers category.

Check the Enable Date/Time Trigger property to arm date/time trigger, depicted in the image above. Next, click on the Associate radio button within the Schedules panel. Associate allows you to associate existing schedules (like Daily) to the plan.

You should see something similar to the above image (you will most likely have to expand the Objects folder to see the contained objects – in this case the Daily schedule). Click on the checkbox next to the schedule name, and then click the OK button. This action associates the schedule with the Plan (as depicted in the image below).

With the Schedule object now associated with the Plan, select the Schedule (as shown above) and click the Edit Times… button. The easiest approach to adding 11pm is to select “Exact Times” and then click the “Add” button.

Select “Exact Time” and then change the time to 11:00 PM. Click OK to this dialog and then OK to the Object Times dialog. You should then see the figure below.

This means the Daily schedule has been associated to the Plan, and the Plan itself has a time trigger set for 11PM (or 2300). We can now click the Save and Close button to create the Plan. It will appear in Object Navigation pane, in the UsersGuideCaseStudies folder.

Defining the PowerShell Script File

Consider the previous steps that we performed as laying the foundation for this tutorial. We will be able to use those objects in case studies that follow. The Objects folder will store the reusable objects (that are non-executing) using a Name that we assigned, to make them easy to find.

In getting our job off the ground, we must first create a simple PowerShell script. This is the payload or the work the job will be doing. For this case study, please do the following:

Create a file and name it Get-Processes.ps1. In the file enter the following single-line of PowerShell code: Get-Process

This command will list all the currently running processes on the system where the job runs.
Create a folder named “ActiveBatchTutorial” off the root of the C: drive on the Execution Agent system where the job will be running. Since the Execution Queue's (Server1) Machine property has a value of "localhost", the assumption is the job will run on the Scheduler server, where an Execution Agent is always installed. However, if you changed the Execution Queue's Machine property to a different value (instead of localhost) to point to a remote Execution Agent system, then you must create the file and folder on the remote Agent system. In summary, the Execution Agent, where the job will run, must be able to access the PowerShell file in the specified directory.

See the image below that depicts what you need to create - the directory and the file - on the Execution Agent system.

This means the full file specification, that we use later in the case study, will be C:\ActiveBatchTutorial\Get-Processes.ps1.

Defining the Job

Now we can define the Job object. To create a new Job, right-click on the CaseStudy1 plan and select New > Job. The job's property sheets are tabbed in the Main view.

On the General property sheet, enter Powershell as the job's Name. Keep the label as-is. Fill in a simple description, as depicted in the above image.

Next, click on the Process tab. Process is the default job type. If you do not see "Process" as the tab name on the left side-menu, directly under the General tab, click on whatever tab name you see (it will either be "Script" or" Jobs Library"). From there, click on the Job Type property on the right-hand side of the page, then select Process from the dropdown.

The Execution Properties section is where you select the queue you want the job to execute on. The Submission Queue field contains a dropdown that lists all defined queues. Look for the node in the navigation tree beginning with UsersGuideCaseStudies, then expand Objects and select Server1.

Next, the User Account field is where you associate the security credentials that you want this job to execute with. Every job requires a User Account object for that purpose. Just as with the submission queue, look for the tree beginning with UsersGuideCaseStudies, then within the Objects folder, select TrainingAccount.

Next, is the Job Type property. As mentioned, Process is the default job type (which is what we want). So leave that field as-is - as long as it states "Process".

The next field is File Name, and it represents the complete file specification to the script file that we created earlier. In this case it’s C:\ActiveBatchTutorial\Get-Processes.ps1. As a reminder, it is critically important that the file specification be accessible to the Execution Agent system, where the job will be running. Do not specify a local path on your client system if the client was launched from a system that is not on the Job Scheduler. As a reminder, the job will run on the local Agent installed on the Scheduler system.

The next field to mention is the Completion Status Rule (or Success Code Rule). This field denotes how ActiveBatch is to determine whether the job succeeded or not. Since this is a PowerShell file we are running, the program typically returns a success code of zero (0) to indicate success. That also is the default value for the success code rule. See the image below, which depicts the properties set thus far.

Next, click on the Execution tab on the left side menu, then enter a directory specification for the Working Directory property. The Working Directory is the default directory for the newly created job. Enter C:\ActiveBatchTutorial. Note, if this property is left blank, there is a default working directory, which varies depending on the OS version the job is running on, and the User Account the job is running under. Here is an example of a default working directory for a Windows job: \Users\TestUser\AppData\Local.

Next, click the New Job's Save and Close button. The Job will appear in the Object Navigation pane, as depicted in the image below.

Now the tree looks like this:

Rather than wait until 11pm (the job's scheduled run time), let’s run the Plan now.

Triggering a Plan

To manually trigger a Plan, we do need proper authorization. Since we created the Plan (and all the other objects) from a security point of view - we are the “Creator/Owner”. When using ActiveBatch, the owner of the object is implicitly granted complete access (full control). Therefore you should not encounter a security issue triggering the plan.

To trigger the Plan, we need to select it in the Object Navigation pane, then right-click on it and select Trigger. Note: You will see 2 trigger methods. One trigger method ("Trigger") triggers the plan as-is, and the second trigger method ("Trigger (Advanced)") is for more advanced usage. If you inadvertently selected the advanced trigger option, just click OK when the resulting dialog appears.

Once the Plan runs, you will see it appear in the Instances pane (if not, just click on the CaseStudy1 plan in the Object Navigation pane, as that action will force an update of the Instances pane). You should see something similar as depicted in the image below (the CaseStudy1 plan will be compressed; click the expand icon to the left of the plan name to open it).

Note: The Instances Pane is open by default. However, if you don't see it, click on the lower right-hand Open/Close Panes button as depicted in the image below, then select "Instances".

As you can see, the job ran successfully. If it had failed, the job (and plan) would be colored red instead of green. If the job failed, right click on the job in the Instances pane, then select View Log (plans don't generate log files). By default, standard output and standard errors are captured in the job log file. Look for clues as to the reason for the failure in the job log file. Note: If you see a "Abat" error in the Exit Code Description column of the Instances pane, it is possible there will be no job log file - if the job did not get far enough along for one to be generated. In that case, the Exit Code Description should be helpful in determining why the job failed. The ActiveBatch Reference Manual provides additional details about Abat errors.

Summary Case Study 1

We were tasked with running a PS1 file that is required to run at 11pm each day. We created the PS1 file and defined each of the objects necessary to successfully run the job. While we might have taken a shortcut or two - for example, we hard-coded the directory where the PowerShell script resides (using a variable would be a best practice). Still, as a beginner, we have laid a good foundation for the next case study.

One final point. Since we ran the Plan manually, how do we know that the Plan is actually scheduled for 11pm (2300) each day? There are several methods available for determining when a specific object (i.e. Plan or Job) is scheduled to run next. Let's look at the Properties pane first, followed by two other options (Instances pane and Browse view).

Properties

Click on CaseStudy1 in the Object Navigation pane. Next, click on the Properties tab in the lower left-hand pane (Under the Object Navigation pane). If the Properties tab is not present, click on the Open/Close Panes button, then select "Properties".

If you look at the bottom of the Properties pane, you will see the plan's Next Run Date/Time. See the image below. Note, the Last Run Date/Time is a result of the ad-hoc manual trigger. As a mention, whenever you select an object in the Object Navigation pane, the Properties pane will update to display the key properties of the selected object.

Instances Pane

If you select a canned date filter to see future runs, you will see that CaseStudy1 has been scheduled to run daily at 11pm. In this example, the "Next 5 days" filter was selected. Other instances views offer future run information as well (e.g. Daily Activity, Operations, Runbook, etc.). Note, if you set a filter on the Instances pane (to try it out), be sure to remove it before moving on to the next case study. The reason this is suggested is we do not want you inadvertently filtering out instances created in future exercises.

Note: Whenever you set or remove a filter in the Instances pane, you must click the refresh icon, circled on the left in the image below.

Browse View

Browsing lets you filter and display objects based on object type as well as display common and useful information that is specific to that object type.

To access the Browse view, right-click on the UsersGuideCaseStudies folder in the Object Navigation pane, then select View > Browse > Jobs, Folders & Plans (see above image). The Browse results are tabbed in the Main view, as depicted below. Observe the column named Next Run Date/Time displays the next expected run-time.

Note: If you do not want this plan to run daily at 11pm, you can disable it. To do so, right-click on the CaseStudy1 plan in the Object Navigation pane, then select Disable. That will stop it from executing.

Spotted a typo or can’t find help on a certain subject? Reach out to the Documentation team at docsupport@redwood.com.