Downloading and customizing validation script files

While manually checking the Jenkins dashboard is useful for determining build status, it's more efficient to have the build system immediately notify authors whenever a build fails or becomes unstable as the result of a recent check-in. This allows authors to quickly resolve any problems that they accidentally introduce to a project. To implement build validation, we've provided a template build validation script that you can use in your environment. The script consists of these components:

• ValidateBuilds.ps1 - This is the Windows PowerShell script that performs validation operations. Prior to using this script in your environment, you must edit the script and update the values of some system-defined constants (as described in the procedure below).
• buildConfiguration.json - This JSON file is used to customize build validation for each project that you add to your repository. The configuration file defines the email addresses to which notifications are sent (in the event of build warnings or errors), the build output files that are checked to verify publication, and the build log files that are searched for warnings or errors. Configuring and using this file is also described in the procedure below.
• ValidateBuilds.cmd - This is a batch file that runs the ValidateBuilds.ps1 script. This script doesn't require any customization; you'll use the script in Jenkins jobs to start build validation operations.

To download and customize the script component files

1. Click Download Scripts to download a Zip file containing the script component files.
2. Extract the script contents to a folder in your Git repository (such as a JenkinsScripts folder).

Prior to using the downloaded script files, you must customize the files for your environment as described in the sections below:

• Customizing the ValidationBuilds.ps1 script
• Customizing the buildConfiguration.json file

Customizing the ValidationBuilds.ps1 script

The ValidationBuilds.ps1 PowerShell script includes some constant values that must be customized for your environment, prior to script execution.

To customize the script

1. Using an editor such as Visual Studio Code, open the script and scroll down to the following region:

37
38
39
40
41
42
43
#region **Customize these constants before using this script**
$buildManagerEmail = "admin@yourCompany.com" #The email address to which to send critical build notifications.
$scriptLogFile = "C:\yourLogFiles\" + $ProjectsToValidate[0] + ".log" #The log file for this script.
$smtpServer = "mail.yourdomain.com" #The SMTP server used to email warning and error notifications.
$senderEmail = "no_reply@yourCompany.com" #The address from which email notifications are sent
$zipDirectory = "C:\Temp" #The temporary directory where the Zip file is created
#endregion

2. On line 38, change admin@yourCompany.com to your email address (or a system administrator at your facility). This is the address to which the job sends error messages that indicate problems with the Jenkins job or build script itself (that is, problems that are typically not a result of author commits to the repository).
3. On line 39, change the C:\yourLogFiles\ portion of the $scriptLogFile path to the folder where you want to save the script's log file output. The log file is automatically saved with the name of the project it is validating and has a .log extension. (The script logs messages to this log file to assist you in troubleshooting any build-related issues; note that these same messages are also logged to the Jenkins build log when it executes this script. For information about reviewing the Jenkins build log, see Troubleshooting Jenkins builds.
4. On line 40, change mail.yourdomain.com to an SMTP server at your site that the script can use to send email notifications. (You might need to check with your IT department to find an available SMTP server and ensure that your host machine is authorized to send email messages using the server.)

Important   The script includes a very basic SMTP server configuration that sends unencrypted messages without authentication on the default server port (25). If your SMTP server uses SSL, requires credentials, and/or uses a custom port, then you'll need to modify the Send-MailMessage commands throughout the script to include the required arguments. For more information, see Send-MailMessage.

5. On line 41, change no_reply@yourCompany.com to the email address from which email notifications are sent.

Tip   If you want authors who receive build notifications to be able to reply to you directly, you can change this value to your email address (or another administrator). Alternatively, using the address no_reply is a cue to authors who receive email build notifications that the email was generated by an automated system and that they cannot reply to the messages directly.

6. On line 42, change C:\Temp to a directory on your host machine where the build script creates a temporary Zip file containing authoring tool build logs that contain warnings or errors. The script automatically emails this Zip file to the appropriate writers, so that they can review the log files and resolve the warnings or errors encountered during target builds.
7. Save your changes.
8. As a best practice, review the rest of the script file and its comments to understand all operations performed by the script. When you're satisfied with the script operations, close the script file.

You're now ready to customize the build configuration file.

Customizing the buildConfiguration.json file

The buildConfiguration.json file defines project-specific values that are unique to your environment. Each time you add a new Flare project to the automated builds, you must customize this file to reflect your changes.

To customize the build configuration file

1. Using an editor such as Visual Studio Code, open the configuration file and scroll to the first project configuration:

4
5
6
7
8
9
10
11
12
13
14
"name": "MyProject1",
            "configuration": {
                "recipientEmailAddresses": [
                    "emailUser1@myCompany.com",
                    "emailUser2@myCompany.com"
                ],
                "flareLogs": [
                    "absolutePathToLog1",
                    "absolutePathToLog2"
                ]
            }

2. On line 4, change MyProject1 to the name of a Flare project that you want to build and validate. This value must match the value of the $ProjectsToValidate argument that your Jenkins job passes to the ValidationBuilds.ps1 script when performing build validation. As a best practice, use the same name as the Flare project file whose builds you want to validate; you can omit the project's .flprj file extension.

Note   Each of the remaining project configuration options (that is, recipientEmailAddresses and flareLogs) are defined as JSON arrays. JSON arrays are defined as a list of comma-separated array elements nested within square brackets ([ ]). You can reduce the number of arrayed elements to a single entry (for example, to only notify one email address of build warnings or errors) by deleting the comma after the first arrayed element, and then deleting the second element from the array. Alternatively, you can increase the number of arrayed elements (for example, to notify more than two email addresses of build warnings or errors) by appending a comma to the end of the second arrayed element, and then adding an additional line (and appended comma) for each additional element you want to add. Be sure to omit a comma after the last array element.

3. On lines 7-8, define the email addresses of the authors to whom you want to send build validation notifications for this project. These are the authors who are checking in project source files changes (and consequently, who could be responsible for introducing build warnings or errors).

4. On lines 11-12, define the absolute path of each .mclog file that the authoring tool generates for targets that it builds. The build script automatically parses these log files to check for warnings or errors that occur during the project build. If either are found, the script packages the appropriate log files and includes them in the email notification for authors to use for troubleshooting build issues related to their recent commits.

Note   When building an output target, Flare writes build log files to the following path: JenkinsWorkspacePath\GitRepository\ProjectPath\Output\BuildUserName\TargetPath\TargetName.mclog where:

• JenkinsWorkspacePath is the path of the Jenkins workspace that you defined for the build job.
• GitRepository is the name of the repository you defined on the GitHub site.
• ProjectPath is the relative path (in the Git repository) to the directory containing the Flare project file (that is, the .flprj file).
• BuildUserName is the name of the user account that Jenkins uses to build projects.
• TargetPath is the relative path within the Flare project, from the Targets folder to this target. If there are no folders (for example, all targets are defined within the Flare project's Targets folder itself), then this value is omitted.
• TargetName.mclog is the name of the Flare log file generated for this target build.

Tip   You can ensure that you add the correct path to the file by building the project within Jenkins and then navigating to each generated .mclog file on the build computer. Then, enter the full path of the log file for each target to the flareLogs array in the buildConfiguration.json file.

You have now fully configured validation for this project.

Note   The ValidationBuilds.ps1 script parses Flare .mclog files by looking for the XML elements <Warnings> and <Errors> within the log file. If you are using a different authoring tool, you'll need to customize the script to parse the log file generated by your tool.

5. Repeat this procedure to configure validation for all projects for which you have configured automated builds at your facility.

Now that you've customized the build validation configuration, you're ready to add build validation to an existing job.