Documentation updates

README

@@ -11,6 +11,12 @@ client library provides a high level wrapper for invoking ePO remote commands vi
 The purpose of this library is to allow users to invoke ePO remote commands without having to focus
 on lower-level details such as ePO-specific DXL topics and message formats.
 
+This client requires an ePO DXL service to be running and available on the DXL fabric.
+
+A Python-based implementation of an ePO DXL service is available here:
+
+* `McAfee ePolicy Orchestrator (ePO) DXL Python Service <https://github.com/opendxl/opendxl-epo-service-python>`_
+
 Documentation
 -------------
 

dist.py

@@ -49,6 +49,11 @@
 print("\nCalling sphinx-build\n")
 subprocess.check_call(["sphinx-build", "-b", "html", DIST_DOCTMP_DIR, os.path.join(DIST_DIRECTORY, "doc")])
 
+# Delete .doctrees
+remove_tree(os.path.join(os.path.join(DIST_DIRECTORY, "doc"), ".doctrees"), verbose=1)
+# Delete .buildinfo
+os.remove(os.path.join(os.path.join(DIST_DIRECTORY, "doc"), ".buildinfo"))
+
 # Move README.html to root of dist directory
 print("\nMoving README.html\n")
 move_file(os.path.join(DIST_DOCTMP_DIR, "README.html"), DIST_DIRECTORY)

doc/sdk/basiccorehelpexample.rst

