ZExplore Development Interface (ZEDI) User Guide Feb 2013

Transcription

1 ZExplore Development Interface (ZEDI) User Guide Feb 2013

2 Table of Contents 1 OVERVIEW 3 2 GUI COMPONENTS 4 3 CONNECT TO AN API SERVER CONNECT TO DATA ONTAP SERVER SELECT TRANSPORT TYPE HTTP/HTTPS VFILER OR VSERVER TUNNELING CONNECT TO DATAFABRIC MANAGER SERVER SELECT TRANSPORT TYPE HTTP/HTTPS 8 4 GENERATE XML REQUEST METHODS TO GENERATE XML RIGHT CLICK -> GENERATE GENERATE ARROW BUTTON DRAG-AND-DROP 11 5 EXECUTE AN API VIEW API EXECUTION RESPONSE XML FORMAT TREE FORMAT 13 6 GENERATE SAMPLE CODES 14 7 OTHER FEATURES SAVE & SAVE ALL IMPORT EXPORT RIGHT CLICK ON A WORKFLOW TAB ADDED APIS WORKFLOWS PROMPT TO SAVE UNSAVED WORKFLOWS WHILE QUITTING ZEDI LAUNCHES IN THE SAME STATE/SETTINGS AS IT WAS CLOSED 21 8 MENU FILE EDIT PREFERENCES HELP 23 9 RUN ZEDI ON LINUX 23 2

3 1 Overview ZEDI is a utility with graphical user interface bundled with NetApp Manageability SDK (NMSDK). This utility enables you to test DATA ONTAP APIs and OnCommand Unified Manager APIs. This utility allows you to generate raw XML request for any given API. You can supply necessary arguments in the XML request before invoking the API through HTTP or HTTPS and you can view the response in raw XML format or tree format. Additionally, for a given API, the utility can generate sample codes in Java, Perl, C, C#, Python and Ruby to demonstrate how the said API can be invoked using NMSDK Core APIs. You can choose to include comments (API documentation descriptions) and/or optional parameters while generating the XML request and sample codes. You can generate workflows by sequencing multiple APIs in logical order. It also supports vfiler and Vserver tunneling, which enables a DATA ONTAP API to be invoked directly on a vfiler or a Vserver respectively. 3

4 2 GUI Components Various graphical user interface components of ZEDI are shown below. Generate New Workflow Save current workflow Save all Open workflows Import a Workflow Export Selected Workflow Connect to DATA ONTAP or DataFabric Manager XML Request Editor Execute selected workflow on a connected server XML Response Viewer Connection Tab API explorer Add a value to selected parameter Sample Codes Response in Tree format Generate codes for selected nodes Move the node up Filter APIs displayed using a regular expression Move the node down List of APIs added to currently selected workflow in execute or develop tab Lists all the canned, imported, saved and unsaved workflows Delete the node Filter added APIs using a regular expression Status Bar Take the cursor on an API to see the API documentation. Expand the API to see the list of input and output parameters. Input parameters are preceded by arrow Output parameters are preceded by arrow Red colored arrows indicate mandatory parameters whereas Blue colored arrows indicate optional parameters. 4

5 Note: In some APIs when either one of the two input parameters is required, both these input parameters are marked by Blue color arrow and not Red. 5

6 3 Connect to an API server You can either click the "Connect" button (lightening icon) on the toolbar or select the "Connect" option from the "Preferences" menu to get a popup window as shown below: ZEDI will not automatically decide the server type. You need to select appropriate server type from the radio button. 3.1 Connect to DATA ONTAP server In order to connect to a Data ONTAP server, select the Data ONTAP radio button (marked by default). Enter the storage system hostname or IP address in the input box with the label Server and provide the Username and Password in the corresponding input boxes. Click the Connect button to connect to the storage system. You can also choose to save your connection details and load the saved connection details next time instead of entering the details every time. You can load a saved connection by both double clicking on a saved connection in the Manage connections tab or by selecting a connection and clicking on load. The password field will need to be populated even for a saved connection. You can delete a saved connection. Connections are not saved by default. You need to give the current connection a name and click on Save to store the connection details. You can also set a timeout for the connection in the advanced tab. Once the connection is established, the correct API definitions corresponding to the ONTAPI version will be loaded on the API Explorer. The Status Bar will indicate the connection status and display the hostname, username, the port number, transport protocol and the version information. 6

