Using macros with parameter values
Q100115: Using macros with parameter values
The JobServer.NET Management Application is the tool we use for creating, modifying, and all other aspects of managing the jobs that we create and rely upon on our JobServer services. When you use some of the built in tools on the management app, such as Globals and Connections, behind the scenes, you are making use of the built-in macro features in JobServer.NET. There are a number of built-in macros that are used by the management app directly, and when they are used in this fashion, you generally don't even see that this is happening and it is completely transparent to you. But an interesting thing about the macro features, are that they are also available for you to use as part of the values you provide for input parameters to the modules in your job definitions.
Types of macros
There are multiple types of macros that JobServer.NET uses and makes available for use within your job definitions. These are outlined in the following table with more specific details in the following sections.
| Macro Type | Appearance | Description |
|---|---|---|
| Connection | {{$connection.connectionName}} | Provides the value of the specified connectionName from the defined Connections. |
| Globals | {{::globalName}} | Provides the value of the specified globalName from the defined Globals. |
| Runtime | {{#macroName}} | Provides a value at runtime from internal functions and features in the running job. |
| Step Parameter | {{StepName.stepParamName}} | Provides a value at runtime from the specified parameter name in the specified step. |
| Job Parameter | {{$job.stepParamName}} | Provides a value at runtime from the specified local job parameter. |
Connection Macros
Connection macros are used internally by the management application when you use the user interface to assign defined connections to various input parameters in any number of modules. You don't really notice this, as the management application automatically can sense when the parameter is just the connection. When it does detect that the value of the parameter is a connection assignment, then it automatically displays the connection information. Assuming you have a SMTP connection defined with the name GeneralSMTPconnection. The definition of it might look something like this example.
When you use this connection in a module, such as [Email] Send Message, then you would see it appear in the step editor showing just the description of your defined SMTP connection as you see in this example.
The step editor in the management application makes the use of the connections simpler by providing the automatic lookup and assignment of the macro to the parameter value. Thus in normal usage, you do not actively need to know how to use connection macros at all, since the management application simplifies this for you. You can see that it works this way be manually entering in the connection macro into the input parameter. If you used the name of GeneralSMTPConnection as shown in the previous examples, you could enter the macro in the blank field and it would look like the following example.
When you save this step and then open it again, you will see that the step editor has recognized the connection macro you specified and now allows you to use the GUI features of the editor to modify the assignment of the connection.
Global Macros
Similarly to how we saw the connection macros used in the previous section, the global macros work in the exact same fashion for the Globals that you can define. When using the user interface in the Management Application, the behavior is nearly exactly as we saw before in that the assignment and use of the macros is transparent. But if you have occasion to use the Globals directly, the behavior is the same. A good example for trying this is again with the [Email] Send Message module. Create a new Global with the name EmailSignature. In this example below, the value for the global will be the text we want to include in our email signature.
In a job step using the [Email] Send Message module, add the macro for the global you just created to the end of the value in the Message parameter. You do this by typing in {{::EmailSignature}} and saving the changes. Now as long as you have already created that global with that same name, the text from the global will be inserted at the end of the message when the email step is executed in the job.
Runtime Macros
Runtime macros provide access to information or functionality within the JobServer environment while the job is running. This allows you to provide access to information that can be used by your job. An example might be to get the Day of the Week which you could provide as a value to pass through to a SQL Server statement you execute in a SQL database. This is common for various data processing and reporting jobs. A complete reference to all of the available runtime macros are available at the Runtime Macro Reference Article.
Using a runtime macro is very simple. An example might be that you want to include the name of the job in the email subject that your job sends out. To do this, you put whatever you want in the subject parameter in the [Email] Send Message module, then where you want the job name to appear, you would type in the macro {{#Job}}. Then when the job is run, the macro is automatically updated with the job name in the message. A nice benefit to using the macro this way, is if you later refine this job and change the name of it, then you don't have to remember to update the test in the email message subject. Since it is a macro, it will always use the current name as it is defined when the job runs.
Runtime macros can also be inserted into the parameter editor in the step editor by pressing Ctrl-3 while the cursor is in the parameter value field. This will bring up a list of available runtime macros that you can select to insert into the parameter value.
Step Parameter Macros
If you have used the JobServer Management Application to create a job, and as part of that job you used the output parameter from one step, as the value for an input parameter in a later step, then you have already been using step parameter macros. This is another case where the manager application will automatically detect the use of the step parameters and will provide the enhance user interface for selecting step parameter values.
Step parameter macros allow you to access the value of an output parameter from any specific previous steps. The format for the step parameter will be the step name followed by a period character ".", and then the name of the desired output parameter from the specified step. Therefore an example step parameter macro might be {{FindFiles.FileList}} which would get the value output by the FileList parameter in the FindFiles step.
Job Parameter Macros
Job parameter macros allow you to access the value of local job parameters that you have defined for your job. This is useful when you want to define a parameter that can be used in multiple steps within your job. The format for the job parameter macro is {{$job.parameterName}}, where parameterName is the name of the local job parameter you want to access.