@manyos/smileconnect-api 1.39.1 → 1.40.1

package/docs/quickstart.md

@@ -0,0 +1,9 @@
+# Introduction
+
+The easiest way to deploy our API is via Docker. [Contact Us](https://manyos.it) to get access to the containers.
+
+Set the container environment variables as described [here](configuration/config)
+
+Create a client within your OIDC Provider and start with the configuration in the GUI.
+
+See our How-Tos to get an [Access Token](howto/token) and how to create your first [Incidents](howto/incidents)

package/docs/releases.md

@@ -0,0 +1,21 @@
+# Release Notes
+
+## API 
+
+### 1.40.0 - 30.07.21
+
+Dynamic Impersonate Users added.
+
+If the clientConfig has the option allowDynamicImpersonate set to *true* then the URL Parameter *impersonateUser* can be used to determine the used Remedy User.
+
+e.g.
+
+*/v1/incidents?impersonateUser=abc123
+
+## Event Manager
+
+### 1.15.0 - 30.07.21
+
+The eventmanager will check all outbound webhooks for an event. If one fails, the whole Event will be set to error and the details will be added to the error message.
+
+## GUI

package/docs/scripts.md

@@ -0,0 +1,272 @@
+# Scripts
+
+Scripts are used to modify requests, gather data or to drive external actions.
+
+Scripts can call adapter to interact with other systems and they can be reused.
+
+#### **`workOrder_lookupSericeNameByReconId.js`**
+```javascript
+//lookup service ci name if reconId is given
+
+if (requestData['ReconciliationIdentity']) {
+    const remedyResult = await adapter.remedy.search("BMC.CORE:BMC_BusinessService", `'ReconciliationIdentity' = "${requestData['ReconciliationIdentity']}" AND 'DatasetId' = "BMC.ASSET"`, "Name")
+
+    if (remedyResult && remedyResult.data && remedyResult.data[0]) {
+        const data = remedyResult.data[0];
+        requestData['CI Name'] = data['Name'];
+    }
+
+}
+resolve()
+```
+
+The above script will lookup the service name for a given reconciliation id.
+
+# Manage Scripts
+
+Scripts are stored in the /conf/scripts folder. They can be managed in the GUI.
+
+![Scripts in the GUI](_media/gui_scripts_edit.png)
+
+If you edit a script that is already in use, the GUI will show a warning.
+
+![Script usage warning](_media/gui_scripts_warning.png)
+
+You can also see in detail where the script is used.
+
+![Script usage details](_media/gui_scripts_usage.png)
+
+# Execution points
+
+A script can be executed at different times.
+
+![Client Script Usage](_media/gui_clients_scripts.png)
+
+For each execution point a list of scripts can be defined. These will be executed in the defined order.
+
+## GET
+
+During all get operations (get, getAll, search) the following execution points are available:
+
+### preMapping
+
+The scripts are executed directly after the data is fetched from the Remedy System. No field mapping was applied yet. Field names are the same as in Remedy. 
+
+### postMapping
+
+The scripts are executed after the mapping is done. All field names are now as defined in the mapping.
+
+## POST / PUT
+
+During POST & PUT operations an additional execution point (afterExecution) is available. 
+
+### preMapping
+
+The scripts are executed before the mapping is applied. All field names are as defined in the mapping. If additional data is sent from the client (e.g. additional attributes that are not on the form), you will still have access to them. 
+
+### postMapping
+
+The scripts are executed after the mapping is applied. All field names are now the same as in Remedy. Additional attributes and inaccessible fields are removed.
+
+### afterExecution
+
+The scripts are executed after the create or update operation was executed. Use this execution point to create additional records (e.g. for Reporting or Notifications).
+
+# Accessible Variables
+
+Within scripts the following variables are available.
+
+## params
+
+The parameter params can be defined in a script and used when another script is called. This is useful to reuse scripts.
+
+e.g.
+```javascript
+const subScriptParams = {
+    myAttribute1: "myValue1",
+    myAttribute2: [
+        "val1",
+        "val2"
+    ]
+}
+const returnValue = await script('ars101', {}, subScriptParams);
+```
+
+Within the called script params can be accessed:
+
+```javascript
+if (params && params.myAttribute1 === "myValue1") {
+    requestData.message = "Value was set"
+}
+```
+
+
+## globalScriptParams
+
+Global script params are set by the application and handed over to the script. They include the following parameter:
+
+**query**: This property is an object containing a property for each query string parameter in the route.
+
+**id**: the id of the ticket. Only set in GET & PUT actions
+
+**id2**: the id of child ticket. e.g. Tasks or Worklogs. Only set in GET & PUT actions
+
+**id2**: the id of child worklogs. e.g. Tasksworklog. Only set in GET & PUT actions
+
+**classId**: the classId of cmdbobjects. Only set in POST & PUT actions
+
+```json
+{
+    "query": {
+        "includeObjects": "true",
+        "limit": "3",
+        "include": "supportGroupRelations,persons"
+    },
+    "id": "INC000000001507"
+}
+```
+
+## requestData
+
+This parameter holds the complete request data.
+
+## clientId
+
+This id of the client who executes the script.
+
+## executedByScript
+
+This parameter will be set to *true* if the script is executed by another script.
+
+## env
+
+This parameter allows access to the environment variables.
+
+## log
+
+Can be used to write data to the applications log stream.
+
+The following log level can be used:
+
+* trace
+* debug
+* info
+* warn
+* error
+* fatal
+
+e.g.
+
+```javascript
+ log.debug('log text', variable);
+ log.info('log text', variable);
+ log.error('error text', variable);
+```
+
+## script
+
+Can be used to execute a script within a script.
+
+script(scriptId, requestData, params)
+
+e.g.
+```javascript
+const returnValue = await script('ars101', {}, params);
+```
+
+## fetch
+
+Allows access to external webservices via the package *node-fetch*
+
+See https://www.npmjs.com/package/node-fetch for details.
+
+## adapter
+
+Allows to make adapter calls. [See details](../configuration/adapter.md)
+
+# Returning values
+
+Values can be returned with the function *resolve()*
+
+e.g.
+
+```javascript
+const values = [
+    "value1",
+    "value2",
+    "value3"
+]
+resolve (values)
+```
+
+# Error handling
+
+Values can be returned with the fuction *reject()*
+
+e.g.
+
+```javascript
+if (!params.form) {
+    reject("The parameter form is required")
+}
+```
+
+# Async calls
+
+Within scripts *await* can be used to make async calls.
+
+```javascript
+ const returnValue = await script('ars101', {}, params);
+```
+
+# Samples
+
+## Simple Assign Back Script
+
+This script looks up the previous assignment group if an incident is set to "assigned"
+
+```javascript
+//lookup Previous Assigned Support Group for Incident
+// and assign this group if status is changed to "assigned", and assignedGroup is not set.
+
+
+if ( requestData['id'] && requestData['status']=="Assigned"  && !requestData.hasOwnProperty("assignedGroup") ) {
+    const remedyResult = await adapter.remedy.search("HPD:Help Desk Assignment Log", `'Incident Number' = "${requestData.id}"`, "Submit Date,Assigned Support Company,Assigned Support Organization,Assigned Group,Assigned Group ID")
+
+    if (remedyResult && remedyResult.data && Array.isArray(remedyResult.data)) {
+        const data = remedyResult.data;
+        let entry = 0;
+        if (data.length > 1) {
+            entry = data.length - 2;
+        }
+
+        if (data[entry] && data[entry].hasOwnProperty("Assigned Group ID")) {
+            requestData['assignedGroup'] = data[entry]['Assigned Group ID'];
+        } else {
+            reject("could not find previous group. automatic re-ssignement failed. set assigendGroup manually")
+        }
+
+    }
+}
+
+resolve()
+```
+
+## Lookup Service CI Name in WorkOrder
+
+If you change the Service CI in Work Orders you need to provide the ReconId and the Service Name. The Script looks up the Name if you only provide the id.
+
+```javascript
+//lookup service ci name if reconId is given
+
+if (requestData['ReconciliationIdentity']) {
+const remedyResult = await adapter.remedy.search("BMC.CORE:BMC_BusinessService", `'ReconciliationIdentity' = "${requestData['ReconciliationIdentity']}" AND 'DatasetId' = "BMC.ASSET"`, "Name")
+
+    if (remedyResult && remedyResult.data && remedyResult.data[0]) { 
+        const data = remedyResult.data[0]; 
+        requestData['CI Name'] = data['Name']; 
+    } 
+
+}
+resolve() 
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@manyos/smileconnect-api",
-  "version": "1.39.1",
+  "version": "1.40.1",
   "description": "A proxy and abstraction layer for BMCs IT Service Management Suite",
   "main": "app.js",
   "scripts": {

package/docs/.gitattributes

@@ -1,48 +0,0 @@
-# Define standard eol format
-
-# Web Files
-*.html text eol=lf
-*.md text eol=lf
-*.css text eol=lf
-*.js text eol=lf
-
-# Jekyll related files
-*.yml text eol=lf
-
-# Git related files
-.gittattributes text eol=lf
-.gitignore text eol=lf
-.gitkeep text eol=lf
-
-# Ruby files
-*.rb text eol=lf
-Gemfile text eol=lf
-Gemfile.lock text eol=lf
-
-# Github specific fies
-LICENCE text eol=lf
-
-# Docker specific files
-Dockerfile text eol=lf
-
-# VSCode files
-*.json text eol=lf
-
-# General multimedia files
-*.jpg binary
-*.jpeg binary
-*.gif binary
-*.png binary
-*.t3x binary
-*.t3d binary
-*.exe binary
-*.data binary
-*.ttf binary
-*.eof binary
-*.eot binary
-*.swf binary
-*.mov binary
-*.mp4 binary
-*.mp3 binary
-*.ogg binary
-*.flv binary

package/docs/404.html

@@ -1,13 +0,0 @@
----
-layout: default
-title: 404 - Page not found
-permalink: /404.html
----
-
-<div class="text-center">
-  <h1>Whoops, this page doesn't exist.</h1>
-  <h1>Move along. (404 error)</h1>
-  <br/>
-
-  <img src="{{ 'img/404-southpark.jpg' | relative_url }}" />
-</div>

package/docs/Gemfile

@@ -1,7 +0,0 @@
-source 'https://rubygems.org'
-
-gem "github-pages", '197', group: :jekyll_plugins
-
-# enable tzinfo-data for local build
-# gem 'tzinfo-data', platforms: [:mingw, :mswin, :x64_mingw]
-gem 'jekyll-paginate'

package/docs/Gemfile.lock

@@ -1,249 +0,0 @@
-GEM
-  remote: https://rubygems.org/
-  specs:
-    activesupport (4.2.10)
-      i18n (~> 0.7)
-      minitest (~> 5.1)
-      thread_safe (~> 0.3, >= 0.3.4)
-      tzinfo (~> 1.1)
-    addressable (2.5.2)
-      public_suffix (>= 2.0.2, < 4.0)
-    coffee-script (2.4.1)
-      coffee-script-source
-      execjs
-    coffee-script-source (1.11.1)
-    colorator (1.1.0)
-    commonmarker (0.17.13)
-      ruby-enum (~> 0.5)
-    concurrent-ruby (1.1.3)
-    dnsruby (1.61.2)
-      addressable (~> 2.5)
-    em-websocket (0.5.1)
-      eventmachine (>= 0.12.9)
-      http_parser.rb (~> 0.6.0)
-    ethon (0.11.0)
-      ffi (>= 1.3.0)
-    eventmachine (1.2.7-x64-mingw32)
-    execjs (2.7.0)
-    faraday (0.15.3)
-      multipart-post (>= 1.2, < 3)
-    ffi (1.9.25-x64-mingw32)
-    forwardable-extended (2.6.0)
-    gemoji (3.0.0)
-    github-pages (193)
-      activesupport (= 4.2.10)
-      github-pages-health-check (= 1.8.1)
-      jekyll (= 3.7.4)
-      jekyll-avatar (= 0.6.0)
-      jekyll-coffeescript (= 1.1.1)
-      jekyll-commonmark-ghpages (= 0.1.5)
-      jekyll-default-layout (= 0.1.4)
-      jekyll-feed (= 0.11.0)
-      jekyll-gist (= 1.5.0)
-      jekyll-github-metadata (= 2.9.4)
-      jekyll-mentions (= 1.4.1)
-      jekyll-optional-front-matter (= 0.3.0)
-      jekyll-paginate (= 1.1.0)
-      jekyll-readme-index (= 0.2.0)
-      jekyll-redirect-from (= 0.14.0)
-      jekyll-relative-links (= 0.5.3)
-      jekyll-remote-theme (= 0.3.1)
-      jekyll-sass-converter (= 1.5.2)
-      jekyll-seo-tag (= 2.5.0)
-      jekyll-sitemap (= 1.2.0)
-      jekyll-swiss (= 0.4.0)
-      jekyll-theme-architect (= 0.1.1)
-      jekyll-theme-cayman (= 0.1.1)
-      jekyll-theme-dinky (= 0.1.1)
-      jekyll-theme-hacker (= 0.1.1)
-      jekyll-theme-leap-day (= 0.1.1)
-      jekyll-theme-merlot (= 0.1.1)
-      jekyll-theme-midnight (= 0.1.1)
-      jekyll-theme-minimal (= 0.1.1)
-      jekyll-theme-modernist (= 0.1.1)
-      jekyll-theme-primer (= 0.5.3)
-      jekyll-theme-slate (= 0.1.1)
-      jekyll-theme-tactile (= 0.1.1)
-      jekyll-theme-time-machine (= 0.1.1)
-      jekyll-titles-from-headings (= 0.5.1)
-      jemoji (= 0.10.1)
-      kramdown (= 1.17.0)
-      liquid (= 4.0.0)
-      listen (= 3.1.5)
-      mercenary (~> 0.3)
-      minima (= 2.5.0)
-      nokogiri (>= 1.8.2, < 2.0)
-      rouge (= 2.2.1)
-      terminal-table (~> 1.4)
-    github-pages-health-check (1.8.1)
-      addressable (~> 2.3)
-      dnsruby (~> 1.60)
-      octokit (~> 4.0)
-      public_suffix (~> 2.0)
-      typhoeus (~> 1.3)
-    html-pipeline (2.9.1)
-      activesupport (>= 2)
-      nokogiri (>= 1.4)
-    http_parser.rb (0.6.0)
-    i18n (0.9.5)
-      concurrent-ruby (~> 1.0)
-    jekyll (3.7.4)
-      addressable (~> 2.4)
-      colorator (~> 1.0)
-      em-websocket (~> 0.5)
-      i18n (~> 0.7)
-      jekyll-sass-converter (~> 1.0)
-      jekyll-watch (~> 2.0)
-      kramdown (~> 1.14)
-      liquid (~> 4.0)
-      mercenary (~> 0.3.3)
-      pathutil (~> 0.9)
-      rouge (>= 1.7, < 4)
-      safe_yaml (~> 1.0)
-    jekyll-avatar (0.6.0)
-      jekyll (~> 3.0)
-    jekyll-coffeescript (1.1.1)
-      coffee-script (~> 2.2)
-      coffee-script-source (~> 1.11.1)
-    jekyll-commonmark (1.2.0)
-      commonmarker (~> 0.14)
-      jekyll (>= 3.0, < 4.0)
-    jekyll-commonmark-ghpages (0.1.5)
-      commonmarker (~> 0.17.6)
-      jekyll-commonmark (~> 1)
-      rouge (~> 2)
-    jekyll-default-layout (0.1.4)
-      jekyll (~> 3.0)
-    jekyll-feed (0.11.0)
-      jekyll (~> 3.3)
-    jekyll-gist (1.5.0)
-      octokit (~> 4.2)
-    jekyll-github-metadata (2.9.4)
-      jekyll (~> 3.1)
-      octokit (~> 4.0, != 4.4.0)
-    jekyll-mentions (1.4.1)
-      html-pipeline (~> 2.3)
-      jekyll (~> 3.0)
-    jekyll-optional-front-matter (0.3.0)
-      jekyll (~> 3.0)
-    jekyll-paginate (1.1.0)
-    jekyll-readme-index (0.2.0)
-      jekyll (~> 3.0)
-    jekyll-redirect-from (0.14.0)
-      jekyll (~> 3.3)
-    jekyll-relative-links (0.5.3)
-      jekyll (~> 3.3)
-    jekyll-remote-theme (0.3.1)
-      jekyll (~> 3.5)
-      rubyzip (>= 1.2.1, < 3.0)
-    jekyll-sass-converter (1.5.2)
-      sass (~> 3.4)
-    jekyll-seo-tag (2.5.0)
-      jekyll (~> 3.3)
-    jekyll-sitemap (1.2.0)
-      jekyll (~> 3.3)
-    jekyll-swiss (0.4.0)
-    jekyll-theme-architect (0.1.1)
-      jekyll (~> 3.5)
-      jekyll-seo-tag (~> 2.0)
-    jekyll-theme-cayman (0.1.1)
-      jekyll (~> 3.5)
-      jekyll-seo-tag (~> 2.0)
-    jekyll-theme-dinky (0.1.1)
-      jekyll (~> 3.5)
-      jekyll-seo-tag (~> 2.0)
-    jekyll-theme-hacker (0.1.1)
-      jekyll (~> 3.5)
-      jekyll-seo-tag (~> 2.0)
-    jekyll-theme-leap-day (0.1.1)
-      jekyll (~> 3.5)
-      jekyll-seo-tag (~> 2.0)
-    jekyll-theme-merlot (0.1.1)
-      jekyll (~> 3.5)
-      jekyll-seo-tag (~> 2.0)
-    jekyll-theme-midnight (0.1.1)
-      jekyll (~> 3.5)
-      jekyll-seo-tag (~> 2.0)
-    jekyll-theme-minimal (0.1.1)
-      jekyll (~> 3.5)
-      jekyll-seo-tag (~> 2.0)
-    jekyll-theme-modernist (0.1.1)
-      jekyll (~> 3.5)
-      jekyll-seo-tag (~> 2.0)
-    jekyll-theme-primer (0.5.3)
-      jekyll (~> 3.5)
-      jekyll-github-metadata (~> 2.9)
-      jekyll-seo-tag (~> 2.0)
-    jekyll-theme-slate (0.1.1)
-      jekyll (~> 3.5)
-      jekyll-seo-tag (~> 2.0)
-    jekyll-theme-tactile (0.1.1)
-      jekyll (~> 3.5)
-      jekyll-seo-tag (~> 2.0)
-    jekyll-theme-time-machine (0.1.1)
-      jekyll (~> 3.5)
-      jekyll-seo-tag (~> 2.0)
-    jekyll-titles-from-headings (0.5.1)
-      jekyll (~> 3.3)
-    jekyll-watch (2.1.2)
-      listen (~> 3.0)
-    jemoji (0.10.1)
-      gemoji (~> 3.0)
-      html-pipeline (~> 2.2)
-      jekyll (~> 3.0)
-    kramdown (1.17.0)
-    liquid (4.0.0)
-    listen (3.1.5)
-      rb-fsevent (~> 0.9, >= 0.9.4)
-      rb-inotify (~> 0.9, >= 0.9.7)
-      ruby_dep (~> 1.2)
-    mercenary (0.3.6)
-    mini_portile2 (2.3.0)
-    minima (2.5.0)
-      jekyll (~> 3.5)
-      jekyll-feed (~> 0.9)
-      jekyll-seo-tag (~> 2.1)
-    minitest (5.11.3)
-    multipart-post (2.0.0)
-    nokogiri (1.8.5-x64-mingw32)
-      mini_portile2 (~> 2.3.0)
-    octokit (4.13.0)
-      sawyer (~> 0.8.0, >= 0.5.3)
-    pathutil (0.16.2)
-      forwardable-extended (~> 2.6)
-    public_suffix (2.0.5)
-    rb-fsevent (0.10.3)
-    rb-inotify (0.9.10)
-      ffi (>= 0.5.0, < 2)
-    rouge (2.2.1)
-    ruby-enum (0.7.2)
-      i18n
-    ruby_dep (1.5.0)
-    rubyzip (1.2.2)
-    safe_yaml (1.0.4)
-    sass (3.7.2)
-      sass-listen (~> 4.0.0)
-    sass-listen (4.0.0)
-      rb-fsevent (~> 0.9, >= 0.9.4)
-      rb-inotify (~> 0.9, >= 0.9.7)
-    sawyer (0.8.1)
-      addressable (>= 2.3.5, < 2.6)
-      faraday (~> 0.8, < 1.0)
-    terminal-table (1.8.0)
-      unicode-display_width (~> 1.1, >= 1.1.1)
-    thread_safe (0.3.6)
-    typhoeus (1.3.1)
-      ethon (>= 0.9.0)
-    tzinfo (1.2.5)
-      thread_safe (~> 0.1)
-    unicode-display_width (1.4.0)
-
-PLATFORMS
-  x64-mingw32
-
-DEPENDENCIES
-  github-pages (= 193)
-  jekyll-paginate
-
-BUNDLED WITH
-   1.17.1