@itentialopensource/adapter-paragon_ems_device_manager 0.2.4 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (18) hide show
  1. package/AUTH.md +49 -57
  2. package/BROKER.md +31 -19
  3. package/CALLS.md +59 -23
  4. package/CHANGELOG.md +16 -0
  5. package/PROPERTIES.md +5 -0
  6. package/README.md +60 -63
  7. package/SYSTEMINFO.md +16 -6
  8. package/TAB1.md +13 -0
  9. package/TAB2.md +377 -0
  10. package/metadata.json +15 -4
  11. package/package.json +7 -9
  12. package/propertiesSchema.json +5 -0
  13. package/refs?service=git-upload-pack +0 -0
  14. package/report/adapterInfo.json +4 -4
  15. package/report/updateReport1717075981795.json +120 -0
  16. package/sampleProperties.json +69 -31
  17. package/test/integration/adapterTestIntegration.js +1 -0
  18. package/test/unit/adapterTestUnit.js +1 -3
package/AUTH.md CHANGED
@@ -1,77 +1,69 @@
1
- ## Authenticating Paragon_ems_device_manager Adapter
1
+ ## Authenticating Paragon EMS Device Manager Adapter
2
2
 
3
- This document will go through the steps for authenticating the Paragon_ems_device_manager adapter with Basic Authentication. Properly configuring the properties for an adapter in IAP is critical for getting the adapter online. You can read more about adapter authentication <a href="https://www.itential.com/automation-platform/integrations/adapters-resources/authentication/" target="_blank">HERE</a>.
3
+ This document will go through the steps for authenticating the Paragon EMS Device Manager adapter with Multi Step Authentication. Properly configuring the properties for an adapter in IAP is critical for getting the adapter online. You can read more about adapter authentication <a href="https://docs.itential.com/opensource/docs/authentication" target="_blank">HERE</a>.
4
4
 
5
5
  ### Multi Step Authentication
6
- The Paragon_ems_device_manager adapter requires Muti Step Authentication. If you change authentication methods, you should change this section accordingly and merge it back into the adapter repository.
6
+ The Paragon EMS Device Manager adapter requires Multi Step Authentication. If you change authentication methods, you should change this section accordingly and merge it back into the adapter repository.
7
7
 
8
8
  STEPS
9
- 1. Ensure you have access to a Paragon_ems_device_manager server and that it is running
9
+ 1. Ensure you have access to a Paragon server and that it is running
10
10
  2. Follow the steps in the README.md to import the adapter into IAP if you have not already done so
11
11
  3. Use the properties below for the ```properties.authentication``` field
12
12
  ```json
13
- "authentication": {
14
- "auth_method": "multi_step_authentication",
15
- "username": "admin@pronghorn",
16
- "password": "admin",
17
- "token": "",
18
- "token_user_field": "username",
19
- "token_password_field": "password",
20
- "token_result_field": "token",
21
- "token_URI_path": "",
22
- "invalid_token_error": 401,
23
- "token_timeout": 600000,
24
- "token_cache": "local",
25
- "auth_field": "header.headers.x-iam-token",
26
- "auth_field_format": "{tokenp2}",
27
- "auth_logging": true,
28
- "client_id": "",
29
- "client_secret": "",
30
- "grant_type": "",
31
- "multiStepAuthCalls": [
32
- {
33
- "name": "getFirstToken",
34
- "requestFields": {
35
- "user": {
36
- "domain": "",
37
- "name": "admin"
38
- },
39
- "password": "Secretpassword",
40
- "methods": [
41
- "PASSWORD"
42
- ]
43
- },
44
- "responseFields": {
45
- "firstIdToken": "id_token",
46
- "scopeId": "scopes.0.id"
47
- },
48
- "successfullResponseCode": 200
49
- },
50
- {
51
- "name": "getSecondToken",
52
- "requestFields": {
53
- "token": "{getFirstToken.responseFields.firstIdToken}",
54
- "scopeId": "{getFirstToken.responseFields.scopeId}",
55
- "methods": [
56
- "TOKEN"
57
- ]
58
- },
59
- "responseFields": {
60
- "tokenp2": "id_token"
61
- },
62
- "successfullResponseCode": 200
63
- }
13
+ "authentication": {
14
+ "auth_method": "multi_step_authentication",
15
+ "token_timeout": 1800000,
16
+ "token_cache": "local",
17
+ "invalid_token_error": 401,
18
+ "auth_field": "header.headers.x-iam-token",
19
+ "auth_field_format": "{tokenp2}",
20
+ "auth_logging": false,
21
+ "multiStepAuthCalls": [
22
+ {
23
+ "name": "getFirstToken",
24
+ "requestFields": {
25
+ "user": {
26
+ "domain": "",
27
+ "name": ""
28
+ },
29
+ "password": "",
30
+ "methods": [
31
+ "PASSWORD"
64
32
  ]
65
- }
33
+ },
34
+ "responseFields": {
35
+ "firstIdToken": "id_token",
36
+ "scopeId": "scopes.0.id"
37
+ },
38
+ "successfullResponseCode": 200
39
+ },
40
+ {
41
+ "name": "getSecondToken",
42
+ "requestFields": {
43
+ "token": "{getFirstToken.responseFields.firstIdToken}",
44
+ "scopeId": "{getFirstToken.responseFields.scopeId}",
45
+ "methods": [
46
+ "TOKEN"
47
+ ]
48
+ },
49
+ "responseFields": {
50
+ "tokenp2": "id_token"
51
+ },
52
+ "successfullResponseCode": 200
53
+ }
54
+ ]
55
+ }
66
56
  ```
