@manyos/smileconnect-api 1.39.0 → 1.40.0

package/app.js

@@ -233,11 +233,23 @@ app.get('/debug', function (req, res, next) {
 //global authentication
 app.use(passport.authenticate('jwt', {session: false}), responseHandler.logRequest);
 
+//Check for dynamic impersonate
+app.use(function (req, res, next) {
+    if (req.user) {
+        const clientConfig = req.user.config;
+        const dynamicARUser = req.query.impersonateUser;
+        if (clientConfig && clientConfig.options && clientConfig.options.allowDynamicImpersonate === true && dynamicARUser) {
+            log.debug('Dynamic impersonate to user', dynamicARUser)
+            clientConfig.options.impersonateUser = dynamicARUser
+        }
+    }
+    next()
+})
+
 //set globalscript params
 app.use(function (req, res, next) {
     req.globalScriptParams = {
-        query: req.query,
-        params: req.params
+        query: req.query
     }
     next()
 });

package/conf/clients.json

@@ -133,6 +133,7 @@
         "dateFormati": "dd.MM.yyyy HH:mm.ss",
         "clientLimit": 100000,
         "impersonateUser": "rhannemann",
+        "allowDynamicImpersonate": true,
         "translateSelectionFieldsX": false
       },
       "custom_Sample:Enrollments": {

package/docs/README.md

@@ -0,0 +1 @@
+Our ITSM API creates a RESTful layer on-top of BMCs ITSM Suite. It allows you to expose all of your services with an easy and powerful REST-API. You can perform create, read and update operations on Incidents, Changes, Problems, Work Orders, Tasks and Assets. With no need for customization.

package/docs/_coverpage.md

@@ -0,0 +1,12 @@
+![logo](_media/logo.png)
+
+# SMILEconnect
+
+> Learn all about manyos ITSM API on these pages
+
+- The easy way to integrate providers
+- Reduce efforts and license cost
+- State of the art ITSM REST API
+
+[manyos](https://manyos.it)
+[Get Started](quickstart#Introduction)

package/docs/_sidebar.md

@@ -0,0 +1,25 @@
+- Getting started
+
+  - [Quick start](quickstart.md)
+  - [Architecture](architecture.md)
+  - [API Specification](spec/index.html)
+
+- Configuration
+
+  - [Global Settings](configuration/config.md)
+  - [Mapping](configuration/mapping.md)
+  - [Client Configuration](configuration/clients.md)
+  - [Events](configuration/events.md)
+
+- Data manipulation
+
+  - [Scripts](scripts.md)
+  - [Adapter](adapter.md)
+
+- How-Tos
+
+  - [Authentication](howto/token.md)
+  - [Incident Requests](howto/incidents.md)
+  - [Handle Worklogs](howto/worklogs.md)
+  - [Handle Attachments](howto/attachments.md)
+  - [Read Configuration Items](howto/cmdbobjects.md)

package/docs/adapter.md

@@ -0,0 +1,309 @@
+# Adapter
+
+Adapter are used to integrate with different systems. SMILEconnect comes with a flexible adapter architecture. Multiple types of adapters can be used and also multiple adapters of the same type can be configured. This can be useful if you need to interact e.g. with two different LDAP Systems.
+
+# Adapter Configuration
+
+Adapter are configured in the file *adapterConfig.js* in the root of the conf folder. Within the configuration file the variable *env* can be used to access system environment variables. E.g. *env.AR_USER* reflects the value of the system variable *AR_USER*.
+
+For security, it is advised to store confidential information, like passwords, in the environment variables and not in the configuration file itself.
+
+Configuration example:
+```javascript
+const adapterParams = {
+    remedy: {
+        type: "remedy",
+        arServer: env.AR_SERVER,
+        arUser: env.AR_USER,
+        arPassword: env.AR_PASSWORD,
+        arPort: env.AR_PORT,
+        rapiUri: env.RAPI_URL,
+        cacheTime: env.AR_CACHE_TTL,
+        limitDefault: env.LIMIT_DEFAULT || 100,
+        limitMax: env.LIMIT_MAX
+    },
+    ldap: {
+        type: "ldap",
+        ldapUrl: env.LDAP_URL,
+        ldapBind: env.LDAP_BIND,
+        ldapSecret: env.LDAP_SECRET
+    },
+    ldapIDM: {
+        type: "ldap",
+        ldapUrl: env.LDAP_IDM_URL,
+        ldapBind: env.LDAP_IDM_BIND,
+        ldapSecret: env.LDAP_IDM_SECRET
+    },
+    smileconnect: {
+        type: "SMILEconnect",
+        clientId: env.SC_CLIENT,
+        secret: env.SC_SECRET,
+        ssoUrl: env.SC_SSO_URL,
+        smileConnectUrl: env.SC_SMILECONNECT_URL
+    }
+};
+
+// noinspection JSAnnotator
+return adapterParams;
+```
+
+The different Adapter and their configuration values are described in detail below.
+
+## Remedy
+
+The Remedy Adapter is used to connect to BMC Remedy Action Request Servers. It allows you to create, query and update records.
+
+### Configuration values
+
+**arServer**: The name of the arsystem server. e.g. ars1.mydomain.com
+
+**arUser**: The user which is used to connect to the remedy server. E.g. Allen
+
+**arPassword**: The password of the ar user.
+
+**arPort**: The port of the arsystem server. e.g. 5142. Use 0 if you want to a portmapper.
+
+**rapiUri**: The URL of the RAPI Server wich is used as middleware to connect to the arsystem server. e.g. https://rapi.mydomain.com
+
+**cacheTime**: The default time in seconds in which the result of queries is stored in a cache. This is used to increase performance dramatically. Defaults to 300s.
+
+**limitDefault**: The default limit of records retrieved in a query. This value is used whenever no value is specified. Can be overwritten in queries.
+
+**limitMax**: The maximum number of records retrieved in a query. This parameter can be used to enforce a limit. The limit can not be overwritten by queries.
+
+### Functions
+
+#### Search
+
+```javascript
+async function search(form, query, fields, options)
+```
+
+Parameter:
+
+* form (string):
+
+The form used to query data. e.g. CTM:People
+
+* query (string):
+
+The query used in the form. e.g. 'Remedy Login ID' = "Allen"
+
+* fields (comma separated list):
+
+The fields to be returned by the query. e.g. "Full Name, Remedy Login ID, First Name, Last Name, Department"
+
+Full example:
+```javascript
+const result = await adapter.remedy.search(
+    "CTM:People",
+    "'Remedy Login ID' = \"Allen\"",
+    "Full Name, Remedy Login ID, First Name, Last Name, Department");
+```
+
+Will return an object with a data array and some meta data.
+
+```javascript
+{
+    "status": "success",
+    "query": "'Remedy Login ID' = \"Allen\"",
+    "server": "arserver:51423",
+    "form": "CTM:People",
+    "runtime": 106,
+    "dataSize": 1,
+    "data": [
+        {
+            "Person ID": "PPL000000000013",
+            "Remedy Login ID": "Allen",
+            "Department": "Customer Service",
+            "Full Name": "Allen Allbrook",
+            "Last Name": "Allbrook",
+            "First Name": "Allen"
+        }
+    ]
+}
+```
+
+
+#### Create
+
+```javascript
+async function create(form, entry, options)
+```
+
+Parameter:
+
+* form (string):
+
+The form in which a new record is created. e.g. CTM:People
+
+* entry (object):
+
+The entry object that is ceated.
+
+e.g.
+
+```javascript
+{
+    "Source Keyword": "SMILEcatalog",
+    "Company": "Calbro Services",
+    "AppRequestSummary": "New Request from SMILEcatalog",
+    "TitleInstanceID": "SRGAA5V0GEfds7LO5YL6Q945Z",
+    "Login ID": "Allen"
+}
+```
+
+Full example:
+
+```javascript
+const settings = {
+    "createForm":"SRM:RequestInterface_Create",
+    "entry": {
+        "Source Keyword": "SMILEcatalog",
+        "Company": "Calbro Services",
+        "AppRequestSummary": "New Request from SMILEcatalog",
+        "TitleInstanceID": "SRGAA5V0GEfds7LO5YL6Q945Z",
+        "Login ID": "Allen"
+    }
+};
+//Create Service Request
+const resultCreate = await adapter.remedy.create(settings.createForm, settings.entry);
+```
+
+Will return return the id of the created record. e.g. REQ00000002893
+
+#### Options
+
+* limit
+
+The maximum number of records that should be returned by this query. e.g. 5. Use this value to increase performance or to overwrite a default limit.
+
+* offset
+
+Use together with limit to allow pagination. e.g. limit=10 & offset=10
+
+* dateFormat
+
+The format in which dates are returned.
+
+* sort
+
+The fields that are to sort the result on the remedy server. Use 1 for ascending and -1 for descending order.
+
+e.g.
+```javascript
+{
+    "Name": 1,
+    "Status": -1
+}
+```
+
+
+* countOnly (only search)
+
+Can be used to retrieve only the size of the results without any payload. This improves performance.
+
+Full example:
+
+```javascript
+const options = {
+    limit: 100,
+    offset: 100,
+    dafeFormat: "yyyy-MM-dd HH:mm:ss.SSSZ",
+    sort: {
+        "Name": 1,
+        "Status": -1
+    }
+}
+```
+
+## LDAP
+
+
+### Configuration values
+
+* ldapUrl
+
+The connection URL of the LDAP Server. e.g. ldap://ldap.forumsys.com:389
+
+* ldapBind
+
+The Bind DN to authenticate with. e.g. cn=smilecatalog-user,dc=example,dc=com
+
+* ldapSecret
+
+The secret to use with the Bind DN. e.g. password
+
+### Functions
+
+
+#### Search
+
+```javascript
+async search(base, options)
+```
+Runs a query against the ldap Server.
+
+Parameter:
+
+* base
+
+A DN string to start.
+
+* options
+
+Options for the search. Like filters and returned attributes. See http://ldapjs.org/client.html for more details.
+
+```javascript
+const opts = {
+  filter: '(&(l=Seattle)(email=*@foo.com))',
+  scope: 'sub',
+  attributes: ['dn', 'sn', 'cn']
+};
+```
+
+Full example:
+
+```javascript
+const base = "dc=example,dc=com";
+const options = {
+    attributes: ['dn', 'sn', 'cn'],
+    scope: "sub",
+    filter: "sn=Riemann"
+}
+const result = await adapter.ldap.search(base, options);
+resolve(result);
+```
+
+Returns an array of records. e.g.
+
+```javascript
+[
+    {
+        "dn": "uid=riemann,dc=example,dc=com",
+        "controls": [],
+        "cn": "Bernhard Riemann",
+        "sn": "Riemann"
+    }
+]
+```
+
+## SMILEconnect
+
+The SMILEconnect Adapter can be used to do calls against SMILEconnect. It will act as it is called externally.
+
+### Configuration values
+
+**smileConnectUrl**: The url of your SMILEconnect installation e.g. https://smileconnect.mydomain.io
+
+**ssoUrl**: The url of the oidc identity provider. e.g. https://sso.mydomain.io/auth/realms/smileconnect
+
+**clientId**: The name of the client that is used to connect to SMILEconnect
+
+**secret**: The secret of the client. e.g. jd92hd-03283d-2293s-232
+
+### Functions
+
+The SMILEconnect adapter is an open source project.
+
+[Visit the project homepage for details](https://github.com/manyosit/smileconnect-client)

package/docs/architecture.md

@@ -0,0 +1,8 @@
+# Architecture
+
+In this guide we will explain the different components of ISAPI and how you can use them.
+
+![architecure of smileconnect](_media/architecture.jpeg)
+
+
+![architecure of smileconnect](_media/dataflow.png)

package/docs/configuration/clients.md

@@ -0,0 +1,69 @@
+# Client Config
+
+On a per client base it can be configured which fields are returned for each object and if a basequery is applied. This expose certain fields only dedicated clients. It also allows to define which rows a client can access. Clients are configured in conf/clients.json
+
+```json
+[
+  {
+    "name": "jira",
+    "config": {
+      "options" : {
+        "dateFormat" : "dd.MM.yyyy HH:mm.ss",
+        "clientLimit": 100
+      },
+      "cmdbobject": {
+        "basequery": "'Data Set Id' = \"BMC.ASSET\" AND ('Mark As Deleted' = \"No\" OR 'Mark As Deleted' = $NULL$) AND 'Class Id' = \"BMC_COMPUTERSYSTEM\"",
+        "fields": [
+          "Instance Id",
+          "Tag Number",
+          "Name",
+          "AssetLifecycleStatus",
+          "Category",
+          "Item",
+          "Type",
+          "Availability",
+          "Confidentiality",
+          "Integrity",
+          "Authenticity",
+          "Model Number",
+          "Class Id",
+          "Reconciliation Identity"
+        ]
+      },
+      "orgdata": {
+        "basequeryPeople": "'Profile Status' = \"Enabled\"",
+        "basequeryOrganisation": "'Status'=\"Enabled\"",
+        "basequerySupportGroup": "'Status'=\"Enabled\""
+      },
+      "change": {
+        "fields": [
+          "Infrastructure Change ID",
+          "Categorization Tier 1",
+          "Categorization Tier 2",
+          "Categorization Tier 3",
+          "Product Cat Tier 1",
+          "Product Cat Tier 2",
+          "Product Cat Tier 3",
+          "Product Name (2)",
+          "Description",
+          "Detailed Description",
+          "Status Reason",
+          "Change Request Status",
+          "Requested Start Date",
+          "Requested End Date",
+          "Scheduled Start Date",
+          "Scheduled End Date",
+          "Support Group ID",
+          "Support Group ID 2",
+          "Customer Person ID"
+        ],
+        "constants" : [
+          {"name": "Location Company", "value" : "Calbro Services"},
+          {"name": "Company", "value" : "Calbro Services"},
+          {"name": "RequesterLoginID", "value" : "Allen"}
+        ]
+      }
+    }
+  }
+]
+```