HPE Software is now Micro Focus
HPE Software is now Micro Focus
All About the Apps
cancel

How to leverage EUM Admin Open APIs

How to leverage EUM Admin Open APIs

Ajith_R

Cloud Master.PNG

 

 Hewlett Packard Enterprise APM End User Management monitors business applications from the end user point of view. It is used primarily for monitoring business applications from many locations, of varied type scripts. It is known for its availability, performance, usability and ability to further drilldown. Most of the key functionality involved in this process has have been exposed as Open APIs for the flexibility of the users. We shall go over the details in this article.

The EUM Administration Open API enables the user to perform operations on EUM configuration without using the End User Management Administration user interface in Business Service Management. The API supports retrieving, updating and creating Business Process Monitor and Real User Monitor configurations.

Supported entities include:

  • Business Application
  • Business Transaction Flow
  • Business Transaction
  • BPM Agent
  • Schedule
  • Script artifacts
  • Single URL
  • Web trace

The EUM Admin Open API is a RESTful Web service. It contains an integrated server side module that is compliant to JAX-RS v1.0 standard.

The EUM Open API is located at <HPBSM>\tools\EumOpenApiClient. The documentation is located at

 BSM Online Help -> Extensibility Guide -> End User Management -> EUM Admin Open API Reference

As well as <HPBSM>\AppServer\webapps\site.war\amdocs\eng\doc_lib\API_docs\EUM_API\EUM_Administration_API.htm

 There are two possible approaches to work with EUM Admin Open API:

  1. Directly invoke the resources.
  2. Use the java client provided.

In this blog, I am going to give examples of using both the approaches. As an example I will use below flow to demonstrate the API usage:

  1. Display the list of applications existing in BSM (GET Method)
  2. Create new folder in script repository (POST Method)
  3. Upload new script into the folder created in step b(POST Method)
  4. Create an application with the script uploaded in step c(POST Method)
  5. Assign Data collector to the created Application (PUT Method)

 

  1. Directly invoke the resources

For this approach, we have exposed REST APIs, which can be called directly in the browser (GET method) or by using browser add-on like REST Client or by any programming Languages. Running REST in a browser add-on is pretty straight forward and because of this, I will skip the description.

Since Python has been requested by many customers in my interactions as the choice of programming language, I will use the Python script here to demonstrate on how to call REST APIs. You need to import the below modules which help in calling the REST API and parsing the xml respectively.

import requests

import xml.etree.ElementTree as ET

 

If the ‘requests’ module is not already downloaded, use the command below to download it.

C:\Python\Scripts>pip install requests

 

NOTE: If any API is executed successfully, it always returns status code as 200.

 

a. Display the list of applications exists in BSM (GET Method)

Code:

url = http://< BSM > /topaz/eumopenapi/bpm/application'
r = requests.get(url, auth=('<user_name>', '<password>'))
if r.status_code == 200:
	print "Get application successful"
	clientResp = r.text
	root = ET.fromstring(clientResp)
	for application in root.findall('bpm_application'):
		name = application.find('name').text
		print "Name: "+name
else:
	print "Get application failed"

 

b. Create new folder in script repository (POST Method)

You can refer to the XSD reference section to create request payload for any APIs. For this API, the XSD schema is CreateSrFolderRequestBean. Below is the schema definition:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xs:schema version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema">
    <xs:element name="request_data" type="createSrFolderRequestBean"/>
    <xs:complexType name="createSrFolderRequestBean">
        <xs:sequence>
            <xs:element name="folder_name" type="xs:string"/>
            <xs:element name="parent_folder_id" type="xs:long"/>
        </xs:sequence>
    </xs:complexType>
</xs:schema>

By using above schema definition we can create the request payload as below:

<request_data>
	<folder_name>OpenAPI</folder_name>
	<parent_folder_id>0</parent_folder_id>
</request_data>

Code:

url = 'http://<BSM>/topaz/eumopenapi/sr/folder'
data='<request_data>\
		<folder_name>OpenAPI</folder_name>\
		<parent_folder_id>0</parent_folder_id>\
	</request_data>'