57
+ you can leave all of the other properties in the authentication section, they will not be used when the auth_method is multi_step_authentication. <br>
67
58
  4. Restart the adapter. If your properties were set correctly, the adapter should go online.
68
59
 
69
60
  ### Troubleshooting
70
- - Make sure you copied over the correct username and password.
61
+ - Make sure you copied over the correct credentials.
71
62
  - Turn on debug level logs for the adapter in IAP Admin Essentials.
72
63
  - Turn on auth_logging for the adapter in IAP Admin Essentials (adapter properties).
73
64
  - Investigate the logs - in particular:
74
65
  - The FULL REQUEST log to make sure the proper headers are being sent with the request.
75
66
  - The FULL BODY log to make sure the payload is accurate.
76
67
  - The CALL RETURN log to see what the other system is telling us.
68
+ - Credentials should be ** masked ** by the adapter so make sure you verify the username and password - including that there are erroneous spaces at the front or end.
77
69
  - Remember when you are done to turn auth_logging off as you do not want to log credentials.
package/BROKER.md CHANGED
@@ -22,18 +22,25 @@ Below is an example of how you may set up the properties for this call.
22
22
  {
23
23
  "path": "/{org}/get/devices",
24
24
  "method": "GET",
25
+ "pagination": {
26
+ "offsetVar": "",
27
+ "limitVar": "",
28
+ "incrementBy": "limit",
29
+ "requestLocation": "query"
30
+ },
25
31
  "query": {},
26
32
  "body": {},
27
33
  "headers": {},
28
34
  "handleFailure": "ignore",
35
+ "responseDataKey": "",
29
36
  "requestFields": {
30
37
  "org": "555"
31
38
  },
32
39
  "responseFields": {
33
- "name": "host",
34
- "ostype": "os",
40
+ "name": "{hostField}",
41
+ "ostype": "{osField}",
35
42
  "ostypePrefix": "system-",
36
- "ipaddress": "attributes.ipaddr",
43
+ "ipaddress": "{attributes.ipaddr}",
37
44
  "port": "443"
38
45
  }
39
46
  },
@@ -44,16 +51,17 @@ Below is an example of how you may set up the properties for this call.
44
51
  "body": {},
45
52
  "headers": {},
46
53
  "handleFailure": "ignore",
54
+ "responseDataKey": "",
47
55
  "requestFields": {
48
56
  "org": "777"
49
57
  },
50
58
  "responseFields": {
51
- "name": "host",
52
- "ostype": "os",
59
+ "name": "{hostField}",
60
+ "ostype": "{osField}",
53
61
  "ostypePrefix": "system-",
54
- "ipaddress": "attributes.ipaddr",
62
+ "ipaddress": "{attributes.ipaddr}",
55
63
  "port": "443",
56
- "myorg": "org"
64
+ "myorg": "{orgField}"
57
65
  }
58
66
  }
59
67
  ]
@@ -88,12 +96,13 @@ Below is an example of how you may set up the properties for this call.
88
96
  "headers": {},
89
97
  "handleFailure": "ignore",
90
98
  "statusValue": "online",
99
+ "responseDataKey": "",
91
100
  "requestFields": {
92
- "org": "myorg",
93
- "id": "name"
101
+ "org": "{myorg}",
102
+ "id": "{name}"
94
103
  },
95
104
  "responseFields": {
96
- "status": "status"
105
+ "status": "{status}"
97
106
  }
98
107
  }
99
108
  ]
@@ -129,9 +138,10 @@ Below is an example of how you may set up the properties for this call.
129
138
  "body": {},
130
139
  "headers": {},
131
140
  "handleFailure": "ignore",