@@ -0,0 +1,99 @@
+Basic Core Help Example
+========================
+
+This sample invokes and displays the results of the "core help" remote command via the ePO DXL service.
+The "core help" command lists the remote commands that are exposed by a particular ePO server.
+
+
+Prerequisites
+*************
+* The samples configuration step has been completed (see :doc:`sampleconfig`)
+* The ePO DXL service is running and available on the fabric (see `ePO DXL Python Service <https://github.com/opendxl/opendxl-epo-service-python>`_)
+* The client is authorized to invoke the ePO DXL Service (see `ePO DXL Service Client Authorization <https://opendxl.github.io/opendxl-epo-service-python/pydoc/authorization.html#client-authorization>`_)
+
+Setup
+*****
+
+Modify the example to include the `unique identifier` associated with the ePO to invoke the remote command on.
+
+For more information on the ePO unique identifier, refer to the following:
+
+* `Configuration File for ePO DXL Python Service (uniqueId property) <https://opendxl.github.io/opendxl-epo-service-python/pydoc/configuration.html#dxl-service-configuration-file-dxleposervice-config>`_
+*  The :func:`dxlepoclient.client.EpoClient.lookup_epo_unique_identifiers` method which will return a ``set``
+   containing the identifiers for all ePO servers that are currently connected to the fabric.
+
+For example:
+
+    .. code-block:: python
+
+        EPO_UNIQUE_ID = "epo1"
+
+If only one ePO server is connected to the DXL fabric this constant can be set to ``None`` (the client will
+automatically determine the ePO's unique identifier).
+
+Running
+*******
+
+To run this sample execute the ``sample/basic/basic_core_help_example.py`` script as follows:
+
+    .. parsed-literal::
+
+        python sample/basic/basic_core_help_example.py
+
+The output should appear similar to the following:
+
+    .. code-block:: python
+
+        ComputerMgmt.createAgentDeploymentUrlCmd deployPath groupId [edit] [ahId]
+        [fallBackAhId] [urlName] [agentVersionNumber] [agentHotFix] - Create Agent
+        Deployment URL Command
+        ComputerMgmt.createCustomInstallPackageCmd deployPath [ahId] [fallBackAhId] -
+        Create Custom Install Package Command
+        ComputerMgmt.createDefaultAgentDeploymentUrlCmd tenantId - Create Default
+        Non-Editable Agent Deployment URL Command
+        ComputerMgmt.createTagGroup parentTagGroupId newTagGroupName - Create a new
+        subgroup under an existing tag group.
+        ComputerMgmt.deleteTag tagIds [forceDelete] - Delete one or more tags.
+        ComputerMgmt.deleteTagGroup tagGroupIds [deleteTags] - Delete one or more Tag
+        Groups.
+        ComputerMgmt.listAllTagGroups - List All Tag Groups in Tag Group Tree
+        ComputerMgmt.moveTagsToTagGroup tagIds tagGroupId - Move tags to an existing tag
+        group.
+
+        ...
+
+Each remote command exposed by the particular ePO server is listed along with its associated parameters.
+
+Details
+*******
+
+The majority of the sample code is shown below:
+
+    .. code-block:: python
+
+        # The ePO unique identifier
+        EPO_UNIQUE_ID = None
+
+        # Create the client
+        with DxlClient(config) as client:
+
+            # Connect to the fabric
+            client.connect()
+
+            # Create the ePO client
+            epo_client = EpoClient(client, EPO_UNIQUE_ID)
+
+            # Display the help
+            print epo_client.help()
+
+
+Once a connection is established to the DXL fabric, a :class:`dxlepoclient.client.EpoClient` instance is created
+which will be used to invoke remote commands on the ePO server. The `unique identifier` of the ePO server
+to invoke remote commands on is specified as an argument to the client constructor. In this particular case, a
+value of ``None`` is specified which triggers the client to automatically determine the ePO server's unique identifier.
+This will not work if multiple ePO servers are connected to the fabric (an exception will be raised).
+
+Next, the results of invoking the :func:`dxlepoclient.client.EpoClient.help` method are displayed to the screen.
+
+
+

doc/sdk/basicsystemfindexample.rst

@@ -0,0 +1,120 @@
+Basic System Find Example
+=========================
+
+This sample invokes and displays the results of a "system find" remote command via the ePO DXL service.
+The results of the find command are displayed in JSON format.
+
+Prerequisites
+*************
+* The samples configuration step has been completed (see :doc:`sampleconfig`)
+* The ePO DXL service is running and available on the fabric (see `ePO DXL Python Service <https://github.com/opendxl/opendxl-epo-service-python>`_)
+* The client is authorized to invoke the ePO DXL Service (see `ePO DXL Service Client Authorization <https://opendxl.github.io/opendxl-epo-service-python/pydoc/authorization.html#client-authorization>`_)
+* The user that is connecting to the ePO server (within the ePO DXL service) has permission to execute the
+  "system find" remote command
+
+Setup
+*****
+
+Modify the example to include the `unique identifier` associated with the ePO to invoke the remote command on.
+
+For more information on the ePO unique identifier, refer to the following:
+
+* `Configuration File for ePO DXL Python Service (uniqueId property) <https://opendxl.github.io/opendxl-epo-service-python/pydoc/configuration.html#dxl-service-configuration-file-dxleposervice-config>`_
+*  The :func:`dxlepoclient.client.EpoClient.lookup_epo_unique_identifiers` method which will return a ``set``
+   containing the identifiers for all ePO servers that are currently connected to the fabric.
+
+For example:
+
+    .. code-block:: python
+
+        EPO_UNIQUE_ID = "epo1"
+
+If only one ePO server is connected to the DXL fabric this constant can be set to ``None`` (the client will
+automatically determine the ePO's unique identifier).
+
+Modify the example to include the search text for the system find command.
+
+For example:
+
+    .. code-block:: python
+
+        SEARCH_TEXT = "broker"
+
+
+Running
+*******
+
+To run this sample execute the ``sample/basic/basic_system_find_example.py`` script as follows:
+
+    .. parsed-literal::
+
+        python sample/basic/basic_system_find_example.py
+
+The output should appear similar to the following:
+
+    .. code-block:: python
+
+        [
+            {
+                "EPOBranchNode.AutoID": 7,
+                "EPOComputerProperties.CPUSerialNum": "N/A",
+                "EPOComputerProperties.CPUSpeed": 2794,
+                "EPOComputerProperties.CPUType": "Intel(R) Core(TM) i7-4980HQ CPU @ 2.80GHz",
+                "EPOComputerProperties.ComputerName": "broker1",
+                "EPOComputerProperties.DefaultLangID": "0409",
+                "EPOComputerProperties.Description": null,
+
+                ...
+            }
+        ]
+
+The properties for each system found will be displayed.
+
+Details
+*******
+
+The majority of the sample code is shown below:
+
+    .. code-block:: python
+
+        # The ePO unique identifier
+        EPO_UNIQUE_ID = None
+
+        # The search text
+        SEARCH_TEXT = "broker"
+
+        # Create the client
+        with DxlClient(config) as client:
+
+            # Connect to the fabric
+            client.connect()
+
+            # Create the ePO client
+            epo_client = EpoClient(client, EPO_UNIQUE_ID)
+
+            # Run the system find command
+            res = epo_client.run_command("system.find",
+                                         {"searchText": SEARCH_TEXT},
+                                         output_format=OutputFormat.JSON)
+
+            # Load find result into dictionary
+            res_dict = json.loads(res, encoding='utf-8')
+
+            # Display the results
+            print json.dumps(res_dict, sort_keys=True, indent=4, separators=(',', ': '))
+
+
+Once a connection is established to the DXL fabric, a :class:`dxlepoclient.client.EpoClient` instance is created
+which will be used to invoke remote commands on the ePO server. The `unique identifier` of the ePO server
+to invoke remote commands on is specified as an argument to the client constructor. In this particular case, a
+value of ``None`` is specified which triggers the client to automatically determine the ePO server's unique identifier.
+This will not work if multiple ePO servers are connected to the fabric (an exception will be raised).
+
+Next, the :func:`dxlepoclient.client.EpoClient.run_command` method is invoked with an output
+format of ``json`` and a ``searchText`` parameter that is specified with the value of ``broker``.
+
+Finally, the JSON response text is loaded into a Python dictionary (``dict``), formatted,
+and displayed to the screen.
+
+
+

doc/sdk/index.rst

@@ -41,4 +41,7 @@ Basic
 .. toctree::
     :maxdepth: 1
 
+    basiccorehelpexample
+    basicsystemfindexample
+
 

doc/sdk/installation.rst

@@ -1,3 +1,38 @@
 Library Installation
 ====================
 
+Prerequisites
+*************
+
+* OpenDXL Python Client library installed
+ * `<https://github.com/opendxl/opendxl-client-python>`_
+* The OpenDXL Python Client prerequisites must be satisfied
+ * `<https://opendxl.github.io/opendxl-client-python/pydoc/installation.html>`_
+* McAfee ePolicy Orchestrator (ePO) service is running and available on DXL fabric
+ * `<https://github.com/opendxl/opendxl-epo-service-python>`_ (Python-based service implementation)
+* OpenDXL Python Client has permission to invoke ePO remote commands
+ * `<https://opendxl.github.io/opendxl-epo-service-python/pydoc/authorization.html#client-authorization>`_
+
+Installation
+************
+
+Use ``pip`` to automatically install the module:
+
+    .. parsed-literal::
+
+        pip install dxlepoclient-\ |version|\-py2.7-none-any.whl
+
+Or with:
+
+    .. parsed-literal::
+
+        pip install dxlepoclient-\ |version|\.zip
+
+As an alternative (without PIP), unpack the dxlepoclient-\ |version|\.zip (located in the lib folder) and run the setup
+script:
+
+    .. parsed-literal::
+
+        python setup.py install
+
+

doc/sdk/overview.rst

@@ -1,2 +1,15 @@
 Overview
 ========
+
+The `McAfee ePolicy Orchestrator <https://www.mcafee.com/us/products/epolicy-orchestrator.aspx>`_ (ePO) DXL Python
+client library provides a high level wrapper for invoking ePO remote commands via the
+`Data Exchange Layer <http://www.mcafee.com/us/solutions/data-exchange-layer.aspx>`_ (DXL) fabric.
+
+The purpose of this library is to allow users to invoke ePO remote commands without having to focus
+on lower-level details such as ePO-specific DXL topics and message formats.
+
+This client requires an ePO DXL service to be running and available on the DXL fabric.
+
+A Python-based implementation of an ePO DXL service is available here:
+
+* `McAfee ePolicy Orchestrator (ePO) DXL Python Service <https://github.com/opendxl/opendxl-epo-service-python>`_

doc/sdk/sampleconfig.rst

@@ -1,3 +1,23 @@
 Samples Configuration
 =====================
 
+The ePO DXL Python client distribution contains a configuration file (``dxlclient.config``) located
+in the ``sample`` sub-directory that must be populated in order for the samples to connect to the DXL fabric.
+
+The steps to populate this configuration file are the same as those documented in the `OpenDXL Python
+SDK`, see the
+`OpenDXL Python SDK Samples Configuration <https://opendxl.github.io/opendxl-client-python/pydoc/sampleconfig.html>`_
+page for more information.
+
+The following is an example of a populated configuration file:
+
+   .. code-block:: python
+
+       [Certs]
+       BrokerCertChain=c:\\certificates\\brokercerts.crt
+       CertFile=c:\\certificates\\client.crt
+       PrivateKey=c:\\certificates\\client.key
+
+       [Brokers]
+       {5d73b77f-8c4b-4ae0-b437-febd12facfd4}={5d73b77f-8c4b-4ae0-b437-febd12facfd4};8883;mybroker.mcafee.com;192.168.1.12
+       {24397e4d-645f-4f2f-974f-f98c55bdddf7}={24397e4d-645f-4f2f-974f-f98c55bdddf7};8883;mybroker2.mcafee.com;192.168.1.13

dxlepoclient/__init__.py

@@ -6,7 +6,7 @@
 
 from .client import EpoClient, OutputFormat
 
-__version__ = "0.0.1"
+__version__ = "0.1.0"
 
 
 def get_version():

sample/basic/basic_core_help_example.py

@@ -1,14 +1,17 @@
-# This sample invokes and displays the results of the "core help" command via
-# the ePO DXL service. This displays the remote commands that are exposed by
-# the ePO server.
+# This sample invokes and displays the results of the "core help" remote
+# command via the ePO DXL service. The "core help" command lists the
+# remote commands that are exposed by the particular ePO server.
 #
 # NOTE: Prior to running this sample you must provide values for the following
 #       constants in this file:
 #
 #       EPO_UNIQUE_ID : The unique identifier used to identify the ePO server
 #                       on the DXL fabric.
+#
+#                       If only one ePO server is connected to the DXL fabric
+#                       this constant can be set to None (the client will
+#                       automatically determine the ePO's unique identifier).
 
-import json
 import os
 import sys
 

sample/basic/basic_system_find_example.py

@@ -8,6 +8,10 @@
 #       EPO_UNIQUE_ID : The unique identifier used to identify the ePO server
 #                       on the DXL fabric.
 #
+#                       If only one ePO server is connected to the DXL fabric
+#                       this constant can be set to None (the client will
+#                       automatically determine the ePO's unique identifier).
+#
 #       SEARCH_TEXT   : The search text to use (system name, etc.)
 
 import json
@@ -33,8 +37,7 @@
 EPO_UNIQUE_ID = None
 
 # The search text
-#SEARCH_TEXT = "<specify-find-search-text>"
-SEARCH_TEXT = "broker"
+SEARCH_TEXT = "<specify-find-search-text>"
 
 # Create the client
 with DxlClient(config) as client:
@@ -50,5 +53,8 @@
                                  {"searchText": SEARCH_TEXT},
                                  output_format=OutputFormat.JSON)
 
+    # Load find result into dictionary
+    res_dict = json.loads(res, encoding='utf-8')
+
     # Display the results
-    print json.dumps(json.loads(res, encoding='utf-8'), sort_keys=True, indent=4, separators=(',', ': '))
+    print json.dumps(res_dict, sort_keys=True, indent=4, separators=(',', ': '))