Technical Articles
Automate it! An overview on SAP PI/PO APIs
ome time ago I read in the comments under a SAP blog that it is a pity that SAP PI/PO has many administrative/management APIs, but these are not documented. If these APIs were known, there would be new use cases and maybe new, great tools from the community would arise.
I thought about how I could contribute my share to the community. What I cannot do is officially release and document APIs. This decision is up to SAP. But what I can do, however, is document the APIs that “came my way” during my years as an SAP PI/PO consultant.
Disclaimer: The following list does not claim to be complete, but only documents my findings. It is not meant to be an official documentation. Usage of this APIs, which may change, is done at your own risk. That said, If you know of any other APIs, have additional information or tips and tricks – just write a comment. Your input is appreciated!
List of SAP PI/PO management APIs
The following table gives a quick overview of the APIs shown in this article.
# | Name | Description |
1 | Directory API(s) | A set of SOAP APIs to read and change Integration Builder/Directory objects e.g. read communication channel settings or change value mappings. |
2 | SimpleQuery | A simple HTTP/HTML based “webservice” which gives read-only access to Enterprise Service Repository (ESR) and Integration Builder (IB). Can be used to read message mappings and other ESR objects. |
3 | HMI Servlet API(s) | A set of XML-based webservices which are used by NWDS. Can be used to read/manipulate SAP PI/PO content. |
4 | Transport Service APIs | Two APIs to receive information about SAP PI/PO transports and their contents. |
5 | Channel Ping-API | A XML-based webservice that allows to trigger the Ping functionality of a given communication channel. |
6 | Channel Statuslog-API | A HTML-based “webservice” that allows to read communication channel logs as shown in SAP PI’s communication channel monitor. |
7 | Channel Status Servlet | A simple XML-based webservice that allows to read a communication channel’s status as well as giving you the chance to start/stop a channel. |
8 | CCMS/SAP Control-API | This SOAP-API offers a huge list of SAP PI management api including possibilities to run OS commands or start/stop/restart PI nodes. |
9 | Message Monitor Overview-Servlet | This XML-based webservice returns a XML file containing the summarized values from message monitoring overview. |
10 | Performance Data-Servlet | This XML-based webservice returns a XML document containing the performance overview data from SAP PI’s message performance monitor. |
11 | NWA Status Overview-API | This XML-based webservice returns the Java stack system status. (It contains the same values that are rendered in the system status overview rendering in the NWA.) |
12 | CPA- & Mapping Runtime-Cache | This “API” allows to manage the CPA and Mapping cache. (It’s not really an API, but more an automation-friendly website.) |
13 | WSDL Generator | This webservice allows you to generate WSDL files for SOAP interfaces in difference facettes. |
14 | SOAP Endpoint Registry API | This XML-based service lists all SOAP endpoints and WSDL urls for the configured interfaces in Integration Builder. The service follows the WSIL standard and acts as “meta API”. |
15 | Service Registry API | This XML-based service lists all registered at the PI registered services (like the Directory API, etc.). The service follows the WSIL standard and acts as “meta API”. |
16 | Operation Mapping Test API | This API enables the caller to run Operation Mappings (+ Message Mappings) via API and get back the result of the mapping as API response. |
Let’s have a close look into the APIs now…
[1] Directory API(s)
State of API: Officially documented
Technology: SOAP/XML
Authentication/Requirements: Basic Authentication (via HTTP header). User has to have the following roles: SAP_XI_API_DISPLAY_J2EE, SAP_XI_API_DEVELOP_J2EE
Service-/Base-Url: http(s)://<host>:<port>/<ServiceName>InService/<ServiceName>ImplBean
How to use: The APIs are regular SOAP webservices. Since there is a huge amount of services (one for Communication Channels, one for ServiceInterfaces, one for …) the best way is to start in the Webservice Navigator (open via http(s)://<host>:<port>/wsnavigator), then choose “Provider System” an click on search to get a complete list of the Directory APIs. (If the WSNavigator isn’t available, activate it as described in SAP-Note 2602277)
If you prepend the custom url with “?wsdl” (like http(s)://<host>:<port>/IntegratedConfigurationInService/IntegratedConfigurationInImplBean?wsdl) you receive an WSDL which can be imported into SoapUI for further testing or which can be used for developing an API client in your favourite programming language.
Documentation/Read more:
- Official documentation: https://help.sap.com/viewer/d0a0a7cb51dc40529bfcac724dd05796/7.3.20/en-US/48d127e1e1c60783e10000000a42189d.html
- Tutorial on SAP Blogs: https://blogs.sap.com/2017/11/07/sap-pipo-directory-api-extract-detailed-communication-channel-configurations-into-an-excel-sheet-without-custom-codesmacros/
[2] Simple Query
If you are wondering why you should use Simple Query at all, when you have to parse HTML and build HTTP requests with a lot of effort, let me tell you this: Some of the PI objects, especially the repository content, are (or were – more about this in the HMI Servlet section) only accessible via Simple Query. So it is not unlikely that you can retrieve certain elements only via the Simple Query. Thus the question about the effort does not arise anymore…
State of API: Not officially documented
Technology: (Plain)HTTP/HTML (partly XML)
Authentication/Requirements: Basic Authentication (via HTTP header).
Service-/Base-Url:
- Repository objects: http(s)://<host>:<port>/rep/support/SimpleQuery
- Directory objects: http(s)://<host>:<port>/dir/support/SimpleQuery
How to use: Since this isn’t a standardized api there is now best way to do it. Thus I describe in quick steps how I would do it. Start with opening one of the base urls (e.g. http(s)://<host>:<port>/rep/support/SimpleQuery) in your webbrowser (I prefer Chrome). Then build the query by selecting the target object type, pressing “Refresh dependent values” and selecting the columns/information via the webpage. Next press “Start query” to get the results on the webpage. Check the results table if the query serves the results you were searching for.
If your are happy with your query, press F12 in your browser (or open the “dev tools” via your browser’s menu), step to the “Network” tab, press “Start Query” again and check the request in the network tab.
In the network tab you will find all information that was sent to the PI/PO system to get the result information. Analyze the request headers, the formdata and general information (as shown in the screenshot above.) Now it’s your turn. Write (with whatever toolset or programming language) an application that is able to “replay” the exact same request and you will be able to use the Simple Query “API”.
Tip: If you need some help with coding the request, you can right click the request in the network tab and let Chrome browser generate some sample code for you (which you might use as a beginning/entry point for your application).
If you were able to rebuild/imitate the request in your self-build api client, the next step is to parse the results. Since this is a webpage, you will find all information in the HTML document returned. You could either use a HTML parsing library to get the information out of the response or – if you have the “nerd chromosome” – write some regular expressions. (I usually use regex101.com to test my regular expressions. If you don’t know it, check it out.)
Documentation/Read more:
- Official documentation: Does not exist
- Tutorial on SAP Blogs/Wiki: https://wiki.scn.sap.com/wiki/display/XI/Access+SAP+PI+objects+simply+with+SimpleQuery
[3] HMI Servlet
The HMI servlet is a Java servlet running on SAP PO, which provides a set of HTTP and XML-based apis. (It’s no a classic SOAP service, but just a HTTP endpoint which accepts and responds with XML documents.) The HMI servlet is heavily used by the NWDS. If your PI system is so old that it doesn’t support NWDS or doesn’t support some things in NWDS yet, you won’t have much fun with this system even with the HMI Servlet API.In terms of content, the HMI servlet is similar to the Simple Query, because unlike the Directory API, the HMI servlet can provide not only directory, but also repository objects (and even more).
In short words: Everything what you are able to do with NWDS, can be automated by use of the underlying APIs.
State of API: Not officially documented
Technology: (Plain)HTTP/XML
Authentication/Requirements: Basic Authentication (via HTTP header).
Service-/Base-Url: http(s)://<host>:<port>/dir/hmi_<servlet-name>/int?container=any
(The <servlet-name>-tokens can be figured out by sniffing with a web debugging proxy as described in the next paragraph.)
How to use: Since I could not find any documentation for these APIs and they are not official ones, I will not show step by step how to use them. Instead, I will explain to you how and with which tools you can learn and use the methods of the API yourself. Whether and how you use the API in the end lies in your responsibility.
The key in mastering this API is reverse engineering. So your best bet is to set up an environment which allows you to trace the HTTP(s) communication between the NWDS and the target PO system. The analyze the requests exchanged (like we did for the Simple Query one paragraph above) and rebuild them in your favorite programming environment/language.
Since sniffing Eclipse/NWDS requests can be hard, some steps/hints for setting up such reverse engineering environment:
- Get a good web debugging proxy like Fiddler (Download here)
- Activate SSL decryption in Fiddler’s settings
- Export the SSL root certificate from Fiddler’s SSL settings page, import it into an JKS (Java Key Store) and attach this JKS to the JVM which runs your NWDS. Check this tutorial: https://westerndevs.com/capture-https-traffic-in-java-with-eclipse-and-fiddler/
- Open NWDS and manually do the actions you want to automate. At the same time sniff/capture with Fiddler. Then rebuild the requests, captured with Fiddler.
If you managed to set up everything correctly, you should get results in Fiddle similar to the ones shown in the next screenshot.
As shown in the screenshot most requests to the HMI servlets are POST requests. So you have to setup fitting XML request messages and sent them via POST to the PO. The tabs “Headers” and “Textview” in Fiddler may help you to find out how the XML messages should be structured and which headers you should add to your request.
If you are more in reading code or decompiling, you could check the “com.sap.tc.resource.repository_*.jar” and “com.sap.tc.directory.repository_*.jar” files on your PO system…
Documentation/Read more:
- Official documentation: Does not exist
- Tutorial on SAP Blogs: I’m not aware of any. If you know a tutorial, post the link in the comments.
[4] Transport Service APIs
Both APIs are used by NWDS and could be counted to the HMI Servlet APIs described in the last paragraph. Nevertheless I like to list them separately because transports a topic of interest and in opposite to other HMI Servlet APIs (e.g. the one for receiving communication channel data) these transport api reside only in the HMI Servlet. So it’s worth highlighting them.
State of API: Not officially documented
Technology: (Plain)HTTP/XML
Authentication/Requirements: Basic Authentication (via HTTP header).
Service-/Base-Url:
- Repository transports: http(s)://<host>:<port>/rep/transportservice/int?container=any
- Directory objects: http(s)://<host>:<port>/dir/hmi_iflow_transport_service_log/int?container=any
How to use: Since there are more detailed tutorials (linked below), I’ll give just a short introduction on how to retrieve a list of transports ids for repository objects. Start with setting up a HTTP POST request (either in a test tool like Postman, SoapUI or in your favorite programming language). Add the Authorization header with Basic Auth to the request and provide credentials for the target PI system. Point the POST request to http(s)://<host>:<port>/rep/transportservice/int?container=any
Use the following XML as body for the POST request you just set up.
<?xml version="1.0" encoding="UTF-8" ?>
<instance typeid="com.sap.aii.util.hmi.core.msg.HmiRequest"><attribute isleave="true" leave_typeid="string" name="ClientId"><value index="0" isnull="false">1baff32c440311e89289025041000001</value></attribute><attribute isleave="true" leave_typeid="string" name="ClientLanguage"><value index="0" isnull="false">EN</value></attribute><attribute isleave="false" name="ClientLevel"><value index="0" isnull="false"><instance typeid="com.sap.aii.util.applcomp.ApplCompLevel"><attribute isleave="true" leave_typeid="string" name="Release"><value index="0" isnull="false">7.50</value></attribute><attribute isleave="true" leave_typeid="string" name="SupportPackage"><value index="0" isnull="false">10</value></attribute></instance></value></attribute><attribute isleave="true" leave_typeid="string" name="ClientPassword"><value index="0" isnull="false">dummy</value></attribute><attribute isleave="true" leave_typeid="string" name="ClientUser"><value index="0" isnull="false">dummy</value></attribute><attribute isleave="true" leave_typeid="string" name="ControlFlag"><value index="0" isnull="false">0</value></attribute><attribute isleave="true" leave_typeid="string" name="HmiSpecVersion"><value index="0" isnull="false">1.0</value></attribute><attribute isleave="true" leave_typeid="string" name="MethodId"><value index="0" isnull="false">read_transport_log</value></attribute><attribute isleave="false" name="MethodInput"><value index="0" isnull="false"><instance typeid="com.sap.aii.util.hmi.api.HmiMethodInput"><attribute isleave="false" name="Parameters"><value index="0" isnull="false"><instance typeid="com.sap.aii.util.hmi.core.gdi2.EntryStringString"><attribute isleave="true" leave_typeid="string" name="Key"><value index="0" isnull="false">p_from_date</value></attribute><attribute isleave="true" leave_typeid="string" name="Value"><value index="0" isnull="false">{{fromTimestamp}}</value></attribute></instance></value><value index="1" isnull="false"><instance typeid="com.sap.aii.util.hmi.core.gdi2.EntryStringString"><attribute isleave="true" leave_typeid="string" name="Key"><value index="0" isnull="false">p_to_date</value></attribute><attribute isleave="true" leave_typeid="string" name="Value"><value index="0" isnull="false">{{toTimestamp}}</value></attribute></instance></value><value index="2" isnull="false"><instance typeid="com.sap.aii.util.hmi.core.gdi2.EntryStringString"><attribute isleave="true" leave_typeid="string" name="Key"><value index="0" isnull="false">p_direction</value></attribute><attribute isleave="true" leave_typeid="string" name="Value"><value index="0" isnull="false">{{direction}}</value></attribute></instance></value></attribute></instance></value></attribute><attribute isleave="true" leave_typeid="string" name="RequestId"><value index="0" isnull="false">1baff32d440311e8b10e025041000001</value></attribute><attribute isleave="true" leave_typeid="string" name="RequiresSession"><value index="0" isnull="false">true</value></attribute><attribute isleave="true" leave_typeid="string" name="ServerApplicationId"><value index="0" isnull="false">{{piHostName}}</value></attribute><attribute isleave="true" leave_typeid="string" name="ServerLogicalSystemName"><value index="0" isnull="true"></value></attribute><attribute isleave="true" leave_typeid="string" name="ServiceId"><value index="0" isnull="false">transportservice</value></attribute></instance>
Keep attention to the following two things:
- Don’t add linebreaks or whitespaces to the XML above. (Yes, readibility is bad, but adding linebreaks will make the API call fail.)
- Replace the following four tokens inside the XML before posting it to the PI system:
- {{fromTimestamp}} – earliest time from which transport ids should be returned by the API (as unix timestamp in milliseconds)
- {{toTimestamp}} – latest time from which transport ids should be returned by the API (as unix timestamp in milliseconds)
- {{direction}} – either “export” or “import”, depending on what you want – a list of imported or exported transports
- {{piHostName}} – hostname of the PI system you are pointing the request to. (Attention: Only the hostname. No protocol, port or path information!)
The just send out your post request. If you’ve done everything right, your should receive a list of transport ids (as long as there were transports made during the interval you gave with fromTimestamp and toTimestamp.)
For a more detailed “how to use” and a description how to retrieve directory transport information, please check the tutorials linked below.
Documentation/Read more:
- Official documentation: Does not exist
- Tutorial on SAP Blogs:
[5] Channel Ping-API
State of API: Not officially documented
Technology: (Plain)HTTP/XML
Authentication/Requirements: Basic Authentication (via HTTP header).
Service-/Base-Url: http(s)://<host>:<port>/remoteapi/channelselftest?channel=<communication channel name>&service=<communication channel service/component>&party=<communication channel party>
How to use: Simply take the service url from above and insert a channels object name, service and party into the placeholder. (If the channel has no party, just provide an empty value for the party parameter like: &party=) Then call the url via HTTP GET request and you will receive a XML-based response with all the information you usually will see in SAP PI’s communication channel monitor when pressing the “Ping” button.
Documentation/Read more:
- Official documentation: Does not exist
- Tutorial on SAP Blogs: I’m not aware of any. If you know a tutorial, post the link in the comments.
[6] Channel Statuslog-API
As shown in the screenshot on the right-hand side you can see that the api returns only the persisted logs, not the memory logs. So you will retrieve only the errornous entries via this api. (If you found out how to retrieve the memory logs, too, let me know in the comments.)
The major difference to the channel ping api is, that the statuslog doesn’t return a xml document, but a html document. (But since HTML is following the XML syntax and I know that you’re all good coders, I guess parsing the response shouldn’t be a problem for you.)
State of API: Not officially documented
Technology: (Plain)HTTP/HTML
Authentication/Requirements: Basic Authentication (via HTTP header).
Service-/Base-Url: http(s)://<host>:<port>/remoteapi/getstatuslogs?channelName=<communication channel name>&service=<communication channel service/component>&party=<communication channel party>&adapterType=<type of adapter>
How to use: The handling of this api is similiar to the handling of the channel ping api. Take the service url as shown in the paragraph above and insert a channel’s object name, service, party and channel type into the placeholder. (If the channel has no party, just provide an empty value for the party parameter like: &party=). Then call the url via HTTP GET request and you will receive a XML-based response with all the information you usually will see in SAP PI’s communication channel monitor when pressing the “Ping” button.
Documentation/Read more:
- Official documentation: Does not exist
- Tutorial on SAP Blogs: I’m not aware of any. If you know a tutorial, post the link in the comments.
[7] Channel Status Servlet
Note: The Channel Status Servlet displays only a limited number of logs. For a more detailed log overview, use the Channel Status Log API. The strength of the Servlet lies in its ability to display channel status and control channels.
State of API: Officially documented
Technology: (Plain)HTTP/XML
Authentication/Requirements: Basic Authentication (via HTTP header).
Service-/Base-Url: http(s)://<host>:<port>/AdapterFramework/ChannelAdminServlet?party=*&service=*&channel=*SOAP*&action=status
How to use: To use the api either call it via HTTP GET or POST method. The api itself is controlled via url parameters. The following table explains the different parameters.
Name | Occurence | Default | How to fill |
party | required | n/a | Can be used to filter for party. * can be used as wildcard. |
service | required | n/a | Can be used to filter for communication component. * can be used as wildcard. |
channel | required | n/a | Can be used to filter for channel names. * can be used as wildcard. |
action | required | n/a | Controls how api behaves. Possible values: status, start, stop |
status | optional | all | Allows to filter for channels of a specific state. (Should be used in combination with action=status and any party/service/channel combination.) Possible values: all, ok, error, stopped, inactive, unknown, unregistered |
showProcessLog | optional | false | When action=status, this controls if last processing log entries are provided. Possible values: true, false |
showAdminHistory | optional | false | When action=status, this controls if the admin history (=who has stopped, started, etc. a channel) is provided, too. Possible values: true, false |
So to list all channels on a SAP PI system with status failed, you have to call the following url:
http(s)://<host>:<port>/AdapterFramework/ChannelAdminServlet?party=*&service=*&channel=*&action=status&status=error
If you want to stop the channel |BS_MySystem|CC_SND_FILE_Filepicker you have to call the following url:
http(s)://<host>:<port>/AdapterFramework/ChannelAdminServlet?party=*&service=BS_MySystem&channel=CC_SND_FILE_Filepicker&action=stop
Note: To start or stop channels, the corresponding channel has to be in “External” control mode. You have to set the control mode to external in the communication channel monitor first!
Keep in mind that changing a channel to “External” control mode breaks the automatic channel scheduling. You can either use external mode an control the channels via api or use automatic mode an make use of the communication channel scheduler. Both at the same time isn’t possible.
Documentation/Read more:
- Official documentation: https://help.sap.com/viewer/0158596e99ae4f7386f5c302d343368c/7.5.7/en-US/4ba2862d182b63a3e10000000a42189c.html
- Tutorial on SAP Blogs: https://blogs.sap.com/2016/04/25/handle-communication-channel-externally/
[8] CCMS/SAP Control-API
Since many of the methods/actions of the SAP Control Service are system-near or even have effects on operating system level, an Operating System User (OS User) is sometimes required.
Via the SAP Control API, various things can be done, such as starting/stopping the entire system, listing Java processes, creating and importing system snapshots, and much more.
State of API: Officially documented
Technology: SOAP/XML
Authentication/Requirements: Basic Authentication (via HTTP header).
Service-/Base-Url: http://<host>:50<instace id>13?wsdl or https://<host>:50<instace id>14?wsdl
How to use: Since the SAP Control API is a classic SOAP web service, the API can be used with any SOAP client or programming language that supports HTTP or SOAP services.
For a first insight and to familiarize yourself with the API, it is worthwhile to import the above WSDL-Url into SoapUI and evaluate the individual methods. The different services sometimes require different users/roles. (For example, retrieving the Java processes works with a regular user with sufficient permissions, whereas other methods require an OS user) The individual roles can be taken from the documentation linked below.
Attention: Some services have an impact on the availability of the system (e.g. the shutdown method). Please use these services only in consultation with the respective system owner!
The service supports the following methods:
Name/Operation | Description (taken from the service’s WSDL) |
ABAPAcknowledgeAlerts | Acknowledge CCMS Alerts in the SAP ABAP system. Requires SAP user credentials and a list of alert ids to acknowledge. Returns a list of success code for each alerts (1=success, 0=failure). |
ABAPCheckRFCDestinations | Returns a list of single point of failure RFC destination definitions. |
ABAPGetComponentList | Returns a list of installed ABAP components in the system as defined in CVERS database table. |
ABAPGetSystemWPTable | Returns a list of all or all active ABAP workprocesses in the system (similar to sm66 transaction). |
ABAPGetWPTable | Returns a list of the ABAP workprocesses (similar to sm50 transaction). |
ABAPReadRawSyslog | Reads the SAP ABAP Syslog and returns it as an array of raw entries (similar to sm21 transaction). |
ABAPReadSyslog | Reads the SAP ABAP Syslog and returns it as an array of entries (similar to sm21 transaction). |
AccessCheck | Checks execute permission of webservice function. |
AnalyseLogFiles | Service definition of function SAPControl__AnalyseLogFiles |
Bootstrap | Executes bootstrap of actual or other instance of the system, webservice restarts after return. |
CheckPSE | compares an existing PSE in instance SECUDIR directory against given PSE and returns mode if PSEs match. |
CheckParameter | Returns profile parameter details and check results. |
CheckUpdateSystem | Checks prerequisites for executing UpdateSystem. |
ConfigureLogFileList | Configures a list of logfiles accessable via ReadLogFile (Hostagent mode only). |
CreatePSECredential | stores a credential/pin for an existing PSE in instance SECUDIR directory in cred_v2 files in SECUDUR directory. |
CreateSnapshot | Creates a zipped instance snapshot on the server side. |
DeletePSE | deletes a PSE from instance SECUDIR directory. |
DeleteSnapshots | Deletes snapshot(s) on the server side. |
EnqGetLockTable | Returns enque locking table. |
EnqGetStatistic | Returns enque statistic. |
EnqRemoveLocks | Removes locks from enque locking table. |
EnqRemoveUserLocks | Removes all locks of given user from enque locking table. |
GWCancelConnections | Cancels given gateway connections |
GWDeleteClients | Deletes given gateway clients |
GWDeleteConnections | Deletes given gateway connections |
GWGetClientList | Returns a list of gateway clients |
GWGetConnectionList | Returns a list of gateway connections |
GetAccessPointList | Returns a list of instance network access points. |
GetAlertTree | Returns CCMS Alert tree as an array, parent-child node relationship is encoded via the parent index of each node (similar to rz20 transaction). |
GetAlerts | Returns a list of all CCMS alerts for a given node and it’s child nodes. |
GetCallstack | Returns callstack of all threads of specified process. |
GetEnvironment | Returns the process environment as an array of strings. |
GetInstanceProperties | Returns a list of available instance features and information how to get it. |
GetLogFileList | Returns a list of configured logfiles accessable via ReadLogFile (Hostagent mode only). |
GetNetworkId | Returns a unique network ID for a given service. |
GetProcessList | Returns a list of all processes directly started by the webservice according to the SAP start profile. |
GetProcessParameter | Returns actual Profile Parameters for a given process. |
GetQueueStatistic | Returns a list of queue information of work processes and icm (similar to dpmon). |
GetSecNetworkId | Returns a unique network ID and verification proof for a given service. |
GetStartProfile | Returns start profile name and content as array of lines. |
GetSystemInstanceList | Returns a list of SAP instances of the SAP system. |
GetSystemUpdateList | Returns a list of instances restarting by ongoing UpdateSystem execution. |
GetTraceFile | Returns webservice trace file name and content as array of lines. |
GetVersionInfo | Returns a list version information for the most important files of the instance |
HACheckConfig | Checks high availability configurration and status of the system. |
HACheckFailoverConfig | Checks HA failover third party configuration and status of an instnace. |
HACheckMaintenanceMode | Check if HA maintenance mode is available for all instances or single instance of the system. |
HAFailoverToNode | Moves instance to given HA cluster node. |
HAGetFailoverConfig | Returns HA failover third party information. |
HASetMaintenanceMode | Enables or disables HA maintenance mode of all instances or single instance of the system. |
ICMGetCacheEntries | Returns a list of objects cached by ICM. |
ICMGetConnectionList | Returns a list of incoming network connections handled by ICM. |
ICMGetProxyConnectionList | Returns a list of outgoing network proxy connections handled by ICM. |
ICMGetThreadList | Returns a list of threads used by ICM. |
InstanceStart | Triggers a start of another instance of the system and returns immediately. |
InstanceStop | Triggers a stop of another instance of the system and returns immediately. |
J2EEControlCluster | Service definition of function SAPControl__J2EEControlCluster |
J2EEControlComponents | Performs a given function (start/stop/restart) on the given J2EE components on the given J2EE process. |
J2EEControlProcess | Performs a given function (StartInstance, StopInstance, RestartInstance, BootInstance, RebootInstance) on the J2EE instance or (EnableProcess, StartProcess, DisableProcess, StopProcess, SoftStopProcess, ActivateProcess, DeactivateProcess, RestartProcess, SoftRestartProcess, DumpStackTrace, EnableDebugging, DisableDebugging, IncrementTrace, DecrementTrace) on a given J2EE process. |
J2EEDisableDbgSession | Removes a J2EE debug session created by J2EEEnableDbgSession. |
J2EEEnableDbgSession | Creates a J2EE debug session on given node or automatically selected node (processname = “”) with the given debug flags (blank separated keywords “SuspendAll”, “CodeIsolate”, “LoadIsolate”, “MigrateSessions”) for the given client name. Returns debug key an network port. |
J2EEGetApplicationAliasList | Returns a list of application aliases in the J2EE instance. |
J2EEGetCacheStatistic2 | Returns a list of caches in the J2EE instance (supersedes J2EEGetCacheStatistic). |
J2EEGetCacheStatistic | Returns a list of caches in the J2EE instance (superseded by J2EEGetCacheStatistic2). |
J2EEGetClusterMsgList | Returns a list of J2EE cluster communication statistic from the message server. |
J2EEGetComponentList | Returns a list of J2EE services and applications. |
J2EEGetEJBSessionList | Returns a list of EJB sessions in the J2EE instance. |
J2EEGetProcessList2 | Returns a list of J2EE processes controlled by jcontrol (supersedes J2EEGetProcessList). |
J2EEGetProcessList | Returns a list of J2EE processes controlled by jcontrol (superseded by J2EEGetProcessList2). |
J2EEGetRemoteObjectList | Returns a list of remote object connections in the J2EE instance. |
J2EEGetSessionList | Returns a list of (HTTP) sessions in the J2EE instance (superseded by J2EEGetWebSessionList, J2EEGetWebSessionList2). |
J2EEGetSharedTableInfo | Returns a list of SAP startup framework shared memory table information. |
J2EEGetThreadCallStack | Returns java callstack of specified J2EE thread or all J2EE threads (index = -1). |
J2EEGetThreadList2 | Returns a list of threads in the J2EE instance (supersedes J2EEGetThreadList). |
J2EEGetThreadList | Returns a list of threads in the J2EE instance (superseded by J2EEGetThreadList2). |
J2EEGetThreadTaskStack | Returns java taskstack of specified J2EE thread or all J2EE threads (index = -1). |
J2EEGetVMGCHistory2 | Returns a list of JAVA VM garbage collections in the J2EE instance (supersedes J2EEGetVMGCHistory). |
J2EEGetVMGCHistory | Returns a list of JAVA VM garbage collections in the J2EE instance (superseded by J2EEGetVMGCHistory2). |
J2EEGetVMHeapInfo | Returns a list of JAVA VM heap information. |
J2EEGetWebSessionList2 | Returns a list of (HTTP) sessions in the J2EE instance (supersedes J2EEGetSessionList, J2EEGetWebSessionList). |
J2EEGetWebSessionList | Returns a list of (HTTP) sessions in the J2EE instance (supersedes J2EEGetSessionList, superseded by J2EEGetWebSessionList2). |
ListConfigFiles | Returns list of configuration files. |
ListDeveloperTraces | Returns a list of all instance trace files (superseded by ListLogFiles). |
ListLogFiles | Returns a list of all instance log files. |
ListSnapshots | Returns a list of all available snapshots on the server side. |
OSExecute | Executes an external OS command. |
ParameterValue | Returns a SAP profile parameter value for a given profile parameter. If the given profile parameter is empty it returns a string with all known parameter value pairs separated by newline. |
ReadConfigFile | Returns content of given configuration file. |
ReadDeveloperTrace | Returns the content of a given trace file. Use size=0 to read the entire file, size bigger 0 to read the first size bytes, size smaller 0 to read the last size bytes (superseded by ReadLogFile). |
ReadLogFile | Returns the content of a given log file. Use statecookie to specify starting position (“”=beginning), use maxentries to specify upper limit of returned entries (0=all) and reading direction (positive: forward, negative: backward). |
ReadSnapshot | Downloads a zipped snapshot from the server. |
RequestLogonFile | Returns a logon file for local authentication. |
RequestTicket | Internal usage only. |
RestartInstance | Triggers an instance restart and returns immediately. |
RestartService | Triggers webservice restart without any effects on the eventually running instance and returns immediately. |
RestartSystem | Triggers restart of entire system or parts of it. |
SendSignal | Sends a given OS signal to a given process. The signal can be given by name or number. |
SendTicket | Internal usage only. |
SetProcessParameter2 | Sets dynamic and persistent Profile Parameters for a given process. |
SetProcessParameter | Sets dynamic Profile Parameters for a given process. |
ShmDetach | Triggers sapstarstrv to detach from shared memory (for internal usage only). |
Shutdown | Triggers a graceful instance stop and returns immediately. |
Start | Triggers an instance start and returns immediately. |
StartBypassHA | Triggers an instance start without checking HA product integration and returns immediately (for HA product internal use only). |
StartSystem | Triggers start of entire system or parts of it. |
Stop | Triggers an instance stop and returns immediately. |
StopBypassHA | Triggers an instance stop without checking HA product integration and returns immediately (for HA product internal use only). |
StopService | Triggers webservice stop without any effects on the eventually running instance and returns immediately. After that the webservice needs to started in order to use the interface again. |
StopSystem | Triggers stop or soft shutdown of entire system or parts of it. |
StorePSE | stores a given PSE with given mode in instance SECUDIR directory. |
UpdateInstancePSE | Updates instance PSE of system internal private key infrastructure if necessary. Use force flag to enforce update. |
UpdateSCSInstance | Service definition of function SAPControl__UpdateSCSInstance |
UpdateSystem | Triggers sequential restart of all instance to activate changes. |
UpdateSystemPKI | Updates the system internal private key infrastructure (system root PSE and instance PSE(s)) of the entire system if necessary. Use force flag to enforce update. |
WebDispGetGroupList | Returns a list of webdispatcher groups. |
WebDispGetServerList | Returns a list backend servers connected to the webdispatcher. |
WebDispGetUrlPrefixList | Returns a list of webdispatcher url prefixes. |
WebDispGetVirtHostList | Returns a list of webdispatcher virtual hosts. |
Documentation/Read more:
- Official documentation: https://www.sap.com/documents/2016/09/0a40e60d-8b7c-0010-82c7-eda71af511fa.html
- Tutorial on SAP Blogs:
- Usage via SQL Anywhere: https://blogs.sap.com/2018/02/09/using-sql-anywhere-to-start-stop-and-monitor-sap-netweaver/
- Usage via Powershell: https://blogs.sap.com/2014/06/12/scripting-sapmmc-operations/
[9] Message Monitor Overview-Servlet
Here it is possible (just like in the PI Monitor in the GUI) to restrict the data to certain time periods. The return values can be sorted or grouped by sender/receiver in addition to the interval to be considered.
State of API: Not officially documented
Technology: (Plain)HTTP/XML
Authentication/Requirements: Basic Authentication (via HTTP header).
Service-/Base-Url: http(s)://<host>:<port>/mdt/messageoverviewqueryservlet
How to use:To use the servlet it can be called via HTTP-GET request with the appropriate URL parameters. The respective parameters can be determined quite easily by calling the base URL mentioned above. On the “start page” of the servlet it is then displayed which parameters has to be maintained at the URL and which values are available.
As shown in the screenshot above, just follow the tips inside the “usage”-tags in the servlet’s entry point. A fully developed request could then look like this, for example:
http(s)://<host>:<port>/mdt/messageoverviewqueryservlet?component=<component_name>&view=<view_type>&begin=<begin_datetime>&end=<end_datetime>&detailedStatus=true
For more detailed usage instructions check out the blog which is linked in the following paragraph.
Documentation/Read more:
- Official documentation: Does not exist
- Tutorial on SAP Blogs: https://blogs.sap.com/2012/06/27/michals-pi-tips-how-to-get-rwb-message-overview-data-to-an-external-system/
[10] Performance Data-Servlet
State of API: Not officially documented
Technology: (Plain)HTTP/XML
Authentication/Requirements: Basic Authentication (via HTTP header).
Service-/Base-Url: http(s)://<host>:<port>/mdt/performancedataqueryservlet
How to use: To use the servlet, call it via HTTP-GET request while handing over the appropriate URL parameters. The respective URL parameters can be determined easily by calling the base URL mentioned above. On the servlet’s “entry page” (=calling the servlet’s base url) you will find XML “usage”-tags which contain information about valid parameters and their values. Follow the usage advices to build a valid url.
A proper call to the “Performance Data”-servlet could look like this:
http://<host>:<port>/mdt/performancedataqueryservlet?component=<component_name>&begin=<start_datetime>&end=<end_datetime>
Note: You can’t pass not just any begin and end date, but only ones known to the servlet. To find out valid values for the begin and end parameter, just call the servlet by passing only the component parameter. This way, the servlet presents you a list of valid begin and end datetime combinations.
Documentation/Read more:
- Official documentation: Does not exist
- Tutorial on SAP Blogs: https://blogs.sap.com/2014/02/25/external-collection-of-message-processing-statistics-from-advanced-adapter-engine-of-pi/
[11] NWA Status Overview-API
Theoretically almost all this information can also be retrieved via the SAP Control API (see section [8]), but this requires a user with elevated rights, whereas the NWA System Overview API can be used by any user who also has the rights to view the status widget in the NWA.
State of API: Not officially documented
Technology: SOAP/XML
Authentication/Requirements: Basic Authentication + specific Cookies (see “How to use”)
Service-/Base-Url: http(s)://<host>:<port>/_tc~monitoring~webservice~web/JEEMONWSService
How to use: In theory, the NWA Status webservice can be used just like any other SOAP webservice by using a SOAP testing tool or a suitable SOAP library. Practically, however, there are two pitfalls:
- Logging on to the service; it is not sufficient to send a BasicAuth header with the SOAP requests, but certain cookies must be sent along. (Without sending the cookies you won’t get an SOAP exception, but simply an empty response.)
- The content that must be sent to the service in the request is unclear.
We will look at both points in the following. For demo purposes I’ll show you the “manual” way to call the service via SoapUI. (If you manage to do so and you’re a programmer – you know what to do, to rebuild SoapUI’s behaviour in your favourite programming environment.) So let’s start.
Open SoapUI, create a new SOAP project and import the webservice’s WSDL, which can be access via the following url:
http(s)://<host>:<port>/_tc~monitoring~webservice~web/JEEMONWSService?wsdl
Then open the demo request for the “retrieveMonitors” operation and you should end up with a view as follows.
Next we need to add the Cookie header which is necessary for making successful requests to the webservice. We need following three cookies: JSESSIONID, MYSAPSSO2 and JSESSIONMARKID
For test purposes just open your webbrowser, press F12 (to open the developer tools) and navigate to http(s)://<host>:<port>/nwa
After page loading has finished, check the network tab, search for the “FloorPlanApp”-request, check its Headers tab and search for the “Cookie” header. Then copy the three cookies named before and enter them in SoapUI’s header tab inside the request window as shown below.
Now that we have prepared the authorization part, we just need to fix the request towards the service. As you may have seen, SoapUI already generated a dummy message from the WSDL. Unfortunately without knowing the correct parameters this won’t help. So remove the “monitors” tag and all its content from the request editor and replace it with the following XML.
<monitors>
<aggregationType>1</aggregationType>
<monitorName>HTTP.RequestsFrequency</monitorName>
<monitorPath>\\Services\\Http Provider\\General\\Requests frequency</monitorPath>
<monitorType>2</monitorType>
<textMonitorName />
</monitors>
<monitors>
<aggregationType>1</aggregationType>
<monitorName>JSF_J2EESessions_Num_Brw</monitorName>
<monitorPath>\\Sessions AS Java\\Browser Sessions</monitorPath>
<monitorType>3</monitorType>
<textMonitorName />
</monitors>
<monitors>
<aggregationType>1</aggregationType>
<monitorName>LOG_CFG.NumberOfErrorLogs</monitorName>
<monitorPath>\\Services\\Log Configurator\\Messages\\Error</monitorPath>
<monitorType>2</monitorType>
<textMonitorName />
</monitors>
<monitors>
<aggregationType>1</aggregationType>
<monitorName>SessMgmt.ActiveWebSessionCount</monitorName>
<monitorPath>\\Kernel\\Session Manager\\Active Web Sessions Count</monitorPath>
<monitorType>2</monitorType>
<textMonitorName />
</monitors>
<monitors>
<aggregationType>1</aggregationType>
<monitorName>SessMgmt.OpenWebSessionCount</monitorName>
<monitorPath>\\Kernel\\Session Manager\\Opened Web Sessions Count</monitorPath>
<monitorType>2</monitorType>
<textMonitorName />
</monitors>
<monitors>
<aggregationType>3</aggregationType>
<monitorName>WEB.AverageProcessingTime</monitorName>
<monitorPath>\\Services\\Web Container\\AverageProcessingTime</monitorPath>
<monitorType>2</monitorType>
<textMonitorName />
</monitors>
<monitors>
<aggregationType>3</aggregationType>
<monitorName>CPU_Utilization</monitorName>
<monitorPath>\\OperatingSystem\\CPU\\CPU_Utilization</monitorPath>
<monitorType>1</monitorType>
<textMonitorName />
</monitors>
<monitors>
<aggregationType>1</aggregationType>
<monitorName>LOG_CFG.NumberOfFatalLogs</monitorName>
<monitorPath>\\Services\\Log Configurator\\Messages\\Fatal</monitorPath>
<monitorType>2</monitorType>
<textMonitorName />
</monitors>
<monitors>
<aggregationType>2</aggregationType>
<monitorName>LicenseMgr.LicenseValidPeriod</monitorName>
<monitorPath>\\Kernel\\Licensing Manager\\License Validity Period\\J2EE-Engine_%l</monitorPath>
<monitorType>2</monitorType>
<textMonitorName />
</monitors>
<monitors>
<aggregationType>2</aggregationType>
<monitorName>ICM_GENERAL_QUEUELEN_GROUP</monitorName>
<monitorPath>\\R3Services\\ICM\\General\\QueueLen</monitorPath>
<monitorType>1</monitorType>
<textMonitorName />
</monitors>
<monitors>
<aggregationType>2</aggregationType>
<monitorName>SYSTEM.ENTRY.EXPIRATION.PERIOD</monitorName>
<monitorPath>\\Services\\Keystore\\DaysToExpire</monitorPath>
<monitorType>2</monitorType>
<textMonitorName />
</monitors>
<monitors>
<aggregationType>3</aggregationType>
<monitorName>ThreadMgr.WaitTasksQueOverflow</monitorName>
<monitorPath>\\Kernel\\System Threads Pool\\Waiting Tasks Queue Overflow</monitorPath>
<monitorType>2</monitorType>
<textMonitorName />
</monitors>
<monitors>
<aggregationType>1</aggregationType>
<monitorName>HeapFileNumber</monitorName>
<monitorPath>\\Performance\\Out Of Memory\\Heapdump file number</monitorPath>
<monitorType>2</monitorType>
<textMonitorName />
</monitors>
<monitors>
<aggregationType>2</aggregationType>
<monitorName>DEPLOY.FailedToStart</monitorName>
<monitorPath>\\Services\\Deploy\\Common Information\\Failed To Start Applications</monitorPath>
<monitorType>2</monitorType>
<textMonitorName />
</monitors>
<monitors>
<aggregationType>2</aggregationType>
<monitorName>FailedToStartServices</monitorName>
<monitorPath>\\Kernel\\Services\\Failed to start services</monitorPath>
<monitorType>2</monitorType>
<textMonitorName />
</monitors>
<monitors>
<aggregationType>3</aggregationType>
<monitorName>LOG_CFG.LogsPerMin</monitorName>
<monitorPath>\\Services\\Log Configurator\\Messages\\Log frequency</monitorPath>
<monitorType>2</monitorType>
<textMonitorName />
</monitors>
<monitors>
<aggregationType>3</aggregationType>
<monitorName>MemoryUtilizationGroup</monitorName>
<monitorPath>\\Performance\\System\\Memory Utilization</monitorPath>
<monitorType>2</monitorType>
<textMonitorName />
</monitors>
<monitors>
<aggregationType>2</aggregationType>
<monitorName>MemoryUtilizationGroup</monitorName>
<monitorPath>\\Performance\\System\\Memory Utilization</monitorPath>
<monitorType>2</monitorType>
<textMonitorName />
</monitors>
<monitors>
<aggregationType>1</aggregationType>
<monitorName>Con.SA.pack.raName.TOCRPS</monitorName>
<monitorPath>\\Services\\Connector Service\\Stand Alone\\javax.sql.DataSource\\SAP%sDB\\TimedOutConnectionRequestsPerSecond</monitorPath>
<monitorType>2</monitorType>
<textMonitorName />
</monitors>
<monitors>
<aggregationType>2</aggregationType>
<monitorName>Con.SA.pack.raName.MCUR</monitorName>
<monitorPath>\\Services\\Connector Service\\Stand Alone\\javax.sql.DataSource\\SAP%sDB\\ManagedConnectionsUsageRate</monitorPath>
<monitorType>2</monitorType>
<textMonitorName />
</monitors>
<monitors>
<aggregationType>3</aggregationType>
<monitorName>EXT_COMM.AverageExternalTime</monitorName>
<monitorPath>\\Performance\\External Communication\\Average RFC Time</monitorPath>
<monitorType>2</monitorType>
<textMonitorName />
</monitors>
<monitors>
<aggregationType>4</aggregationType>
<monitorName>getFreeDiskSpace</monitorName>
<monitorPath>\\Performance\\System\\Free Disk Space</monitorPath>
<monitorType>2</monitorType>
<textMonitorName />
</monitors>
<monitors>
<aggregationType>3</aggregationType>
<monitorName>EXT_COMM.AverageExternalTime</monitorName>
<monitorPath>\\Performance\\External Communication\\Average WebService Time</monitorPath>
<monitorType>2</monitorType>
<textMonitorName />
</monitors>
<monitors>
<aggregationType>3</aggregationType>
<monitorName>EXT_COMM.AverageIO</monitorName>
<monitorPath>\\Performance\\External Communication\\Average RFC IO</monitorPath>
<monitorType>2</monitorType>
<textMonitorName />
</monitors>
<monitors>
<aggregationType>3</aggregationType>
<monitorName>EXT_COMM.AverageIO</monitorName>
<monitorPath>\\Performance\\External Communication\\Average WebService IO</monitorPath>
<monitorType>2</monitorType>
<textMonitorName />
</monitors>
<monitors>
<aggregationType>3</aggregationType>
<monitorName>EXT_COMM.NumberOfCalls</monitorName>
<monitorPath>\\Performance\\External Communication\\External WebService Calls</monitorPath>
<monitorType>2</monitorType>
<textMonitorName />
</monitors>
<monitors>
<aggregationType>3</aggregationType>
<monitorName>EXT_COMM.NumberOfCalls</monitorName>
<monitorPath>\\Performance\\External Communication\\External RFC Calls</monitorPath>
<monitorType>2</monitorType>
<textMonitorName />
</monitors>
<monitors>
<aggregationType>1</aggregationType>
<monitorName>Con.SA.pack.raName.WMCC</monitorName>
<monitorPath>\\Services\\Connector Service\\Stand Alone\\javax.sql.DataSource\\SAP%sDB\\WaitingForManagedConnectionCount</monitorPath>
<monitorType>2</monitorType>
<textMonitorName />
</monitors>
<monitors>
<aggregationType>2</aggregationType>
<monitorName>JSF_JavaMemory_LocalObjects_Ratio</monitorName>
<monitorPath>\\Java Heap Memory\\Memory of %s\\Utilization Local Objects</monitorPath>
<monitorType>3</monitorType>
<textMonitorName />
</monitors>
<monitors>
<aggregationType>3</aggregationType>
<monitorName>JSF_JavaMemory_LocalObjects_Ratio</monitorName>
<monitorPath>\\Java Heap Memory\\Memory of %s\\Utilization Local Objects</monitorPath>
<monitorType>3</monitorType>
<textMonitorName />
</monitors>
<monitors>
<aggregationType>1</aggregationType>
<monitorName>JSF_Process_NumRestarts</monitorName>
<monitorPath>\\Process Table\\%s\\Number of Restarts</monitorPath>
<monitorType>3</monitorType>
<textMonitorName />
</monitors>
<monitors>
<aggregationType>1</aggregationType>
<monitorName>JSF_Threads_Num_Longrunners</monitorName>
<monitorPath>\\Threads\\Threads of %s\\Long Running Threads</monitorPath>
<monitorType>3</monitorType>
<textMonitorName />
</monitors>
<monitors>
<aggregationType>2</aggregationType>
<monitorName>CPU_Utilization</monitorName>
<monitorPath>\\OperatingSystem\\CPU\\CPU_Utilization</monitorPath>
<monitorType>1</monitorType>
<textMonitorName />
</monitors>
<monitors>
<aggregationType>2</aggregationType>
<monitorName>JSF_GarbageColl_Duration_Full_GC</monitorName>
<monitorPath>\\Garbage Collection\\GC of %s\\Duration of Last Full GC</monitorPath>
<monitorType>3</monitorType>
<textMonitorName />
</monitors>
<monitors>
<aggregationType>2</aggregationType>
<monitorName>JSF_GarbageColl_CollectedMemory</monitorName>
<monitorPath>\\Garbage Collection\\GC of %s\\Released Memory per Minute</monitorPath>
<monitorType>3</monitorType>
<textMonitorName />
</monitors>
<monitors>
<aggregationType>1</aggregationType>
<monitorName>Page_In</monitorName>
<monitorPath>\\OperatingSystem\\Paging\\Page_In</monitorPath>
<monitorType>1</monitorType>
<textMonitorName />
</monitors>
<monitors>
<aggregationType>1</aggregationType>
<monitorName>Page_Out</monitorName>
<monitorPath>\\OperatingSystem\\Paging\\Page_Out</monitorPath>
<monitorType>1</monitorType>
<textMonitorName />
</monitors>
<monitors>
<aggregationType>2</aggregationType>
<monitorName>JSF_GarbageColl_AvgDuration</monitorName>
<monitorPath>\\Garbage Collection\\GC of %s\\Average Proportion of Total Time</monitorPath>
<monitorType>3</monitorType>
<textMonitorName />
</monitors>
<monitors>
<aggregationType>1</aggregationType>
<monitorName>JSF_Process_Status</monitorName>
<monitorPath>\\Process Table\\%s\\Process Status</monitorPath>
<monitorType>3</monitorType>
<textMonitorName>StartedNodes</textMonitorName>
</monitors>
<monitors>
<aggregationType>1</aggregationType>
<monitorName>JSF_Process_Status</monitorName>
<monitorPath>\\Process Table\\%s\\Process Status</monitorPath>
<monitorType>3</monitorType>
<textMonitorName>FailedNodes</textMonitorName>
</monitors>
<monitors>
<aggregationType>1</aggregationType>
<monitorName>JSF_Instance_numServerNodes</monitorName>
<monitorPath>\\General Instance Information\\Number of Server Nodes</monitorPath>
<monitorType>3</monitorType>
<textMonitorName />
</monitors>
<monitors>
<aggregationType>2</aggregationType>
<monitorName>SYSTEM.ENTRY.EXPIRATION.PERIOD</monitorName>
<monitorPath>\\Services\\Keystore\\DaysToExpire</monitorPath>
<monitorType>2</monitorType>
<textMonitorName />
</monitors>
<monitors>
<aggregationType>1</aggregationType>
<monitorName>WEB.Error500Count</monitorName>
<monitorPath>\\Services\\Web Container\\Error500Count</monitorPath>
<monitorType>2</monitorType>
<textMonitorName />
</monitors>
<monitors>
<aggregationType>2</aggregationType>
<monitorName>getGCProblems</monitorName>
<monitorPath>\\Kernel\\SAPJVM\\GCProblemReporting\\GC Problems</monitorPath>
<monitorType>2</monitorType>
<textMonitorName />
</monitors>
<monitors>
<aggregationType>2</aggregationType>
<monitorName>getSystemProblems</monitorName>
<monitorPath>\\Kernel\\SAPJVM\\SystemProblemReporting\\System Problems</monitorPath>
<monitorType>2</monitorType>
<textMonitorName />
</monitors>
After you fixed the request, you should be able to successfully call the status webservice. (In case you get no results from the request, it is likely that you messed up with the Cookie header. That’s because the service doesn’t respond with an 401 error, but with an data-less response, if the authroization is messed up.) The final result should look similar to the following.
If you want to call the whole thing from a program, you have to send a HTTP request to /nwa first (including BasicAuth credentials) and then record the cookies in the response. These cookies then should appended to the requests of your SOAP class. The whole thing is a bit “tricky” at first sight, but in the end it’s not that difficult.
Documentation/Read more:
- Official documentation: Does not exist
- Tutorial on SAP Blogs: Does not exist
[12] CPA Cache
State of API: Not officially documented (at least not as API)
Technology: HTML-Forms + XML
Authentication/Requirements: Basic Authentication (via HTTP header) + Cookies + XSRF-Token
Service-/Base-Url:
- Mapping Cache: http(s)://<host>:<port>/run/MappingCache/refresh
- CPA Cache: http(s)://<host>:<port>/CPACache/refresh
How to use:To make a successful call against the cache APIs, you first need to get some security token/cookies. First make a simple HTTP/GET call against the appropriate base url as listed above. From the response to your GET request you secure the cookies that are stored in the “set-cookie” header of the response. Then you parse the HTML code of the response. This code contains an HTML input tag called “xsrfid”, which in turn contains an XSRF token in the value attribute, as the following example shows:
<input type="hidden" name="xsrfid" value="gpnIC74a7A0xxxxxxx_5Ll6nDxxxxxx"/>
Once you have saved the cookies as well as the value of the XSRF token, you can access the API. To do this, make a post-request against the above base urls. As request header you must at least provide the following:
- Name: Cookie, Value: <the cookies extracted from the first call>
- Name: Content-Type, Value: application/x-www-form-urlencoded
The body of the POST request depends on whether the CPA or the runtime cache is to be refreshed and whether it is a delta or full refresh. The following four code boxes show the necessary body value:
CPA Cache / Delta refresh:
mode=delta&xsrfid=<xsrf_token_from_first_request>
CPA Cache / Full refresh:
mode=full&xsrfid=<xsrf_token_from_first_request>
Mapping/Runtime Cache / Delta refresh:
mode=C&xsrfid=<xsrf_token_from_first_request>
Mapping/Runtime Cache / Full refresh:
mode=F&xsrfid=<xsrf_token_from_first_request>
Documentation/Read more:
- Official documentation: Does not exist
- Tutorial on SAP Blogs: (No information about automated calling of the service, but at least some documentation.) https://blogs.sap.com/2014/09/01/it-does-not-work-refresh-the-cache-architecture-and-caching-process-in-sap-pi-74/
[13] WSDL Generator
For example, the service can be used to generate a WSDL for an ICO in which hostname/port are dynamically replaced. (For example, if there is still a gateway/proxy between the SAP PO that the caller must address or if the PI has an external domain).
State of API: Not officially documented
Technology: (Plain)HTTP/XML
Authentication/Requirements: Basic Authentication (via HTTP header).
Service-/Base-Url: http(s)://<host>:<port>/dir/wsdl
How to use: Using the service is very simple. The service must be called via HTTP/GET request and then returns different variants of the WSDL file for an integrated configuration, depending on the selected URL parameters. For HTTP calls, the SAP PI access data should be provided in the Authorization/Basic Auth header. An overview of the possible URL parameters can be obtained by calling the base URL (/dir/wsdl) in the web browser.
The simplest API call only passes the object ID (can be looked up in the Integration Builder, for example) of an ICO and displays the WSDL.
http(s)://<pi-hostname>:<pi-port>/dir/wsdl?p=ic/991c7729330e30caa123456789
If you now want to get a version of the same WSDL, but with a different hostname inside, you could change the url as follows:
http(s)://<pi-hostname>:<pi-port>/dir/wsdl?oid=991c7729330e30caa123456789&endp_url=https://demo.gateway.de:8080
For more examples, just call the base url of the service.
Documentation/Read more:
- Official documentation: Does not exist (or couldn’t find one)
- Tutorial on SAP Blogs: Does not exist (or couldn’t find one)
[14] SOAP Endpoint Registry API
State of API: Not officially documented (couldn’t find a reference)
Technology: WSIL (HTTP/XML)
Authentication/Requirements: Basic Authentication (via HTTP header).
Service-/Base-Url: http(s)://<host>:<port>/dir/inspection.wsil/
How to use: To use the service, simply call its base url via HTTP-GET-request. The SAP PI credentials should be passed in “Basic Auth” format via the authorization header when calling the service. The response of the service – which is also the list of all SOAP interfaces – is in plain XML. This can then be parsed and evaluated as required.
Documentation/Read more:
- Official documentation: Does not exist (or couldn’t find one)
- Tutorial on SAP Blogs: Does not exist (or couldn’t find one)
[15] Service Registry API
In contrast to the SOAP Endpoint Service mentioned above, this WSIL service provides endpoints and urls to WSDL files for all standard SAP PI web services, such as the Directory APIs (see section [1] of this blog). The Service Registry API is thus more of a technical variant of the SAP PI “Webservice Navigator”.
State of API: Officially documented
Technology: WSIL (HTTP/XML)
Authentication/Requirements: Basic Authentication (via HTTP header).
Service-/Base-Url: http(s)://<host>:<port>/inspection.wsil/
How to use: To use the service, simply call its base url via HTTP-GET-request. The SAP PI credentials should be passed in “Basic Auth” format via the authorization header when calling the service. The response of the service comes as plain XML. This can then be parsed and evaluated as required.
Documentation/Read more:
- Official documentation: https://help.sap.com/doc/saphelp_nw73ehp1/7.31.19/en-US/c8/ba3c12637649e48ef3f0649f19d685/content.htm?no_cache=true
- Tutorial on SAP Blogs: Does not exist (or couldn’t find one)
[16] Operation Mapping Test API
Strictly speaking, the Operation Mapping Test API is a subset of the HMI Servlet API we discussed in section [3] of this blog. But since the Mapping API is so well documented, I have added it to the list again separately.
State of API: Not officially documented
Technology: (Plain)HTTP/XML
Authentication/Requirements: Basic Authentication (via HTTP header).
Service-/Base-Url: http(s)://<host>:<port>/rep/mappingtestservice/int?container=any
How to use:
- Short explanation: Create a sample XML for the mapping test, wrap this in the standard message of the mapping test API. Parameterize the wrapper XML and send the data via HTTP post to the base URL.
- Detailed explanation: Read the blog entry linked below, which explains how to use the API step-by-step.
Documentation/Read more:
- Official documentation: Does not exist
- Tutorial on SAP Blogs: https://blogs.sap.com/2020/10/08/sap-po-operation-mapping-test-with-postman/
Conclusion
I’d love to hear what you think of this article? Did you already work with the APIs or did you even know all APIs from the list? What kind of thoughts come into your head? Do you already have new ideas or even one or the other API that is missing from the list? I am looking forward to your comments and ideas.
Hi Raffael,
Excellent.. Thanks for documenting APIs at one place.
You can add Alerting API into your list.
Best Regards,
Umesh
Thanks the kind words Umesh. 🙂
By "Alerting API" you mean this one? https://help.sap.com/saphelp_snc_uiaddon_10/helpdata/en/9b/b8b1b38fc74043a90fbc79d2e7abd4/content.htm?no_cache=true (If so, do you have any blogs/links/resource that may be useful for my research, before adding it to the blog?)
Kind regards,
Raffael
Hi Raffael,
Please check the below Michal blog on Alerting API.
https://blogs.sap.com/2012/05/05/michals-pi-tips-component-based-message-alerting-api/
Vadim has mentioned the same in comments.
Best Regards, Umesh
Excellent.!
Nice list of "API". A shame much of it is unofficial.
In the Figaf Tool we do use a number of those APIs.
Maybe the PIT Odata API could be mentioned.
And you also have the option to send test messages via the XI30 protocol remotely. We use it for sending test messages.
Hi Daniel,
Could you please share any info on this API "send test messages via the XI30 protocol remotely"?
Thanks in advance.
Mikel
Hi Mikel
We used this one
https://blogs.sap.com/2014/02/20/michals-po-tips-how-to-send-messages-directly-to-aex-ico-adapter-independent-soapui-version/
And it can ofcause also be used in different cases.
Very nice overview, Raffael. This goes straight into my bookmarks 😀
Fantastic Raffael as always
Hi Raffael. This is so brilliant compilation and description of PI/PO's APIs! Thank you for bringing information about various APIs together and putting it all in a single place.
While reading through the blog post, I could think of a few APIs that we used in some projects (or which are used by SAP in some tools) - some of them are just alternative ways to fulfil requirements that you already mentioned:
Web service AdapterMessageMonitoringVi - to retrieve information about messages in Adapter Engine, as well as resend/cancel messages:
https://blogs.sap.com/2013/03/09/michals-popi-tips-audit-logs-from-a-native-ws-new-feature/
https://blogs.sap.com/2015/01/22/reading-messages-from-pi-system/
https://blogs.sap.com/2015/07/15/external-search-of-messages-processed-by-advanced-adapter-engine-of-pi/
Web service ProfileProcessorVi - similarly to PerformanceDataQueryServlet, to access message processing performance statistics:
https://blogs.sap.com/2014/02/25/external-collection-of-message-processing-statistics-from-advanced-adapter-engine-of-pi/
Web service IChannelAdmin - similarly to ChannelAdminServlet, to administer states of communication channels:
https://blogs.sap.com/2012/03/01/sap-pi-startstop-communication-channel-using-webservice/
Web service AlertRetrieveAPI_V2 - to consume alerts:
https://blogs.sap.com/2012/05/05/michals-pi-tips-component-based-message-alerting-api/
https://blogs.sap.com/2016/04/13/alerting-for-stuck-messages/
Do you know about API related PIT tool?
Great article man. Thank you. Did not know about Simple Query, so I gave it a try and it seems exactly what I need.
Good article.
sap note
766332 - XI 3.0/7.0 Adapter Development: API Changes since SP9/SP0 - SAP ONE Support Launchpad
it has attachments
whitePaperPIAdaptersSAPCluster10.pdf
AAM_Prg_Guide.pdf
Start and stop of communication channels and much more with the AAM API
https://help.sap.com/doc/2f39047ed6b141cb83658041d2d4e029/7.5.23/en-US/PI/com/sap/aii/af/service/administration/api/cpa/CPAFactory.html