141
+ "responseDataKey": "",
132
142
  "requestFields": {
133
- "org": "myorg",
134
- "id": "name"
143
+ "org": "{myorg}",
144
+ "id": "{name}"
135
145
  }
136
146
  "responseFields": {}
137
147
  },
@@ -142,8 +152,9 @@ Below is an example of how you may set up the properties for this call.
142
152
  "body": {},
143
153
  "headers": {},
144
154
  "handleFailure": "ignore",
155
+ "responseDataKey": "",
145
156
  "requestFields": {
146
- "org": "myorg"
157
+ "org": "{myorg}"
147
158
  }
148
159
  "responseFields": {}
149
160
  }
@@ -178,17 +189,18 @@ Below is an example of how you may set up the properties for this call.
178
189
  "body": {},
179
190
  "headers": {},
180
191
  "handleFailure": "ignore",
192
+ "responseDataKey": "",
181
193
  "requestFields": {
182
- "org": "myorg",
183
- "id": "name"
194
+ "org": "{myorg}",
195
+ "id": "{name}"
184
196
  },
185
197
  "responseFields": {
186
- "name": "host",
187
- "ostype": "os",
198
+ "name": "{hostField}",
199
+ "ostype": "{osField}",
188
200
  "ostypePrefix": "system-",
189
- "ipaddress": "attributes.ipaddr",
201
+ "ipaddress": "{attributes.ipaddr}",
190
202
  "port": "443",
191
- "myorg": "org"
203
+ "myorg": "{orgField}"
192
204
  }
193
205
  }
194
206
  ]
package/CALLS.md CHANGED
@@ -19,7 +19,7 @@ These are adapter methods that IAP or you might use. There are some other method
19
19
  </tr>
20
20
  <tr>
21
21
  <td style="padding:15px">healthCheck(callback)</td>
22
- <td style="padding:15px">This call ensures that the adapter can communicate with Paragon_ems_device_manager. The actual call that is used is defined in the adapter properties and .system entities action.json file.</td>
22
+ <td style="padding:15px">This call ensures that the adapter can communicate with Adapter for Paragon EMS Device Manager. The actual call that is used is defined in the adapter properties and .system entities action.json file.</td>
23
23
  <td style="padding:15px">No</td>
24
24
  </tr>
25
25
  <tr>
@@ -29,7 +29,7 @@ These are adapter methods that IAP or you might use. There are some other method
29
29
  </tr>
30
30
  <tr>
31
31
  <td style="padding:15px">encryptProperty(property, technique, callback)</td>
32
- <td style="padding:15px">This call will take the provided property and technique, and return the property encrypted with the technique. This allows the property to be used in the adapterProps section for the credential password so that the password does not have to be in clear text. The adapter will decrypt the property as needed for communications with Paragon_ems_device_manager.</td>
32
+ <td style="padding:15px">This call will take the provided property and technique, and return the property encrypted with the technique. This allows the property to be used in the adapterProps section for the credential password so that the password does not have to be in clear text. The adapter will decrypt the property as needed for communications with Adapter for Paragon EMS Device Manager.</td>
33
33
  <td style="padding:15px">No</td>
34
34
  </tr>
35
35
  <tr>
@@ -37,11 +37,6 @@ These are adapter methods that IAP or you might use. There are some other method
37
37
  <td style="padding:15px">This call provides the ability to update the adapter configuration from IAP - includes actions, schema, mockdata and other configurations.</td>
38
38
  <td style="padding:15px">Yes</td>
39
39
  </tr>
40
- <tr>
41
- <td style="padding:15px">iapFindAdapterPath(apiPath, callback)</td>
42
- <td style="padding:15px">This call provides the ability to see if a particular API path is supported by the adapter.</td>
43
- <td style="padding:15px">Yes</td>
44
- </tr>
45
40
  <tr>
46
41
  <td style="padding:15px">iapSuspendAdapter(mode, callback)</td>
47
42
  <td style="padding:15px">This call provides the ability to suspend the adapter and either have requests rejected or put into a queue to be processed after the adapter is resumed.</td>
@@ -57,12 +52,16 @@ These are adapter methods that IAP or you might use. There are some other method
57
52
  <td style="padding:15px">This call will return the requests that are waiting in the queue if throttling is enabled.</td>
58
53
  <td style="padding:15px">Yes</td>
59
54
  </tr>
55
+ <tr>
56
+ <td style="padding:15px">iapFindAdapterPath(apiPath, callback)</td>
57
+ <td style="padding:15px">This call provides the ability to see if a particular API path is supported by the adapter.</td>
58
+ <td style="padding:15px">Yes</td>
59
+ </tr>
60
60
  <tr>