r = requests.post(url, data=data, headers={'content-type': 'application/xml'}, auth=('<user_name>', '<password>'))
if r.status_code == 200:
	print "SR Folder created Successful"
	clientResp = r.text
	root = ET.fromstring(clientResp)
	folder_id = root.find('folder_id').text
	print folder_id
else:
	print "SR Folder creation Failed"

 

c. Upload the new script into the folder you created in step b (POST Method)

Code:

with open("C:\VugenScripts\TC_Web_FF_avail.zip", "rb") as scriptFile:
	f = scriptFile.read()
	b = bytearray(f)
url = "http://<BSM>/topaz/eumopenapi/sr/script/upload?script_name=TC_Web_FF_avail&parent_folder_id="+ str(folder_id)
r = requests.post(url,data=b,headers={'content-type': 'application/octet-stream'},auth=('<user_name>', '<password>'))
if r.status_code == 200:
	print "Script Uploaded Successful"
	clientResp = r.text
	root = ET.fromstring(clientResp)
	script_id = root.find('script_id').text
	print script_id
else:
	print "Script Upload Failed"

 

d. Create an application with the script that was uploaded in step c (POST Method)

Code:

url = 'http://<BSM>/topaz/eumopenapi/bpm/application'
data = '<?xml version="1.0" encoding="utf-8"?>\
	<request_data>\
	<name>OpenAPITest</name>\
	<description>Open API testing</description>\
	<active>true</active>\
	<profile_db_id>1</profile_db_id>\
	<time_zone_id>Asia/Calcutta</time_zone_id>\
	<license_id>BPM_TX_ANY_LOCATION</license_id>\
	<default_ok_threshold>8.0</default_ok_threshold>\
	<default_critical_threshold>12.0</default_critical_threshold>\
	<default_outlier_threshold>45.0</default_outlier_threshold>\
	<default_availability_threshold>90.0</default_availability_threshold>\
	<ignore_outlier_values>true</ignore_outlier_values>\
	<transaction_breakdown>\
	<enable_breakdown>true</enable_breakdown>\
	<report_additional_error_information>true</report_additional_error_information>\
	<perform_component_breakdown>true</perform_component_breakdown>\
	<enable_diag_tv_breakdown>false</enable_diag_tv_breakdown>\
	<enable_siebel_breakdown>false</enable_siebel_breakdown>\
	<enable_soa_breakdown>false</enable_soa_breakdown>\
	</transaction_breakdown>\
	<scripts>\
	   <script_id>'+str(script_id)+'</script_id>\
	</scripts>\
	</request_data>'

r = requests.post(url,data=data,headers={'content-type': 'application/xml'},auth=('<user_name>', '<password>'))
if r.status_code == 200:
	print "Application created Successful"
	clientResp = r.text
	root = ET.fromstring(clientResp)
	appci_id = root.find('ci_id').text
	name = root.find('name').text
	print "Application CI ID: "+ appci_id
	print "Application Name: "+ name	
else:
	print "Application creation Failed"

 

e. Assign Data collector to the created Application (PUT Method)

This operation can be achieved with 2 API calls:

e.1 Get the agent_id from the list of agents: In this example, we are getting the agent id from the combination of hostname (India_host) and location (Bangalore_loc)

Code:

agent_id = -1
hostName = 'India_host'
locationName = 'Bangalore_loc'
url = 'http://<BSM>/topaz/eumopenapi/bpm/agent'
r = requests.get(url, auth=('<user_name>', '<password>'))
if r.status_code == 200:
	print "Get agents REST API Successful"
	print "Searching agent id for the hostname "+hostName+" and location "+locationName
	clientResp = r.text
	root = ET.fromstring(clientResp)
	for agent in root.findall('bpm_agent'):
		host_name = agent.find('host_name').text
		location = agent.find('location').text
		if(host_name == hostName and locationName == location):
			agent_id = agent.find('agent_id').text
			print "Agent id found : "+agent_id
			break
	if agent_id == -1:
		print "Couldn't find the agent id"
		
else:
	print "Get agents REST API Failed"

 

e.2 Pass retrieved agent_id to assign data collector API

Code:

url = 'http://<BSM>/topaz/eumopenapi/bpm/agent/assign/application?app_ci_id='+appci_id