7 3.1.1 Select Transport type HTTP/HTTPS Click on Advanced button to select the Transport type HTTP For making API invocations using HTTP, select HTTP from the Transport dropdown menu (default is HTTPS). The default HTTP port number (80 for Data ONTAP) is automatically selected as the port for API invocation. In case, the storage system is listening to a different port for HTTP connections, enter the changed port number at the Port field. Uncheck the Use vfiler or Vserver tunneling check-box (it is unchecked by default) when vfiler or Vserver tunneling feature is not being used. Click the Connect button to connect to the storage system using HTTP HTTPS The steps for connecting to a Data ONTAP server using HTTPS is exactly same as those for connecting using HTTP, except for the Transport protocol selection part. You need to choose HTTPS from the Transport drop-down menu. The default port number (443 for Data ONTAP) for HTTPS connection is automatically populated in the Port field. In case, the storage system is not listening to the default port for HTTPS, you can enter the updated port number. 7

8 3.1.2 vfiler or Vserver Tunneling Click on Advanced button to see this option. Vserver - The mechanism of accessing Vserver APIs through a clustermanagement interface is called Vserver tunneling. Cluster administrator can administer Vservers from the Vserver context by using Vserver tunneling in NMSDK. After setting up a functional Vserver or a Vserver with basic network configuration, you can optionally delegate the administration of the Vserver to a Vserver administrator. You can delegate Vserver administration by creating and assigning user accounts either with predefined roles or customized roles. Vserver administrator can directly connect to Vserver IP using the appropriate username and password to execute Vserver APIs. vfiler vfiler tunneling is a Data ONTAP feature that allows you to invoke an ONTAP API on a vfiler through the physical storage system on which the vfiler is contained. This means that in order to execute an API on a vfiler, you need not connect to the vfiler itself (though it is also an option). You can simply connect to the physical storage system and tunnel the API request to the vfiler. This feature is supported from ONTAPI 1.7 onwards. To use this feature, you need to enable the vfiler or Vserver tunneling, which is disabled by default, before you generate and execute an API. Just check the Use vfiler or Vserver tunneling checkbox and provide the vfiler or Vserver hostname or IP address in the input box labeled as vfiler unit or Vserver name. Now, when you execute the API, it will be tunneled through the physical storage system to the vfiler or Vserver unit. 3.2 Connect to DataFabric Manager server For establishing a connection with DataFabric Manager server, select the DataFabric Manager server radio button. You need to provide the DataFabric Manager server hostname or IP address in the input box labeled with Server along with the Username and Password. Click the Connect button to set the connection. ZEDI will automatically determine the DataFabric Manager server version and load the corresponding API definitions on the API Explorer. The Status Bar will indicate the connection status and display the hostname, username, the port number, transport protocol and the version information Select Transport type HTTP/HTTPS Click on Advanced button to select the Transport type. 8

9 HTTP In order to use HTTP for connecting to the DataFabric Manager server, opt for HTTP from the Transport drop-down menu. The default port number (8088) for DataFabric Manager HTTP connection is automatically populated in the Port field. Modify the port number only if the server is listening to a different port number for the given transport protocol HTTPS To connect to a DataFabric Manager server using HTTPS, select HTTPS as the transport protocol in the Transport drop-down menu in the DataFabric Manager Connection Panel. The default port number (8488) for DataFabric Manager HTTPS connection is automatically populated in the Port field. Modify the port number only if the server is listening to a different port number for the given transport protocol. 4 Generate XML Request To generate XML request for an API, you need not connect to an API server. However, to send the XML request to an API server, you do need an active connection with the server (as discussed in Section 3). You can choose any API version (both ONTAPI and DFM API) from the API Explorer drop-down menu, irrespective of whether ZEDI is connected to one or more API servers. Once you choose an API version, corresponding API definitions will be loaded in the API Explorer window. The definitions are loaded in expandable tree format with all the API categories showing up at the top level. Instead of choosing from the API Explorer drop-down menu, if you connect to an API server, ZEDI will automatically load the correct API definitions in the API Explorer window. Alternatively, you can add new API documentation by selecting the Add New Api Document option as shown in the figure below. 9

