@adobe/acc-js-sdk 1.1.16 → 1.1.18
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.
- package/docs/caches.html +25 -10
- package/docs/changeLog.html +15 -0
- package/docs/observability.html +115 -58
- package/package-lock.json +785 -922
- package/package.json +8 -8
- package/src/application.js +1 -1
- package/src/cacheRefresher.js +2 -1
- package/src/campaign.js +1 -1
- package/src/client.js +345 -181
- package/src/soap.js +3 -2
- package/test/application.test.js +28 -0
- package/test/client.test.js +84 -5
- package/test/mock.js +5 -0
- package/test/observability.test.js +149 -0
- package/test/soap.test.js +4 -4
package/docs/caches.html
CHANGED
|
@@ -24,25 +24,35 @@ client.clearEntityCache();
|
|
|
24
24
|
client.clearAllCaches();
|
|
25
25
|
</pre>
|
|
26
26
|
|
|
27
|
-
<p>Caches have a TTL of 5 minutes by default. The TTL can be changed at connection time using connection options
|
|
27
|
+
<p>Caches have a TTL of 5 minutes by default. The TTL can be changed at connection time using connection options
|
|
28
|
+
<b>entityCacheTTL</b>, <b>methodCacheTTL</b>, and <b>optionCacheTTL</b>.</p>
|
|
28
29
|
|
|
29
|
-
<p>Caches can be de-activated by setting a TTL of -1 which will have the effect of making all cached data always
|
|
30
|
+
<p>Caches can be de-activated by setting a TTL of -1 which will have the effect of making all cached data always
|
|
31
|
+
invalid.</p>
|
|
30
32
|
|
|
31
33
|
|
|
32
34
|
|
|
33
35
|
<h1>Persistent caches</h1>
|
|
34
|
-
<p>In addition to memory caches, it is possible to use persistent caches as well. This was introduced in version 1.0.5
|
|
36
|
+
<p>In addition to memory caches, it is possible to use persistent caches as well. This was introduced in version 1.0.5
|
|
37
|
+
and is active by default as well when using the SDK in a browser. The browser local storage is used (if allowed).</p>
|
|
35
38
|
|
|
36
|
-
<p>Cached data is stored in local storage with keys prefixed with
|
|
39
|
+
<p>Cached data is stored in local storage with keys prefixed with <b>acc.js.sdk.{{version}}.{{server}}.cache.</b> where
|
|
40
|
+
<b>version</b> is the SDK version and <b>server</b> is the Campaign server name. This means that the cached data is
|
|
41
|
+
lost when upgrading the SDK.</p>
|
|
37
42
|
|
|
38
43
|
<p>It's possible to disable persistent caches using the <b>noStorage</b> connection option.</p>
|
|
39
44
|
|
|
40
|
-
<p>It is also possible to setup one's own persistent cache, by passing a <b>storage</b> object as a connection option.
|
|
45
|
+
<p>It is also possible to setup one's own persistent cache, by passing a <b>storage</b> object as a connection option.
|
|
46
|
+
This object should implement 3 methods: <b>getItem</b>, <b>setItem</b>, and <b>removeItem</b> (synchronous)</p>
|
|
41
47
|
|
|
48
|
+
<p>Additionally, since version 1.1.18, the <b>storage</b> object should also support the for...in operator to iterate through its keys</p>
|
|
42
49
|
|
|
43
50
|
<h1>Auto-refresh caches</h1>
|
|
44
51
|
|
|
45
|
-
<p>The SDK includes a mechnism to maintain the schemas and options caches up-to-date by polling the Campaign server on a
|
|
52
|
+
<p>The SDK includes a mechnism to maintain the schemas and options caches up-to-date by polling the Campaign server on a
|
|
53
|
+
regular basis (10 seconds by default). The server returns the list of entities (schemas or options) which have changed
|
|
54
|
+
since they were cached, and the client removes them from the cache. When a schema changes, the corresponding methods
|
|
55
|
+
are also removed from the method cache.</p>
|
|
46
56
|
|
|
47
57
|
<p>This mechanism is not activate by default but can be activated or deactivated by the following functions</p>
|
|
48
58
|
|
|
@@ -51,7 +61,8 @@ client.startRefreshCaches(30000); // activate cache auto-refresh mechanism eve
|
|
|
51
61
|
client.stopRefreshCaches(); // de-activate cache auto-refresh
|
|
52
62
|
</pre>
|
|
53
63
|
|
|
54
|
-
<p>This mechanism is based on the <b>xtk:session#GetModifiedEntities</b> SOAP method which is only available in Campaign
|
|
64
|
+
<p>This mechanism is based on the <b>xtk:session#GetModifiedEntities</b> SOAP method which is only available in Campaign
|
|
65
|
+
8.4 and above only. For other builds of Campaign, the auto-refresh mechanism will not do anything. </p>
|
|
55
66
|
|
|
56
67
|
<p>The following changes are handled:</p>
|
|
57
68
|
<ul>
|
|
@@ -62,7 +73,11 @@ client.stopRefreshCaches(); // de-activate cache auto-refresh
|
|
|
62
73
|
|
|
63
74
|
<p>The refresh mechanism includes the following guardrails</p>
|
|
64
75
|
<ul>
|
|
65
|
-
<li>Both xtk:option and xtk:schema caches are refreshed every n seconds. To avoid issuing two API calls at the same
|
|
66
|
-
|
|
67
|
-
|
|
76
|
+
<li>Both xtk:option and xtk:schema caches are refreshed every n seconds. To avoid issuing two API calls at the same
|
|
77
|
+
time to the server, the schema cache refresh call is delayed by a few seconds. In the future this delay may change.
|
|
78
|
+
</li>
|
|
79
|
+
<li>If the xtk:session#GetModifiedEntities API is not available, the auto refresh mechanism will silently stop
|
|
80
|
+
automatically</li>
|
|
81
|
+
<li>If an error occurs while trying to refresh, a warning will be logged to the JavaScript console but the auto
|
|
82
|
+
refresh will not be stopped. </li>
|
|
68
83
|
</ul>
|
package/docs/changeLog.html
CHANGED
|
@@ -2,6 +2,21 @@
|
|
|
2
2
|
layout: page
|
|
3
3
|
title: Change Log
|
|
4
4
|
---
|
|
5
|
+
<section class="changelog"><h1>Version 1.1.18</h1>
|
|
6
|
+
<h2>2022/12/20</h2>
|
|
7
|
+
|
|
8
|
+
<li>Automatically remove from local storage key items which correspond to previous versions of the SDK.</li>
|
|
9
|
+
</section>
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
<section class="changelog"><h1>Version 1.1.17</h1>
|
|
13
|
+
<h2>2022/12/06</h2>
|
|
14
|
+
|
|
15
|
+
<li>Fix a bug in schemas: the editType property of a schema node was not set properly (internal attribute is named "edit" but property exposed by the API is "editType")</li>
|
|
16
|
+
<li>Fix a bug with encoding of the SOAP urls: query parameter was not escaped properly</li>
|
|
17
|
+
<li>Add observer callbacks before and after SOAP calls (onBeforeCall, onAfterCall) which allow to intercept SOAP calls and modify SOAP call parameters and results. See the "Method Interception" section in <a href="https://opensource.adobe.com/acc-js-sdk/observability.html">the observability documentation</a> for more details</li>
|
|
18
|
+
</section>
|
|
19
|
+
|
|
5
20
|
<section class="changelog"><h1>Version 1.1.16</h1>
|
|
6
21
|
<h2>2022/11/29</h2>
|
|
7
22
|
|
package/docs/observability.html
CHANGED
|
@@ -6,41 +6,95 @@ title: Observability
|
|
|
6
6
|
|
|
7
7
|
<p>The Campaign client implements an observer mechanism that you can use to hook into what's hapenning internally.</p>
|
|
8
8
|
|
|
9
|
-
<p>An <b>Observer</b>is an object
|
|
9
|
+
<p>An <b>Observer</b> is an object which has one or several callback methods which will be called at certain particular points in the SDK</p>
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
|
|
12
|
+
<h1>SOAP calls</h1>
|
|
13
|
+
<p>It is possible to observe the SOAP calls that are performed by the SDK. The following callbacks are called whenever a SOAP call is made. They can observe the SOAP calls but are not supposed to modify any of the parameters</p>
|
|
14
|
+
<p></p>
|
|
12
15
|
<ul>
|
|
13
|
-
<li>onSOAPCall(soapCall, safeCallData)</li>
|
|
14
|
-
<li>onSOAPCallSuccess(soapCall, safeCallResponse) {}</li>
|
|
15
|
-
<li>onSOAPCallFailure(soapCall, exception) {}</li>
|
|
16
|
+
<li><b>onSOAPCall</b> (soapCall, safeCallData)</li>
|
|
17
|
+
<li><b>onSOAPCallSuccess</b> (soapCall, safeCallResponse) {}</li>
|
|
18
|
+
<li><b>onSOAPCallFailure</b> (soapCall, exception) {}</li>
|
|
16
19
|
</ul>
|
|
17
20
|
|
|
18
|
-
<p>
|
|
21
|
+
<p>The <b>soapCall</b> parameter is the SOAP call which is being observed. In the <b>onSOAPCall</b> callback, the SOAP call has not been executed yet.</p>
|
|
22
|
+
|
|
23
|
+
<p>The <b>safeCallData</b> and <b>safeCallResponse</b> represent the text XML of the SOAP request and response, but in which all session and security tokens have been replaced with "***" string. Hence the name "safe". You should use those parameters for any logging purpose to avoid leaking credentials.</p>
|
|
19
24
|
|
|
25
|
+
|
|
26
|
+
<p>The <b>soapCall</b> parameter is a <b>SoapMethodCall</b> object which describes the SOAP call. It has the following public attributes. </p>
|
|
27
|
+
<p></p>
|
|
20
28
|
<ul>
|
|
21
|
-
<li>
|
|
22
|
-
<li>
|
|
23
|
-
<li>
|
|
29
|
+
<li><b>urn</b> is the SOAP URN which corresponds to the Campaign schema id. For instance "xtk:session"</li>
|
|
30
|
+
<li><b>methodName</b> is the name of the method to call. For instance "Logon"</li>
|
|
31
|
+
<li><b>internal</b> is true or false, depending if the SOAP call is an internal SOAP call performed by the framework itself, or if it's a SOAP call issued by a SDK user</li>
|
|
32
|
+
<li><b>request</b> is a literal corresponding to the HTTP request. It's compatible with the <b>transport</b> protocol. It may be undefined if the SOAP call has need been completely built</li>
|
|
33
|
+
<li><b>response</b> is a string containing the XML result of the SOAP call if the call was successful. It may be undefined if the call was not executed yet or if the call failed</li>
|
|
24
34
|
</ul>
|
|
25
35
|
|
|
26
|
-
<p>The <b>soapCall</b>parameter is the SOAP call which is being observed. In the <b>onSOAPCall</b>callback, the SOAP call has not been executed yet.</p>
|
|
27
36
|
|
|
28
|
-
<p>The <b>request</b>parameter is the HTTP request (as defined in the transport protocol above)</p>
|
|
29
37
|
|
|
30
|
-
<
|
|
38
|
+
<h1>HTTP calls</h1>
|
|
39
|
+
<p>For HTTP calls (such as JSP, JSSP...). Note that despite SOAP calls are also HTTP calls, the following callbacks will not be called for SOAP calls. These callbacks are not supposed to modify any of the parameters</p>
|
|
40
|
+
<p></p>
|
|
41
|
+
<ul>
|
|
42
|
+
<li><b>onHTTPCall</b> (request, safeCallData)</li>
|
|
43
|
+
<li><b>onHTTPCallSuccess</b> (request, safeCallResponse) {}</li>
|
|
44
|
+
<li><b>onHTTPCallFailure</b> (request, exception) {}</li>
|
|
45
|
+
</ul>
|
|
31
46
|
|
|
32
47
|
|
|
33
|
-
<p>The <b>
|
|
48
|
+
<p>The <b>request</b> parameter is the HTTP request (as defined in the transport protocol above)</p>
|
|
34
49
|
|
|
35
|
-
<ul>
|
|
36
|
-
<li><b>urn</b>is the SOAP URN which corresponds to the Campaign schema id. For instance "xtk:session"</li>
|
|
37
|
-
<li><b>methodName</b>is the name of the method to call. For instance "Logon"</li>
|
|
38
|
-
<li><b>internal</b>is true or false, depending if the SOAP call is an internal SOAP call performed by the framework itself, or if it's a SOAP call issued by a SDK user</li>
|
|
39
|
-
<li><b>request</b>is a literal corresponding to the HTTP request. It's compatible with the <b>transport</b>protocol. It may be undefined if the SOAP call has need been completely built</li>
|
|
40
|
-
<li><b>response</b>is a string containing the XML result of the SOAP call if the call was successful. It may be undefined if the call was not executed yet or if the call failed</li>
|
|
41
|
-
</ul>
|
|
42
50
|
|
|
43
|
-
<
|
|
51
|
+
<h1>Logging all SOAP calls</h1>
|
|
52
|
+
|
|
53
|
+
<p>SOAP calls can be logged by setting the <b>traceAPICalls</b> attribute on the client at any time. For security reasons, the security and session tokens values will be replaced by "***" to avoid leaking them</p>
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
<pre class="code">
|
|
57
|
+
client.traceAPICalls(true);
|
|
58
|
+
</pre>
|
|
59
|
+
|
|
60
|
+
<p>This is an example of the logs</p>
|
|
61
|
+
<pre class="code">
|
|
62
|
+
SOAP//request xtk:session#GetOption <SOAP-ENV:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema"
|
|
63
|
+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
|
64
|
+
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
|
|
65
|
+
xmlns:ns="http://xml.apache.org/xml-soap">
|
|
66
|
+
<SOAP-ENV:Header>
|
|
67
|
+
<Cookie>__sessiontoken=***</Cookie>
|
|
68
|
+
<X-Security-Token>***</X-Security-Token>
|
|
69
|
+
</SOAP-ENV:Header>
|
|
70
|
+
<SOAP-ENV:Body>
|
|
71
|
+
<m:GetOption xmlns:m="urn:xtk:session" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
|
|
72
|
+
<sessiontoken xsi:type="xsd:string">***</sessiontoken>
|
|
73
|
+
<name xsi:type="xsd:string">XtkDatabaseId</name>
|
|
74
|
+
</m:GetOption>
|
|
75
|
+
</SOAP-ENV:Body>
|
|
76
|
+
</SOAP-ENV:Envelope>
|
|
77
|
+
|
|
78
|
+
SOAP//response xtk:session#GetOption <?xml version='1.0'?>
|
|
79
|
+
<SOAP-ENV:Envelope xmlns:xsd='http://www.w3.org/2001/XMLSchema'
|
|
80
|
+
xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
|
|
81
|
+
xmlns:ns='urn:xtk:session'
|
|
82
|
+
xmlns:SOAP-ENV='http://schemas.xmlsoap.org/soap/envelope/'>
|
|
83
|
+
<SOAP-ENV:Body>
|
|
84
|
+
<GetOptionResponse xmlns='urn:xtk:session' SOAP-ENV:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'>
|
|
85
|
+
<pstrValue xsi:type='xsd:string'>uFE80000000000000F1FA913DD7CC7C4804BA419F</pstrValue>
|
|
86
|
+
<pbtType xsi:type='xsd:byte'>6</pbtType>
|
|
87
|
+
</GetOptionResponse>
|
|
88
|
+
</SOAP-ENV:Body>
|
|
89
|
+
</SOAP-ENV:Envelope>
|
|
90
|
+
</pre>
|
|
91
|
+
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
|
|
95
|
+
|
|
96
|
+
<h1>Observability events</h1>
|
|
97
|
+
<p>In version 1.1.7, the observer interface is extended to listen for internal events of the SDK. The <b>event</b> function of the observer, if it exist will be call for each SDK event with 2 parameters: the event itself, and for some events, a parent event. For instance a SOAP response event will have the SOAP request for a parent event.</p>
|
|
44
98
|
|
|
45
99
|
<pre class="code">
|
|
46
100
|
client.registerObserver({
|
|
@@ -127,43 +181,46 @@ client.registerObserver({
|
|
|
127
181
|
|
|
128
182
|
|
|
129
183
|
|
|
130
|
-
<h1>
|
|
131
|
-
|
|
132
|
-
<p>SOAP calls can be logged by setting the <b>traceAPICalls</b>attribute on the client at any time. For security reasons, the security and session tokens values will be replaced by "***" to avoid leaking them</p>
|
|
133
|
-
|
|
184
|
+
<h1>Method interception</h1>
|
|
134
185
|
|
|
135
|
-
<
|
|
136
|
-
|
|
137
|
-
</
|
|
186
|
+
<p>
|
|
187
|
+
In version 1.1.17 of the SDK, it's possible to use the observer mechanism to intercept SOAP calls, modify parameters before the call is made, or modify the response before it's returned to the caller.
|
|
188
|
+
</p>
|
|
189
|
+
<p>
|
|
190
|
+
Some SOAP calls are not intercepted: internal SOAP calls performed by the SDK itself (for instance to get schemas) are not intercepted. Logon and Logoff methods are not intercepted either.
|
|
191
|
+
</p>
|
|
192
|
+
<p>
|
|
193
|
+
The <b>beforeSoapCall</b> and <b>afterSoapCall</b> methods can be used. They will be passed the following parameters
|
|
194
|
+
</p>
|
|
138
195
|
|
|
139
|
-
<
|
|
140
|
-
<
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
196
|
+
<table>
|
|
197
|
+
<thead>
|
|
198
|
+
<tr>
|
|
199
|
+
<th>Parameter</th>
|
|
200
|
+
<th>Comment / Description</th>
|
|
201
|
+
</tr>
|
|
202
|
+
</thead>
|
|
203
|
+
<tbody>
|
|
204
|
+
<tr>
|
|
205
|
+
<td><b>method</b></td>
|
|
206
|
+
<td>An object describing the SOAP method. It contains the <b>urn</b>, <b>name</b> and <b>isStatic</b> attributes</td>
|
|
207
|
+
</tr>
|
|
208
|
+
<tr>
|
|
209
|
+
<td><b>object</b></td>
|
|
210
|
+
<td>The object ("this") on which the method applies (it will be undefined for static methods). The <b>beforeSoapCall</b> callback is free to modify the object as needed.</td>
|
|
211
|
+
</tr>
|
|
212
|
+
<tr>
|
|
213
|
+
<td><b>inputParameters</b></td>
|
|
214
|
+
<td>Is an array containing the method parameters. The <b>beforeSoapCall</b> callback is free to modify the object as needed. </td>
|
|
215
|
+
</tr>
|
|
216
|
+
<tr>
|
|
217
|
+
<td><b>representation</b></td>
|
|
218
|
+
<td>The representation (SimpleJson, xml, etc.) used for this method and in which the object and parameters are set</td>
|
|
219
|
+
</tr>
|
|
220
|
+
<tr>
|
|
221
|
+
<td><b>outputParameters</b></td>
|
|
222
|
+
<td>For the <b>afterSoapCall</b> method, an array containing the return value of the SOAP calls. The <b>afterSoapCall</b> callback is free to modify the object as needed. </td>
|
|
223
|
+
</tr>
|
|
224
|
+
</tbody>
|
|
225
|
+
</table>
|
|
156
226
|
|
|
157
|
-
SOAP//response xtk:session#GetOption <?xml version='1.0'?>
|
|
158
|
-
<SOAP-ENV:Envelope xmlns:xsd='http://www.w3.org/2001/XMLSchema'
|
|
159
|
-
xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
|
|
160
|
-
xmlns:ns='urn:xtk:session'
|
|
161
|
-
xmlns:SOAP-ENV='http://schemas.xmlsoap.org/soap/envelope/'>
|
|
162
|
-
<SOAP-ENV:Body>
|
|
163
|
-
<GetOptionResponse xmlns='urn:xtk:session' SOAP-ENV:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'>
|
|
164
|
-
<pstrValue xsi:type='xsd:string'>uFE80000000000000F1FA913DD7CC7C4804BA419F</pstrValue>
|
|
165
|
-
<pbtType xsi:type='xsd:byte'>6</pbtType>
|
|
166
|
-
</GetOptionResponse>
|
|
167
|
-
</SOAP-ENV:Body>
|
|
168
|
-
</SOAP-ENV:Envelope>
|
|
169
|
-
</pre>
|