@itentialopensource/adapter-winston_syslog 1.0.1 → 1.1.0

package/README.md

@@ -1,4 +1,4 @@
-# Adapter for Winston Syslog 
+# Adapter for WinstonSyslog 
 
 ## Table of Contents
 
@@ -14,6 +14,7 @@ Some of the page links in this document and links to other GitLab files do not w
   - [Testing](#testing)
 - [Configuration](./PROPERTIES.md)
 - [Using this Adapter](./CALLS.md)
+  - [Authentication](./AUTH.md)
 - [Additional Information](#additional-information)
   - [Enhancements](./ENHANCE.md)
   - [Contributing](./CONTRIBUTING.md)
@@ -29,7 +30,9 @@ Some of the page links in this document and links to other GitLab files do not w
 
 Itential Product and opensource adapters utilize SemVer for versioning. The current version of the adapter can be found in the `package.json` file or viewed in the IAP GUI on the System page. All Itential opensource adapters can be found in the <a href="https://gitlab.com/itentialopensource/adapters" target="_blank">Itential OpenSource Repository</a>.
 
-Release notes can be viewed in CHANGELOG.md or in the <a href="https://itential.atlassian.net/servicedesk/customer/portals" target="_blank">Customer Knowledge Base</a> for Itential adapters.
+Any release prior to 1.0.0 is a pre-release. Initial builds of adapters are generally set up as pre-releases as there is often work that needs to be done to configure the adapter and make sure the authentication process to WinstonSyslog works appropriately.
+
+Release notes can be viewed in CHANGELOG.md.
 
 ## Supported IAP Versions
 
@@ -45,17 +48,20 @@ These instructions will help you get a copy of the project on your local machine
 
 ### Helpful Background Information
 
-There is adapter documentation available on the Itential Developer Site <a href="https://www.itential.com/automation-platform/integrations/adapters-resources/" target="_blank">HERE</a>. This documentation includes information and examples that are helpful for:
+There is <a href="https://docs.itential.com/opensource/docs/adapters" target="_blank">Adapter documentation available on the Itential Documentation Site</a>. This documentation includes information and examples that are helpful for:
 
 ```text
 Authentication
-Properties
+IAP Service Instance Configuration
 Code Files
-Action Files
-Schema Files
-Mock Data Files
+Endpoint Configuration (Action & Schema)
+Mock Data
+Adapter Generic Methods
+Headers
+Security
 Linting and Testing
-Troubleshooting
+Build an Adapter
+Troubleshooting an Adapter
 ```
 
 Others will be added over time.
@@ -84,7 +90,7 @@ The following list of packages are required for Itential opensource adapters or
   </tr>
   <tr>
     <td style="padding:15px">ajv</td>
-    <td style="padding:15px">Required for validation of adapter properties to integrate with Winsotn Syslog.</td>
+    <td style="padding:15px">Required for validation of adapter properties to integrate with WinstonSyslog.</td>
   </tr>
   <tr>
     <td style="padding:15px">axios</td>
@@ -94,6 +100,10 @@ The following list of packages are required for Itential opensource adapters or
     <td style="padding:15px">commander</td>
     <td style="padding:15px">Utilized by the node scripts that are included with the adapter; helps to build and extend the functionality.</td>
   </tr>
+  <tr>
+    <td style="padding:15px">dns-lookup-promise</td>
+    <td style="padding:15px">Utilized by the node scripts that are included with the adapter; helps to build and extend the functionality.</td>
+  </tr>
   <tr>
     <td style="padding:15px">fs-extra</td>
     <td style="padding:15px">Utilized by the node scripts that are included with the adapter; helps to build and extend the functionality.</td>
@@ -110,14 +120,14 @@ The following list of packages are required for Itential opensource adapters or
     <td style="padding:15px">mongodb</td>
     <td style="padding:15px">Utilized by the node scripts that are included with the adapter; helps to build and extend the functionality.</td>
   </tr>
-  <tr>
-    <td style="padding:15px">network-diagnostics</td>
-    <td style="padding:15px">Utilized by the node scripts that are included with the adapter; helps to build and extend the functionality.</td>
-  </tr>
   <tr>
     <td style="padding:15px">nyc</td>
     <td style="padding:15px">Testing coverage library that is utilized by some of the node scripts that are included with the adapter.</td>
   </tr>
+  <tr>
+    <td style="padding:15px">ping</td>
+    <td style="padding:15px">Utilized by the node scripts that are included with the adapter; helps to build and extend the functionality.</td>
+  </tr>
   <tr>
     <td style="padding:15px">readline-sync</td>
     <td style="padding:15px">Utilized by the node script that comes with the adapter;  helps to test unit and integration functionality.</td>
@@ -141,7 +151,6 @@ eslint
 eslint-config-airbnb-base
 eslint-plugin-import
 eslint-plugin-json
-package-json-validator
 testdouble
 ```
 
@@ -168,13 +177,6 @@ tar -xvf adapter-winston_syslog.tar
 
 3. Run the adapter install script.
 
-```bash
-cd adapter-winston_syslog
-npm run adapter:install
-```
-
-3. Install adapter dependencies and check the adapter.
-
 ```bash
 cd adapter-winston_syslog
 npm install
@@ -194,6 +196,25 @@ systemctl restart pronghorn
 
 7. Change the adapter service instance configuration (host, port, credentials, etc) in IAP Admin Essentials GUI
 
+
+For an easier install of the adapter use npm run adapter:install, it will install the adapter in IAP. Please note that it can be dependent on where the adapter is installed and on the version of IAP so it is subject to fail. If using this, you can replace step 3-5 above with these:
+
+3. Install adapter dependencies and check the adapter.
+
+```bash
+cd adapter-winston_syslog
+npm run adapter:install
+```
+
+4. Restart IAP
+
+```bash
+systemctl restart pronghorn
+```
+
+5. Change the adapter service instance configuration (host, port, credentials, etc) in IAP Admin Essentials GUI
+
+
 ### Testing
 
 Mocha is generally used to test all Itential Opensource Adapters. There are unit tests as well as integration tests performed. Integration tests can generally be run as standalone using mock data and running the adapter in stub mode, or as integrated. When running integrated, every effort is made to prevent environmental failures, however there is still a possibility.
@@ -211,14 +232,42 @@ npm run test:baseunit
 
 To add new unit tests, edit the `test/unit/adapterTestUnit.js` file. The tests that are already in this file should provide guidance for adding additional tests.
 
+#### Integration Testing - Standalone
 
-## Configuration
+Standalone Integration Testing requires mock data to be provided with the entities. If this data is not provided, standalone integration testing will fail. When the adapter is set to run in stub mode (setting the stub property to true), the adapter will run through its code up to the point of making the request. It will then retrieve the mock data and return that as if it had received that data as the response from WinstonSyslog. It will then translate the data so that the adapter can return the expected response to the rest of the Itential software. Standalone is the default integration test.
 
-The critical information required for this adapter to work as expected are the host, port, and log protocol (udp4, tcp4, etc.). These options ensure we can connect to the correct syslog server. An optional property is minLogLevel. This will tell the adapter which log levels to send logs at. If this is not set, it will default to info and above. Note that the options in the task will not change when this is set, so the user will need to be careful and only select the appropriate log levels. An example of what these properties might look like are included in the sampleProperties.json file. Note that the healthcheck type for this adapter should always be set to `none`, as there is no way to ensure connectivity over UDP which is the mechanism for writing to the syslog. 
+Similar to unit testing, there are two ways to run integration tests. Using the testRunner script is better because it prevents you from having to edit the test script; it will also resets information after testing is complete so that credentials are not saved in the file.
 
-## Using this Adapter
+```bash
+node utils/testRunner
+  answer no at the first prompt
+
+npm run test:integration
+```
+
+To add new integration tests, edit the `test/integration/adapterTestIntegration.js` file. The tests that are already in this file should provide guidance for adding additional tests.
 
-This adapter has one task, `postLog` that can be used to post a log to the the server whose details have been provided in the adapter's properties. This task takes in three arguments: severity, facility and the message to send.
+#### Integration Testing
+
+Integration Testing requires connectivity to WinstonSyslog. By using the testRunner script it prevents you from having to edit the integration test. It also resets the integration test after the test is complete so that credentials are not saved in the file.
+
+> **Note**: These tests have been written as a best effort to make them work in most environments. However, the Adapter Builder often does not have the necessary information that is required to set up valid integration tests. For example, the order of the requests can be very important and data is often required for `creates` and `updates`. Hence, integration tests may have to be enhanced before they will work (integrate) with WinstonSyslog. Even after tests have been set up properly, it is possible there are environmental constraints that could result in test failures. Some examples of possible environmental issues are customizations that have been made within WinstonSyslog which change order dependencies or required data.
+
+```bash
+node utils/testRunner
+answer yes at the first prompt
+answer all other questions on connectivity and credentials
+```
+
+Test should also be written to clean up after themselves. However, it is important to understand that in some cases this may not be possible. In addition, whenever exceptions occur, test execution may be stopped, which will prevent cleanup actions from running. It is recommended that tests be utilized in dev and test labs only.
+
+> **Reminder**: Do not check in code with actual credentials to systems.
+
+## [Configuration](./PROPERTIES.md)
+
+## [Using this Adapter](./CALLS.md)
+
+### [Authentication](./AUTH.md)
 
 ## Additional Information
 
@@ -228,7 +277,7 @@ This adapter has one task, `postLog` that can be used to post a log to the the s
 
 ### Helpful Links
 
-<a href="https://www.itential.com/automation-platform/integrations/adapters-resources/" target="_blank">Adapter Technical Resources</a>
+<a href="https://docs.itential.com/opensource/docs/adapters" target="_blank">Adapter Technical Resources</a>
 
 ### Node Scripts
 
@@ -263,9 +312,21 @@ There are several node scripts that now accompany the adapter. These scripts are
     <td style="padding:15px">npm run adapter:revert</td>
     <td style="padding:15px">Allows you to revert after a migration or update if it resulted in issues.</td>
   </tr>
+  <tr>
+    <td style="padding:15px">npm run troubleshoot</td>
+    <td style="padding:15px">Provides a way to troubleshoot the adapter - runs connectivity, healthcheck and basic get.</td>
+  </tr>
+  <tr>
+    <td style="padding:15px">npm run connectivity</td>
+    <td style="padding:15px">Provides a connectivity check to the WinstonSyslog system.</td>
+  </tr>
   <tr>
     <td style="padding:15px">npm run healthcheck</td>
-    <td style="padding:15px">Checks whether the configured healthcheck call works to Winston Syslog.</td>
+    <td style="padding:15px">Checks whether the configured healthcheck call works to WinstonSyslog.</td>
+  </tr>
+  <tr>
+    <td style="padding:15px">npm run basicget</td>
+    <td style="padding:15px">Checks whether the basic get calls works to WinstonSyslog.</td>
   </tr>
 </table>
 <br>
@@ -282,4 +343,4 @@ Custom Adapters are maintained by other sources.
 
 ## Product License
 
-[Apache 2.0](./LICENSE)
+[Apache 2.0](./LICENSE)

package/SUMMARY.md

@@ -0,0 +1,9 @@
+## Overview
+
+This adapter is used to integrate the Itential Automation Platform (IAP) with the WinstonSyslog System. The API that was used to build the adapter for WinstonSyslog is usually available in the report directory of this adapter. The adapter utilizes the WinstonSyslog API to provide the integrations that are deemed pertinent to IAP. The ReadMe file is intended to provide information on this adapter it is generated from various other Markdown files.
+
+>**Note**: It is possible that some integrations will be supported through the WinstonSyslog adapter while other integrations will not. If you need additional API calls, you can use the Update capabilities provided by the Adapter Builder or request Itential to add them if the Adapter is an Itential opensourced adapter.
+
+Itential provides information on all of its product adapters in the Customer Knowledge Base. Information in the <a href="https://itential.atlassian.net/servicedesk/customer/portals" target="_blank">Customer Knowledge Base</a> is consistently maintained and goes through documentation reviews. As a result, it should be the first place to go for information.
+
+For opensourced and custom built adapters, the ReadMe is a starting point to understand what you have built, provide the information for you to be able to update the adapter, and assist you with deploying the adapter into IAP.

package/TROUBLESHOOT.md

@@ -0,0 +1,47 @@
+## Troubleshoot
+
+Run `npm run troubleshoot` to start the interactive troubleshooting process. The command allows you to verify and update connection, authentication as well as healthcheck configuration. After that it will test these properties by sending HTTP request to the endpoint. If the tests pass, it will persist these changes into IAP.
+
+You also have the option to run individual commands to perform specific test:
+
+- `npm run healthcheck` will perform a healthcheck request of with current setting.
+- `npm run basicget` will perform some non-parameter GET request with current setting.
+- `npm run connectivity` will perform networking diagnostics of the adatper endpoint.
+
+### Connectivity Issues
+
+1. You can run the adapter troubleshooting script which will check connectivity, run the healthcheck and run basic get calls.
+
+```bash
+npm run troubleshoot
+```
+
+2. Verify the adapter properties are set up correctly.
+
+```text
+Go into the Itential Platform GUI and verify/update the properties
+```
+
+3. Verify there is connectivity between the Itential Platform Server and WinstonSyslog Server.
+
+```text
+ping the ip address of WinstonSyslog server
+try telnet to the ip address port of WinstonSyslog
+execute a curl command to the other system
+```
+
+4. Verify the credentials provided for WinstonSyslog.
+
+```text
+login to WinstonSyslog using the provided credentials
+```
+
+5. Verify the API of the call utilized for WinstonSyslog Healthcheck.
+
+```text
+Go into the Itential Platform GUI and verify/update the properties
+```
+
+### Functional Issues
+
+Adapter logs are located in `/var/log/pronghorn`. In older releases of the Itential Platform, there is a `pronghorn.log` file which contains logs for all of the Itential Platform. In newer versions, adapters can be configured to log into their own files.