61
61
  <td style="padding:15px">iapTroubleshootAdapter(props, persistFlag, adapter, callback)</td>
62
62
  <td style="padding:15px">This call can be used to check on the performance of the adapter - it checks connectivity, healthcheck and basic get calls.</td>
63
63
  <td style="padding:15px">Yes</td>
64
64
  </tr>
65
-
66
65
  <tr>
67
66
  <td style="padding:15px">iapRunAdapterHealthcheck(adapter, callback)</td>
68
67
  <td style="padding:15px">This call will return the results of a healthcheck.</td>
@@ -83,6 +82,21 @@ These are adapter methods that IAP or you might use. There are some other method
83
82
  <td style="padding:15px">This call will push the adapter configuration from the entities directory into the Adapter or IAP Database.</td>
84
83
  <td style="padding:15px">Yes</td>
85
84
  </tr>
85
+ <tr>
86
+ <td style="padding:15px">iapDeactivateTasks(tasks, callback)</td>
87
+ <td style="padding:15px">This call provides the ability to remove tasks from the adapter.</td>
88
+ <td style="padding:15px">Yes</td>
89
+ </tr>
90
+ <tr>
91
+ <td style="padding:15px">iapActivateTasks(tasks, callback)</td>
92
+ <td style="padding:15px">This call provides the ability to add deactivated tasks back into the adapter.</td>
93
+ <td style="padding:15px">Yes</td>
94
+ </tr>
95
+ <tr>
96
+ <td style="padding:15px">iapExpandedGenericAdapterRequest(metadata, uriPath, restMethod, pathVars, queryData, requestBody, addlHeaders, callback)</td>
97
+ <td style="padding:15px">This is an expanded Generic Call. The metadata object allows us to provide many new capabilities within the generic request.</td>
98
+ <td style="padding:15px">Yes</td>
99
+ </tr>
86
100
  <tr>
87
101
  <td style="padding:15px">genericAdapterRequest(uriPath, restMethod, queryData, requestBody, addlHeaders, callback)</td>
88
102
  <td style="padding:15px">This call allows you to provide the path to have the adapter call. It is an easy way to incorporate paths that have not been built into the adapter yet.</td>
@@ -94,23 +108,46 @@ These are adapter methods that IAP or you might use. There are some other method
94
108
  <td style="padding:15px">Yes</td>
95
109
  </tr>
96
110
  <tr>
97
- <td style="padding:15px">iapHasAdapterEntity(entityType, entityId, callback)</td>
98
- <td style="padding:15px">This call verifies the adapter has the specific entity.</td>
99
- <td style="padding:15px">No</td>
111
+ <td style="padding:15px">iapRunAdapterLint(callback)</td>
112
+ <td style="padding:15px">Runs lint on the addapter and provides the information back.</td>
113
+ <td style="padding:15px">Yes</td>
100
114
  </tr>
101
115
  <tr>
102
- <td style="padding:15px">iapVerifyAdapterCapability(entityType, actionType, entityId, callback)</td>
103
- <td style="padding:15px">This call verifies the adapter can perform the provided action on the specific entity.</td>
104
- <td style="padding:15px">No</td>
116
+ <td style="padding:15px">iapRunAdapterTests(callback)</td>
117
+ <td style="padding:15px">Runs baseunit and unit tests on the adapter and provides the information back.</td>
118
+ <td style="padding:15px">Yes</td>
105
119
  </tr>
106
120
  <tr>
107
- <td style="padding:15px">iapUpdateAdapterEntityCache()</td>
108
- <td style="padding:15px">This call will update the entity cache.</td>
109
- <td style="padding:15px">No</td>
121
+ <td style="padding:15px">iapGetAdapterInventory(callback)</td>
122
+ <td style="padding:15px">This call provides some inventory related information about the adapter.</td>
123
+ <td style="padding:15px">Yes</td>
110
124
  </tr>
111
125
  </table>
112
126
  <br>
127
+
128
+ ### Adapter Cache Calls
113
129
 
