Metadata-Version: 2.1
Name: opsrampcli
Version: 0.4.3
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/markdown

# OpsRamp General Purpose Utility

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|
| [exportservicemaps](#exportservicemaps)   |Export one or more full Service Map definitions to a file which can be manipulated and re-imported|
| [importservicemaps](#importservicemaps)   |Import (and optionally transform while doing so) from a Service Map export file|
| [cloneservicemaps](#cloneservicemaps)    |Copy an existing Service Map, with transformations/replacements (useful when you have a template Service Map to re-use)|
| [transformsvcmap](#transformsvcmap)     |Apply regex replacements to an exported Service Map and create a new transformed export file with the changes|
| [getservicemaps](#getservicemaps)      |Get Service Map definitions|
| [getchildsvcgroups](#getchildsvcgroups)   |Get child Service Groups of a parent Service|
| [getservicegroup](#getservicegroup)     |Get the full definition of a Service Group|
| [exportcustattrfile](#exportcustattrfile)  |Generate an Excel or csv file from existing custom attribute values|
| [importcustattrfile](#importcustattrfile)  |Import an Excel file containing custom attribute values|
| [getcustomattrs](#getcustomattrs)      |Get custom attribute definitions|
| [getdiscoprofile](#getdiscoprofile)     |Get discovery profile definition|
| [getalertesc](#getalertesc)         |Search and get Escalation Policy definitions|
| [migratealertesc](#migratealertesc)     |Migrate/copy Escalation Policies within same tenant or from one tenant to another|


&nbsp;
&nbsp;

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

```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:

```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.

&nbsp;
&nbsp;
# Commands

## getalerts
Search for and take action on alerts

```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)
```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
```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
```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|
```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|
```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)|
```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

```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|
```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|
```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|
```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|
```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|
```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|
```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|
```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|
```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|
```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|
```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)
```





