|
| 1 | +# ServiceNow Incidents Plugin |
| 2 | + |
| 3 | +View ServiceNow incidents associated with a Cortex service! |
| 4 | + |
| 5 | +<div align="center"><img src="img/incidents_cortex.png" width="550" /></div> |
| 6 | + |
| 7 | +The ServiceNow Incidents plugin shows you recent incidents that have been filed against a given service in Cortex. It does this by associating the Cortex entity with a CMDB CI, and searching the ServiceNow `incident` table for incidents whose `cmdb_ci`, `business_service`, or `affected_ci` match the associated CI. Here are the ways the plugin looks for the CI for a Cortex entity: |
| 8 | + |
| 9 | +- If the Cortex entity is already mapped to a ServiceNow CMDB CI using the Cortex ServiceNow integration, the plugin will show incidents pertaining to that CI. |
| 10 | +- If it's not mapped, the plugin uses the service name in Cortex to find a corresponding service with the same name in the CMDB by searching `cmdb_ci_service` for objects with the same name as the entity's tag or name. |
| 11 | +- If you don't want to search, and want to configure a specific CI without mapping the entity to ServiceNow, you can set a custom data key `servicenow-sys_id` on the entity to the sys_id of the CI for which you want to show incidents when the plugin is displayed for that entity. |
| 12 | + |
| 13 | +<div align="center"><img src="img/incidents_snow.png" width="550" /></div> |
| 14 | + |
| 15 | +## Setup |
| 16 | + |
| 17 | +To see how to run the plugin inside of Cortex, see [our docs](https://docs.cortex.io/docs/plugins). This plugin will require a proxy to ServiceNow. |
| 18 | + |
| 19 | +### Proxy Setup |
| 20 | + |
| 21 | +- Define a Secret that is a base64 encoding of `username:password`. You can use a tool similar to [this](https://www.debugbear.com/basic-auth-header-generator) to convert it. |
| 22 | +- Define a proxy that is pointed at your ServiceNow instance with the nescessary headers. For help figuring out which headers to use, refer to the REST API explorer in your servicenow instance. Here is an example of what your proxy may look like: |
| 23 | + |
| 24 | +<div align="center"><img src="img/proxy_changes.png" width="550" /></div> |
| 25 | + |
| 26 | +### Plugin Registration |
| 27 | + |
| 28 | +- Create a Plugin and associate it with the proxy you created in the previous step |
| 29 | +- This Plugin will not work in the Global context. |
| 30 | +- Select the entity types that will have a corresponding CMDB CI. Below is what a configuration may look like. In this example the plugin will be available to both Services and Resources. |
| 31 | +<div align="center"><img src="img/snow_changes_config.png" width="350" /></div> |
| 32 | + |
| 33 | +- Follow the directions under **Getting Started** below to build `ui.html` and upload it |
| 34 | + |
| 35 | +### Set your ServiceNow instance URL |
| 36 | + |
| 37 | +Your ServiceNow instance URL should look like `https://something.service-now.com`. It's the same URL you used to set up the proxy above. We also want to create a new entity to tell the plugin what ServiceNow URL to load: |
| 38 | + |
| 39 | +- Consider creating a new entity type, so that any existing scorecards are not affected by ths configuration entity. In this example, we have created a new entity type called `plugin-configuration` |
| 40 | +- Create a new entity with the tag `servicenow-plugin-config` |
| 41 | +- Set `x-cortex-definition.servicenow-url` to the value of your ServiceNow Instance URL. For example, if my ServiceNow Instance URL was `https://martindstone.service-now.com`, my `servicenow-plugin-config` entity would look like this: |
| 42 | + |
| 43 | +``` |
| 44 | +openapi: 3.0.1 |
| 45 | +info: |
| 46 | + title: ServiceNow Plugin Config |
| 47 | + description: "" |
| 48 | + x-cortex-tag: servicenow-plugin-config |
| 49 | + x-cortex-type: plugin-configuration |
| 50 | + x-cortex-definition: |
| 51 | + servicenow-url: https://martindstone.service-now.com |
| 52 | +``` |
| 53 | + |
| 54 | +Now when you load the plugin on an entity, you should see any ServiceNow incidents that were filed against that entity's CMDB CI. |
| 55 | + |
| 56 | +## Setting up your dev environment |
| 57 | + |
| 58 | +### Prerequisites |
| 59 | + |
| 60 | +Developing and building this plugin requires either [yarn](https://classic.yarnpkg.com/lang/en/docs/install/) or [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm). |
| 61 | + |
| 62 | +## Getting started |
| 63 | + |
| 64 | +1. Run `yarn` or `npm install` to download all dependencies |
| 65 | +2. Run `yarn build` or `npm run build` to compile the plugin code into `./dist/ui.html` |
| 66 | +3. Upload `ui.html` into Cortex on a create or edit plugin page |
| 67 | +4. Add or update the code and repeat steps 2-3 as necessary |
| 68 | + |
| 69 | +### Notable scripts |
| 70 | + |
| 71 | +The following commands come pre-configured in this repository. You can see all available commands in the `scripts` section of [package.json](./package.json). They can be run with npm via `npm run {script_name}` or with yarn via `yarn {script_name}`, depending on your package manager preference. For instance, the `build` command can be run with `npm run build` or `yarn build`. |
| 72 | + |
| 73 | +- `build` - compiles the plugin. The compiled code root is `./src/index.tsx` (or as defined by [webpack.config.js](webpack.config.js)) and the output is generated into `dist/ui.html`. |
| 74 | +- `test` - runs all tests defined in the repository using [jest](https://jestjs.io/) |
| 75 | +- `lint` - runs lint and format checking on the repository using [prettier](https://prettier.io/) and [eslint](https://eslint.org/) |
| 76 | +- `lintfix` - runs eslint in fix mode to fix any linting errors that can be fixed automatically |
| 77 | +- `formatfix` - runs Prettier in fix mode to fix any formatting errors that can be fixed automatically |
| 78 | + |
| 79 | +### Available React components |
| 80 | + |
| 81 | +See available UI components via our [Storybook](https://cortexapps.github.io/plugin-core/). |
0 commit comments