130
+ These are adapter methods that are used for adapter caching. If configured, the adapter will cache based on the interval provided. However, you can force a population of the cache manually as well.
131
+
132
+ <table border="1" class="bordered-table">
133
+ <tr>
134
+ <th bgcolor="lightgrey" style="padding:15px"><span style="font-size:12.0pt">Method Signature</span></th>
135
+ <th bgcolor="lightgrey" style="padding:15px"><span style="font-size:12.0pt">Description</span></th>
136
+ <th bgcolor="lightgrey" style="padding:15px"><span style="font-size:12.0pt">Workflow?</span></th>
137
+ </tr>
138
+ <tr>
139
+ <td style="padding:15px">iapPopulateEntityCache(entityTypes, callback)</td>
140
+ <td style="padding:15px">This call populates the adapter cache.</td>
141
+ <td style="padding:15px">Yes</td>
142
+ </tr>
143
+ <tr>
144
+ <td style="padding:15px">iapRetrieveEntitiesCache(entityType, options, callback)</td>
145
+ <td style="padding:15px">This call retrieves the specific items from the adapter cache.</td>
146
+ <td style="padding:15px">Yes</td>
147
+ </tr>
148
+ </table>
149
+ <br>
150
+
114
151
  ### Adapter Broker Calls
115
152
 
116
153
  These are adapter methods that are used to integrate to IAP Brokers. This adapter currently supports the following broker calls.
@@ -129,32 +166,31 @@ These are adapter methods that are used to integrate to IAP Brokers. This adapte
129
166
  <tr>
130
167
  <td style="padding:15px">getDevice(deviceName, callback)</td>
131
168
  <td style="padding:15px">This call returns the details of the requested device.</td>
132
- <td style="padding:15px">Yes</td>
169
+ <td style="padding:15px">No</td>
133
170
  </tr>
134
171
  <tr>
135
172
  <td style="padding:15px">getDevicesFiltered(options, callback)</td>
136
173
  <td style="padding:15px">This call returns the list of devices that match the criteria provided in the options filter.</td>
137
- <td style="padding:15px">Yes</td>
174
+ <td style="padding:15px">No</td>
138
175
  </tr>
139
176
  <tr>
140
177
  <td style="padding:15px">isAlive(deviceName, callback)</td>
141
178
  <td style="padding:15px">This call returns whether the device status is active</td>
142
- <td style="padding:15px">Yes</td>
179
+ <td style="padding:15px">No</td>
143
180
  </tr>
144
181
  <tr>
145
182
  <td style="padding:15px">getConfig(deviceName, format, callback)</td>
146
183
  <td style="padding:15px">This call returns the configuration for the selected device.</td>
147
- <td style="padding:15px">Yes</td>
184
+ <td style="padding:15px">No</td>
148
185
  </tr>
149
186
  <tr>
150
187
  <td style="padding:15px">iapGetDeviceCount(callback)</td>
151
188
  <td style="padding:15px">This call returns the count of devices.</td>
152
- <td style="padding:15px">Yes</td>
189
+ <td style="padding:15px">No</td>
153
190
  </tr>
154
191
  </table>
155
192
  <br>
156
193
 
157
-
158
194
  ### Specific Adapter Calls
159
195
 
160
196
  Specific adapter calls are built based on the API of the Paragon_ems_device_manager. The Adapter Builder creates the proper method comments for generating JS-DOC for the adapter. This is the best way to get information on the calls.
package/CHANGELOG.md CHANGED
@@ -1,4 +1,20 @@
1
1
 
2
+ ## 0.3.0 [07-17-2024]
3
+
4
+ * Minor/2024 auto migration
5
+
6
+ See merge request itentialopensource/adapters/controller-orchestrator/adapter-paragon_ems_device_manager!7
7
+
8
+ ---
9
+
10
+ ## 0.2.5 [03-28-2024]
11
+
12
+ * Changes made at 2024.03.28_13:31PM
13
+
14
+ See merge request itentialopensource/adapters/controller-orchestrator/adapter-paragon_ems_device_manager!6
15
+
16
+ ---
17
+
2
18
  ## 0.2.4 [03-15-2024]
3
19
 
4
20
  * Update metadata.json
package/PROPERTIES.md CHANGED
@@ -97,6 +97,7 @@ This section defines **all** the properties that are available for the adapter,
97
97
  }
98
98
  },
99
99
  "devicebroker": {
100
+ "enabled": false,
100
101
  "getDevice": [
101
102
  {
102
103
  "path": "/call/to/get/device/details",
@@ -580,6 +581,10 @@ The device broker section defines the properties used integrate Paragon_ems_devi
580
581
  <th bgcolor="lightgrey" style="padding:15px"><span style="font-size:12.0pt">Property</span></th>
581
582
  <th bgcolor="lightgrey" style="padding:15px"><span style="font-size:12.0pt">Description</span></th>
582
583
  </tr>
584
+ <tr>
585
+ <td style="padding:15px">enabled</td>
586
+ <td style="padding:15px">Whether or not the device broker calls have been mapped.</td>
587
+ </tr>
583
588
  <tr>
584
589
  <td style="padding:15px">getDevice</td>
585
590
  <td style="padding:15px">The array of calls used to get device details for the broker</td>