Reference Object

A Reference object points to an existing job or plan. Therefore, you can create job and plan references. References are triggerable objects and will run the job or plan they are referencing. It is used when there is a need to execute an existing job or plan in different workflows. Your first thought might be to copy and paste the existing job or plan. But this can create more work for you, later on, if something in the copied job or plan changes. Updating the same changes in multiple objects would create extra work. This is where the reference object comes into play - to prevent this kind of unnecessary maintenance of your ActiveBatch objects.

 

You can create one or more references to point to an existing job or plan. Whenever the original object’s payload (or other shared properties) are modified, the reference object also sees that modification. In this respect a Reference object is like a shortcut in the Windows operating system. Reference objects reference the payload as well as several other properties that are most likely to be shared. Reference objects also have properties that are configurable on the reference itself. 

 

Described below is a reference object example.

 

Assume you’ve already created a job named JobA that performs all the necessary operations, and you need to perform the same actions in a new and different job stream. Rather than creating a copy of JobA (which you could do) a better approach would be to create a reference to that job. This way if JobA is modified, the resulting changes will be seen by both job streams. This is the key purpose of the Reference object - to allow you to reuse what you have already created, thus minimizing the maintenance of your ActiveBatch objects. It can be a significant time saver to modify the payload of a single triggerable object when compared to performing the same modification on multiple (copied) objects that are doing the same work.

 

To create a reference to a job, select the job object in the Navigation pane, then right-click and select the Create Reference operation from the menu. The same menu option is available for a plan.

 

 

When you select this operation, you should see a window similar to the one below:

 

 

You need to indicate where you would like the newly created Reference object to be placed. You can keep the default location, which is the same location as the referenced (target) object, or you can select any other container (root, folder, or plan) in the tree. 

 

Below you will find a description of the General and Properties tabs.

 

 

 

A Reference object has its own identity apart from the object it’s referencing. The Reference object can have different Scheduled or Event Triggers, Constraints, Completion Triggers, Alerts, Queue, User Account, and Security. The figure above shows the General properties of a job Reference object.

 

Name: This mandatory property represents the name of the object. The name is limited to 128 characters. The object’s name should be unique to avoid confusion. We recommend that it also be somewhat descriptive so it’s easy to find. The name is used to identify the object in the Navigation pane and other places in the UI.

 

Label: Every object must be uniquely labeled within the scope of the namespace. The label is limited to sixty-four (64) characters. The label is typically the same value as the name (it is auto-filled to match the name you enter); however, uniqueness is always enforced for an object’s label. The label is recorded in the ActiveBatch namespace. The characters that may be used for the label property are restricted to alphanumeric (A-Z, a-z, 0-9), space, period (.), dash (-) and underscore (_). The label itself must begin with an alphabetic character. The label is typically used when scripting. All searches are case-insensitive. ActiveBatch does allow you to search for objects using either the label or the name properties.

 

ID: This is a unique read-only number that can be used to retrieve the object. Is it assigned by the system when a new object is saved.

 

Full Path: This read-only property provides the full namespace specification of the object. It consists of the container(s) the object has been placed in, with the object’s label appended to the end. For example, the fullpath: /IT Jobs/Nightly Run/<object label>, is such that IT Jobs is a root-level folder, Nightly Run is a plan, followed by the label of the object you are creating.

 

Description: This free form property is provided so you can document and describe the object to others. The description is limited to 512 characters. Clicking on the pencil icon will pull up a mini text editor where you can more easily enter your description.

 

State: This read-only field indicates whether the Schedule is enabled for use. It is either enabled or disabled.

 

Hide in Runbook, Gantt and Daily Activity List: This checkbox indicates whether you would like to hide this reference in the views mentioned. This can be useful when you have a job that runs very often and would only clutter the usefulness of the other views.

 

Read Only: This checkbox, when enabled, means the schedule's properties cannot be changed.  You must have “Modify” access permission to the calender object to set this feature.  To clear the read-only attribute, uncheck the box.

 

 

Reference To: This property is a read-only field set to the full path of the object (job or plan) that it is referencing. In this example, it is the target job named JobA within the folder /Database Jobs. While this field cannot be directly changed, you’ll notice a button named “Change…” to the far right of the property. This button allows you to change your reference (i.e. the target job or plan). A small button to the left of the Change button (…) allows you to quickly view the properties of the target object, which in this example is JobA.  

 

Submission Queue: (unchecked by default) – This property is applicable to job references only. It displays the default queue the Reference object is associated with. It is the same queue that the target job is associated with. This can be changed if you would like the reference job to be associated with a different queue, and subsequently run on a different Execution Agent system. 

 

