Working with Freestyle Job

In this guide, you'll learn how to create your very first Jenkins project using the Freestyle Job option. We will walk you through creating a new job, configuring it with various options, and adding a shell script that fetches advice from a REST API. The script then validates the output and uses the cowsay library to display the advice as creative ASCII artwork.

Creating the Jenkins Project

Begin by logging in to your Jenkins instance and navigating to the dashboard. Click on “New Item” (or the plus icon) to create a new job. You will be prompted to enter a name for your project and choose the type of job. The available options depend on the plugins installed on your Jenkins server. For this tutorial, select the Freestyle Project and name it “generate ASCII artwork.”

Configuring the Job

After selecting the Freestyle Project, you will see several configuration sections:

• General
• Source Control Management (SCM)
• Build Triggers
• Build Environment
• Build Steps
• Post-build Actions

Under the General section, add the following description:

"Generate ASCII artwork using the cowsay library and the AdviceSlip REST API."

You can leave the Source Code Management as “none” (unless you would like to connect a GitHub repository) and skip adding automated build triggers. In the Build Environment section, consider enabling the "Add timestamps to the console output" option—this feature is provided by the Timestamp Plugin.

Adding the Build Steps

Within the Build Steps section, add a new build step by selecting the shell script execution option. Depending on your environment, you can choose either a Windows batch command or a shell script. In this example, we are using shell commands.

Below is the complete shell script added as a build step. This script performs the following operations:

1. Fetches advice from the AdviceSlip REST API and saves it as a JSON file.
2. Uses the jq tool to extract the advice text and verifies if it contains more than five words.
3. Installs the cowsay library if it is not already installed.
4. Updates the PATH variable so that Jenkins can locate the cowsay command.
5. Pipes the advice text through cowsay to generate the ASCII artwork output.

# Call the AdviceSlip API and save output as JSON
curl -s https://api.adviceslip.com/advice > advice.json
cat advice.json | jq -r '.slip.advice' > advice.message

# Ensure the advice has more than 5 words
[ $(wc -w < advice.message) -gt 5 ] && echo "Advice has more than 5 words" || (echo "Advice - $(cat advice.message) has 5 words or less")

# Install cowsay (if not already installed) and generate ASCII artwork
sudo apt-get install cowsay -y
echo $PATH
export PATH="$PATH:/usr/games:/usr/local/games"
cat advice.message | cowsay -f $(ls /usr/share/cowsay/cows | shuf -n 1)

Understanding the Shell Script

When the build is triggered, the following steps occur:

1. The script uses curl to fetch a piece of advice from the API, saving the JSON output to advice.json. A typical JSON response looks like this:

   {
     "slip": {
       "id": 135,
       "advice": "If you want to be happily married, marry a happy person."
     }
   }
   

2. The jq command extracts the advice (.slip.advice) from the JSON file and stores it in advice.message.

3. A word count check is performed on the extracted advice. If the advice contains more than five words, a confirmation message is printed; otherwise, an error message is output, potentially marking the build as failed.

4. The script installs the cowsay library using apt-get (if it is not already installed) and updates the PATH variable to include directories where the cowsay command is located. This update is necessary because the Jenkins environment might not include /usr/games or /usr/local/games in its PATH.

5. Finally, the advice is piped through cowsay, which randomly selects a cow file from /usr/share/cowsay/cows (using shuf) to generate ASCII artwork in the Jenkins console output.

Build Execution and Diagnostics

Once you save the configuration, the project dashboard will display the project description, build status, and workspace details. The workspace is created under the Jenkins home directory, storing any generated files like advice.json and advice.message.

Click “Build Now” to trigger the build. The build progress can be monitored in real time, and selecting the build number provides detailed logs, including the user who started the build, build duration, and console output with timestamps.

In the event of a build failure, you might encounter console output similar to the example below:

+ cat advice.message
+ ls /usr/share/cowsay/cows
+ shuf -n 1
+ cowsay -f unipony-smaller.cow
/tmp/jenkins...: 14: cowsay: not found
Build step 'Execute shell' marked build as failure
Finished: FAILURE

This error indicates that the cowsay command was not found. The solution is to update the PATH variable inside your job configuration (as shown in the script above) or configure the global environment variables in Jenkins to include the required directories.

Reviewing the Workspace

After a successful build, the workspace will include the generated files (advice.json and advice.message). These files can be reviewed on the Jenkins workspace page or accessed directly via SSH/terminal on the Jenkins server. Below is an example of a sample advice.json:

{
  "slip": {
    "id": 148,
    "advice": "Some people would be better off if they took their own advice."
  }
}

Summary

In this article, you learned how to set up a Jenkins Freestyle Job that:

• Fetches dynamic data from a REST API.
• Processes JSON data using the jq tool.
• Validates the advice message to ensure it meets a minimum word count.
• Installs and utilizes the cowsay library to render the advice as ASCII artwork.

By understanding each step—from job creation and build configuration to troubleshooting environment variables—you can apply these practices to various Jenkins projects and build pipelines.

For more in-depth knowledge, consider exploring the Jenkins Documentation.

Thank you for reading our guide on working with Freestyle jobs in Jenkins.