Introduction
In this blog post I would like to show how logs and errors from a Project "Piper" pipeline can be sent to the SAP Alert Notification service for SAP BTP.
Pipelines are used in modern software development to automate development processes. Steps such as unit testing or the software build are carried out continuously and regularly provide an impression of the quality of the software. Problems are recognized quickly and can be fixed at an early stage.
In order to be able to use the results of a pipeline as well as possible, the information from the log data must be sent to the responsible persons as simply and clearly as possible. In our scenario, we would like to send our developers an email as soon as an error occurs in the software build. The SAP Alert Notification service for SAP BTP is suitable for this use case. It allows to receive event messages from different resources and the distribution to different channels and recipients. Once set up, this scenario can easily be expanded. In addition to e-mails, messages can also be sent to Microsoft Teams or Slack channels.
Requirements
To perform the following steps we need some requirements:
- A SAP Cloud Application Programming Model application
- SAP Continuous Integration and Delivery
- SAP Alert Notification service for SAP BTP
- Git repository (for example: GitHub)
Implementation
In this blog post we're going to set up a basic Node.js service using the SAP Cloud Application Programming model. On top of it we're building a pipeline with the Jenkins library provided by Project "Piper". We'll configure the steps MTA build and deployment to a cloud foundry space on the SAP BTP. Afterwards we connect the SAP Alert Notification service for SAP BTP with our created pipeline and send log data as an email for any occurring pipeline error.
Prepare CAP application
For this demo we need a basic application we can build and deploy to a SAP BTP Cloud Foundry Space. In our scenario I'll show how to create a basic Node.js service using the SAP Cloud Application Programming Model since this is one major cloud technology on the SAP BTP.
As development environment I recommend using the SAP Business Application Studio which is a fully web based Full Stack IDE preconfigured for many development tasks in the environment of the SAP BTP. In this blog post I assume that you've already created a Dev Space in the SAP Business Application Studio of type "Full Stack". Now I'll show you how to generate a new Node.js with the SAP Cloud Application Programming Model. Start by select the "Start from template" tile on the welcome screen.
Now we can select the type of application we like to generate. The SAP Business Application Studio offers many different templates to quick start your development. I can highly recommend to become familiar with the capabilities of the IDE. In our use case we select the option "CAP project".
You will be navigated to the following screen. Please select the following options and choose a name. Press "Finish" to generate the project.
This generates a project with the following structure:
There are three components I like to highlight because of there special role for this use case. First, the .pipeline directory with the config.yml file in it which are used to configure the different steps and stages of the Project "Piper" Jenkins library. The library will be imported using some lines of code in the Jenkinsfile. Finally, there is the mta.yaml which describes all components of this application and is used by the MTA build step to create a deployable *.mtar archive.
For validation let's test run our application. First, we need to install all dependencies by running the following command in the terminal of the SAP Business Application Studio.
npm installAfter the installation is finished we can start the service by running the command:
cds watchThis will open a popover in the bottom right corner to open the served route in a new tab:
Clicking the button "Open in a New Tab" will open the following page:
Setup SAP Continuous Integration and Delivery
Let's setup SAP Continuous Integration and Delivery which is a runtime for Project "Piper" pipelines as SaaS subscription on the SAP BTP. I assume that you're familiar with the SAP BTP account structure and that you already have setup a Subaccount with at least one Space and enabled Cloud Foundry environment.
On the left menu panel go to "Instances and subscriptions" and click on the "Create" button in the top right corner. This will open the following window:
Select the service "Continuous Integration & Delivery" from the dropdown list and choose a service plan. (e.g.: free, default or trail) - Press "Create" and wait until the service has been created. Afterwards you need to assign the needed roles and permissions. For more information on the initial setup look here.
Finishing the setup let's go into the application by navigating to "Instances and subscriptions" and clicking on "Go to application".
This opens the following screen. Please note that in my case there is already on demo project. Depending on your circumstances this list might be empty.
Create a new job
To finish the initial configuration we will create a pipeline job. Click on the create button and enter the following information. It's very important to select the correct pipeline type from the dropdown menu. In this case its "SAP Cloud Application Programming Model". Also be aware to create a git repository for your project and commit the changes to it.
In case your repository is not publicly available you have to create and add the corresponding credentials to the service. Click on the "Credentials" tab and enter your user name and personal git access token.
Now you can use these credentials to add an existing repository to the service. To create a repository go to the "Repositories" tab and click "Create". Afterwards you will see the following screen. Enter a name for the repository and paste the "Clone URL". Furthermore, you can select one of your credentials which should be used for authentication against e.g.: GitHub.
Click "Add" to finish. - After successfully creating your first job it's time to run your pipeline in order to validate everything is configured correctly. Since we haven't configured one of the Project "Piper" steps yet the pipeline will only run an initialisation. To start a new job click the button with tooltip "Trigger job". A new entry will appear.
Setup SAP Alert Notification service for SAP BTP
Like in the previous section of this blog post we need to create a service instance of the SAP Alert Notification service for SAP BTP before we can consume it. Please go back to the SAP BTP Cockpit and navigate to the Subaccount with SAP Continuous Integration and Delivery. Select "Instances and subscriptions" from the menu bar and click in top right corner on "Create".
Please select the service "Alert Notification" from the list. In case this service is not available in the list it's very likely that your Subaccount does not meet all requirements. Please see here for more information. Click "Create" to finish.
Copy the service key and save it a text file. We will need it in a following section.
Create a condition
A condition is an entity in SAP Alert Notification service for SAP BTP that represents under what condition one event is matched for delivery. You can create a condition by using the Conditions menu of the SAP Alert Notification service for SAP BTP view.
Enter a name for the condition. In our scenario we like to catch every Error event by our pipeline. Therefore the condition to check is if the severity Contains "ERROR". See also the configuration below and for more information you can also see the help page.
Define an action
It's our goal to inform our developers in a easy and convenient way about failures in the pipeline. An Action is an entity in SAP Alert Notification service for SAP BTP that represents where an event will be delivered. Therefore, we need to create an action which sends an email with the event information to a group of people.
In the left menu bar go to "Actions" and press "Create". This will open a wizard dialog where you can choose one of the available action types. For our case we select the first one "Email" and click "Next". Following we define a name for the action and give it an optional description. The last wizard step requires the email address of the recipients. Note, that the recipients will receive an email with a confirmation link. They have to click on this link in order to confirm that the email address is correct.
For more information see this help page.
Subscribe to pipeline events
A Subscription is an entity in SAP Alert Notification service for SAP BTP that combines actions and conditions, defining what actions are executed upon what events. Since we have already created a condition and an action it's time to combine them in a Subscription.
First enter a name for your subscription. It's best practice to choose something which references to your project name and pipeline and for more complex pipelines also the desired purpose.
Select the previously created condition.
Choose the previously defined action.
Click "Assign" to finish. Now check the created Subscription to confirm everything is correct.
Configure Pipeline
Currently there are two major CI infrastructures used in the environment of the SAP BTP:
- Jenkins
- SAP Continuous Integration and Delivery
Although, Project "Piper" supports Azure DevOps as CI infrastructure as well, this blog post will not cover this scenario for now. We will update this blog post in future. So stay tuned!
SAP Continuous Integration and Delivery
Setting up the integration of the SAP Alert Notification service for SAP BTP with our pipeline requires only a few steps using SAP Continuous Integration and Delivery. Go back to the overview of all your Jobs and select the one which we have just created. This will open the job detail page. In the top right click "edit" to enter edit mode an scroll down to the section "Build Notification" and turn on "Send Build Notifications via SAP Alert Notification Service".
The last thing we need to do is entering the service key we previously created and saved to a text file. Open the "Service Key" drop down menu and select "Create Credentials" to open the credentials wizard. Enter a name for the credentials and copy the json content of the SAP Alert Notification service for SAP BTP service key.
Jenkins Setup
The Jenkins setup of the SAP Alert Notification service for SAP BTP requires a few more steps. Instead of just configuring the Service Key using an UI we have to provide the configuration using a so called "Custom Defaults" configuration file. There are multiple ways how we can provide the custom defaults to our pipeline. In this case, I recommend to serve the file using GitHub and pointing to the location using the URL to the raw file.
Let's start by creating a new empty branch in our git repository. We name this branch "custom-defaults" and it will contain only the custom-defaults.yml file. To create the new empty branch use the following command in the terminal.
$ git checkout --orphan custom-defaultsNow we need to create a new file in the root directory of our project called custom-defaults.yml. Paste the following code into the file and save it.
hooks:
ans:
serviceKeyCredentialsId: 'alert_notification_key'Now make sure that only the custom-defaults.yml is staged in your staging area and commit this file before you perform a push to the remote repository. You will see a new branch on GitHub with only our configuration file.
Each file on GitHub can be reached via its raw url. Select the file on GitHub and will see a button "Raw" in the top right corner of the file section. Pressing it will open an new tab with the file and you can easily copy the url.
Following, please open the config.yml file inside the .pipeline directory and add the following code line on top of the general section.
customDefaults: ['https://<your-url-to-custom-defaults>/']The last step we have to perform is to add the service key for SAP Alert Notification service for SAP BTP as a credential key in Jenkins. Open Jenkins and select "Manage Jenkins" --> "Manage Credentials" and create new credentials. Credentials type is "Secret text" and the "Secret" is the json file copied from the service key. Please make sure that you enter the same ID as in the custom-defaults.yml for serviceKeyCredentialsId.
For further information on how to set up the configuration for Jenkins you can also have a look in Project "Piper" documentation.
Demo
Now it's time to check if our implementation really works. For this we need to create an error in our pipeline run. Since we only have the MTA Build step currently available we can manipulate the mta.yaml file in order to create an error on this step. Open the file and change the "path" value as follows:
path: gen/srv-wrong-pathYou can now test it by triggering a new build in the SAP Continuous Integration and Delivery service. It can take a few minutes but if everything is configured correctly you will receive an email by the SAP Alert Notification service for SAP BTP with all information regarding the error.
Summary
In this blog post we created a pipeline with the Jenkins library of Project "Piper" for a Node.js application build with the SAP Cloud Application Programming Model. I showed you how to setup SAP Continuous Integration and Delivery as well as the SAP Alert Notification service for SAP BTP. We configured the pipeline to send log data to the SAP Alert Notification service for SAP BTP and created a suitable subscription to distribute the log information as an email.
The scenario shown in this blog post is a very basic example how you can leverage the SAP Alert Notification service for SAP BTP in your Development process. You can easily integrate different channels and differentiate between recipients using multiple conditions and subscription. I am really curious about how you will use this new pipeline feature and the feedback you may have. Let's have a conversation in the comments!
You can also follow me for more blog posts about this and other topics of the SAP BTP and DevOps with Project "Piper". - I really recommend you to check the blog feed and the Q&A for the SAP BTP.
Links
Blog Feed for SAP BTP
Q&A section for SAP BTP
Documentation of Project "Piper"
GitHub repository of the Project "Piper" Jenkins Library
Setup SAP Alert Notification service for SAP BTP
Setup SAP Continuous Integration and Delivery
- SAP Managed Tags:
