Metadata-Version: 2.1
Name: opsrampcli
Version: 0.4.4
Summary: 
License: MIT
Author: Michael Friedhoff
Author-email: michael.friedhoff@opsramp.com
Requires-Python: >=3.8,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Requires-Dist: DateTime (>=4.4,<5.0)
Requires-Dist: PyYAML (>=6.0,<7.0)
Requires-Dist: XlsxWriter (>=3.0.3,<4.0.0)
Requires-Dist: json5 (>=0.9.8,<0.10.0)
Requires-Dist: pandas (>=1.4.3,<2.0.0)
Requires-Dist: requests (>=2.28.0,<3.0.0)
Description-Content-Type: text/x-rst

OpsRamp Command Line Interface
==============================

This is a utility script that allows easy searching and manipulation of
various OpsRamp items and configurations. Before trying out any of the
commands, you'll first need to `set up an environments
file <#credentials>`__ to contain the credentials you need to use.

Available Commands
------------------

The available commands are:

+----------------------------------+----------------------------------+
| opcli Command                    | Description                      |
+==================================+==================================+
| `getalerts <#getalerts>`__       | Search for and take action on    |
|                                  | alerts                           |
+----------------------------------+----------------------------------+
| `postalerts <#postalerts>`__     | Post alerts to a Webhook         |
|                                  | integration (using vtoken) or    |
|                                  | directly to the API (using OAuth |
|                                  | creds)                           |
+----------------------------------+----------------------------------+
| `getincidents <#getincidents>`__ | Search and take action on        |
|                                  | Incidents                        |
+----------------------------------+----------------------------------+
| `getresources <#getresources>`__ | Search for and take action on    |
|                                  | resources/devices                |
+----------------------------------+----------------------------------+
| `exportser                       | Export one or more full Service  |
| vicemaps <#exportservicemaps>`__ | Map definitions to a file which  |
|                                  | can be manipulated and           |
|                                  | re-imported                      |
+----------------------------------+----------------------------------+
| `importser                       | Import (and optionally transform |
| vicemaps <#importservicemaps>`__ | while doing so) from a Service   |
|                                  | Map export file                  |
+----------------------------------+----------------------------------+
| `clonese                         | Copy an existing Service Map,    |
| rvicemaps <#cloneservicemaps>`__ | with                             |
|                                  | transformations/replacements     |
|                                  | (useful when you have a template |
|                                  | Service Map to re-use)           |
+----------------------------------+----------------------------------+
| `trans                           | Apply regex replacements to an   |
| formsvcmap <#transformsvcmap>`__ | exported Service Map and create  |
|                                  | a new transformed export file    |
|                                  | with the changes                 |
+----------------------------------+----------------------------------+
| `get                             | Get Service Map definitions      |
| servicemaps <#getservicemaps>`__ |                                  |
+----------------------------------+----------------------------------+
| `getchilds                       | Get child Service Groups of a    |
| vcgroups <#getchildsvcgroups>`__ | parent Service                   |
+----------------------------------+----------------------------------+
| `getse                           | Get the full definition of a     |
| rvicegroup <#getservicegroup>`__ | Service Group                    |
+----------------------------------+----------------------------------+
| `exportcusta                     | Generate an Excel or csv file    |
| ttrfile <#exportcustattrfile>`__ | from existing custom attribute   |
|                                  | values                           |
+----------------------------------+----------------------------------+
| `importcusta                     | Import an Excel file containing  |
| ttrfile <#importcustattrfile>`__ | custom attribute values          |
+----------------------------------+----------------------------------+
| `get                             | Get custom attribute definitions |
| customattrs <#getcustomattrs>`__ |                                  |
+----------------------------------+----------------------------------+
| `getdi                           | Get discovery profile definition |
| scoprofile <#getdiscoprofile>`__ |                                  |
+----------------------------------+----------------------------------+
| `getalertesc <#getalertesc>`__   | Search and get Escalation Policy |
|                                  | definitions                      |
+----------------------------------+----------------------------------+
| `migra                           | Migrate/copy Escalation Policies |
| tealertesc <#migratealertesc>`__ | within same tenant or from one   |
|                                  | tenant to another                |
+----------------------------------+----------------------------------+

   

For more detailed help on a specific command use the -h option with the
command, for example to get help on the cloneservicemaps command:

.. code:: shell

   % opcli cloneservicemaps -h
   usage: opcli cloneservicemaps [-h] --env ENV [--secure SECURE] [--envfile ENVFILE] --name NAME --replace REGEX REPLACEWITH [--parentlink] [--clobber]

   optional arguments:
     -h, --help            show this help message and exit
     --env ENV             Name of environment to use, as defined in your environments.yml file (default: None)
     --secure SECURE       Whether or not to verify SSL cert (default: True)
     --envfile ENVFILE     Location of environments YAML file (default: environments.yml)
     --name NAME           Name of Service Map to transform and clone (default: None)
     --replace REGEX REPLACEWITH
                           Transforming regex pattern and replacement string (option can be repeated) (default: None)
     --parentlink          If root Service has a link to a parent, link the imported Service Map (default: False)
     --clobber             Overwrite Service Map (i.e. with same name) if it already exists (default: False)

Credentials
-----------

By default, opcli requires an *environments.yml* file to be located in
the directory where you running it. Optionally you can specify an
explicit environments file path & name using the --envfile option. The
file must follow the following format, where the name is the value you
will specify to the --env option to define the URL and credentials you
will use:

.. code:: yaml

   - name: example1
     url:  https://customer2name.api.opsramp.com
     partner: msp_nnnnn
     tenant: client_nnnnn
     client_id: abcdefg1234567
     client_secret: abcdefg1234567
     vtoken: abcdefg1234567

   - name: example2
     url:  https://customer2name.api.opsramp.com
     partner: msp_nnnnn
     tenant: client_nnnnn
     client_id: abcdefg1234567
     client_secret: abcdefg1234567
     vtoken: abcdefg1234567

Note that you only need to provide the attributes needed for the kind of
API calls you are making. Therefore:

-  If you are making an API call that does not require a partner id
   (which is not needed in most cases) you do not need to provide a
   *partner* value.
-  If you are not doing webhook alert posts, you would not need to
   specify the *vtoken* value.
-  If you are doing only webhook alert posts then you would not need
   *client_id* and *client_secret*.
-  If you are using the environment for a bunch of different scenarios,
   there is no harm in having the extra values there for the cases where
   they are not needed.

   

Commands
========

getalerts
---------

Search for and take action on alerts

.. code:: shell

   usage: opcli getalerts [-h] --env ENV [--secure SECURE] [--envfile ENVFILE] --query QUERY [--brief] [--descr] [--count] [--filter FILTER] [--action ACTION] [--heal]

   optional arguments:
     -h, --help         show this help message and exit
     --env ENV          Name of environment to use, as defined in your environments.yml file (default: None)
     --secure SECURE    Whether or not to verify SSL cert (default: True)
     --envfile ENVFILE  Location of environments YAML file (default: environments.yml)
     --query QUERY      Query String to filter alerts as per https://develop.opsramp.com/resource-management/tenants-tenantid-resources-search (default: None)
     --brief            Include only key fields in output (default: False)
     --descr            Include the description field in results (runs *much* slower as it requires a separate api call per alert) (default: False)
     --count            Only show the count of matching alerts (default: False)
     --filter FILTER    Post-query filter on alerts. Python expression that will evaluate to True or False such as alert["resource"]["name"].startswith("prod") (default: None)
     --action ACTION    Perform an action on matching alerts (Heal, acknowledge, suppress, close, unsuppress, unAcknowledge) (default: None)
     --heal             Heal the matching alerts (i.e. send a matching Ok) (default: False)

Alert search criteria
~~~~~~~~~~~~~~~~~~~~~

Alert search --query option uses the syntax documented
`here <https://web.archive.org/web/20211024221749/https://docs.opsramp.com/api/alerts/tenants-tenantid-alerts-search/>`__

*Note: Above link is to an Internet Archive capture of an old doc page,
as the latest doc no longer lists query variables*

Examples
~~~~~~~~

Search for all alerts with matching resource/device numeric id and
metric

::

   % opcli getalerts --env myenvname --query 'resourceIds:9798408+metrics:testmetric' --brief

Search for all alerts last updated during given time range, and heal &
close them

::

   % opcli getalerts --env myenvname --query 'startDate:2000-01-01T00:00:00 0000+endDate:2020-12-01T00:00:00 0000+alertTimeBase:updated+states:Critical,Warning,Info' --heal --action close

postalerts
----------

Post alerts to a Webhook integration (using vtoken) or directly to the
API (using OAuth creds)

.. code:: shell

   usage: opcli postalerts [-h] --env ENV [--secure SECURE] [--envfile ENVFILE] --infile INFILE [--range RANGE] [--auth AUTH]

   optional arguments:
     -h, --help         show this help message and exit
     --env ENV          Name of environment to use, as defined in your environments.yml file (default: None)
     --secure SECURE    Whether or not to verify SSL cert (default: True)
     --envfile ENVFILE  Location of environments YAML file (default: environments.yml)
     --infile INFILE    File containing an array of json alert payloads (default: None)
     --range RANGE      An integer or range identifying which alert in the file to send (default: all)
     --auth AUTH        Authentication method: vtoken or oauth (default: vtoken)

Example
~~~~~~~

Post alert #5 from the specified json file (expected to contain an array
of alerts), using vtoken authentication

::

   % opcli postalerts --env myenvname --infile myalertsamples.json --auth vtoken --range 5

getincidents
------------

Search and take action on Incidents

.. code:: shell

   usage: opcli getincidents [-h] --env ENV [--secure SECURE] [--envfile ENVFILE] --query QUERY [--brief] [--count] [--filter FILTER] [--resolve]

   optional arguments:
     -h, --help         show this help message and exit
     --env ENV          Name of environment to use, as defined in your environments.yml file (default: None)
     --secure SECURE    Whether or not to verify SSL cert (default: True)
     --envfile ENVFILE  Location of environments YAML file (default: environments.yml)
     --query QUERY      Query String to filter incidents (default: None)
     --brief            Include only key fields in output (default: False)
     --count            Only show the count of matching incidents (default: False)
     --filter FILTER    Post-query filter on incidents. Python expression that will evaluate to True or False such as incident["resource"]["name"].startswith("prod") (default: None)
     --resolve          Resolve the matching incidents (default: False)

getresources
------------

Search for and take action on resources/devices

.. code:: shell

   usage: opcli getresources [-h] --env ENV [--secure SECURE] [--envfile ENVFILE] [--query QUERY] [--search SEARCH] [--count] [--delete] [--manage] [--filter FILTER]

   optional arguments:
     -h, --help         show this help message and exit
     --env ENV          Name of environment to use, as defined in your environments.yml file (default: None)
     --secure SECURE    Whether or not to verify SSL cert (default: True)
     --envfile ENVFILE  Location of environments YAML file (default: environments.yml)
     --query QUERY      Query String to filter resources as per https://develop.opsramp.com/resource-management/tenants-tenantid-resources-search (default: None)
     --search SEARCH    Search String to filter resources as it would be entered under Resources -> Search (default: None)
     --count            Only show the count of matching resources (default: False)
     --delete           Delete the matching resources (default: False)
     --manage           Manage the matching resources (default: False)
     --filter FILTER    Post-query filter on resources. Python expression that will evaluate to True or False such as alert["resource"]["name"].startswith("prod") (default: None)

exportservicemaps
-----------------

Export one or more full Service Map definitions to a file which can be
manipulated and re-imported\|

.. code:: shell

   usage: opcli exportservicemaps [-h] --env ENV [--secure SECURE] [--envfile ENVFILE] [--name NAME] [--outdir OUTDIR] [--clobber] [--timestamp]

   optional arguments:
     -h, --help         show this help message and exit
     --env ENV          Name of environment to use, as defined in your environments.yml file (default: None)
     --secure SECURE    Whether or not to verify SSL cert (default: True)
     --envfile ENVFILE  Location of environments YAML file (default: environments.yml)
     --name NAME        Name of the root level Service Map/Group (export all if not specified) (default: None)
     --outdir OUTDIR    Directory path where export will be saved (default: .)
     --clobber          Remove/overwrite prior exports of same maps (default: False)
     --timestamp        Include a timestamp in the Service Map dir name (default: False)

importservicemaps
-----------------

Import (and optionally transform while doing so) from a Service Map
export file\|

.. code:: shell

   usage: opcli importservicemaps [-h] --env ENV [--secure SECURE] [--envfile ENVFILE] --src SRC [--replace REGEX REPLACEWITH] [--parentlink] [--clobber]

   optional arguments:
     -h, --help            show this help message and exit
     --env ENV             Name of environment to use, as defined in your environments.yml file (default: None)
     --secure SECURE       Whether or not to verify SSL cert (default: True)
     --envfile ENVFILE     Location of environments YAML file (default: environments.yml)
     --src SRC             Source: Path to the export file of a Service Map (default: None)
     --replace REGEX REPLACEWITH
                           Transforming regex pattern and replacement string (option can be repeated) (default: None)
     --parentlink          If root Service has a link to a parent, link the imported Service Map (default: False)
     --clobber             Overwrite Service Map (i.e. with same name) if it already exists (default: False)

cloneservicemaps
----------------

Copy an existing Service Map, with transformations/replacements (useful
when you have a template Service Map to re-use)\|

.. code:: shell

   usage: opcli cloneservicemaps [-h] --env ENV [--secure SECURE] [--envfile ENVFILE] --name NAME --replace REGEX REPLACEWITH [--parentlink] [--clobber]

   optional arguments:
     -h, --help            show this help message and exit
     --env ENV             Name of environment to use, as defined in your environments.yml file (default: None)
     --secure SECURE       Whether or not to verify SSL cert (default: True)
     --envfile ENVFILE     Location of environments YAML file (default: environments.yml)
     --name NAME           Name of Service Map to transform and clone (default: None)
     --replace REGEX REPLACEWITH
                           Transforming regex pattern and replacement string (option can be repeated) (default: None)
     --parentlink          If root Service has a link to a parent, link the imported Service Map (default: False)
     --clobber             Overwrite Service Map (i.e. with same name) if it already exists (default: False)

.. _example-1:

Example
~~~~~~~

.. code:: shell

   % opcli cloneservicemaps --env myenv --name "HUB" --replace HUB HUBCOPY --parentlink

transformsvcmap
---------------

Apply regex replacements to an exported Service Map and create a new
transformed export file with the changes\|

.. code:: shell

   usage: opcli transformsvcmap [-h] src dest --replace REGEX REPLACEWITH [--clobber]

   positional arguments:
     src                   Source: File path where a Service Map was previously exported
     dest                  Destination: File path where the transformed export will be saved

   optional arguments:
     -h, --help            show this help message and exit
     --replace REGEX REPLACEWITH
                           Transforming regex pattern and replacement string (option can be repeated) (default: None)
     --clobber             Overwrite dest file if it already exists (default: False)

getservicemaps
--------------

Get Service Map definitions\|

.. code:: shell

   usage: opcli getservicemaps [-h] --env ENV [--secure SECURE] [--envfile ENVFILE]

   optional arguments:
     -h, --help         show this help message and exit
     --env ENV          Name of environment to use, as defined in your environments.yml file (default: None)
     --secure SECURE    Whether or not to verify SSL cert (default: True)
     --envfile ENVFILE  Location of environments YAML file (default: environments.yml)

getchildsvcgroups
-----------------

Get child Service Groups of a parent Service\|

.. code:: shell

   usage: opcli getchildsvcgroups [-h] --env ENV [--secure SECURE] [--envfile ENVFILE] --parent PARENT

   optional arguments:
     -h, --help         show this help message and exit
     --env ENV          Name of environment to use, as defined in your environments.yml file (default: None)
     --secure SECURE    Whether or not to verify SSL cert (default: True)
     --envfile ENVFILE  Location of environments YAML file (default: environments.yml)
     --parent PARENT    ID of the parent Service Map/Group (default: None)

getservicegroup
---------------

Get the full definition of a Service Group\|

.. code:: shell

   usage: opcli getservicegroup [-h] --env ENV [--secure SECURE] [--envfile ENVFILE] --id ID

   optional arguments:
     -h, --help         show this help message and exit
     --env ENV          Name of environment to use, as defined in your environments.yml file (default: None)
     --secure SECURE    Whether or not to verify SSL cert (default: True)
     --envfile ENVFILE  Location of environments YAML file (default: environments.yml)
     --id ID            ID of the Service Map/Group (default: None)

exportcustattrfile
------------------

Generate an Excel or csv file from existing custom attribute values\|

.. code:: shell

   usage: opcli exportcustattrfile [-h] --env ENV [--secure SECURE] [--envfile ENVFILE] [--query QUERY] [--search SEARCH] [--filter FILTER] [--filename FILENAME]

   optional arguments:
     -h, --help           show this help message and exit
     --env ENV            Name of environment to use, as defined in your environments.yml file (default: None)
     --secure SECURE      Whether or not to verify SSL cert (default: True)
     --envfile ENVFILE    Location of environments YAML file (default: environments.yml)
     --query QUERY        Query String to filter resources as per https://develop.opsramp.com/resource-management/tenants-tenantid-resources-search (default: None)
     --search SEARCH      Search String to filter resources as it would be entered under Resources -> Search (default: None)
     --filter FILTER      Post-query filter on resources. Python expression that will evaluate to True or False such as alert["resource"]["name"].startswith("prod") (default: None)
     --filename FILENAME  Name of excel file to generate (.xlsx extension will be added) (default: None)