When the Submission Queue checkbox is checked:

  1. The Submission Queue property will be enabled, allowing you to click on the property’s dropdown arrow, which will display a pick list. Use the list to navigate to the desired queue (Execution or Generic), then select it. Please note, the built-in RuntimeQueue is not displayed as an option because it is not supported in this field.

    The user making the queue change must be granted “Use” permissions to the selected queue. If they do not have this permission, an “access denied” message will pop up when they attempt to save the Reference object.  

  2. The New button will be enabled, in the event you do not wish to select an existing queue, but rather, you would like to create a new one.  If New is selected, you will be prompted to select a container (root, folder or plan) to place the new queue in.  After doing so, the property sheets of the new Execution Queue will be tabbed in the Main view.  You will need to configure the queue and save it. After doing so, the Submission Queue property will be set to the new queue. 

    If you select a different queue or create a new one, you have the option to view the properties of the selected or new queue by clicking on the icon to the left of the New button (…).  This will tab the property sheets of the queue in the Main view. 

If you check the Submission Queue checkbox and you do not select or create a queue (the property value is “None”), and you attempt to save the Reference object, it will fail because a queue must be associated to the reference. You can uncheck the Submission Queue checkbox, which will revert the property back to the default queue. 

 

User Account: (unchecked by default) – This property is applicable to Job references only. It displays the default user account the reference object is associated with.  It is the same user account that the target job is associated with.  This can be changed if you would like the reference job to be associated with a different user account, and subsequently run under different user credentials on the Execution Agent system. 

 

When the User Account checkbox is checked:

  1. The User Account property will be enabled, allowing you to click on the property’s dropdown arrow, which will display a pick list. Use the list to navigate to the desired user account, then select it. Please note, the built-in RuntimeUserAccount is not displayed as an option because it is not supported in this field.

    The user making the change must be granted “Use” permissions on the selected User Account object. If they do not have this permission, an “access denied” message will pop up when they attempt to save the Reference object.  

  2. The New button will be enabled, in the event you do not wish to select a user account, but rather, you would like to create a new one.  If New is selected, you will be prompted to select a container (root, folder or plan) to place the new User Account object in. After doing so, the property sheets of the new user account will be tabbed in the Main view.  You will need to configure the user account and save it. After doing so, the User Account property will be set to the new user account. 

    If you select a different user account or create a new one, you have to option to view the properties of the selected or new account by clicking on the icon to the left of the New button (…).  This will tab the property sheets of the user account in the Main view. 

If you check the User Account checkbox and you do not select or create a user account (the property value is “None”), and you attempt to save the Reference object, it will fail because a user account must be associated to the reference.  You can uncheck the User Account checkbox, which will revert the property back to the default user Account.

 

Note: The above-described Submission Queue and User Account properties were added in ActiveBatch Version 12 SP7.  Prior to the introduction of these properties, reference objects could run on a different queue and/or run under a different user account when using the built-in objects named RuntimeQueue and RuntimeUserAcount. The use of these built-in objects (set on the target job) required additional configuration (other properties had to be set on the target and the reference) for this to work. This method is still supported for any jobs that may be set up this way. Going forward, if you would like a reference job to run on a different queue and/or under a different user account, set the Submission Queue and/or User Account properties described here. It is an easier and more efficient method. 

 

Next, additional property pages specific to the reference object are listed in the left-hand side navigation. These properties may be modified as appropriate. Note the “Variables” property page. This allows you to have different variable values (or methods) for the reference job which greatly expands the usefulness of the reference object. For example, assume the target job has a variable defined named “Var” with a constant value of “server1”.  A reference job pointing to the target job has a variable defined with the same name, but it has a constant value of “server2”.  When the target job is triggered, the variable will resolve to server1.  When the reference job is triggered, the variable will resolve to server2. This implies that subtle differences between the jobs (target vs. reference) can often be managed using variables. 

 

Remember that when you modify the target object that one or more references are pointing to, all objects referencing the target Job or Plan object will be impacted by the change. If you delete a reference, only the reference to the existing Job or Plan is removed. If you disable a reference, only the reference is disabled. If you disable the target object, only the target object is disabled.  If you set the “Global Disable” property located on the target job or plan’s General property sheet, the target will display the word “DISABLED” next to it in the Navigation pane.  This means that the target and all its references will not run if triggered. For example, on a manual trigger, you will see a message like the one depicted below.

 

 

Any properties not configurable on the reference object will not be present when creating the reference, and will be inherited from the job or plan the reference is pointing to.  For example, the Monitoring tab is not configurable on a reference object. This means monitoring, if enabled, will be inherited from the object the reference is pointing to.

 

All the other reference property sheets (Variables, Triggers, Constraints, Security, etc.) are the same properties described in the Job Object and Plan Object sections of the documentation.