noc-connector 1.0.5
NOC connector
Requires Python: >=3.6

# NOC Connector 

This project aims to raise new tickets programmatically for the NOC team

## Installation

Use the package manager [pip](https://pip.pypa.io/en/stable/) to install noc-connector.

```bash
pip install noc-connector
```

## Requirements

Python version >= 3.6

Python required dependencies: 

```bash
pip install jsonschema==3.2.0
```

Python optional dependencies: 
```bash
pip install slackclient==2.8.0 
```



## Usage

There are two alternatives to use the module, bash or import the module in Python. Both require a JSON configuration file, in this file the parameters for the alert and the script must be indicated. 

**Required parameters**
- *alert_info* : NOC alert parameters, [see this Confluence article for reference](https://confluence.nexgen.neustar.biz/pages/viewpage.action?spaceKey=ITSMTools&title=Event+Management+System+-+EMS#EventManagementSystem-EMS-NMF-NormalizedMessageFormat).
  - *alert_info.Node* : Required
  - *alert_info.Domain* : Required
  - *alert_info.NOC_Alert_Code* : Required
  - *alert_info.AlertKey* : Required
  - *alert_info.Severity* : Required
  - *alert_info.Summary* : Required
  - *alert_info.URL* : Optional
- *http_auth_username* : NOC HTTP user, [see this Confluence article](https://confluence.nexgen.neustar.biz/display/ITSMTools/Event+Management+System+-+EMS#EventManagementSystem-EMS-HTTPSWebService(RESTAPI)), the *username* is indicated there
- *http_auth_password* : NOC HTTP password, [see this Confluence article](https://confluence.nexgen.neustar.biz/display/ITSMTools/Event+Management+System+-+EMS#EventManagementSystem-EMS-HTTPSWebService(RESTAPI)), the *password* is indicated there

**Optional parameters**
- *send_slack_notification* : Boolean, it can be **true** or **false**. If **true**, the script will send a Slack message to the indicated channel.
- *slack_api_key* : Slack API Token, [see this article as reference](https://slack.com/help/articles/215770388-Create-and-regenerate-API-tokens#internal-app-tokens). If **send_slack_notification** is true, this parameter is required
- *slack_channel* : Slack channel to be notified. If **send_slack_notification** is true, this parameter is required

**JSON example**

```json
{
    "alert_info" : {
        "Node":"<Node>",
        "Domain":"<NOC_Alert_Code>",
        "NOC_Alert_Code":"<NOC_Alert_Code>",
        "AlertGroup":"<AlertGroup>",
        "AlertKey":"<AlertKey>",
        "Severity":"<Severity>",
        "Summary":"<Summary>",
        "URL":"<URL>"
    },
    "http_auth_username": "<http_auth_username>",
    "http_auth_password": "<http_auth_password>",
    "send_slack_notification" : "<true|false>",
    "slack_api_key" : "<slack_api_key>",
    "slack_channel" : "<slack_channel>"
}
```

**Environment variables**

Alternatively and highly recommended, you can export environment variables to avoid passing sensitive and repetitive parameters in the JSON file. **Environment variable has higher precedence level than JSON file**

```bash
export NOC_CONNECTOR_HTTP_AUTH_USERNAME=<http_auth_username>
export NOC_CONNECTOR_HTTP_AUTH_PASSWORD=<http_auth_password>
export NOC_CONNECTOR_SEND_SLACK_NOTIFICATION=<send_slack_notification>
export NOC_CONNECTOR_SLACK_API_KEY=<slack_api_key>
export NOC_CONNECTOR_SLACK_CHANNEL=<slack_channel>

```
As you can see these variables map to the JSON parameters explained above, for example the first NOC_CONNECTOR_HTTP_AUTH_USERNAME maps to http_auth_username


**JSON example using environment variables**

```json
{
    "alert_info" : {
        "Node":"<Node>",
        "Domain":"<NOC_Alert_Code>",
        "NOC_Alert_Code":"<NOC_Alert_Code>",
        "AlertGroup":"<AlertGroup>",
        "AlertKey":"<AlertKey>",
        "Severity":"<Severity>",
        "Summary":"<Summary>",
        "URL":"<URL>"
    }
}
```

### Bash

There is a script called noc_alert, its use is very simple, it only receives one parameter. This parameter is the path of the JSON file and receives the same parameters mentioned above. 

By default, if no parameters are indicated, the script will look for **config.json** file in the current directory that the script is executed.

```bash
noc_alert <JSON_file_path> 
```

### Python

There is a library called noc_connector, you can import it into Python file. Its use is simple, you just have to use the **noc_connector.noc_alert.send_alert** method, it only receives one parameter, a JSON that must contain the same parameters mentioned above.

```python
import json
from noc_connector import noc_alert

response = noc_alert.send_alert({ "alert_info" : {...} })

print(json.dumps(response, indent=4, default=str)) 
```

## Response 
The output of the script will be a JSON, it can contain the following keys
- **status** : can be **ok** or **error**
- **message** : If *status* is **error**, it contains the error message. if the status is **ok**, it contains the NOC response, [see this Confluence article for details](https://confluence.nexgen.neustar.biz/display/ITSMTools/Event+Management+System+-+EMS#EventManagementSystem-EMS-HTTPSWebService(RESTAPI))
- **slack_status** :  If send_slack_notification is true, can be **ok** or **error**
- **slack_message** : If the slack_status is **error**, it contains the error message. if the status is **ok**, contains the sent Slack message


## Autor

Aaron Elizondo Gamboa

aaron.elizondo@team.neustar