importcustattrfile
------------------

Import an Excel file containing custom attribute values\|

.. code:: shell

   usage: opcli importcustattrfile [-h] --env ENV [--secure SECURE] [--envfile ENVFILE] [--commit] [--writeblanks] [--filename FILENAME]

   optional arguments:
     -h, --help           show this help message and exit
     --env ENV            Name of environment to use, as defined in your environments.yml file (default: None)
     --secure SECURE      Whether or not to verify SSL cert (default: True)
     --envfile ENVFILE    Location of environments YAML file (default: environments.yml)
     --commit             Make the actual updates on the platform. If not specified, only error checking and import simulation will occur. (default: False)
     --writeblanks        When no value is provided in the spreadsheet for a resource, remove any existing value for that resource on the platform. If not specified then no action is taken for empty values. (default: False)
     --filename FILENAME  Name of excel file to import (.xlsx extension will be added if not specified.) (default: None)

getcustomattrs
--------------

Get custom attribute definitions\|

.. code:: shell

   usage: opcli getcustomattrs [-h] --env ENV [--secure SECURE] [--envfile ENVFILE]

   optional arguments:
     -h, --help         show this help message and exit
     --env ENV          Name of environment to use, as defined in your environments.yml file (default: None)
     --secure SECURE    Whether or not to verify SSL cert (default: True)
     --envfile ENVFILE  Location of environments YAML file (default: environments.yml)

getdiscoprofile
---------------

Get discovery profile definition\|

.. code:: shell

   usage: opcli getdiscoprofile [-h] --env ENV [--secure SECURE] [--envfile ENVFILE] --id ID --tenantId TENANTID

   optional arguments:
     -h, --help           show this help message and exit
     --env ENV            Name of environment to use, as defined in your environments.yml file (default: None)
     --secure SECURE      Whether or not to verify SSL cert (default: True)
     --envfile ENVFILE    Location of environments YAML file (default: environments.yml)
     --id ID              Discovery profile ID (default: None)
     --tenantId TENANTID  Client ID or MSP ID of the tenant (default: None)

getalertesc
-----------

Search and get Escalation Policy definitions\|

.. code:: shell

   usage: opcli getalertesc [-h] --env ENV [--secure SECURE] [--envfile ENVFILE] [--query QUERY] [--details] [--count] [--filter FILTER]

   optional arguments:
     -h, --help         show this help message and exit
     --env ENV          Name of environment to use, as defined in your environments.yml file (default: None)
     --secure SECURE    Whether or not to verify SSL cert (default: True)
     --envfile ENVFILE  Location of environments YAML file (default: environments.yml)
     --query QUERY      Query String to filter alerts (default: None)
     --details          Get the full details for all matched policies (default: False)
     --count            Only show the count of matching alerts (default: False)
     --filter FILTER    Post-query filter on alerts. Python expression that will evaluate to True or False such as alert["resource"]["name"].startswith("prod") (default: None)

migratealertesc
---------------

Migrate/copy Escalation Policies within same tenant or from one tenant
to another\|

.. code:: shell

   usage: opcli migratealertesc [-h] --env ENV [--secure SECURE] [--envfile ENVFILE] [--query QUERY] [--filter FILTER] [--preexec PREEXEC] [--postexec POSTEXEC] --to_env TO_ENV [--test] [--update] [--setactive SETACTIVE]

   optional arguments:
     -h, --help            show this help message and exit
     --env ENV             Name of environment to use, as defined in your environments.yml file (default: None)
     --secure SECURE       Whether or not to verify SSL cert (default: True)
     --envfile ENVFILE     Location of environments YAML file (default: environments.yml)
     --query QUERY         Query string to filter policies from source/from instance (default: None)
     --filter FILTER       Filter for which policies to migrate. Python expression that will evaluate to True or False such as alert["resource"]["name"].startswith("prod") (default: None)
     --preexec PREEXEC     Pre-mapped exec command (default: None)
     --postexec POSTEXEC   Post-mapped exec command (default: None)
     --to_env TO_ENV       Target environment to which policy definitions will be migrated. (--env option defines the source/from environment) (default: None)
     --test                Test run only. Will check object mappings for missing items and not actually change the target instance. (default: False)
     --update              Used for bulk updates, will only work if --env and --to_env are the same. Try to update existing policies instead of creating new ones. (default: False)
     --setactive SETACTIVE
                           Specify ON or OFF. Will force all policies created on the target to be ON or OFF. Otherwise will be set the same as the source. (default: None)

