KBEC-00167 - Referencing workspaces in the email notifier formatting template

Summary

This article discusses the following:

• How to refer to a full platform-independent workspace path
• Where the workspace reference belongs in a notifier template and why

Background

• Workspaces are defined at the step level.
• Every step has exactly one workspace.
• You can refer to the workspace, in a step context, as /myWorkspace.
• A job has one or more workspaces (because each step can have a different workspace).
• There is no such thing as “the job’s workspace” because there can be more than one. This is why you cannot expand /myWorkspace in a job context.
• A Job Notifier expands in a job context.
• A Step Notifier expands in a step context.

FAQ

Q: If there is one workspace per step, why does my getJobDetails output have only one workspace for the whole job?
A: It is because getJobDetails aggregates all the workspaces used within that job. If all the steps in your job use the same workspace, then only one shows up.

Solution

1. Create a step notifier. If you use the same workspace for all steps, you can add this notifier to the last step. Or you can add a dummy, “Always Run” step at the end and tie the notifier to it.

2. Make sure this step is running using the workspace that you want to show. To reference files in the workspace that you want use the syntax:
   $\[/myWorkspace/agentUncPath\]/$\[/myJob/directoryName\]
   For example, to create a property with the first step’s log file in the property value on a Linux agent that can be referenced in a notifier use:

   ectool setProperty /myJob/logFileText --valueFile "$[/myWorkspace/agentUnixPath]/$[/myJob/directoryName]/$[/myParent/jobSteps/step1/logFileName]"
   

3. To create a URL using a HTML reference to a file foo.txt in the artifacts directory of the job in an email notifier use the syntax:

   <td class="success">
   https://$[/server/hostName/]/commander/jobs/$[/myJob/jobId]/$[/myJobStep/workspaceName]/foo.txt
   </td>