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 Execution Methods shortcut from the Shortcut Bar.

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:

1. Add a new execution method by clicking on the Add Button from the Control Bar.
    
2. In the dialog window, specify a unique name, enter a description (optional), and select a Base Method. In this example we will be using the Command Execution Method. Selecting "Ok" with the Edit After Adding option enabled will open the properties after creating for further modification.
   
3. A Job Module can be tied to the newly created execution method by navigating to the Properties tab and entering the name of the template library that will be used within the Job Module field located within the Source section. We will be creating a new one later in this example called CustomParsed. Notice the default file extension can also be altered.
   
4. Save and Close Execution Method editor window.

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:

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 user's 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.

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.