10 ZEDI will remember the path of the added api document and load it when Remember the path of the API document during subsequent launches is checked. You can find the latest ZEDI API doc at edi. 4.1 Methods to generate XML Right Click -> Generate Depending on the API for which XML input and sample code has to be generated, you can expand the API category from the tree of categories displayed in the "API Explorer" pane. This lists all the APIs falling under the expanded category. You select the API for which XML input and sample code has to be generated and right-click on the API. This brings up a popup menu containing the only item "Generate". 10

11 Click on the "Generate" option. This creates the XML input in the currently selected workflow tab in "Execute" pane. The sample code is also generated at the same time in the currently selected workflow tab in "Develop" pane Generate Arrow Button "Right Arrow" button (hereafter called the "Generate" button) is located beside the drop-down box for API version selection in the "API Explorer" pane. Expand the API category (discussed above in Section 4.1.1), selects the required API and clicks the "Generate" button to generate corresponding XML input in the currently selected workflow tab in "Execute" pane and sample codes in corresponding workflow tab in "Develop" pane. You can use "Ctrl" key to select multiple API and generate the XML inputs and sample codes at the same time. The order in which the APIs are selected will be retained during the generation of XML inputs and sample codes (discussed in more detail in Section 7.4) Drag-and-Drop Drag-and-Drop option for XML input and sample code generation is also provided in ZEDI. In order to use this mechanism, you have to expand the API category (discussed above in Section 4.1.1) and then you can drag the APIs under question and drop it to the currently selected workflow tab in the "Execute" pane to see the generated XML input and sample codes in "Execute" pane and "Develop" pane respectively. 11

12 5 Execute an API If the server is connected, you can execute the API or a series of APIs (i.e. workflow) by clicking the "Execute" button (last icon on the toolbar, next to lightening "Connect" icon) on the toolbar. If there are multiple workflows (identified by the individual tabs under "Execute/Develop" pane), the workflow under currently selected workflow tab will be executed, and not all of them. If there are multiple APIs in the currently executed workflow, each of the APIs will be executed all at once (this is the default behavior which can be changed from the options menu). The results will be updated in the Output (XML/Tree) pane in the order of API invocation. If there is a failure in invocation of API, ZEDI will not stop the invocation of subsequent APIs (if any) unless it is in single invocation mode (see options under preferences). You can see which API failed from the Output pane. Three APIs are listed in the Execute tab above. We can execute them by clicking on Execute button and see the output in XML and Tree format. If you would like to execute multiple APIs in single invocation, you can check execute multiple APIs in single invocation in options under the preferences menu. Please see Section 8.3 for more information. The execution time of the workflow and the number of APIs that executed successfully will be updated on the right side of the Status Bar. 5.1 View API Execution Response All three APIs executed successfully. We can see the output below. 12

13 5.1.1 XML Format To view the raw XML response returned by the API server on executing an API, select the XML tab from the Response Viewer Tabs Tree Format To view the API invocation response in tree format, select the Tree tab from Response Viewer Tabs. 13

14 6 Generate Sample Codes The steps for generating sample codes are same as those for generating XML request (as mentioned in Section 4). However, to view the generated sample codes, you need to select the Develop Tab. The language can be selected and set from the "Preference" menu as shown below: ZEDI supports sample code generation in C, C#, Java, Perl, Python, and Ruby. 14

15 7 Other Features 7.1 Save & Save All You can "Save" the generated workflow by clicking the "Save" button (single floppy disk icon) on the toolbar or the Save option from the File menu. If there are multiple workflows to be saved at the same time, you can click the "Save All" button (three stacked floppy disks icon) on the toolbar or the "Save All" option from the "File" menu as shown below: The workflows are saved as XML files at the Workflows Path location set by you at the "Preferences" menu. Default location is the current working directory of ZEDI. 7.2 Import You can load saved workflows using the "Import" option available on the toolbar and also on the "File" menu. Imported workflows will show up in the under the "Workflows" tab along with canned workflows. On importing a workflow, the XML input structure will be loaded on a new workflow tab under Execute pane and the corresponding sample codes are also auto-generated at the same time and available under the "Develop" tab. An imported workflow 15

