Configuring scheduled builds

Scheduled builds allow you to automatically build your project's output targets at specified intervals and times of day. For example, you can configure your builds to run after a standard workday ends (to pick up all changes that your team made that day), or you can schedule your builds to run just before a product's installer builds (to ensure that the installer always picks up the latest documentation changes).

Note   The location(s) to which Jenkins publishes builds is typically defined by your authoring tool—not by the build configuration. To build a project, Jenkins clones a copy of your Git source code repository to one of its own workspace directories. After automatically updating its copy of the repository with the latest remote changes, the Jenkins job then runs your authoring tool to build and publish the appropriate output targets. When using the Flare authoring tool, you define where you want to publish builds by creating one or more publish destinations, and then assigning those destinations to a specific output target (in the target's properties). As a best practice, you should create a batch target (for example, named PublishAllTargets) that selects which targets you want to build and publish. When Jenkins builds the batch target, it automatically builds and publishes all targets enabled in the batch. You can also easily enable or disable specific targets, or change their publishing destinations from within Flare (that is, without needing to change the job's configuration).

To define a Jenkins job that builds your project on a recurring schedule

  1. If you are not already displaying the Jenkins dashboard in a browser, navigate to the Jenkins URL (for example, http://localhost:8080, if working on the Jenkins host computer), and then log in as the administrator user you created during installation.
  1. In the sidebar menu, click New Item.
  2. In the name box, enter a descriptive job name, such as MyProjectScheduledBuilds (substituting MyProject with the name of your project).
  3. In the item list, click Freestyle project, and then click OK.
  4. Continue configuring the remaining build job options, described separately in each of the following sections:

Configuring General options

Use the General options to describe your build job, indicate how long you want to keep old build logs, and add a Jenkins sidebar menu option for quickly accessing your GitHub repository.

To configure General options

  1. In the Description box, describe the operations performed by this job (for example, what targets are built and where they are published).
  2. Select Discard old builds.
  3. In the Days to keep builds box, enter the number of days of build logs that you want to retain (for example, 14).
  4. Select GitHub project.
  5. In the Project url box, enter the HTTP URL of the project's repository on GitHub (for example, https://github.com/MyAccount/MyRepository).

Tip   Defining the GitHub project option adds a GitHub link to the build's sidebar menu that allows you to easily navigate from Jenkins to your project on the GitHub site.

  1. Click Advanced, and then select Use custom workspace.

This option allows you to specify a custom directory where Jenkins builds your project. You will later reference this path when specifying the build log files that you want to validate for warnings or errors.

  1. In the Directory box, enter the path to a job-specific folder where you want to build this project (for example, C:\JenkinsWS\MyProjectName).

Configuring Source Code Management options

Use the Source Code Management options to configure Jenkins' access to your GitHub source code repository.

To configure Source Code Management options

  1. In the Source Code Management section, select Git.
  2. In the Repository URL, enter the SSH URL of your GitHub repository.

Tip   To find the URL, navigate to your repository page on the Git Hub site. In the Code drop-down list, click SSH, and then copy the URL that displays for your repository.

  1. In the Credentials section select the credentials you created earlier to access your GitHub repository.
  2. In the Branch Specifier box, set the branch to */main.
  3. In the Repository browser box, select githubweb.
  4. In the URL box, enter the HTTP URL of the project's repository on GitHub (this is the same URL you entered for the GitHub project in the previous procedure).

Configuring Build Triggers

Use the Build Triggers options to define when to perform target builds.

To configure Build Triggers

  1. In the Build Triggers section, select Build periodically.
  2. In the Schedule box, define a schedule that specifies how frequently you want Jenkins to build your project.

For information about the valid syntax for defining a build schedule, click the Help icon ().

As an example, here's a schedule that starts builds between 4 AM and 6 AM, Sunday through Saturday:

Copy 
TZ=America/Los_Angeles
H H(4-6) * * 0-6

Note   Providing a range (rather than an exact instant) for the job's start time allows Jenkins to select a time with fewer simultaneously running jobs for optimized performance.

Configuring a build step for your project

Use the Build section to define the command(s) needed to build your output targets. This section also allows you to define which ERRORLEVEL is used to mark unstable builds. An ERRORLEVEL (also known as an exit code) is an integer value returned by a process to indicate its outcome (for example, whether the process succeeded or experienced errors). An unstable build is a build of one or more targets that succeeds but that includes warnings or errors that could affect the generated target (in a Help system build, for example, an unstable build could include an output target with broken links or missing topic files).

Note   For descriptions of ERRORLEVEL values returned by the Flare command-line compiler, see ERRORLEVEL Global Variable. Some of the ERRORLEVEL values (displayed in red text) indicate build failures, while others (displayed in black text) indicate warnings.

Jenkins automatically marks builds that return an ERRORLEVEL of 0 as successful; by default, any other ERRORLEVEL value is marked as a build failure. Optionally, Jenkins allows you to configure a single ERRORLEVEL value to designate an unstable build. As a best practice, you should configure your build step to convert the ERRORLEVEL value for all warnings to the "unstable build" value, while letting other ERRORLEVEL values continue to flag build failures, as described in the procedure below.

Note   This procedure assumes that you are running on a Windows server, using Flare as an authoring tool, and that you have created a batch target in your Flare project to build and publish all appropriate output targets. If you are using a different authoring tool, change the build step to use commands and arguments appropriate for your tool.

To define a build step

  1. In the Add build step list, click Execute Windows batch command.
  2. In the Command box, enter the appropriate batch commands to build your output target and convert the ERRORLEVEL values that indicate warnings to a single value. For example:
Copy

Batch

REM For error code descriptions, see https://help.madcapsoftware.com/flare2021/Content/Flare/Step5-Building-Publishing-Output/Build-Options/Building-Targets-Using-Command-Line.htm#ERRORLEVELGlobalVariable
madbuild -project "%WORKSPACE%\MyProject\MyProject.flprj" -batch PublishAllTargets
IF %ERRORLEVEL% GTR 2 IF %ERRORLEVEL% LSS 10 SET ERRORLEVEL=3

Line 1 of the above command provides a remark that references where to obtain a description of Flare's ERRORLEVEL values.

Line 2 of the command then uses the madbuild command to build a batch target named PublishAllTargets, which is defined for the Flare project named MyProject.

Note    

  • The command uses the Jenkins %WORKSPACE% variable to reference the local directory in which Jenkins automatically clones the Git repository each time the build runs. The path following the %WORKSPACE% variable is the path within the repository to the Flare project. For more information about the arguments supported by Flare's madbuild executable, see Building Targets Using the Command Line. For more information about variables available for use in Jenkins build steps, click See the list of available environment variables underneath the Command box in Jenkins.
  • Assuming your batch target is set to publish your output target in Flare, then madbuild uses the same credentials that you defined for the publish destination in Flare to connect and write to the destination. If, for any reason, you need to use different credentials, you define additional arguments to can pass credentials to madbuild for use when publishing. For more information, see Passing Credentials in Madbuild (for Command Line Publishing).

Line 3 of the command then resets any ERRORLEVEL value greater than 2 and less than 10 to a value of 3 (indicating that the build was successful, but contains errors that could affect end-users). To designate the ERRORLEVEL value of 3 for indicating unstable builds in Jenkins, you must complete additional steps, as described below.

  1. Under the Command box, click Advanced.
  2. Set the ERRORLEVEL to set build unstable value to 3.
  3. Click Save.

You have now configured a scheduled build for your project. Rather than waiting for the build to run, you can manually start and troubleshoot the build.

Important   If you are automating builds for a Flare project that imports content from the common project, you must copy the import file that you created earlier (see Importing common project components) to the local copy of the project in the Jenkins workspace (in the path you defined in the Directory box). You can copy the import file from the Flare project on another computer (in Project\Imports\Common.flimpfl). Or, to make your build configuration more easy to maintain, you can store the import file in your Git repository (but outside of the Flare project folder) and then add another build step to your Jenkins job to automatically copy the import file into the project's Project\Imports folder prior to running madbuild. This allows you to make changes to the import file stored in the repository (from any writer's computer), and have those changes picked up by the automated builds—without needing to manually update your build environment.

Note   Currently, the scheduled build does not perform any validation. That is, when build errors or warnings occur, they are only displayed in the job's log files and the build outcome on the Jenkins dashboard. Later, we'll look at how to enhance your automated build job to notify writers when build warnings or errors occur.

Related Topics