This blog post is the second part of the series about our RealCore SAP CPI dashboard tool. It deals with the installation and configuration of the dashboard tool. You can find the first article, which is about the capabilities and features of the dashboard, over here:
Advanced monitoring and health check with RealCore’s CPI Dashboard
Before we start, let's have a quick look on the restrictions while installing and using the dashboard.
Restrictions
Since the Cloud Foundry (CF) variant of SAP CPI as of now doesn't send the WWW-Authenticate-header, the IFlow isn't usable via webbrowser. Thus the dashboard isn't supported on SAP CPI on CF environments for now because the dashboard's webinterface itself is delivered via an IFlow and thus need a webbrowser-friendly authentication method.
Installation
Since the complete dashboard and all its code is packed into one single Integration Flow (IFlow), the installation of the dashboard is done within minutes.
At first you should download the current release from our Github repository. You can find latest release here: https://github.com/codebude/cpi-dashboard/releases
Next you should open your SAP CPI tenant, switch to the Design-perspective and create/choose the package you want to place the monitoring IFlow into. Then edit the package, switch to the Artifacts-tab and click Add, to upload the beforehand downloaded SAP CPI Dashboard release.
That's it for the installation part. In the next section we will deal with the configuration.
Configuration
All things that need to be configured can be maintained via "Externalized Parameters". Thus, it is not necessary to make changes to the IFlow itself or its code. Some of the externalized parameters are used multiple times and therefore only need to be maintained once. So trust me - it's not that much to configure.
To start the configuration, we switch to the configuration perspective now.
Let's have a look onto the different parameters which have to be set...
Sender configuration
On the Sender-tab you will find one system with multiple adapters (since the IFlow has multiple endpoints), but you have to configure only one parameter, because it is used in all sender channels.
Parameter Name: DASHBOARD_URL_BASE
How to set: Set this parameter to an url-slug you personally prefer. It will be the base url of all endpoints of the IFlow.
Receiver configuration
On the Receiver-tab you will find three Receivers (SAP_CP = general Cloud Platform APIs, SAP_CPI = Cloud Platform Integration specific APIs, MAIL_SERVER = e-mail server to send out alerts) with 3 (SAP_CP), 7 (SAP_CPI) and 1 (MAIL_SERVER) channel. We will consider the different receiver systems separately.
Receiver - SAP_CP
All three SAP_CP receivers share the same configuration parameters. Thus you only have to do the configuration for one of the HTTP channels.
Parameter Name: SAP_CP_HOST
How to set: This must be set to the hostname of your SAP Cloud Platform API host. It is build like:
api.{regional hostname}The {regional hostname} depends on the region your Cloud Platform account sits in. A list of possible hostnames can be found here: https://help.sap.com/viewer/ed6ce7a29bdd42169f5f0d7868bce6eb/Cloud/en-US/0a7d8fb9bc2c4bbd9355146722a...
Parameter Name: SAP_CPI_TECHNICALNAME
How to set: This should be set to the technical name of your SAP CPI tenant. You will find the technical name in the Cloud Platform Cockpit via Region --> Global Account --> SAP CPI Subaccount.
At the bottom of the subaccount page you will find the technical name of your SAP CPI tenant.
Explanation: This credentials are used to query the authorization and management api to retireve a list of roles for the dashboard user/caller. The roles itself are needed to show/hide different functions of the dashboard.
Parameter Name: Credential Name/SAP_CP_AUTH_API_CREDENTIALS
How to set: Enter the name of the security material/credentials which contains the credentials for the SAP Cloud Platform Authorization Management API. Note: If you haven't used the Authorization Management API before, you have to create an account first. Create the OAuth credentials as described here and here. Then store the OAuth credentials in your SAP CPI's security material section and enter the name of the security material as the needed configuration parameter.
Receiver - SAP_CPI
In opposite to the SAP_CP receivers not all of the SAP_CPI receivers share the same configuration parameters. The channels can be divided in two groups. The first group is calling urls to "/itspaces/odata/..." and the second group to "/api/v1/...".
The screenshot below shows how you can differentiate the groups. Ensure that you configure at least one channel of each group from the screenshot.
Parameter Name (Group): SAP_CPI_HOST (Group 1)
How to set: Set this to the hostname of your SAP CPI tenant management node. Take the screenshot below for example.
Parameter Name (Group): Credential Name/SAP_CPI_AUTH_API_CREDENTIALS_BASICAUTH (Group 1)
How to set: Enter the name of the security material/credentials which contains user and password (S-User/technical S-User) of an account which has sufficient rights to access the SAP CPI tenant.
Explanation: This credentials are used to access some unofficial SAP CPI APIs (the ones which are used by the SAP CPI webinterface itself) to retrieve a list of runtime and designtime artifacts.
Parameter Name (Group): Credential Name/SAP_CPI_AUTH_API_CREDENTIALS_OAUTH (Group 2)
How to set: Enter the name of the security material/credentials which contains the OAuth credentials for the SAP CPI OData API.
Note: If you haven't used the SAP CPI OData API via OAuth before, you have to create a set of OAuth credentials first. Check this article which describes how to setup the credentials. (Basically it's the same like you did before for the Auth&Management API, but this time you use the "Clients"-tab instead of the "Platform API"-tab in the OAuth section of your CPI-subaccount.) When creating the credentials you need to assign at least the following two rules:
- NodeManager.read
- IntegrationOperationServer.read
Then store the OAuth credentials in your SAP CPI's security material section and enter the name of the security material as the needed configuration parameter.
Attention: Since Dashboard version 1.0.2 the credential has to be stored in a security material of type "OAuth2 Credentials"!
Explanation: This credentials are used to query the MessageProcessingLogs-resource (and more) of the SAP CPI OData API which is used to retrieve the message volume/counts.
Receiver - Mail Server
This part of the cofiguration is optional. You only have to configure this receiver, if you want to use the alerting feature of the RealCore CPI Dashboard.
If you want to use the dashboard's alerting engine, configure a valid mail server here. The dashboard will use it to send out alerting mails. If you don't want to use the alerting engine, you can fill out the configuration with dummy values.
More(-Configuration)
Congratulations, if you managed to get to this point - the hardest part of the configuration is done. On the "More"-tab you have to configure some more parameters.
Parameter Name: ALERT_MAIL_SENDER
How to set: If you plan to use the alerting engine of the dashboard, then you can set up the mail address here which should be shown as sender/origin of the alert mails.
Parameter Name: CACHE_DATASTORE_NAME
How to set: You can set this parameter to any value. It defines the name of the Datastore which is used by dashboard to cache the message count information. So ideally choose a name that is not yet in use as well as one that fits your naming conventions for datastores.
Parameter Name: CPU_USAGE_MESEASUREMENT_TIME_IN_MS
How to set: This values describes the measured interval for CPU utilization in milliseconds. (To measure the utilization of CPU the CPU time is read out twice. The higher the interval, the better the CPU usage results in dashboard. But on the same side - the higher the interval, the longer the dashboard loading time. Everything higher than 1000 should be fine.
Parameter Name: ROLE_GENERAL_ACCESS
How to set: Define the name of the role a dashboard user must have assigned to get access to the dashboard. When the IFlow is called it checks if the user has the role defined here. If not, it blocks access to the dashboard. If you want to work with your own rules, read this article of mine, which describes custom role handling.
Parameter Name: ROLE_LOG_AND_FILE_ACCESS
How to set: Define the name of the role a dashboard user must have assigned to view and download logfiles via the dashboard. When the IFlow is called it checks if the user has the role defined here. If not, it hides the logfiles section in the dashboard and blocks file download requests. If you want to work with your own rules, read this article of mine, which describes custom role handling.
Parameter Name: ROLE_SECURITY_MAT_ACCESS
How to set: Define the name of the role a dashboard user must have assigned to view security material/credentials. When the IFlow is called it checks if the user has the role defined here. If not, it hides the security material section in the dashboard and blocks manually executed calls to the secmat-service. If you want to work with your own rules, read this article of mine, which describes custom role handling.
Parameter Name:DIFF_REMOTE_CPI_TENANTS
How to set: This parameter is optional. You can enter connection data for multiple remote CPI tenants (separated by 😉 here. The tenants configured here will be used for the dashboard's IFlow comparison tool. Each remote system has to be entered in the format: <hostname of tenant>|<name of security material>
Example: If your remote tenant is available via "https://x0815-tmn.hci.eu1.hana.ondemand.com/itspaces" and you have created a security material containing an S-User with password in your current tenant named "CPI_x0815_CREDENTIALS" then you should enter the following into the DIFF_REMOTE_CPI_TENANTS field:
x0815-tmn.hci.eu1.hana.ondemand.com|CPI_x0815_CREDENTIALSIf you want to connect multiple remote tenants, just separate the tenant entries by use of a semicolon (;).
Timer(-Configuration)
If you plan to use the alerting engine, you can configure here how often the engine should check for errors. Regardless of the interval you configure, the engine will check the complete time interval since the last check. So by setting a larger interval in the timer, you just configure how often you will receive mails.
Deployment and Usage
Now that we have finalized the configuration, we have to deploy the IFlow. Either click on the Deploy-button from the configuration page or use the deploy option from the package view.
After the successful deployment, switch to the operations view of your SAP CPI tenant and go to the Manage Integration Content -> All-perspective. Search for the dashboard IFlow. From here you can find the dashboard's url. Copy the url and open it in a (modern) web browser.
Summary
Now we have reached the end of the second article. I hope you have successfully set up the RealCore Dashboard on your SAP CPI tenant. If there are problems or questions, just write a comment. I'm sure together we can figure out what went wrong.
- SAP Managed Tags:
107 Comments
