How to Create a Custom Parsed Execution Method

Follow

Creating a custom execution method can be very helpful in customizing how JAMS runs jobs. It is possible to utilize a technology which JAMS does not interface with out of the box, or modify an existing execution method to add, or customize functionality. In this guide, we will copy an existing execution method and modify how it runs jobs.

Users can find a list of the JAMS execution methods by selecting the Configuration tab, and then clicking on the Execution Methods icon.

For this example, we will be copying the Parsed Windows Command procedure to a new execution method and adding some custom functionality.

 

First, we need to create a new execution method in JAMS. We can add a new execution method by clicking on the Add icon in the above dialog. This will start the JAMS Execution Method Definition Wizard. In the wizard, we must specify a unique name. Also, we can enter a description of the new method.

 

Next, we must specify an Execution Type. We will be selecting Command.

 

The new execution method will now be added to the execution method list. We can now edit the new definition further. Open the definition and select the Source tab. In Job Module field, enter the name of the template library which will be used. We will be creating a new one later in this example called CustomParsed. Also, enter cmd as the Default File Extension.

 

Now, select the Execution tab. In the Command field, enter “cmd.exe /c "{0}"”.

 

There are other properties which may be needed for other execution methods. A full list of the available execution method properties, and descriptions of the properties can be found here.

Now that we have created a new entry in JAMS for our custom execution method, we need to create a new Job Module in the BaseMacros.xml file. This file provides JAMS with a template for parsing a Job’s command procedure. To add a new entry to the file, open the BaseMacros.xml file which is located in C:\Program Files\MVPSI\JAMS\Scheduler\BaseMacros.xml

Since we are adding functionality to an existing execution method, we can copy the existing macro for Parsed jobs. This is the first Macro entry in the file.

 

<Macro name="Parsed"> 
 <Code> 
   <![CDATA[REM JAMS Parsed Macro <%Symbol(JAMS.Parameters)%> 
   <<JAMS.Source>> 
   exit %errorlevel% ]]> 
 </Code> 
</Macro>

 


Copy and paste this code back into the BaseMacros.xml file, inside of the <ArrayOfMacro> tags. We will now change the macro to provide our custom functionality. First, we need to change the name of the macro to match the execution method’s Job Module property. In this example, it is “CustomParsed”. Next, we can begin changing the macro. When a job executes, the code contained within the “<Code><![CDATA[“ tags will be evaluated by JAMS, and then sent to where the execution method properties specify.

JAMS can retrieve data from the job currently executing. This data is then used to execute the job. Data is contained within the <<>> tags. JAMS can also evaluate and insert other macros, which are contained in the <%%> tags.

In this example code, the JAMS.Parameters collection, and the JAMS.Source property are being referenced. The objects users can retrieve data from are as follows:

Folder

The Job or Setup’s JAMS Folder

Setup

Only accessible when running a Setup

Job

Only accessible when running a Job

SetupJob

Only accessible when running a Setup

Current

The CurJob object

Node

A NodeInfo object

Source

The Source property provided by the Job

NotifyEMail

The final list of email addresses to be notified. This is a combination of e-mail addresses from the DefaultNotifyEmail config setting, System, Setup, and Job notify lists.

 

Users can reference any of the above objects starting by starting with “JAMS.”. So, if we want to retrieve a description of the System this job is running under, we would use <<JAMS.System.Description>> in our macro. It is possible to access any public property from any of the above objects. If one of the above objects are not specified, the Current object is inserted. So, in the macro source, <<JAMS.JobName>> and <<JAMS.Current.JobName>> would evaluate to the same value.

Parameters and variable values can also be accessed. If users do not start out the reference with “JAMS.”, the value of a Parameter or JAMS variable will be used instead, if one is found. So, if a users job specifies a parameter named “FileLocation”, the user can access the value from the macro by using “<<FileLocation>>”.

It is also possible to add formatting to a value. For example, we could use <<JAMS.Current.StartTime(”d”)>> to format the StartTime of the Current job in a Short Date pattern. Any format supported by the .NET String.Format method can be used. A listing of these formats can be found here: http://msdn.microsoft.com/en-us/library/fbxft59x.aspx

Macro tags will insert another macro from within the BaseMacros.xml file. They can be used with any object which supports the IEnumerable interface. In this example, the Symbol macro is used.

<%Symbol(JAMS.Parameters)%>

It will be inserted once for each of the JAMS.Parameters which are retrieved from the job at execution time. The Symbol macro is as follows:

 

<Macro name="Symbol"> 
 <Code> 
   <![CDATA[SET <<NAME>>=<<VALUE>> ]]> 
  </Code> 
</Macro>

 

Once inside of a sub macro, users can access the properties of the current object within the enumeration by specifying the property name within angle brackets. So, for each parameter in the JAMS.Current.Parameters collection, the Symbol macro is inserted. Then, the values of the NAME and VALUE properties are retrieved and inserted into the SET line.

When the default Parsed macro is executed, it looks similar to this:

C:\Windows\system32>REM JAMS Parsed Macro

C:\Windows\system32>SET Param1=Value1

C:\Windows\system32>SET Param2=Value1

C:\Windows\system32>REM Source of Job inserted here

C:\Windows\system32>exit 0

 

Now that we have an understanding of how the parsing works, we can modify the default to add some custom functionality. We will be adding a couple of lines to the beginning of the job execution to better log what job is being executed. Make the highlighted changes to the CustomParsed macro we pasted into the BaseMacros.xml file.

 

<Macro name="CustomParsed"> 
 <Code> 
   <![CDATA[REM JAMS Custom Parsed Macro 
   REM Job Name: <<JAMS.Current.JobName>> 
   REM Job Description: <<JAMS.Job.Description>> 
   REM Running under System: <<JAMS.Folder.FolderName>> 
   <%Symbol(JAMS.Parameters)%> 
   <<JAMS.Source>> 
   exit %errorlevel% ]]> 
 </Code> 
</Macro>

 

Now, save the BaseMacros.xml file. In order for the new macro to be used, the JAMSScheduler service must be restarted. This must be done every time a change is made to the BaseMacros.xml file, or the changes will not take effect when job runs. This can be done in Windows PowerShell using the command Restart-Service JAMSScheduler.

Once the service has restarted, users can create a new job to test the execution method we just made, or change the execution method of an existing job. This property can be found in the Source Options tab of a job definition.

 

 

Note: If users do not see the CustomParsed Execution method in the dialog, users may need to hit the Refresh button in order for the newly created method to appear.

Now, submit the job and view the resulting log file when the job completes. Users can now see that the additional information we inserted in the BaseMacros.xml file has been parsed, and the additional logging comments have been displayed successfully.

Have more questions? Submit a request

Comments