16 7.3 Export If you want to save the XML code or sample code for the language set (through Preferences -> Languages as discussed above in Section 6) for current workflow, you can use the "Export" button on the toolbar or use the "Export" option from the "File" menu. This option exports/saves sample code. If you use the export icon on the toolbar and if Develop tab is selected, it will export the language sample code with proper extension (e.g. Java sample code is saved with.java extension) at the location specified by you and if the Execute tab is selected, it will export the XML code. The exported XML code can be imported back to ZEDI. See Section 7.2 for more details. 7.4 Right click on a workflow tab 16

17 When you right click on a workflow tab a menu shows up. The functionality of each item in the menu is as follows: Save Saves the select workflow. See section 7.1 for more details. Save As Saves your workflow to a location of your choice and renames the workflow to a name given by you while saving this workflow. Subsequent saves will save the workflow in this location. Save All Saves all open unsaved workflows. See section 7.1 for more details. Clone is a feature you can use to make a copy of the current tab in a new tab. The same API(s) along with the xml and code is copied on to a new tab. Close Closes the current workflow tab. ZEDI will prompt you to save it if it is unsaved. Close Other Tabs Closes all other workflow tabs except for the selected one. If any of the workflows being closed are unsaved ZEDI will prompt you to save it. Undo Close Tab In case you mistakenly close a workflow tab you can undo that action by this option. If there is no tab closed in current launch session, this option will be disabled. You cannot perform this action for a tab closed in a previous ZEDI launch session. Delete Closes the selected workflow and deletes it from the disk. ZEDI will prompt you to confirm this action. Once confirmed this action is irreversible. If the workflow tab has not been saved then ZEDI will show a prompt asking you if you would like to close the selected tab or cancel this action. Delete All Closes all saved workflows and deletes them from the disk. ZEDI will prompt to confirm this action along with some other options. Import Import a workflow. See section 7.2. Export Export this workflow. See section 7.3. Connect - Connect to a server. See section 3. Execute - Execute the current workflow. See section Added APIs With ZEDI you can generate a series of XML inputs (and hence sample codes) from multiple APIs to generate a workflow. You can use any or all of the methods (discussed above in Section 4 & Section 6) to generate the XML inputs and sample codes for the APIs. You can use "Ctrl" key to select multiple API and generate the XML inputs and sample codes at the same time. The order in which the APIs are selected will be retained during the generation of XML inputs and sample codes. You can add one or more APIs to a workflow having one or more APIs already added to it. Newly added APIs are always appended at the end of existing workflow. 17

18 Added APIs will show up in the "Added APIs" tab (next to "Execute/Develop" pane) as shown below: As seen in the above diagram, the "Added APIs" has the following components (which are also available for "Workflows" tab): Edit Button Insert value for input parameters. See below for more details. Left Arrow Button - This generates the XML input structure and sample codes for the selected API in the current workflow. This button can also be used to duplicate (re-generate) input parameters within an API. Up Arrow Button This moves the selected API up. This button can also be used to move an input parameter up in the list of input parameter within an API. The change is also reflected in the current workflow as well as in the generated sample codes. Down Arrow Button - This moves the selected API down. This button can also be used to move an input parameter up in the list of input parameter within an API. The change is also reflected in the current workflow as well as in the generated sample codes. "X" Button - This deletes the API from the list of the APIs. This button can also be used to delete an input parameter. The change is also reflected in the current workflow as well as in the generated sample codes. Value for Input parameters can be provided in the right pane, which is reflected in both XML and Generated Code. To do so: Right click on the parameter and click on edit. Then enter the value for the parameter in the value field of the window that opens once you click edit. 18

