@manyos/smileconnect-api 1.39.0 → 1.39.1

package/app.js

@@ -236,8 +236,7 @@ app.use(passport.authenticate('jwt', {session: false}), responseHandler.logReque
 //set globalscript params
 app.use(function (req, res, next) {
     req.globalScriptParams = {
-        query: req.query,
-        params: req.params
+        query: req.query
     }
     next()
 });

package/docs/_config.yml

@@ -24,6 +24,8 @@ navbar-links:
   Resources:
     - Architecture: "general/architecture"
     - Configuration: "general/config"
+    - Scripts: "configuration/scripts"
+    - Adapter: "configuration/adapter"
     - Specification: "spec/index.html"
   How-Tos:
     - Authenticate: "howto/token"

package/docs/configuration/adapter.md

@@ -0,0 +1,317 @@
+---
+layout: page
+title: Adapter
+subtitle: Talk to the outside world
+use-site-title: true
+bigimg: /img/gb-isapi.jpg
+toc: true
+---
+
+# Introduction
+
+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/configuration/scripts.md

@@ -0,0 +1,207 @@
+---
+layout: page
+title: Scripts
+subtitle: How-to modify data
+use-site-title: true
+bigimg: /img/gb-isapi.jpg
+---
+
+# Introduction
+
+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`**
+```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.
+
+# 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 returnValue = await script('ars101', {}, params);
+```
+
+## 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, scope)
+
+e.g.
+```javascript
+const returnValue = await script('ars101', {}, params);
+```
+
+For more information see subscripts.
+
+## 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 fuction *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 Static Menu
+
+This script creates the data for a simple static menu in a Selection (Drop Down) field.
+
+```javascript
+const data = [
+    {
+        "value": "Menu Item 1",
+        "label": "internalVal1"
+    },
+    {
+        "value": "Menu Item 2",
+        "label": "internalVal2"
+    },
+    {
+        "value": "Menu Item 3",
+        "label": "internalVal3"
+    },
+    {
+        "value": "Menu Item 4",
+        "label": "internalVal4"
+    }
+];
+resolve(data);
+
+```
+
+## Simple Query Menu
+
+This script calls another script query data for a menu.
+
+```javascript
+//prepare params
+const params = {
+    "query": "'Remedy Login ID'=\"astern\"",
+    "form": "CTM:People",
+    "labelField": "Full Name",
+    "valueField": "Remedy Login ID"
+};
+//execute script
+const personResult = await script('remedy/ars101', {}, params, "global");
+//return parameter
+resolve(personResult);
+```

package/package.json

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

package/routes/cmdbObjectRoutes.js

@@ -107,6 +107,7 @@ module.exports = (function () {
     cmdbObjectRoutes.get('/:id', passport.authenticate('jwt', {session: false}),
         function (req, res, next) {
             const id = req.params.id;
+            req.globalScriptParams.id = id
             const includeString = req.query.include;
             eventLog.setEventData(
                 req,
@@ -165,6 +166,8 @@ module.exports = (function () {
         const id = req.params.id;
         const classId = req.body.classId;
         const includeString = req.query.include;
+        req.globalScriptParams.id = id
+        req.globalScriptParams.classId = classId
         eventLog.setEventData(
             req,
             CONSTANTS.EVENT_BASE_AST,
@@ -200,6 +203,7 @@ module.exports = (function () {
     cmdbObjectRoutes.post('/', checkSchema(fieldMappingSchemas.CMDBCreateDataSchema), async function (req, res, next) {
         const classId = req.body.classId;
         const includeString = req.query.include;
+        req.globalScriptParams.classId = classId
         eventLog.setEventData(
             req,
             CONSTANTS.EVENT_BASE_AST,
@@ -215,6 +219,7 @@ module.exports = (function () {
             const result = [];
             try {
                 const ciInstanceId = await cmdbobjects.createCmdbObject(req.ticketConfig, req.user.config, classId, req.body.data, req.globalScriptParams);
+                req.globalScriptParams.id = ciInstanceId
                 const ci = await cmdbobjects.getCmdbObject(req.user.config, ciInstanceId, includeString, undefined, req.globalScriptParams);
                 req.result = ci;
                 next();

package/routes/customFormRoutes.js

@@ -130,6 +130,7 @@ module.exports = (function() {
     });
 
     function getRecord(req, res, next, clientConfig, id, mapping, includeString) {
+        req.globalScriptParams.id = id
         customFormController.getRecord(req.formConfig, clientConfig, id, mapping, includeString, globalScriptParams).then(function (result) {
             log.debug('result', result);
             req.includeObjectsList = result.included;
@@ -145,6 +146,7 @@ module.exports = (function() {
 
     routes.put('/:id', function (req, res, next) {
         const id = req.params.id;
+        req.globalScriptParams.id = id
         const origData = JSON.parse(JSON.stringify(req.body));
         const includeString = req.query.include;
         eventLog.setEventData(

package/routes/taskRoutes.js

@@ -85,6 +85,8 @@ module.exports = (function () {
     taskRoutes.get('/:taskId', async function (req, res, next) {
         const parentId = req.parentId;
         const taskId = req.params.taskId;
+        req.globalScriptParams.id = parentId
+        req.globalScriptParams.id2 = taskId
         eventLog.setEventData(
             req,
             req.parentEventBase + '_' + CONSTANTS.EVENT_BASE_TAS,
@@ -103,6 +105,8 @@ module.exports = (function () {
 
     taskRoutes.put('/:taskId', function (req, res, next) {
         const taskId = req.params.taskId;
+        req.globalScriptParams.id = req.parentId;
+        req.globalScriptParams.id2 = taskId
         const origData = JSON.parse(JSON.stringify(req.body));
         eventLog.setEventData(
             req,
@@ -134,6 +138,8 @@ module.exports = (function () {
 
     taskRoutes.get('/:taskId/worklogs', async function (req, res, next) {
         const taskId = req.params.taskId;
+        req.globalScriptParams.id = req.parentId;
+        req.globalScriptParams.id2 = taskId
         eventLog.setEventData(
             req,
             req.parentEventBase + '_' + CONSTANTS.EVENT_BASE_TAS,
@@ -158,6 +164,8 @@ module.exports = (function () {
 
         const origData = JSON.parse(JSON.stringify(req.body));
         const taskId = req.params.taskId;
+        req.globalScriptParams.id = req.parentId;
+        req.globalScriptParams.id2 = taskId
         eventLog.setEventData(
             req,
             req.parentEventBase + '_' + CONSTANTS.EVENT_BASE_TAS,
@@ -199,6 +207,9 @@ module.exports = (function () {
     taskRoutes.get('/:taskId/worklogs/:worklogId', async function (req, res, next) {
         const taskId = req.params.taskId;
         const worklogId = req.params.worklogId;
+        req.globalScriptParams.id = req.parentId;
+        req.globalScriptParams.id2 = taskId
+        req.globalScriptParams.id3 = worklogId
         eventLog.setEventData(
             req,
             req.parentEventBase + '_' + CONSTANTS.EVENT_BASE_TAS,

package/routes/ticketRoutes.js

@@ -136,6 +136,7 @@ module.exports = (function() {
     });
 
     function getTicket(req, res, next, clientConfig, id, mapping, includeString) {
+        req.globalScriptParams.id = id
         ticketController.getTicket(req.ticketConfig, clientConfig, id, mapping, includeString, req.globalScriptParams).then(function (result) {
             log.debug('result', result);
             req.includeObjectsList = result.included;
@@ -151,6 +152,7 @@ module.exports = (function() {
 
     ticketRoutes.put('/:id', function (req, res, next) {
         const id = req.params.id;
+        req.globalScriptParams.id = id
         const origData = JSON.parse(JSON.stringify(req.body));
         const includeString = req.query.include;
         eventLog.setEventData(

package/routes/ticketWorkLogRoutes.js

@@ -36,6 +36,8 @@ module.exports = (function() {
     ticketWorkLogRoutes.get('/:worklogId', function (req, res, next) {
             const ticketId = req.parentId;
             const worklogId = req.params.worklogId;
+            req.globalScriptParams.id = ticketId
+            req.globalScriptParams.id2 = worklogId
             eventLog.setEventData(
                 req,
                 req.parentEventBase,
@@ -167,6 +169,8 @@ module.exports = (function() {
                 .then(result => {
                     const worklogId = result['0'];
                     req.eventData.ticketNumber2 = worklogId;
+                    req.globalScriptParams.id = ticketId
+                    req.globalScriptParams.id2 = worklogId
                     log.debug('WorkLog created', worklogId);
                     ticketWorkLogController.getWorklog(req.ticketConfig, req.user.config, ticketId, worklogId, undefined, req.globalScriptParams).then(worklogResult => {
                         req.result = worklogResult;