data = '<?xml version="1.0" encoding="utf-8"?>\
	<request_data>\
		<agent_id>'+str(agent_id)+'</agent_id>\
		<schedules>\
			<schedule>\
				<frequency>5</frequency>\
				<frequency_in_minutes>true</frequency_in_minutes>\
				<from_day_of_week>1</from_day_of_week>\
				<to_day_of_week>7</to_day_of_week>\
				<frequency_from_hours>0</frequency_from_hours>\
				<frequency_from_minutes>0</frequency_from_minutes>\
				<frequency_to_hours>23</frequency_to_hours>\
				<frequency_to_minutes>59</frequency_to_minutes>\
				<timezone_hours_offset>2</timezone_hours_offset>\
				<timezone_minutes_offset>0</timezone_minutes_offset>\
				<frequency_offset>1</frequency_offset>\
			</schedule>\
		</schedules>\
		<advanced_setting>\
			<run_mode>Classic</run_mode>\
			<timeout>900</timeout>\
		</advanced_setting>\
	</request_data>'
r = requests.put(url,data=data,headers={'content-type': 'application/xml'},auth=('<user_name>', '<password>'))
if r.status_code == 200:
	print "Agent assigned Successfully"
else:
	print "Agent assign Failed"

 

2. Use the java client provided

To use the client provided:

  • Add the jar files to the classpath. They are under directory <APM installation>\tools\EumOpenApiClient\lib.
  • Create a java class with a main method.
  • Create an instance of the EumOpenApiClient class:
    EumOpenApiClient client = new EumOpenApiClient(<APM URL>, <user name>, <user password>));
    The APM URL format is: <protocol>://<host>/topaz
  • If APM is configured for SSL, import the certificate to the JRE and to the browser.

Below is the sample program for all of the 5 flows.

First create an instance of the EumOpenApiClient class as below and use eumOpenApiClient object for API call.

EumOpenApiClient eumOpenApiClient = new EumOpenApiClient("http://<BSM>/topaz/", "<user_name>", "<password>");

 

 

a. Display the list of applications that exists in BSM (GET Method)

//a. Get all the applications
Collection<BpmApplicationBean> bpmApplications = eumOpenApiClient.getBpmApplications();
for (BpmApplicationBean app : bpmApplications)  {
    System.out.println("Application CI ID=" + app.getCiId() + " Application name=" + app.getName());
}

 

 

b. Create a new folder in the script repository (POST Method)

//b. Create new folder in script repository
SrFolderBean srFolderBean = eumOpenApiClient.createFolderInScriptRepository("OpenAPI", 0L);
System.out.println("Folder created successfully, Folder ID: "+srFolderBean.getFolderId());

 

 

c. Upload new script into the folder created in step b (POST Method)

//c. Upload new script into the folder created in above step
File scriptFile = new File("C:\\scripts\\VugenScripts\\", "TC_Web_FF_avail.zip");
SrScriptBean srScriptBean = eumOpenApiClient.uploadScriptToScriptRepository(scriptFile, srFolderBean.getFolderId());
System.out.println("Script uploaded successfully, Script ID: "+srScriptBean.getScriptId());

 

 

d. Create an application with the script uploaded in step c (POST Method)

//d. Create an application with the script uploaded above
CreateBpmApplicationRequestBean requestBean = new CreateBpmApplicationRequestBean();
requestBean.setName("Open_API_Test");
requestBean.setDescription("Open API Test");
requestBean.setActive(true);
requestBean.setLicenseId(EumLicenseTypeEnum.BPM_TX_ANY_LOCATION);
requestBean.setProfileDbId(1L);
requestBean.setTimeZoneId("Asia/Calcutta");
requestBean.setDefaultOkThreshold(8.0);
requestBean.setDefaultCriticalThreshold(12.0);
requestBean.setDefaultOutlierThreshold(45.0);
requestBean.setDefaultAvailabilityThreshold(90.0);
requestBean.setIgnoreOutlierValues(true);
requestBean.setEnableBreakdown(true);
requestBean.setReportAdditionalErrorInformation(true);
requestBean.setPerformComponentBreakdown(false);
requestBean.setEnableDiagTvBreakdown(false);
requestBean.setEnableSiebelBreakdown(false);
requestBean.setEnableSoaBreakdown(false);
requestBean.addScriptId(srScriptBean.getScriptId());
BpmApplicationBean bpmApplicationBean = eumOpenApiClient.createBpmApplication(requestBean);
String appId = bpmApplicationBean.getCiId();
System.out.println("Application created successfully");
System.out.println("Application name: " + bpmApplicationBean.getName() + " Application CI Id: "+appId);

 

 