19 It is note-worthy that generating an API multiple times will result in multiple entries of the same API in the "Added APIs List" while retaining the order in which it is regenerated. 7.6 Workflows Sample workflows will be bundled as part of ZEDI. The list of canned workflows will be listed in the "Workflows" pane (beside "Execute/Develop" pane) as shown below: You can select the workflow and then click on the "Generate" button (left arrow in the "Workflows" pane) to generate the XML input structure in "Execute" pane and corresponding sample code in "Develop" pane. The canned workflows cannot be deleted. However, they can be modified and saved as new workflows. Canned workflows will be marked with green flag icon while the custom workflows will be marked with single book icon. Imported workflows are represented with "Two overlapping pages" icon. 19

20 All unsaved workflows have an asterisk (*) suffixed to their name. When you save an unsaved workflow (imported or manually generated), the asterisk disappears immediately to indicate that the workflow is saved. Also, when any change is done in a saved workflow (imported or manually generated), the asterisk appears with the workflow name to show that it is unsaved. 7.7 Prompt to save unsaved workflows while quitting In case you try to quit ZEDI without saving any workflows, ZEDI will prompt you to save (or choose to not save) them. It lists the unsaved workflow(s) with workflow name and the file location to contain the XML content for the workflow. Each workflow name in the list is accompanied by a check-box. By default, all the workflows (check-boxes) are selected. If ZEDI fails to save a workflow due to any reason (say, I/O failure), ZEDI does not exit and throws an error message dialog (not shown here) stating the reason of the failure and the file(s) not saved. ZEDI then displays the "Save Unsaved Workflows" dialog with the list (same or smaller list compared to previous list) of unsaved workflow. Attempt to save the workflows may result in same behavior and you may get into a loop. In such a case, you need to deselect (uncheck) the file(s) causing the 20

21 issue and try to "Save Selected". If even if that fails, you need to press the "Save None, Exit" button. 7.8 ZEDI launches in the same state/settings as it was closed ZEDI remembers the state/settings with which ZEDI was closed previously. When you launch ZEDI next: It uses the same preferred language of code generation. It uses the same Options Settings. It has the same Workflow Path. It is loaded with the same API version. It has the same saved workflow tabs along with its inputs provided if any. It preserves all imported workflows in workflows tab. Please note that ZEDI uses Operating System specific backing store (e.g. registry in Windows). If for some reason these entries are deleted or edited, ZEDI will show an error message and will load with its default settings. 8 Menu 8.1 File New is to generate a new workflow; it has the same function as the New icon (first on toolbar). All other File menu options are discussed above in Section Edit You can clear the Execute or Develop pane using Clear All option. 21

22 8.3 Preferences Various configuration preferences and options are under this Menu. Out of the four menu items currently available, three (Connect, Languages and Workflows Path) have been already discussed in previous sections. The "Options" menu item pops up a window containing the options shown below: By default, inclusion of comments (API element descriptions) is disabled in code generation. To enable this check the Include comments in generated code checkbox in the Options Panel and press Save Changes button. To disable it, uncheck the checkbox and press Save Changes. To include optional parameters in sample code generation, check Include optional elements in code generation checkbox. Press the Save Changes button and generate the sample code to see the included optional elements. This can be disabled by un-checking the said checkbox and pressing Save Changes before generating the sample codes. 22

23 Iterator Comprehension - For iterative APIs, fetches the complete list of iterative results at one instance. It is enabled by default. Iterator Fetch Size sets the maximum number of iterative results that can be fetched at one instance. Multiple APIs in Single Invocation o Sequential Invocation - By default, APIs will execute sequentially (one after another) in ZEDI i.e. in your preferred order it exists in your workflow. Only after the result of the first API is received from the server will ZEDI send the next API. In case any API fails (or for any other reason) you can choose to abort further execution. o Single Invocation When Multiple APIs in Single Invocation option is checked, consider that your request would be sent in one packet to the server. The APIs in the workflow may not execute in your preferred order. 8.4 Help It contains two items as shown below: On selecting the first item, User Guide for ZEDI shows up in a different window. The "About" menu item provides the version information and copyright notice. 9 Run ZEDI on Linux zexplore.jar will be provided (under <nmsdk_root>/zedi/) which Linux users can run with Java to get the full functionality of ZEDI. 23