[et_pb_section fb_built=”1″ admin_label=”Header Image and Title” _builder_version=”4.16″ _module_preset=”default” background_enable_image=”off” background_size=”contain” min_height=”229px” custom_padding=”4px||0px|||” global_colors_info=”{}”][et_pb_row _builder_version=”4.16″ _module_preset=”default” min_height=”140px” global_colors_info=”{}”][et_pb_column type=”4_4″ _builder_version=”4.16″ _module_preset=”default” global_colors_info=”{}”][et_pb_image src=”https:\/\/richrijnders.com\/file\/2022\/03\/soapui-datapower-framework-01-banner.jpg” alt=”SoapUI DataPower Framework Banner” title_text=”soapui-datapower-framework-01-banner” align=”center” _builder_version=”4.16.0″ _module_preset=”default” min_height=”178px” custom_margin=”-25px|||||” global_colors_info=”{}”][\/et_pb_image][\/et_pb_column][\/et_pb_row][\/et_pb_section][et_pb_section fb_built=”1″ admin_label=”Introduction” _builder_version=”4.16″ _module_preset=”default” custom_padding=”3px||0px|||” global_colors_info=”{}”][et_pb_row _builder_version=”4.16″ _module_preset=”default” min_height=”481px” custom_padding=”||0px|||” global_colors_info=”{}”][et_pb_column type=”4_4″ _builder_version=”4.16″ _module_preset=”default” global_colors_info=”{}”][et_pb_text ol_item_indent=”5px” _builder_version=”4.17.0″ _module_preset=”default” text_orientation=”justified” global_colors_info=”{}”]<\/p>\n
We all know that IBM DataPower is a very powerful edge platform for the deployment, management, protection, and execution of cloud and on-prem API’s. The most ubiquitous method of managing the appliances (and now instances) is the provided Web Management Console. As its name implies, this is the provided browser-based management interface with menus and utilities to perform management functions in DataPower. \u00a0If you have one DataPower or, more typically, two (one DMZ and one Internal) then this management interface is probably all you need. \u00a0But if you are in an environment with thousands or millions of transactions per minute, then you probably have four, eight, a dozen, or more appliances or instances redundantly grouped across multiple datacenters. \u00a0In such cases, logging on to each via individual browser tabs to perform similar functions or check status can get very tedius very quickly.<\/p>\n
IBM provides another interface in DataPower called the XML Management Interface. \u00a0This interface services a set of API’s called SOMA (SOap MAnagement) and AMP (App Management Protocol) services. These are SOAP services defined by a WSDLs (more on that later). You can execute these calls with any SOAP tool, or even from a command line with CURL. But we are going to use these SOMA and AMP API’s to create toolbox of reusable utilities and reports using SoapUI<\/a>.\u00a0Our toolbox will have a common library of API calls that we can use in multiple utilities without having to re-define them and have redundant code everywhere they are used.<\/p>\n What’s the big deal about that, you ask?\u00a0 You probably create common functions all the time and copy them into different programs with various types of include() <\/em>functions or statements. Yeah, about that. SoapUI has a testing facility with limited scripting capabilities. It’s not really an HLL so it doesn’t support things like copybooks or includes.\u00a0 So this tutorial is going to show you an object based method to set up common libraries and functions within the confines of soapUI’s TestSuites and scripting.<\/p>\n <\/p>\n [\/et_pb_text][\/et_pb_column][\/et_pb_row][\/et_pb_section][et_pb_section fb_built=”1″ admin_label=”The Pieces” _builder_version=”4.16″ _module_preset=”default” custom_margin=”2px|||||” custom_padding=”4px||12px|||” global_colors_info=”{}”][et_pb_row column_structure=”3_5,2_5″ _builder_version=”4.16″ _module_preset=”default” min_height=”253px” custom_margin=”0px|auto|9px|auto||” custom_padding=”10px||0px|||” global_colors_info=”{}”][et_pb_column type=”3_5″ _builder_version=”4.16″ _module_preset=”default” global_colors_info=”{}”][et_pb_text ol_position=”outside” ol_item_indent=”20px” admin_label=”Text” _builder_version=”4.16.1″ _module_preset=”default” text_orientation=”justified” width=”94.4%” custom_padding=”25px||0px|||” global_colors_info=”{}”]<\/p>\n As you may have surmised, the pieces needed for this turorial are:<\/p>\n [\/et_pb_text][\/et_pb_column][et_pb_column type=”2_5″ _builder_version=”4.16″ _module_preset=”default” global_colors_info=”{}”][et_pb_image src=”https:\/\/richrijnders.com\/file\/2020\/12\/puzzle-pieces-shopping-cart.jpg” title_text=”puzzle-pieces-shopping-cart” admin_label=”Image: Puzzle Pieces in Shopping Cart” _builder_version=”4.16″ _module_preset=”default” custom_margin=”||-1px|||” global_colors_info=”{}”][\/et_pb_image][\/et_pb_column][\/et_pb_row][et_pb_row _builder_version=”4.16″ _module_preset=”default” custom_padding=”0px||4px|||” global_colors_info=”{}”][et_pb_column type=”4_4″ _builder_version=”4.16″ _module_preset=”default” global_colors_info=”{}”][et_pb_text ol_position=”outside” ol_item_indent=”20px” _builder_version=”4.17.0″ _module_preset=”default” text_orientation=”justified” min_height=”360px” custom_padding=”||33px|||” global_colors_info=”{}”]<\/p>\n For the purposes of this tutorial I will assume that you have access to at least one DataPower appliance or instance and that you have administrative rights to it.<\/p>\n SoapUI is a great program for easily importing WSDL’s and running the API’s. It also has a testing facility that allows you (with scripting) to string together multiple API calls in order to perform more complete testing or, in our case, to create complex utilities and reports. If you don’t have it, you can download the open source version of SoapUI here<\/a>. For the remainder of this tutorial I will assume that you already have it installed on your computer.<\/p>\n The Apache Groovy language is what SoapUI uses for its test scripting facilities, so you will need to know at least the basics of the language. You don’t need to download anything as it is already included in SoapUI. You can learn the basics of the groovy language here<\/a>.<\/p>\n You will be downloading the SOMA and AMP wsdl and XSD files from your DataPower appliance and then importing those into your SoapUI workspace. \u00a0We will be covering those steps in detail later in the tutorial.<\/p>\n [\/et_pb_text][\/et_pb_column][\/et_pb_row][\/et_pb_section][et_pb_section fb_built=”1″ admin_label=”Enable The XML Mgmt Interface on DataPower” _builder_version=”4.16″ _module_preset=”default” custom_margin=”2px|||||” custom_padding=”4px||12px|||” global_colors_info=”{}”][et_pb_row _builder_version=”4.16″ _module_preset=”default” min_height=”105px” custom_margin=”0px|auto|9px|auto||” custom_padding=”10px||0px|||” global_colors_info=”{}”][et_pb_column type=”4_4″ _builder_version=”4.16″ _module_preset=”default” global_colors_info=”{}”][et_pb_text _builder_version=”4.16.1″ _module_preset=”default” custom_margin=”||0px|||” global_colors_info=”{}”]<\/p>\n Obviously we cannot use the XML Management interface if it’s not enabled. You enable the interface via the Web Management console. Here are the steps to accomplish this:<\/p>\n [\/et_pb_text][\/et_pb_column][\/et_pb_row][et_pb_row column_structure=”1_2,1_2″ _builder_version=”4.16″ _module_preset=”default” custom_padding=”23px||4px|||” global_colors_info=”{}”][et_pb_column type=”1_2″ _builder_version=”4.16″ _module_preset=”default” global_colors_info=”{}”][et_pb_image src=”https:\/\/richrijnders.com\/file\/2022\/04\/framework_00_enable_xml-mgmt-interface.png” alt=”Screenshot: Enable XML Mgmt” title_text=”framework_00_Enable_xml-mgmt-interface” show_in_lightbox=”on” align=”center” _builder_version=”4.16.1″ _module_preset=”default” global_colors_info=”{}”][\/et_pb_image][\/et_pb_column][et_pb_column type=”1_2″ _builder_version=”4.16″ _module_preset=”default” global_colors_info=”{}”][et_pb_text _builder_version=”4.16.1″ _module_preset=”default” min_height=”22px” global_colors_info=”{}”]<\/p>\n [\/et_pb_text][\/et_pb_column][\/et_pb_row][et_pb_row _builder_version=”4.16″ _module_preset=”default” min_height=”122px” custom_margin=”0px|auto|9px|auto||” custom_padding=”10px||0px|||” global_colors_info=”{}”][et_pb_column type=”4_4″ _builder_version=”4.16″ _module_preset=”default” global_colors_info=”{}”][et_pb_text _builder_version=”4.16.1″ _module_preset=”default” global_colors_info=”{}”]<\/p>\n Those are the basics required, but there are some other options on that screen that we will briefly cover here so you don’t obsess over them.<\/p>\n Port Number:\u00a0<\/em><\/strong>The default port for the XML Management Interface is 5550. \u00a0You can change this to another available port number if you wish. For the purposes of this tutorial I am using the default.<\/p>\n Access Control List (ACL):<\/strong> <\/em> You can choose to secure the use of this interface by specifying which IP addresses (via CIDR notation) are allowed to connect to it and\/or specify which IP addresses or ranges are denied access.\u00a0<\/p>\n Enabled Services:<\/em>\u00a0<\/strong>I normally only enable SOAP and AMP interfaces, but you can leave the defaults if you want to experiment with or use the other mentioned services.<\/p>\n Advanced:\u00a0<\/strong><\/em> You can use SSL to secure this interface. You can do so using all of the options available in an SSL Server\/Client profile. This is an advanced feature of DataPower configuration which we will not delve into here. \u00a0If left at the defaults, the interface will still be secured via HTTPS using the appliances global SSL certificate.\u00a0<\/p>\n SLM:<\/strong><\/em>\u00a0<\/strong>If your DataPower is part of an SLM group, you would configure the update interval here. This is another advanced feature of the DataPower platform which we will not cover here.<\/p>\n [\/et_pb_text][\/et_pb_column][\/et_pb_row][\/et_pb_section][et_pb_section fb_built=”1″ admin_label=”Setup SoapUI” _builder_version=”4.16″ _module_preset=”default” custom_margin=”2px|||||” custom_padding=”4px||12px|||” global_colors_info=”{}”][et_pb_row column_structure=”3_5,2_5″ _builder_version=”4.16″ _module_preset=”default” min_height=”122px” custom_margin=”0px|auto|9px|auto||” custom_padding=”10px||0px|||” global_colors_info=”{}”][et_pb_column type=”3_5″ _builder_version=”4.16″ _module_preset=”default” global_colors_info=”{}”][et_pb_text _builder_version=”4.17.1″ _module_preset=”default” global_colors_info=”{}”]<\/p>\n Create a new workspace in SoapUI and name it something creative like “DataPowerTools”.<\/p>\n When you are done with these steps, your workspace should look like this and we are ready to get busy!<\/p>\n [\/et_pb_text][\/et_pb_column][et_pb_column type=”2_5″ _builder_version=”4.16″ _module_preset=”default” global_colors_info=”{}”][et_pb_image src=”https:\/\/richrijnders.com\/file\/2022\/04\/framework_00_Setup-SoapUI-Workspace_2.png” title_text=”framework_00_Setup-SoapUI-Workspace_2″ show_in_lightbox=”on” _builder_version=”4.17.0″ _module_preset=”default” min_height=”242px” global_colors_info=”{}”][\/et_pb_image][\/et_pb_column][\/et_pb_row][\/et_pb_section][et_pb_section fb_built=”1″ admin_label=”Download SOMA WSDL’s” _builder_version=”4.16″ _module_preset=”default” custom_margin=”2px|||||” custom_padding=”4px||12px|||” global_colors_info=”{}”][et_pb_row _builder_version=”4.16″ _module_preset=”default” min_height=”122px” custom_margin=”0px|auto|-21px|auto||” custom_padding=”10px||0px|||” global_colors_info=”{}”][et_pb_column type=”4_4″ _builder_version=”4.16″ _module_preset=”default” global_colors_info=”{}”][et_pb_text _builder_version=”4.17.0″ _module_preset=”default” global_colors_info=”{}”]<\/p>\n You can download the SOMA and AMP WSDL’s directly from the DataPower appliance or instance. Log onto DataPower and navigate to the Administration<\/em> menu. Under the\u00a0Main<\/em> submenu, select the\u00a0File Management<\/em> option.<\/p>\n [\/et_pb_text][\/et_pb_column][\/et_pb_row][et_pb_row column_structure=”1_2,1_2″ _builder_version=”4.16″ _module_preset=”default” custom_padding=”23px||4px|||” global_colors_info=”{}”][et_pb_column type=”1_2″ _builder_version=”4.16″ _module_preset=”default” global_colors_info=”{}”][et_pb_text _builder_version=”4.17.0″ _module_preset=”default” global_colors_info=”{}”]<\/p>\n Scroll down to the “store” folder and expand it.\u00a0Near the top of the folder you will find the “app-mgmt-protocol-v3*”\u00a0files and near bottom of that folder you will find the “xml-mgmt*” files. These are the WSDL’s and XSD files you will need:<\/p>\n You can download them by right-clicking the file name and selecting “save link as”. \u00a0Save them somewhere on your computer. A good place is wherever you are saving your SoapUI workspace and project files (the default is your user’s\u00a0home<\/em> directory “C:\\Users\\youruserid”).<\/p>\n [\/et_pb_text][\/et_pb_column][et_pb_column type=”1_2″ _builder_version=”4.16″ _module_preset=”default” global_colors_info=”{}”][et_pb_image src=”https:\/\/richrijnders.com\/file\/2022\/03\/framework_01_download_xml-mgmt-wsdl.png” title_text=”framework_01_download_xml-mgmt-wsdl” show_in_lightbox=”on” _builder_version=”4.16.1″ _module_preset=”default” global_colors_info=”{}”][\/et_pb_image][\/et_pb_column][\/et_pb_row][\/et_pb_section][et_pb_section fb_built=”1″ admin_label=”Import SOMA WSDL’s to SoapUI” _builder_version=”4.16″ _module_preset=”default” custom_margin=”2px|||||” custom_padding=”4px||12px|||” global_colors_info=”{}”][et_pb_row column_structure=”3_5,2_5″ _builder_version=”4.16″ _module_preset=”default” min_height=”122px” custom_margin=”0px|auto|9px|auto||” custom_padding=”10px||0px|||” global_colors_info=”{}”][et_pb_column type=”3_5″ _builder_version=”4.16″ _module_preset=”default” global_colors_info=”{}”][et_pb_text _builder_version=”4.17.1″ _module_preset=”default” global_colors_info=”{}”]<\/p>\n Now it’s time to add the actual service WSDL’s to SoapUI. You do this by right-clicking on\u00a0the workspace<\/em> name and selecting\u00a0New Soap Project<\/em>. Be sure to right-click on the\u00a0workspace<\/em> name “DataPowerTools” and not the project “DP_Tools”.\u00a0 This is because we are going to import the full WSDL’s as their own projects and select which API’s we will be using as we need them.<\/p>\n [\/et_pb_text][\/et_pb_column][et_pb_column type=”2_5″ _builder_version=”4.16″ _module_preset=”default” global_colors_info=”{}”][et_pb_image src=”https:\/\/richrijnders.com\/file\/2022\/04\/framework_03_add-wsdl.png” alt=”import_project” title_text=”framework_03_Add-WSDL” show_in_lightbox=”on” _builder_version=”4.17.1″ _module_preset=”default” global_colors_info=”{}”][\/et_pb_image][\/et_pb_column][\/et_pb_row][et_pb_row column_structure=”1_2,1_2″ _builder_version=”4.16″ _module_preset=”default” custom_padding=”23px||4px|||” global_colors_info=”{}”][et_pb_column type=”1_2″ _builder_version=”4.16″ _module_preset=”default” global_colors_info=”{}”][et_pb_image src=”https:\/\/richrijnders.com\/file\/2022\/04\/framework_03_add-wsdls.png” alt=”importing_wsdls” title_text=”framework_03_Add-WSDLs” show_in_lightbox=”on” align=”center” _builder_version=”4.17.1″ _module_preset=”default” global_colors_info=”{}”][\/et_pb_image][\/et_pb_column][et_pb_column type=”1_2″ _builder_version=”4.16″ _module_preset=”default” global_colors_info=”{}”][et_pb_text _builder_version=”4.17.1″ _module_preset=”default” min_height=”22px” custom_margin=”88px|||||” global_colors_info=”{}”]<\/p>\n In the “New Soap Project” window, click the browse<\/em> button next to the\u00a0initial WSDL<\/em> box and navigate to the folder where you saved the DataPower WSDL files. Select the “xml-mgmt.wsdl” file and then click “OK”.\u00a0 Don’t worry about the\u00a0Project Name\u00a0<\/em>field, it will be filled in by the WSDL.<\/p>\n After the WSDL is added as a new project, do the same with the “app-mgmt-protocol-v3.wsdl”.<\/p>\n [\/et_pb_text][\/et_pb_column][\/et_pb_row][et_pb_row column_structure=”1_2,1_2″ _builder_version=”4.16″ _module_preset=”default” min_height=”122px” custom_margin=”0px|auto|9px|auto||” custom_padding=”10px||0px|||” global_colors_info=”{}”][et_pb_column type=”1_2″ _builder_version=”4.16″ _module_preset=”default” global_colors_info=”{}”][et_pb_text _builder_version=”4.17.1″ _module_preset=”default” custom_padding=”95px|||||” global_colors_info=”{}”]<\/p>\n After adding both of the WSDL’s as new projects to your workspace, your screen should look something like this.<\/p>\n At this point our base structure is done and we are ready to start developing our first utility, “ShowActiveUsers”<\/p>\n <\/p>\n [\/et_pb_text][\/et_pb_column][et_pb_column type=”1_2″ _builder_version=”4.16″ _module_preset=”default” global_colors_info=”{}”][et_pb_image src=”https:\/\/richrijnders.com\/file\/2022\/04\/framework_04_after-wsdls-added.png” alt=”workspace_with_wsdls” title_text=”framework_04_after-wsdls-added” show_in_lightbox=”on” _builder_version=”4.17.1″ _module_preset=”default” global_colors_info=”{}”][\/et_pb_image][\/et_pb_column][\/et_pb_row][\/et_pb_section][et_pb_section fb_built=”1″ admin_label=”List Active Users SOAP Request” _builder_version=”4.16″ _module_preset=”default” custom_margin=”2px|||||” custom_padding=”4px||12px|||” global_colors_info=”{}”][et_pb_row admin_label=”Intro” _builder_version=”4.16″ _module_preset=”default” min_height=”122px” custom_margin=”0px|auto|9px|auto||” custom_padding=”10px||0px|||” global_colors_info=”{}”][et_pb_column type=”4_4″ _builder_version=”4.16″ _module_preset=”default” global_colors_info=”{}”][et_pb_text _builder_version=”4.17.1″ _module_preset=”default” global_colors_info=”{}”]<\/p>\n We will build out our reusable API framework while simultaneously building our first utility, “Show Active Users”.\u00a0 This utility will cycle through some or all of our appliances and list all user accounts that are currently logged in to the device. This relatively simple utility will use one IBM API that we will put into our common “DP_APIs” test suite, and one common function that we will put into our “DP_Common” test suite. Once created, these functions will be available to be easily reused by any future utility we create.<\/p>\n [\/et_pb_text][\/et_pb_column][\/et_pb_row][et_pb_row column_structure=”2_5,3_5″ admin_label=”Open SOMA Request” _builder_version=”4.16″ _module_preset=”default” custom_padding=”23px||4px|||” global_colors_info=”{}”][et_pb_column type=”2_5″ _builder_version=”4.16″ _module_preset=”default” global_colors_info=”{}”][et_pb_image src=”https:\/\/richrijnders.com\/file\/2022\/04\/framework_06_open-request1-e1650333365576.png” alt=”Screenshot: Enable XML Mgmt” title_text=”framework_06_open-request1″ show_in_lightbox=”on” align=”center” _builder_version=”4.17.1″ _module_preset=”default” global_colors_info=”{}”][\/et_pb_image][\/et_pb_column][et_pb_column type=”3_5″ _builder_version=”4.16″ _module_preset=”default” global_colors_info=”{}”][et_pb_text _builder_version=”4.17.1″ _module_preset=”default” min_height=”22px” custom_margin=”|||-49px||” custom_padding=”|||5px||” global_colors_info=”{}”]<\/p>\n The first thing we need to do is identify the SOMA API that will retrieve for us the list of active users on our DataPower appliances. To do this, expand the “xml-mgmt” project, then the “xml-mgmt-soap” interface, then the “operation” mock service, and finally double-click “Request1”. When you do this, SoapUI opens the request XML in the left-side pane of the editor window.\u00a0The first thing you will notice is that the request XML is HUGE. Every function that the SOMA API supports is in this one request XML!\u00a0 But don’t get intimidated, you only need a small part of this request for any given action.\u00a0 \u00a0<\/p>\n To get the list of all active users, we are only interested in the “get-status” operation, as shown below:<\/p>\n <\/p>\n [\/et_pb_text][\/et_pb_column][\/et_pb_row][et_pb_row column_structure=”1_2,1_2″ admin_label=”Pare Down Monster Request” _builder_version=”4.16″ _module_preset=”default” min_height=”122px” custom_margin=”0px|auto|9px|auto||” custom_padding=”10px||0px|||” global_colors_info=”{}”][et_pb_column type=”1_2″ _builder_version=”4.16″ _module_preset=”default” global_colors_info=”{}”][et_pb_image src=”https:\/\/richrijnders.com\/file\/2022\/03\/framework_06_open-raw-request.png” title_text=”framework_06_open-raw-request” show_in_lightbox=”on” _builder_version=”4.17.1″ _module_preset=”default” global_colors_info=”{}”][\/et_pb_image][\/et_pb_column][et_pb_column type=”1_2″ _builder_version=”4.16″ _module_preset=”default” global_colors_info=”{}”][et_pb_text _builder_version=”4.17.1″ _module_preset=”default” global_colors_info=”{}”]<\/p>\n Remove all the other operations from the request. When you are done paring it down, it should like the image below:<\/p>\n [\/et_pb_text][et_pb_image src=”https:\/\/richrijnders.com\/file\/2022\/03\/framework_07_trimmed-down-request.png” title_text=”framework_07_trimmed-down-request” show_in_lightbox=”on” _builder_version=”4.17.1″ _module_preset=”default” global_colors_info=”{}”][\/et_pb_image][\/et_pb_column][\/et_pb_row][et_pb_row column_structure=”1_2,1_2″ admin_label=”Modify Request Parms” _builder_version=”4.17.1″ _module_preset=”default” global_colors_info=”{}”][et_pb_column type=”1_2″ _builder_version=”4.17.1″ _module_preset=”default” global_colors_info=”{}”][et_pb_text _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”]<\/p>\n Now that we have an API that will return the list ofactive users, we had better test it out and make sure that it will do just that.\u00a0 So the first thing we need to do is modify the request with the parameters it needs to its job.\u00a0 First, modify the request URL so the request goes to one of your DataPower appliances or instances. Leave the port nunber and URI\/endpoint unchanged. Next, set the\u00a0domain\u00a0<\/em>attribute equal to “default” and set the\u00a0class<\/em> attribute equal to “ActiveUsers”. Be sure your letter case is accurate, it matters. You can delete the “object-class” and “object-name” attributes – we don’t need them for this action.<\/p>\n [\/et_pb_text][\/et_pb_column][et_pb_column type=”1_2″ _builder_version=”4.17.1″ _module_preset=”default” global_colors_info=”{}”][et_pb_image src=”https:\/\/richrijnders.com\/file\/2022\/03\/framework_08_modify-request-for-call.png” title_text=”framework_08_modify-request-for-call” show_in_lightbox=”on” _builder_version=”4.17.1″ _module_preset=”default” custom_padding=”27px|||||” global_colors_info=”{}”][\/et_pb_image][\/et_pb_column][\/et_pb_row][et_pb_row column_structure=”1_2,1_2″ admin_label=”Add Basic Auth Header” _builder_version=”4.17.1″ _module_preset=”default” global_colors_info=”{}”][et_pb_column type=”1_2″ _builder_version=”4.17.1″ _module_preset=”default” global_colors_info=”{}”][et_pb_image src=”https:\/\/richrijnders.com\/file\/2022\/03\/framework_09_create-auth-header.png” title_text=”framework_09_create-auth-header” show_in_lightbox=”on” admin_label=”Add Basicauth” _builder_version=”4.17.1″ _module_preset=”default” global_colors_info=”{}”][\/et_pb_image][\/et_pb_column][et_pb_column type=”1_2″ _builder_version=”4.17.1″ _module_preset=”default” global_colors_info=”{}”][et_pb_text _builder_version=”4.17.1″ _module_preset=”default” custom_padding=”15px|||||” global_colors_info=”{}”]<\/p>\n Before you can actually execute your request you need to be able to log into the DataPower.\u00a0 To do this, we are going to add our base 64 encoded user id and password as a\u00a0basic auth<\/em> header to our request.\u00a0 Yes, I know you can do this using the “Auth” panel directly, but adding it manually as a header will allow us to soft-code it later when we turn it into re-usable module.<\/p>\n [\/et_pb_text][\/et_pb_column][\/et_pb_row][et_pb_row column_structure=”1_2,1_2″ admin_label=”Add Base64 String” _builder_version=”4.17.1″ _module_preset=”default” global_colors_info=”{}”][et_pb_column type=”1_2″ _builder_version=”4.17.1″ _module_preset=”default” global_colors_info=”{}”][et_pb_text _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”]<\/p>\n Now you see the “Authorization” header in the Header list. Click the box to the right of the “Authorization” header name and paste\/enter the word “Basic” followed by a space and then the base 64 encoded string of your DataPower user id and password.\u00a0 If you don’t know what this is, it’s basically your userid and password in the form “myuserid:mypassword” and then base 64 encoded (there are plenty of free tools on the Internet to do this). When done, your header should look like the one in this image.\u00a0 You can click the “Headers” button again to close the panel.<\/p>\n [\/et_pb_text][\/et_pb_column][et_pb_column type=”1_2″ _builder_version=”4.17.1″ _module_preset=”default” global_colors_info=”{}”][et_pb_image src=”https:\/\/richrijnders.com\/file\/2022\/03\/framework_10_paste-basic-auth-string.png” title_text=”framework_10_paste-basic-auth-string” show_in_lightbox=”on” _builder_version=”4.17.1″ _module_preset=”default” custom_padding=”26px|||||” global_colors_info=”{}”][\/et_pb_image][\/et_pb_column][\/et_pb_row][et_pb_row column_structure=”1_2,1_2″ admin_label=”Test Run Soap Request” _builder_version=”4.17.1″ _module_preset=”default” global_colors_info=”{}”][et_pb_column type=”1_2″ _builder_version=”4.17.1″ _module_preset=”default” global_colors_info=”{}”][et_pb_image src=”https:\/\/richrijnders.com\/file\/2022\/03\/framework_11_active-users-soap-response.png” title_text=”framework_11_active-users-soap-response” show_in_lightbox=”on” _builder_version=”4.17.1″ _module_preset=”default” global_colors_info=”{}”][\/et_pb_image][\/et_pb_column][et_pb_column type=”1_2″ _builder_version=”4.17.1″ _module_preset=”default” global_colors_info=”{}”][et_pb_text _builder_version=”4.17.1″ _module_preset=”default” global_colors_info=”{}”]<\/p>\n Click the “Run” button on the request.<\/p>\n If you did everything correctly, then the request will return a response that looks something like the image to the left. Looking at the response, you can clearly see id’s of the users currently logged into the device.\u00a0 You will note that\u00a0your own id<\/em> also shows up since you did<\/em> just log in to run this API!\u00a0 Keep this in mind for later.<\/p>\n [\/et_pb_text][\/et_pb_column][\/et_pb_row][et_pb_row column_structure=”1_2,1_2″ admin_label=”Rename Soap Request” _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][et_pb_column type=”1_2″ _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][et_pb_text _builder_version=”4.17.4″ _module_preset=”default” custom_margin=”58px|||||” global_colors_info=”{}”]<\/p>\n Now that we have a working and pared down SOAP call, let’s give it a name that reflects what it actually does.\u00a0 Right-click on the soap operation name and select “Rename” from the pop-up menu. Rename it to “ListActiveUsersSoap”.<\/p>\n \u00a0We’re doing great so far. But even though we have a working SOAP call, it is still in its own soapUI project (xml-mgmt).\u00a0 So now, we are going to create a new\u00a0test case<\/em> under the “DP_APIs”\u00a0test suite<\/em> in our “DataPowerTools” project.\u00a0 This is where all of our re-usable api calls will live.<\/p>\n [\/et_pb_text][\/et_pb_column][et_pb_column type=”1_2″ _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][et_pb_image src=”https:\/\/richrijnders.com\/file\/2022\/05\/framework_12_rename-soap-request.png” title_text=”framework_12_rename-soap-request” show_in_lightbox=”on” _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][\/et_pb_image][\/et_pb_column][\/et_pb_row][et_pb_row column_structure=”1_2,1_2″ admin_label=”Drag Soap Request to Test Steps” _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][et_pb_column type=”1_2″ _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][et_pb_image src=”https:\/\/richrijnders.com\/file\/2022\/05\/framework_13_drag-and-drop-soap-request-onto-test-case.png” title_text=”framework_13_drag-and-drop-soap-request-onto-test-case” show_in_lightbox=”on” _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][\/et_pb_image][\/et_pb_column][et_pb_column type=”1_2″ _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][et_pb_text _builder_version=”4.17.4″ _module_preset=”default” custom_padding=”79px|||||” global_colors_info=”{}”]<\/p>\n Right-click on the “DP_APIs” test suite and select “New Test Case” from the pop-up menu.\u00a0 Enter “ListActiveUsers” for the name and press “OK”.<\/p>\n Now expand the new test case until you see the “Test Steps” section. It should say (0) test steps currently.<\/p>\n Now drag-and-drop your ListActiveUsersSoap request and drop it onto the new “Test Steps” section as shown in the image to the left.<\/p>\n You will get a prompt window asking you to confirm that you want to add the request to the test case. Click “Yes”.<\/p>\n [\/et_pb_text][\/et_pb_column][\/et_pb_row][et_pb_row column_structure=”3_5,2_5″ admin_label=”Missing Interfaces Prompt” _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][et_pb_column type=”3_5″ _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][et_pb_image src=”https:\/\/richrijnders.com\/file\/2022\/05\/framework_13_add-missing-interfaces-prompt.png” title_text=”framework_13_add-missing-interfaces-prompt” show_in_lightbox=”on” _builder_version=”4.17.4″ _module_preset=”default” custom_padding=”23px|||||” global_colors_info=”{}”][\/et_pb_image][\/et_pb_column][et_pb_column type=”2_5″ _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][et_pb_text _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”]<\/p>\n The first time you copy a request from the SOMA project (xml-mgmt) to your DataPowerTools project, you will be notified that your project is missing the necessary\u00a0interfaces<\/em> for the SOMA request and it will prompt you to add them. Click “Yes”.<\/p>\n [\/et_pb_text][\/et_pb_column][\/et_pb_row][et_pb_row column_structure=”1_2,1_2″ admin_label=”Add Request Window” _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][et_pb_column type=”1_2″ _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][et_pb_image src=”https:\/\/richrijnders.com\/file\/2022\/05\/framework_13_add-request-to-test-case-window.png” title_text=”framework_13_add-request-to-test-case-window” show_in_lightbox=”on” _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][\/et_pb_image][\/et_pb_column][et_pb_column type=”1_2″ _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][et_pb_text _builder_version=”4.17.4″ _module_preset=”default” custom_padding=”55px|||||” global_colors_info=”{}”]<\/p>\n You will then be presented with the “Add Request to TestCase” window.\u00a0 You will note how it adds “operation -” to the front of the request name.\u00a0 You can remove that so the name remains “ListActiveUsersSoap”. Uncheck any of the other boxes that may be checked by default (some you cannot uncheck, that’s OK) and press “OK”.<\/p>\n [\/et_pb_text][\/et_pb_column][\/et_pb_row][et_pb_row column_structure=”1_2,1_2″ admin_label=”Current Project State” _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][et_pb_column type=”1_2″ _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][et_pb_image src=”https:\/\/richrijnders.com\/file\/2022\/05\/framework_13_after-copy-request-to-dp-apis.png” title_text=”framework_13_after-copy-request-to-dp-apis” show_in_lightbox=”on” _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][\/et_pb_image][\/et_pb_column][et_pb_column type=”1_2″ _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][et_pb_text _builder_version=”4.17.4″ _module_preset=”default” custom_padding=”38px|||||” global_colors_info=”{}”]<\/p>\n The request will be added to the TestCase and the request will be opened in a window in the editing pane.\u00a0<\/p>\n At this point, your project\u00a0should<\/em> look similar to the image to the left.<\/p>\n Now it’s time to create a\u00a0groovy<\/em> wrapper around this request that will make it into a reusable resource for your utilities.<\/p>\n Time to code!<\/p>\n [\/et_pb_text][\/et_pb_column][\/et_pb_row][\/et_pb_section][et_pb_section fb_built=”1″ admin_label=”ListActiveUsers Object” _builder_version=”4.16″ _module_preset=”default” custom_margin=”2px|||||” custom_padding=”4px||12px|||” global_colors_info=”{}”][et_pb_row admin_label=”Intro” _builder_version=”4.16″ _module_preset=”default” min_height=”122px” custom_margin=”0px|auto|9px|auto||” custom_padding=”10px||0px|||” global_colors_info=”{}”][et_pb_column type=”4_4″ _builder_version=”4.16″ _module_preset=”default” global_colors_info=”{}”][et_pb_text _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”]<\/p>\n So far we only have a usable SOAP request. You can certainly open up this request and run <\/em>it for each of your DataPower devices and look at the SOAP response for each invokation and see who is logged in. But we want to use and execute<\/em> this soap request for each DataPower device in a single operation and output readable messages to the soapUI log<\/em> window so we can quickly and easily check all of our devices at the same time and know who is logged in.<\/p>\n In order to write such a utility that will live in our “DP_Utils” TestSuite (are you seeing a pattern yet?) we will first put our ListActiveUsersSoap<\/em> SOAP request into an object wrapper that we can instaniate and use easily from any utility or report we write. This object wrapper<\/em> will be created as a\u00a0Test Script<\/em> and written in the\u00a0Groovy<\/em> language.<\/p>\n Let’s begin.<\/p>\n [\/et_pb_text][\/et_pb_column][\/et_pb_row][et_pb_row column_structure=”1_2,1_2″ admin_label=”Add Groovy Script” _builder_version=”4.16″ _module_preset=”default” custom_padding=”23px||4px|||” global_colors_info=”{}”][et_pb_column type=”1_2″ _builder_version=”4.16″ _module_preset=”default” global_colors_info=”{}”][et_pb_image src=”https:\/\/richrijnders.com\/file\/2022\/05\/framework_14_add-groovy-script.png” alt=”Screenshot: Enable XML Mgmt” title_text=”framework_14_add-groovy-script” show_in_lightbox=”on” align=”center” _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][\/et_pb_image][\/et_pb_column][et_pb_column type=”1_2″ _builder_version=”4.16″ _module_preset=”default” global_colors_info=”{}”][et_pb_text _builder_version=”4.17.4″ _module_preset=”default” min_height=”22px” global_colors_info=”{}”]<\/p>\n The first thing we are going to do is add a\u00a0Groovy<\/em> script along side our\u00a0ListActiveUsersSoap<\/em> request.<\/p>\n Right-Click on Test Steps<\/em> and select\u00a0Add Step -> Groovy Script <\/em>as shown in the screenshot to the left.<\/p>\n Name the new script\u00a0ListActiveUsers<\/em> and click “OK”. The\u00a0ListActiveUsers<\/em> groovy script will be added below the\u00a0ListActiveUsersSoap\u00a0<\/em>request in your\u00a0Test Steps\u00a0<\/em>and a blank groovy editor window will be opened.<\/p>\n [\/et_pb_text][\/et_pb_column][\/et_pb_row][et_pb_row column_structure=”1_2,1_2″ admin_label=”Object Class Construct” _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][et_pb_column type=”1_2″ _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][et_pb_text _builder_version=”4.17.4″ _module_preset=”default” custom_margin=”||-22px|||” custom_padding=”||0px|||” global_colors_info=”{}”]<\/p>\n So let’s first take a look at the groovy code that defines our basic reusable api object. This will be the same for all of our reusable api’s so you will become very familiar with it. After we understand this construct we will go back and add in the code that actually executes the ListActiveUsersSoap<\/em> SOAP request and returns the results.<\/p>\n (a)<\/span><\/strong> Standard program headers and footers – let’s not be lazy.<\/p>\n (b)<\/strong><\/span> Import some standard utilities and definitions. They both do exactly what they say.<\/p>\n (c)<\/strong><\/span> Here is where we define the reusable\u00a0object class\u00a0<\/em>and its properties. Later api’s may have additional properties, but they will *ALL<\/em> have these three properties at a minimum. In short, because the utilities we create will be scripts that will instantiate this object and execute its methods, we need to pass references to the calling script’s log, context, and testrunner<\/em> in order for our class to function as part of the callers run scope.<\/p>\n (d)<\/strong><\/span> Class Constructor.\u00a0 When the class is instantiated we set the object’s properties to the values passed in as arguments.<\/p>\n [\/et_pb_text][\/et_pb_column][et_pb_column type=”1_2″ _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][et_pb_image src=”https:\/\/richrijnders.com\/file\/2022\/05\/framework_15_list-active-users-object-framework.png” title_text=”framework_15_list-active-users-object-framework” show_in_lightbox=”on” _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][\/et_pb_image][\/et_pb_column][\/et_pb_row][et_pb_row _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][et_pb_column type=”4_4″ _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][et_pb_text _builder_version=”4.17.4″ _module_preset=”default” min_height=”178.8px” custom_padding=”8px|||||” global_colors_info=”{}”]<\/p>\n (e)<\/strong><\/span> runAPI()<\/em> method.\u00a0 This is where we actually execute the SOAP call. IE: the utility or report script will invoke this method each time it wants to make the ListActiveUsersSoap<\/em> call. We will add the required code for that in a moment, but you can immediately see that we will need to pass in a DataPower device name as the argument for each execution. You can also see that we need to instantiate a GroovyUtils<\/em> object based on the current context of the script that is calling this method. GroovyUtils is necessary in order to pass the SOAP response XML back to the calling script as an object.<\/p>\n (f)<\/strong><\/span>\u00a0important! <\/em><\/strong>You will note that this last line of code is outside of the class definition<\/em>.\u00a0 The reason for this is because utilities and reports that use this object will actually execute (run) this<\/em> script in order to both define and instantiate the class – they will not instantiate the object directly with the new()<\/em> operator.\u00a0 So running this script from any utility will load the class definition and then this single line at the end actually instantiates the object using the new() <\/em>operator, and assigns it to a context property <\/em>named “ListActiveUsers”. This property is then used by the utility or report script to access the methods of the class (as we will see later).<\/p>\n [\/et_pb_text][\/et_pb_column][\/et_pb_row][\/et_pb_section][et_pb_section fb_built=”1″ admin_label=”Executing the SOAP Call” _builder_version=”4.16″ _module_preset=”default” custom_margin=”2px|||||” custom_padding=”4px||12px|||” global_colors_info=”{}”][et_pb_row _builder_version=”4.16″ _module_preset=”default” min_height=”122px” custom_margin=”0px|auto|9px|auto||” custom_padding=”10px||0px|||” global_colors_info=”{}”][et_pb_column type=”4_4″ _builder_version=”4.16″ _module_preset=”default” global_colors_info=”{}”][et_pb_text admin_label=”Intro” _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”]<\/p>\n In order for our class to execute the\u00a0ListActiveUsersSoap<\/em> request we need it to do three things first:<\/p>\n <\/p>\n [\/et_pb_text][\/et_pb_column][\/et_pb_row][et_pb_row admin_label=”Create Request Object” _builder_version=”4.16″ _module_preset=”default” min_height=”122px” custom_margin=”0px|auto|9px|auto||” custom_padding=”10px||0px|||” global_colors_info=”{}”][et_pb_column type=”4_4″ _builder_version=”4.16″ _module_preset=”default” global_colors_info=”{}”][et_pb_image src=”https:\/\/richrijnders.com\/file\/2022\/05\/framework_15_code-create-request-object.png” title_text=”framework_15_code-create-request-object” show_in_lightbox=”on” admin_label=”Request Object Code” _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][\/et_pb_image][et_pb_text _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”]<\/p>\n So right below the line where we instantiate GroovyUtils,\u00a0<\/em>add the three lines of code as shown.\u00a0\u00a0<\/p>\n The first line,\u00a0def dp_apis<\/em>, creates a variable that points to our common API library, DP_APIs<\/em>.\u00a0\u00a0<\/p>\n The next line,\u00a0def api,<\/em> creates a variable that points to the actual\u00a0test step<\/em> that is our\u00a0ListActiveUsersSoap<\/em> request. You could do these two lines in one single step, but the line of code would be really long and I like to keep my code readable.\u00a0<\/p>\n Now that we have a variable that points to the soap request, the next line uses the\u00a0.testRequest<\/em> method to instantiate a request object that we can execute in our code.<\/p>\n [\/et_pb_text][\/et_pb_column][\/et_pb_row][et_pb_row column_structure=”1_2,1_2″ _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][et_pb_column type=”1_2″ _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][et_pb_image src=”https:\/\/richrijnders.com\/file\/2022\/05\/framework_15_auth-value-at-suite-level.png” title_text=”framework_15_auth-value-at-suite-level” show_in_lightbox=”on” _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][\/et_pb_image][\/et_pb_column][et_pb_column type=”1_2″ _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][et_pb_text _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”]<\/p>\n The next thing we need to do is add a\u00a0basic auth<\/em> header to our request.\u00a0 We did this back when we were testing the SOAP call so it should be familiar to you. Now, we could<\/em> just do as we did before and add the header to the SOAP request, itself. But if we ever change our password or credentials then we have to go back to\u00a0all<\/em> the SOAP requests in our common library and change them. For this reason, I prefer to save my basic auth credentials in a property at the\u00a0Test Suite<\/em> level and use code to add it dynamically to the request object at execution time.\u00a0<\/p>\n So go ahead and double-click the\u00a0DP_Utils<\/em> Test Suite. When the window opens, click on the\u00a0Properties<\/em> button towards the bottom and the click the “+” sign to add a property. Enter “__Authorization” for the property name and then add your basic auth base64 credentials for the value.\u00a0<\/p>\n [\/et_pb_text][\/et_pb_column][\/et_pb_row][et_pb_row _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][et_pb_column type=”4_4″ _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][et_pb_image src=”https:\/\/richrijnders.com\/file\/2022\/05\/framework_15_code-auth-header.png” title_text=”framework_15_code-auth-header” show_in_lightbox=”on” _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][\/et_pb_image][\/et_pb_column][\/et_pb_row][et_pb_row _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][et_pb_column type=”4_4″ _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][et_pb_text _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”]<\/p>\n Go ahead and add these four lines of code just below where we created the request object.\u00a0 The first line defines a variable named\u00a0authHeader<\/em> that points to the property at the TestSuite level where you just stored your basic auth string.\u00a0 The next line creates a temporary object from the headers of the request object we just instantiated above on line 40. This is necessary in order to manipulate the headers.\u00a0 The third line adds a header named Authorization<\/em> to our temporary object and assigns to it the basic auth value we just retrieved from the test suite property.\u00a0 The last line creates a string map of the temporary object and assigns that back to the headers of the actual request object. Four lines of code are not a bad trade-off for the convenience of soft-coding our basic auth credentials.\u00a0<\/p>\n [\/et_pb_text][\/et_pb_column][\/et_pb_row][et_pb_row _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][et_pb_column type=”4_4″ _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][et_pb_image src=”https:\/\/richrijnders.com\/file\/2022\/05\/framework_15_code-set-soap-endpoint.png” title_text=”framework_15_code-set-soap-endpoint” show_in_lightbox=”on” _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][\/et_pb_image][et_pb_text _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”]<\/p>\n So the last thing we need to do before executing the SOAP call is to override the SOAP request endpoint to send the request to the right DataPower device.\u00a0 This is the equivalent of the drop-down endpoint box at the top of the SOAP request test step.\u00a0 We use the string that is passed in as an argument to concatenate the connection string.\u00a0 The argument can be the DNS name of the device, the IP address of the device, or the name you associated with the devices IP address in your hosts<\/em> file (more on this later). After we have the connection string, we use the\u00a0.setEndpoint()<\/em> method of the request object to assign the string as the endpoint for the call.<\/p>\n Now that we have done all the preliminary work, it’s time to execute the\u00a0ListActiveUsersSoap<\/em> SOAP call.<\/p>\n [\/et_pb_text][\/et_pb_column][\/et_pb_row][et_pb_row _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][et_pb_column type=”4_4″ _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][et_pb_image src=”https:\/\/richrijnders.com\/file\/2022\/05\/framework_15_execute-soap-call-1.png” title_text=”framework_15_execute-soap-call” show_in_lightbox=”on” _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][\/et_pb_image][et_pb_text _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”]<\/p>\n We will put the execution of the SOAP call into a standard try\/catch construct.\u00a0 If an error occurs the catch block will print the error to the running\u00a0log<\/em> output. This is why we pass the calling scripts log object into the constructor of our class. Without that we cannot write messages to the log output of the running script.<\/p>\n To execute the SOAP call, we use the\u00a0.run()<\/em> method of the ListActiveUsersSoap<\/em> test step object (the one we instantiated as the “api” variable).\u00a0 We pass the method the\u00a0testRunner<\/em> and\u00a0context<\/em> objects that were passed in the constructor from the calling script.\u00a0 This ensures that the call is executed in the same scope as the calling script.<\/p>\n Next, we create a pointer to the SOAP response and place it into an XML Holder (remember that GroovyUtils thingy?).\u00a0 Although we can get the SOAP response and save it as an XML object, we no longer have the benefit of having the namespaces defined by the request so the next line of code manually defines that namespace and adds it to the XML Holder.\u00a0<\/p>\n And the last bit of business is to return that XML Holder to the calling script.\u00a0\u00a0<\/p>\n With that, we have completed the coding of the reusable api object. We can now execute this api call from any utility or report that we create without having to copy\/paste a good chunk of this same code into every one of them.\u00a0<\/p>\n <\/p>\n [\/et_pb_text][\/et_pb_column][\/et_pb_row][\/et_pb_section][et_pb_section fb_built=”1″ admin_label=”getDataPowerDeviceList” _builder_version=”4.16″ _module_preset=”default” custom_margin=”2px|||||” custom_padding=”4px||12px|||” global_colors_info=”{}”][et_pb_row _builder_version=”4.16″ _module_preset=”default” min_height=”122px” custom_margin=”0px|auto|9px|auto||” custom_padding=”10px||0px|||” global_colors_info=”{}”][et_pb_column type=”4_4″ _builder_version=”4.16″ _module_preset=”default” global_colors_info=”{}”][et_pb_text _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”]<\/p>\n One of the most common things that we will be doing with our utilities and reports is looping through groups of our DataPower devices to either perform the same function on all the devices in a group or to gather similar information from all the devices in the group.\u00a0 In the case of checking for logged-in users, we will be doing the latter – checking all our devices or a subset of them to see who is logged in. Most likely, we will be using a loop that iterates through a list of the device names and calls our api for each one.\u00a0 We can always create a list of our devices and manipulate it each time we use our utility in order to target the desired subset of devices, and that will work. Or…\u00a0or…\u00a0<\/em>we can create a common function that each utility or report can call to get the correct list of devices on-the-fly!\u00a0<\/p>\n Lo and behold, we have already created a place to put such non-api reusable functions: The “DP_Common” test suite.\u00a0<\/p>\n [\/et_pb_text][\/et_pb_column][\/et_pb_row][et_pb_row column_structure=”1_2,1_2″ _builder_version=”4.16″ _module_preset=”default” custom_padding=”23px||4px|||” global_colors_info=”{}”][et_pb_column type=”1_2″ _builder_version=”4.16″ _module_preset=”default” global_colors_info=”{}”][et_pb_image src=”https:\/\/richrijnders.com\/file\/2022\/05\/framework_16_common-functions.png” alt=”Screenshot: Enable XML Mgmt” title_text=”framework_16_common-functions” show_in_lightbox=”on” align=”center” _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][\/et_pb_image][\/et_pb_column][et_pb_column type=”1_2″ _builder_version=”4.16″ _module_preset=”default” global_colors_info=”{}”][et_pb_text _builder_version=”4.17.4″ _module_preset=”default” min_height=”22px” global_colors_info=”{}”]<\/p>\n When you hit enter, a blank editor window will appear so you can begin coding your groovy script. The Test Suite structure should look similar to the screenshot to the left.<\/p>\n Let’s see what that the structure of our common functions will look like.<\/p>\n [\/et_pb_text][\/et_pb_column][\/et_pb_row][et_pb_row column_structure=”1_3,2_3″ _builder_version=”4.16″ _module_preset=”default” min_height=”122px” custom_margin=”0px|auto|9px|auto||” custom_padding=”10px||0px|||” global_colors_info=”{}”][et_pb_column type=”1_3″ _builder_version=”4.16″ _module_preset=”default” global_colors_info=”{}”][et_pb_text _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”]<\/p>\n Right away we can see that the structure for common functions is going to be almost identical to that we used for our reusable api’s.\u00a0 We create a class definition with our three required properties (log, context, and testRunner) and we create a constructor method that sets those properties to the arguments passed. We also have the single line of code outside of and below the class definition that instantiates the class and assigns it to a context property so it can be used by the calling utility or report.<\/p>\n The difference here is that instead of a\u00a0runAPI()<\/em> method, we create a method that is our common function (a)<\/strong><\/span>.<\/p>\n <\/p>\n [\/et_pb_text][\/et_pb_column][et_pb_column type=”2_3″ _builder_version=”4.16″ _module_preset=”default” global_colors_info=”{}”][et_pb_image src=”https:\/\/richrijnders.com\/file\/2022\/05\/framework_16_get-device-list.png” title_text=”framework_16_get-device-list” show_in_lightbox=”on” _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][\/et_pb_image][\/et_pb_column][\/et_pb_row][et_pb_row _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][et_pb_column type=”4_4″ _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][et_pb_text _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”]<\/p>\n There is nothing that stops us from creating multiple methods in the class. If you wanted, you can create a single class containing multiple methods, one for each common function. But for our example, we will create one class with one common function, getList()<\/em>.\u00a0<\/p>\n [\/et_pb_text][\/et_pb_column][\/et_pb_row][et_pb_row column_structure=”1_3,2_3″ _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][et_pb_column type=”1_3″ _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][et_pb_text _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”]<\/p>\n As you can see, the function will return a\u00a0list[]<\/em> holding the names of DataPower devices (a)<\/strong><\/span>.\u00a0 We first create separate lists holding the names of the devices in our most oft used groupings (b)<\/strong><\/span>. If those names confuse you, check out my other tutorial on setting up better soapUI endpoints<\/a>. Or you can just put in the IP Addresses of your DataPower devices in similar groupings.\u00a0<\/p>\n Next we use a switch statement to return the correct list or combine different lists together based on the desired\u00a0group name<\/em> as input argument (c)<\/strong><\/span>. The\u00a0default<\/em> clause will just return the same string that was passed in as the group name. This allows the calling utility to pass in just the name of a single device if they wish and we will return it as a list so that the rest of the utility can function just on that one device. A good enhancement would be to validate the input argument string to make sure it is a valid device name or group name.<\/p>\n And then we just return the list object to the calling script (d).\u00a0<\/p>\n [\/et_pb_text][\/et_pb_column][et_pb_column type=”2_3″ _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][et_pb_image src=”https:\/\/richrijnders.com\/file\/2022\/05\/framework_16_get-list-method.png” title_text=”framework_16_get-list-method” show_in_lightbox=”on” _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][\/et_pb_image][\/et_pb_column][\/et_pb_row][\/et_pb_section][et_pb_section fb_built=”1″ admin_label=”ShowActiveUsers” _builder_version=”4.16″ _module_preset=”default” custom_margin=”2px|||||” custom_padding=”4px||12px|||” global_colors_info=”{}”][et_pb_row _builder_version=”4.16″ _module_preset=”default” min_height=”122px” custom_margin=”0px|auto|9px|auto||” custom_padding=”10px||0px|||” global_colors_info=”{}”][et_pb_column type=”4_4″ _builder_version=”4.16″ _module_preset=”default” global_colors_info=”{}”][et_pb_text admin_label=”intro” _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”]<\/p>\n So now that we have examples of a reusable api and a reusable common function, let’s create a utility that puts them to good use.\u00a0 We are going to create a utility named\u00a0ShowActiveUsers.\u00a0<\/em>I named it ShowActiveUsers <\/em>in order to distinguish the utility from the reusable api\u00a0ListActiveUsers<\/em> that it will be using. This utility will allow us to specify what group of DataPower devices to check (or all of them) and will write information about all the active (logged in) users to the soapUI log output.\u00a0<\/p>\n [\/et_pb_text][\/et_pb_column][\/et_pb_row][et_pb_row column_structure=”1_2,1_2″ _builder_version=”4.16″ _module_preset=”default” custom_padding=”10px||4px|||” global_colors_info=”{}”][et_pb_column type=”1_2″ _builder_version=”4.16″ _module_preset=”default” global_colors_info=”{}”][et_pb_image src=”https:\/\/richrijnders.com\/file\/2022\/05\/framework_17_create-showactiveusers.png” alt=”Screenshot: Enable XML Mgmt” title_text=”framework_17_create-showactiveusers” show_in_lightbox=”on” align=”center” _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][\/et_pb_image][\/et_pb_column][et_pb_column type=”1_2″ _builder_version=”4.16″ _module_preset=”default” global_colors_info=”{}”][et_pb_text _builder_version=”4.17.4″ _module_preset=”default” min_height=”22px” custom_padding=”51px|||||” global_colors_info=”{}”]<\/p>\n You should be familiar with this process by now, so go ahead and create the ShowActiveUsers<\/em> test case and test step under “DP_Utils”.<\/p>\n An empty editor will open so you can add your groovy code.<\/p>\n Your project navigator should now look similar to the screenshot here.\u00a0<\/p>\n <\/p>\n [\/et_pb_text][\/et_pb_column][\/et_pb_row][et_pb_row column_structure=”1_3,2_3″ _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][et_pb_column type=”1_3″ _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][et_pb_text _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”]<\/p>\n We will start our new utility with the standard header and import the XmlHolder object definition. Recall this is needed in order to get back the SOAP response as an XML object.<\/p>\n I always add a debugging flag that will trigger additional outputs that I add to my code (a)<\/strong><\/span>.\u00a0<\/p>\n We can set the name of the device group that we want to run the check against here (b)<\/strong><\/span>.<\/p>\n Along with your own user ID, there are usually other user ID’s, created for logging and monitoring accessing the device. These will also be returned every time you run the API. we are not interested in those usually, so we add a list of user ID’s that will be ignored when generating the output (c)<\/strong><\/span>.<\/p>\n [\/et_pb_text][\/et_pb_column][et_pb_column type=”2_3″ _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][et_pb_image src=”https:\/\/richrijnders.com\/file\/2022\/05\/framework_17_code-showactiveusers-1.png” title_text=”framework_17_code-showactiveusers-1″ show_in_lightbox=”on” _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][\/et_pb_image][\/et_pb_column][\/et_pb_row][et_pb_row _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][et_pb_column type=”4_4″ _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][et_pb_image src=”https:\/\/richrijnders.com\/file\/2022\/05\/framework_17_code-showactiveusers-2.png” title_text=”framework_17_code-showactiveusers-2″ show_in_lightbox=”on” _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][\/et_pb_image][\/et_pb_column][\/et_pb_row][et_pb_row _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][et_pb_column type=”4_4″ _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][et_pb_text _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”]<\/p>\n Next is where we define and instantiate our common API and function.\u00a0 First, we define variables that point to the common API and common function TestSuites, “DP_APIs” and “DP_Common” respectively (d)<\/span><\/strong>.<\/p>\n Then (e)<\/strong><\/span> we set a variable to the common function TestStep\u00a0GetDataPowerDeviceList\u00a0<\/em>and execute it using the run()<\/em> method. This instantiates the object and sets a context variable pointing to it so that the following line can set a program variable to the same so we can access it directly.\u00a0<\/p>\n The next block does the same things, but for the\u00a0ListActiveUsers<\/em> API (f)<\/strong><\/span>.\u00a0 Now our common function and common API are fired up and ready to use.<\/p>\n [\/et_pb_text][\/et_pb_column][\/et_pb_row][et_pb_row column_structure=”1_3,2_3″ _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][et_pb_column type=”1_3″ _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][et_pb_text _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”]<\/p>\n Here we get to the where the action is.\u00a0 Most of your utilities and reports will be some variation of this basic construct.\u00a0<\/p>\n First (g)<\/strong><\/span> we execute the common function method to retrieve the list of DataPower devices we want to execute our utility against.\u00a0<\/p>\n (h)<\/strong><\/span> We initalize a simple counter variable so that later we can output a total number of active users. We also write out a preamble to the log to remind us what this utility is for.\u00a0<\/p>\n (i)<\/strong><\/span> This is where most of our work takes place. This loop iterates through the list of DataPower device names that we retrieved from our common function. This is where we will execute the common API to check for active users on all of desired devices. We will insert and discuss that code next.<\/p>\n [\/et_pb_text][\/et_pb_column][et_pb_column type=”2_3″ _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][et_pb_image src=”https:\/\/richrijnders.com\/file\/2022\/05\/framework_17_code-showactiveusers-3.png” title_text=”framework_17_code-showactiveusers-3″ show_in_lightbox=”on” _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][\/et_pb_image][\/et_pb_column][\/et_pb_row][et_pb_row column_structure=”1_3,2_3″ _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][et_pb_column type=”1_3″ _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][et_pb_text _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”]<\/p>\n So let’s add some code inside this loop that will execute for each DataPower device.\u00a0 First we just initialize some working variables (j)<\/strong><\/span>.\u00a0 The first one is just a counter to keep track of how many active users we found on this device. The second is just a flag to let my code know if I have output a header message for this device yet.\u00a0<\/p>\n Next (k)<\/strong><\/span> we output a message (if the debugOn flag is true) so we know what iteration of the loop is executing.<\/p>\n (L)<\/strong><\/span> And here we go ahead and execute the common API, passing in the device name as an argument. The result XML is directly assigned to the “xml_ListActiveUsers” variable.<\/p>\n [\/et_pb_text][\/et_pb_column][et_pb_column type=”2_3″ _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][et_pb_image src=”https:\/\/richrijnders.com\/file\/2022\/05\/framework_17_code-showactiveusers-4.png” title_text=”framework_17_code-showactiveusers-4″ show_in_lightbox=”on” _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][\/et_pb_image][\/et_pb_column][\/et_pb_row][et_pb_row column_structure=”1_3,2_3″ _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][et_pb_column type=”1_3″ _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][et_pb_text _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”]<\/p>\n Having executed the API request and received the response, we now need to loop through the xml elements for each active user ID on the device (m)<\/strong><\/span>. Read this for an in-depth explanation<\/a> of how this works.<\/p>\n Note here (n)<\/strong><\/span> that we are skipping any user ID’s if they are found in our\u00a0skipUsers[]<\/em> list.\u00a0\u00a0<\/p>\n Finally, we output the user ID details to the log (o)<\/strong><\/span>.<\/p>\n [\/et_pb_text][\/et_pb_column][et_pb_column type=”2_3″ _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][et_pb_image src=”https:\/\/richrijnders.com\/file\/2022\/05\/framework_17_code-showactiveusers-5.png” title_text=”framework_17_code-showactiveusers-5″ show_in_lightbox=”on” _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][\/et_pb_image][\/et_pb_column][\/et_pb_row][et_pb_row column_structure=”1_2,1_2″ _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][et_pb_column type=”1_2″ _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”][et_pb_text _builder_version=”4.17.4″ _module_preset=”default” global_colors_info=”{}”]<\/p>\n For completeness, we add some code to increment the counter for the number of active users and output that information to the log, as well.<\/p>\n And that completes the\u00a0The Pieces<\/h2>\n
\n
IBM DataPower<\/h3>\n
SoapUI<\/h3>\n
Apache Groovy<\/h3>\n
IBM SOMA and AMP WSDL’s<\/h3>\n
Enabling the XML Mgmt Interface on DataPower<\/h2>\n
\n
Setup SoapUI Workspace<\/h2>\n
\n
Download SOMA and AMP WSDL’s<\/h2>\n
\n
Import SOMA and AMP WSDL’s Into SoapUI<\/h2>\n
List Active Users SOAP Request<\/h2>\n
\n
ListActiveUsers Reusable Object<\/h2>\n
\n
Executing the SOAP Call<\/h2>\n
\n
A Non-API Reusable Function<\/h2>\n
\n
Utility: ShowActiveUsers<\/h2>\n
\n