@manyos/smileconnect-api 1.39.1 → 1.40.1

package/docs/configuration/config.md

@@ -0,0 +1,323 @@
+# Global Application Settings
+
+All of the following global configuration options needs to be set as Environment Variables for the different containers.
+
+# API
+
+## AR Server Connection
+
+### BASEURL
+
+Base URL of the used arrestfulapi
+
+Sample:
+
+*BASEURL=http://localhost:8080*
+
+### AR_SERVER
+
+Remedy Server to connect to.
+
+Sample:
+
+*AR_SERVER=pier1*
+
+### AR_PORT
+
+Remedy Server TCP Port.
+
+Sample:
+
+*AR_PORT=1234*
+
+### AR_USER
+
+Remedy Admin User who is used for all queries.
+
+Sample:
+
+*AR_USER=Demo*
+
+### AR_PASSWORD
+
+Remedy Admin User password.
+
+Sample:
+
+*AR_PASSWORD=password*
+
+## SSO Connection
+
+For a minimum configuration only the SSO Public Key is required.
+
+### SSO_PUBLIC_KEY
+
+Public Key used to validate JWT tokens.
+
+Sample:
+
+*SSO_PUBLIC_KEY=1635rN5xkbubgmuNQCnKKFu7OlAD3QxiDwecg1bJvFhJW9Qj5YhOwGuX54sOSCjmdTcKT1mCHL61FJ5mzxtbrct97zVwXmi4F4KDKj2PsW+qxUg0Jz/06iTVjtv2H1yBq1*
+
+### SSO_AUDIENCE
+
+Audience (Clients) which are allowed to use JWT tokens. This parameter is optional. If it is not set, no check against the JWT token will be performed.
+
+Sample:
+
+*SSO_AUDIENCE=gihub, jira*
+
+### SSO_ISSUER
+
+Issuer (SSO Server) of the JWT tokens.
+
+Sample:
+
+*SSO_ISSUER=https://sso.mydomain.io/auth/realms/itsmproxy*
+
+### SSO_CLIENTNAME_ATTRIBUTE
+
+The attribute that contains the client name in the token.
+
+Default: *azp*
+
+Set this value if you only want to use a single client in the SSO and service accounts as clients in SMILEconnect. This can be used to manage your SMILEconnect clients via a directory service like LDAP/AD. [More Info](https://datatracker.ietf.org/doc/html/rfc6749#section-1.3.3)
+
+Sample:
+
+*SSO_CLIENTNAME_ATTRIBUTE = "preferred_username"*
+
+### ADMIN_USERS
+
+List of users who are allowed to access /v1/appconfig endpoints.
+
+Sample:
+ADMIN_USERS=username1, username2
+
+### MASTER_CLIENTS
+
+List of clients that can act on behalf of other clients.
+
+The URL Parameter *clientId* is used for this.
+
+Sample:
+MASTER_CLIENTS=idm,adminTool
+
+## Cache Settings
+
+### CACHETTL_CMDB
+Interval in seconds in which before cached CMDB Data is deleted from the cache.
+
+Default: *600*
+
+Sample:
+
+*CACHETTL_CMDB=2800*
+
+### CACHETTL_ORGDATA
+Interval in seconds in which before cached Org Data like People, Support Groups, Organisations are deleted from the cache.
+
+Default: *3600*
+
+Sample:
+
+*CACHETTL_ORGDATA=7200*
+
+### CACHETTL_TICKETS
+
+Interval in seconds in which before cached Ticket Data is deleted from the cache.
+
+Default: *1*
+
+Sample: 600
+
+### CACHETTL_TASK
+
+Interval in seconds in which before cached Task Data is deleted from the cache.
+
+Default: *1*
+
+Sample:
+
+*CACHETTL_TASK=600*
+
+## Logging
+
+### Loglevel
+
+Loglevel of the api. Defaults to *error*
+
+## Rate Limits
+
+### RATE_LIMIT
+
+Defines how many API requests from a single IP are allowed within a 15min timeframe.
+
+Default *10000*
+
+Sample:
+
+*RATE_LIMIT=600*
+
+### LIMIT_DEFAULT
+
+Limits the resultsize of all queries against the Remedy Server. Sets a default that can be overwritten by requests. Can be used to prevent performance issues.
+Affects also relations.
+
+Default *unlimited*
+
+Sample:
+
+*LIMIT_DEFAULT=100*
+
+### LIMIT_MAX
+
+Limits the resultsize of all queries against the Remedy Server. Defines a global maximum that can not be overwritten by requests. Will only be overwritten by Limits defined for certains clients. Can be used to prevent performance issues.
+Affects also relations.
+
+Default *unlimited*
+
+Sample:
+
+*LIMIT_MAX=100*
+
+### MAX_HTTP_SOCKETS
+
+Defines how many TCP Sockets are used for outgoing connections. (Parallel connections to the Remedy REST API.)
+
+Reduce this parameter if you see ECONNRESET or socket hang up errors.
+
+This parameter has direct impact on performance.
+
+Default *10*
+
+Sample:
+
+*MAX_HTTP_SOCKETS=15*
+
+
+# Event Manager
+
+## AR Server Connection
+
+### BASEURL
+
+Base URL of the used arrestfulapi
+
+Sample:
+
+*BASEURL=http://localhost:8080*
+
+### AR_SERVER
+
+Remedy Server to connect to.
+
+Sample:
+
+*AR_SERVER=pier1*
+
+### AR_PORT
+
+Remedy Server TCP Port.
+
+Sample:
+
+*AR_PORT=1234*
+
+### AR_USER
+
+Remedy Admin User who is used for all queries.
+
+Sample:
+
+*AR_USER=Demo*
+
+### AR_PASSWORD
+
+Remedy Admin User password.
+
+Sample:
+
+*AR_PASSWORD=password*
+
+## SSO Connection
+
+For a minimum configuration only the SSO Public Key is required.
+
+### SSO_PUBLIC_KEY
+
+Public Key used to validate JWT tokens.
+
+Sample:
+
+*SSO_PUBLIC_KEY=1635rN5xkbubgmuNQCnKKFu7OlAD3QxiDwecg1bJvFhJW9Qj5YhOwGuX54sOSCjmdTcKT1mCHL61FJ5mzxtbrct97zVwXmi4F4KDKj2PsW+qxUg0Jz/06iTVjtv2H1yBq1*
+
+### SSO_AUDIENCE
+
+Audience (Clients) which are allowed to use JWT tokens. This parameter is optional. If it is not set, no check against the JWT token will be performed.
+
+Sample:
+
+*SSO_AUDIENCE=gihub, jira*
+
+### SSO_ISSUER
+
+Issuer (SSO Server) of the JWT tokens.
+
+Sample:
+
+*SSO_ISSUER=https://sso.mydomain.io/auth/realms/itsmproxy*
+
+
+## Logging
+
+### Loglevel
+
+Loglevel of the api. Defaults to *error*
+
+# GUI
+
+## SMILEconnect
+
+### REACT_APP_API_URL
+
+The URL where the api is deployed.
+
+Sample:
+*REACT_APP_API_URL=https://sc-api.mydomain.io/*
+###
+
+Sample:
+*REACT_APP_TOKEN_REFRESHTIME=30*
+
+### REACT_APP_EVENTMGR_URL
+
+The URL where the eventmanager is deployed.
+
+Sample:
+*REACT_APP_EVENTMGR_URL=https://sc-event.mydomain.io/*
+
+
+## SSO
+
+### REACT_APP_SSO_URL
+
+The URL of the OIDC Provider for user authentication
+
+Sample:
+*REACT_APP_SSO_URL=https://sso.mydomain.io/auth/realms/itsmproxy*
+
+## GUI
+
+### REACT_APP_GUI_URL
+
+The Baseurl where the GUI is deployed.
+
+Sample:
+*REACT_APP_GUI_URL=https://sc-gui.mydomain.io/*
+
+### REACT_APP_WIZZARD_URL
+
+Url of the Midtier Appwizzard.
+
+Sample:
+*REACT_APP_WIZZARD_URL=https://midtier.mydomain.io/arsys/forms/arserver/MYS:SMILEconnect_NewVendor*

package/docs/{eventlog → configuration}/events.md

@@ -1,24 +1,27 @@
----
-layout: page
-title: API Queue Events
-subtitle: All events created / processed by the event manager
-use-site-title: true
----
+# Events
+
+The following events are generated by API and can be used to react on.
 
 # Change
 
 * CHG_Query
 
-* CHG_Created 
+* CHG_Created
+
+* CHG_Modified
+
+* CHG_Worklog_Created
 
 # Incident
 
-* INC_Worklog_Created
+* INC_Query
 
 * INC_Created
 
 * INC_Modified
 
+* INC_Worklog_Created
+
 # CMDB
 
 * CMDB_Query

package/docs/configuration/mapping.md

@@ -0,0 +1,60 @@
+# Field Mappings
+
+Field mappings are used to map Remedy Field names to more appropriate REST-API names. We suggest that you remove spaces and use camel case notation. E.g. The remedy field *Remedy Login ID* could be mapped to *userId*. 
+
+Field mappings used globally for all clients.
+
+Mappings are stored in the /conf/mapping.json file. They can be managed in the GUI.
+
+## Manage field mappings
+
+![Client Configuration](../_media/gui_mapping_inc.png)
+
+## Sample client config
+
+
+```json
+{
+  "cmdbobject":[
+    {"oldName":"Instance Id", "newName" : "id"},
+    {"oldName":"Tag Number", "newName" : "tagNumber"},
+    {"oldName":"Name", "newName" : "name"},
+    {"oldName":"AssetLifecycleStatus", "newName" : "assetlifecycleStatus"},
+    {"oldName":"Category", "newName" : "category"},
+    {"oldName":"Item", "newName" : "item"},
+    {"oldName":"Type", "newName" : "type"},
+    {"oldName":"Availability", "newName" : "availability"},
+    {"oldName":"Confidentiality", "newName" : "confidentiality"},
+    {"oldName":"Integrity", "newName" : "integrity"},
+    {"oldName":"Authenticity", "newName" : "authenticity"},
+    {"oldName":"Model Number", "newName" : "model"},
+    {"oldName":"Class Id", "newName" : "classId"},
+    {"oldName":"Reconciliation Identity", "newName" : "reconId"}
+  ],
+  "change":[
+    {"oldName":"Infrastructure Change ID", "newName" : "id"},
+    {"oldName":"Categorization Tier 1", "newName" : "opsCat1"},
+    {"oldName":"Categorization Tier 2", "newName" : "opsCat2"},
+    {"oldName":"Categorization Tier 3", "newName" : "opsCat3"},
+    {"oldName":"Product Cat Tier 1", "newName" : "prodCat1"},
+    {"oldName":"Product Cat Tier 2", "newName" : "prodCat2"},
+    {"oldName":"Product Cat Tier 3", "newName" : "prodCat3"},
+    {"oldName":"Product Name (2)", "newName" : "productName"},
+    {"oldName":"Description", "newName" : "summary"},
+    {"oldName":"Detailed Description", "newName" : "detailedDescription"},
+    {"oldName":"Status Reason", "newName" : "statusReason"},
+    {"oldName":"Change Request Status", "newName" : "status"},
+    {"oldName":"Requested Start Date", "newName" : "requestedStartDate"},
+    {"oldName":"Requested End Date", "newName" : "requestedEndDate"},
+    {"oldName":"Scheduled Start Date", "newName" : "scheduledStartDate"},
+    {"oldName":"Scheduled End Date", "newName" : "scheduledEndDate"},
+    {"oldName":"Support Group ID", "newName" : "managerGroup"},
+    {"oldName":"Support Group ID 2", "newName" : "coordinatorGroup"},
+    {"oldName":"Customer Person ID", "newName" : "customerId"}
+  ],
+  "newChange":[
+    {"oldName":"Description", "newName" : "summary"},
+    {"oldName":"TemplateID", "newName" : "template"}
+  ]
+}
+```

package/docs/howto/{worklog-attachment.md → attachments.md}

@@ -1,11 +1,4 @@
----
-layout: page
-title: Attachments
-subtitle: In this guide we'll show you how to save and read attachments from worklogs.
-use-site-title: true
-gh-badge: [star, fork, follow]
-gh-repo: daattali/beautiful-jekyll
----
+# Attachments
 
 In this guide we'll show you how to save and read attachments from worklogs.
 
@@ -14,7 +7,7 @@ In this guide we'll show you how to save and read attachments from worklogs.
 
 To store an attachment you first need to create a worklog. The worklog contains an attachment url:
 
-{% highlight json linenos %}
+```json
 {
     "data": {
         "summary": "Implementation update",
@@ -30,7 +23,7 @@ To store an attachment you first need to create a worklog. The worklog contains
         }
     ]
 }
-{% endhighlight %}
+```
 
 This URL will be used to upload or download the attachment.
 
@@ -70,11 +63,11 @@ Provide the attachment as application/x-www-form-urlencoded with the key "file".
 
 ### Sample Response
 
-POST:https://*api-fqdn*/v1/incidents/INC000000000217/worklogs/WLG000000001240/attachment
+POST: https://*api-fqdn*/v1/incidents/INC000000000217/worklogs/WLG000000001240/attachment
 
-{% highlight json linenos %}
+```json
 "['WLG000000001240':'success']"
-{% endhighlight %}
+```
 
 ### Postman Sample Request / Response
 ![architecure of isapi](../img/attachment-upload.png)
@@ -108,6 +101,6 @@ Use your [API Token](token.md)
 
 ### Sample Response
 
-GET:https://*api-fqdn*/v1/incidents/INC000000000217/worklogs/WLG000000000533/attachment
+GET: https://*api-fqdn*/v1/incidents/INC000000000217/worklogs/WLG000000000533/attachment
 
-The file will be returned as application/octet-stream. The filename will be returned in the header Content-disposition. e.g. attachment; filename=90502081_l.jpg
+The file will be returned as application/octet-stream. The filename will be returned in the header Content-disposition. e.g. attachment; filename=90502081_l.jpg

package/docs/howto/cmdbobjects.md

@@ -1,10 +1,4 @@
----
-layout: page
-title: Access CMDBObjects
-subtitle: In this guide you will learn to do the basic operations with an CMDB Objects.
-use-site-title: true
-gh-badge: [star, fork, follow]
-gh-repo: daattali/beautiful-jekyll
+CMDBObjects
 ---
 
 # Read a CMDBObject
@@ -31,13 +25,13 @@ To read a cmdbobject you need to do a GET request to the /v1/cmdbobjects/*id* en
 
 *Type*: Bearer
 
-Use your [API Token](token.md)
+Use your [API Token](howto/token.md)
 
 ### Sample Response
 
-GET:https://*api-fqdn*/v1/cmdbobjects/AGGarserver000PMIYWAPL1SMUB5AZ
+GET: https://*api-fqdn*/v1/cmdbobjects/AGGarserver000PMIYWAPL1SMUB5AZ
 
-{% highlight json linenos %}
+```json
 {
     "data": {
         "id": "AGGarserver000PMIYWAPL1SMUB5AZ",
@@ -265,7 +259,7 @@ GET:https://*api-fqdn*/v1/cmdbobjects/AGGarserver000PMIYWAPL1SMUB5AZ
        ]
    }
 }
-{% endhighlight %}
+```
 
 # Search for CMDBObjects
 
@@ -289,7 +283,7 @@ To search for objects do a POST to the /v1/cmdbobjects/search endpoint of your A
 
 *Type*: Bearer
 
-Use your [API Token](token.md)
+Use your [API Token](howto/token.md)
 
 ### Body
 
@@ -297,9 +291,9 @@ Provide the searchString you want to use
 
 ### Sample Request
 
-POST:https://*api-fqdn*/v1/cmdbobjects/search
+POST: https://*api-fqdn*/v1/cmdbobjects/search
 
-{% highlight json linenos %}
+```json
 {
 	"searchString":"'name' LIKE \"Computer%\"",
 	"getRelations":true,
@@ -315,11 +309,11 @@ POST:https://*api-fqdn*/v1/cmdbobjects/search
 	"limit": 100,
 	"offset": 4
 }
-{% endhighlight %}
+```
 
 ### Sample Response
 
-{% highlight json linenos %}
+```json
 {
     "data": [
         {
@@ -336,4 +330,4 @@ POST:https://*api-fqdn*/v1/cmdbobjects/search
     ],
     "included": {}
 }
-{% endhighlight %}
+```

package/docs/howto/incidents.md

@@ -1,13 +1,6 @@
----
-layout: page
-title: Incident handling
-subtitle: In this guide you will learn to do the basic operations with an incident.
-use-site-title: true
-gh-badge: [star, fork, follow]
-gh-repo: daattali/beautiful-jekyll
----
+# Incdent Requests
 
-In this guide we model the full lifecylce of a simple inbound API that delivers Incidents into your system. First we'll create one. We will then read it again and later resolve it. 
+In this guide we model the full lifecylce of a simple inbound API that delivers Incidents into your system. First we'll create one. We will then read it again and later resolve it.
 
 # Create an Incident
 
@@ -39,20 +32,20 @@ Provide all your needed incident data (see mapping -> new Incident) within the *
 
 ### Sample Request
 
-POST:https://*api-fqdn*/v1/incidents
+POST: https://*api-fqdn*/v1/incidents
 
-{% highlight json linenos %}
+```json
 {
     "data": {
         "summary": "New Incident",
         "detailedDescription": "Here are the details"
     }
 }
-{% endhighlight %}
+```
 
 ### Sample Response
 
-{% highlight json linenos %}
+```json
 {
     "data": {
         "id": "INC000000000217",
@@ -91,7 +84,7 @@ POST:https://*api-fqdn*/v1/incidents
         ]
     }
 }
-{% endhighlight %}
+```
 
 # Read an Incident
 
@@ -121,9 +114,9 @@ Use your [API Token](token.md)
 
 ### Sample Response
 
-GET:https://*api-fqdn*/v1/incidents/INC000000000217
+GET: https://*api-fqdn*/v1/incidents/INC000000000217
 
-{% highlight json linenos %}
+```
 {
     "data": {
         "id": "INC000000000217",
@@ -162,7 +155,7 @@ GET:https://*api-fqdn*/v1/incidents/INC000000000217
         ]
     }
 }
-{% endhighlight %}
+```
 
 # Update an Incident
 
@@ -196,21 +189,21 @@ Provide all the attributes you want to update.
 
 ### Sample Request
 
-PUT:https://*api-fqdn*/v1/incidents/INC000000000217
+PUT: https://*api-fqdn*/v1/incidents/INC000000000217
 
-{% highlight json linenos %}
+```json
 {
     "data": {
         "status": "Resolved",
-        "statusReason" : "No Further Action Required", 
+        "statusReason" : "No Further Action Required",
         "resolution": "Please restart your computer."
     }
 }
-{% endhighlight %}
+```
 
 ### Sample Response
 
-{% highlight json linenos %}
+```
 {
     "data": {
         "id": "INC000000000217",
@@ -241,4 +234,4 @@ PUT:https://*api-fqdn*/v1/incidents/INC000000000217
     },
     "included": {}
 }
-{% endhighlight %}
+```