e. Assign a Data collector to the created Application (PUT Method)

//e.1 Get the agent_id from the list of agents
Long agent_id = -1L;
String hostName = "iwfvm01639";
String locationName = "vwagtest";
System.out.println("Searching agent id for the hostname "+hostName+" and location "+locationName);
Collection<BpmAgentBean> beans =  eumOpenApiClient.getBpmAgents();
Iterator it = beans.iterator();
while(it.hasNext()){
    BpmAgentBean agentBean = (BpmAgentBean) it.next();
    if(hostName.equals(agentBean.getHostName()) && locationName.equals(agentBean.getLocation())){
        agent_id = agentBean.getAgentId();
        System.out.println("Agent id found "+agent_id);
    }
}
if(agent_id == -1){
    System.out.println("Couldn't find the agent id");
}
//e.2 Assign Datacollector
AssignBpmAgentRequestBean assignBpmAgentRequestBean = new AssignBpmAgentRequestBean();
Collection<AssignBpmAgentRequestBean.Schedule> schedules = new ArrayList<AssignBpmAgentRequestBean.Schedule>();
AssignBpmAgentRequestBean.Schedule schedule = new AssignBpmAgentRequestBean.Schedule();
schedule.setFrequency(5L);
schedule.setFrequencyInMinutes(true);
schedule.setFromDayOfWeek(1L);
schedule.setToDayOfWeek(7L);
schedule.setFrequencyFromHours(0);
schedule.setFrequencyFromMinutes(0);
schedule.setFrequencyToHours(23);
schedule.setFrequencyToMinutes(59);
schedule.setTimezoneHoursOffset(2);
schedule.setTimezoneMinutesOffset(0);
schedule.setFrequencyOffset(0);
schedules.add(schedule);

AssignBpmAgentRequestBean.AdvancedSetting advancedSettings = new AssignBpmAgentRequestBean.AdvancedSetting();
advancedSettings.setRunMode(AdvancedSettingRunModeEnum.CLASSIC);
advancedSettings.setTimeout(900);

assignBpmAgentRequestBean.setAgentId(agent_id);
assignBpmAgentRequestBean.setSchedules(schedules);
assignBpmAgentRequestBean.setAdvancedSettings(advancedSettings);
eumOpenApiClient.assignBpmAgentToApplication(appId, assignBpmAgentRequestBean);
System.out.println("Data collector assigned successfully");

 

 

Log details

If the API fails unexpectedly, you can check the logs for more information on why it failed. You can find the log file in the below path:

C:\HPBSM\log\jboss-as-all.log – BSM 9.26 onwards

C:\HPBSM\log \topaz_all.ejb – Older BSM versions

If you give the wrong username or password for authentication, you will see below error in the log file:

2017-04-03 15:48:00,991 [ajp-/127.0.0.1:8009-8] (UserImpl.java:142) WARNING - Authentication process failed (AuthenticationException): Unable to find the user in the database (user login='xyzadmin').

com.mercury.topaz.tmc.bizprocess.user.UserUnknownException: Unable to find the user in the database (user login='xyzadmin').

2017-04-03 15:48:01,628 [ajp-/127.0.0.1:8009-8] (BACLoginAuthenticator.java:42) DEBUG - BAC login authentication falied. Failed to authenticate the given user credentials due to a thrown exception (details are available in debug mode).

2017-04-03 15:48:01,630 [ajp-/127.0.0.1:8009-8] (BACLoginAuthenticator.java:52) ERROR - Failed to release user TBP for user login xyzadmin.

  • Application Performance mgnt
About the Author

Ajith_R