opsrampcli 0.4.10

A command line interface for OpsRamp

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 to contain the credentials you need to use.

Available Commands

The available commands are:

opcli Command	Description
getalerts	Search for and take action on alerts
postalerts	Post alerts to a Webhook integration (using vtoken) or directly to the API (using OAuth creds)
getincidents	Search and take action on Incidents
getresources	Search for and take action on resources/devices
exportservicemaps	Export one or more full Service Map definitions to a file which can be manipulated and re-imported
importservicemaps	Import (and optionally transform while doing so) from a Service Map export file
cloneservicemaps	Copy an existing Service Map, with transformations/replacements (useful when you have a template Service Map to re-use)
transformsvcmap	Apply regex replacements to an exported Service Map and create a new transformed export file with the changes
getservicemaps	Get Service Map definitions
getchildsvcgroups	Get child Service Groups of a parent Service
getservicegroup	Get the full definition of a Service Group
exportcustattrfile	Generate an Excel or csv file from existing custom attribute values
importcustattrfile	Import an Excel file containing custom attribute values
getcustomattrs	Get custom attribute definitions
getdiscoprofile	Get discovery profile definition
getalertesc	Search and get Escalation Policy definitions
migratealertesc	Migrate/copy Escalation Policies 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:

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

- 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

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

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)

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

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

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|

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|

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

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

% 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|

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|

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|

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|

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|

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|

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|

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|

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|

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|

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)