@adobe/acc-js-sdk 1.1.9 → 1.1.11

package/docs/connecting.html

@@ -0,0 +1,210 @@
+---
+layout: page
+title: Connecting to Campaign
+---
+
+<p>In order to call any Campaign  API, you need to create a <b>client</b> object first using the <b>sdk.init</b> function. You pass it the Campaign URL, as well as your credentials.</p>
+
+<pre class="code">
+const sdk = require('@adobe/acc-js-sdk');
+const connectionParameters = sdk.ConnectionParameters.ofUserAndPassword(
+                                    "https://myInstance.campaign.adobe.com", 
+                                    "admin", "admin");
+const client = await sdk.init(connectionParameters);
+</pre>
+
+<p>Additional parameters can be passed when creating a connection. The connection parameters are described <a href="{{ site.baseurl }}/connectionParameters.html">here.</a></p>
+<pre class="code">
+const connectionParameters = sdk.ConnectionParameters.ofUserAndPassword(
+    "https://myInstance.campaign.adobe.com", 
+    "admin", "admin",
+    { representation: "xml", rememberMe: true });
+</pre>
+
+
+<h1>Logging on</h1>
+<p>
+    After a <b>client</b> object has been created, it's time to log on to Campaign.
+    The <b>sdk.init</b> call will not actually connect to Campaign, you can call the <b>logon</b> method for this. Logon does not need to be called when using session-token authentication or anonymous authentication.
+</p>
+
+<pre class="code">
+await client.logon();
+</pre>
+
+<p>It's also best practice to logoff when finished</p>
+
+<pre class="code">
+await client.logoff();
+</pre>
+
+
+
+<h1>User info and Server info</h1>
+
+<p>
+    upon return, the <b>logon</b> function returns a lot of useful information
+</p>
+<ul>
+    <li>Informations about the server, such as the build number, etc.</li>
+    <li>The list of available packages</li>
+    <li>Informations about the connected user, and it's privileges</li>
+</ul>
+
+<p>T
+    he most convenient way to access this information is by using the <a href="{{ site.baseurl }}/application.html">Application object</a>, but you can
+    also use the <b>client.getSessionInfo().serverInfo</b> and <b>client.getSessionInfo().sessionInfo</b> calls.
+</p>
+
+
+
+<h1>Credentials</h1>
+
+<p>
+    There are several methods of the <b>sdk.ConnectionParameters</b> depending on the type of authentication you want to use. They are
+    described below.
+</p>>
+
+<h2>Login with user and password</h2>
+<p>This is the most common method to log in to Campaign. User the <b>ofUserAndPassword</b> function and pass it the user name and password</p>
+<pre class="code">
+const connectionParameters = sdk.ConnectionParameters.ofUserAndPassword(
+    "https://myInstance.campaign.adobe.com", 
+    "admin", "admin");
+</pre>
+
+
+<h2>Login with IMS access token</h2>
+<p>The SDK supports IMS access token of an IMS user with the <b>ofBearerToken</b> function. Pass it a bearer token.</p>
+<pre class="code">
+const connectionParameters = sdk.ConnectionParameters.ofBearerToken(
+                                "https://myInstance.campaign.adobe.com", 
+                                "ims_bearer_token");
+</pre>
+
+
+<h2>Login with Session token</h2>
+<p>
+Campaign supports authenticating with a session token in some contexts. This is usually used for Message Center API calls (see the <a href="{{ site.baseurl }}/messageCenter.html">Message Center</a> section).
+
+In the following example, the session token is a string composed of the user name, a slash sign, and the password (often empty)
+
+<pre class="code">
+const connectionParameters = sdk.ConnectionParameters.ofSessionToken(url, "mc/mc");
+</pre>
+<p>
+Note that this authentication mode is very specific and does not actually performs a Logon: the session token will be passed to each API calls as-is (with an empty security token) and requires proper setup of the security zones for access to be granted.
+</p>
+<p>
+Another consequence is that the Application object will not be available (client.application will be undefined) when using this authentication mode. The reason is that the application object requires an actual login call to be made to be populated.
+</p>
+
+
+
+
+<h2>Anonymous logon</h2>
+<p>
+Several Campaign APIs are anonymous, i.e. do not require to actually logon to be used. For instance the <b>/r/test</b> API is anonymous. The SDK supports anonymous APIs but still need to be initialized with anonymous credentials as follows. Of course, anonymous APIs also work if you are logged on with a different method.
+</p>
+
+<pre class="code">
+const connectionParameters = sdk.ConnectionParameters.ofAnonymousUser(url);
+const client = await sdk.init(connectionParameters);
+</pre>
+
+
+
+
+
+<h2>Logon with Security token</h2>
+<p>
+If you want to use the SDK client-side in a web page returned by Campaign, you cannot use the previous authentication functions because you do not know the user and password, and because you cannot read the session token cookie.
+</p>
+<p>
+For this scenario, the `ofSecurityToken` function can be used. Pass it a security token (usually available as document.__securitytoken), and the SDK will let the browser handle the session token (cookie) for you.
+</p>
+
+<pre class="code">
+&lt;script src="acc-sdk.js">&lt;/script>
+&lt;script>
+    (async () => {
+        try {
+            const sdk = document.accSDK;
+            var securityToken = "@UyAN...";
+            const connectionParameters = sdk.ConnectionParameters.ofSecurityToken(url, securityToken);
+            const client = await sdk.init(connectionParameters);
+            await client.logon();
+            const option = await client.getOption("XtkDatabaseId");
+            console.log(option);
+        } catch(ex) {
+            console.error(ex);
+        }
+    })();
+&lt;/script>
+&lt;/body>
+&lt;/html>
+</pre>
+<p>
+Note: if the HTML page is served by the Campaign server (which is normally the case in this situation), you can pass an empty url to the `ofSecurityToken` API call.
+</p>
+
+
+
+
+
+<h2>Login with IMS Service Tokens</h2>
+<p>
+The SDK also supports IMS service token with the <b>ofUserAndServiceToken</b> function. Pass it a user to impersonate and the IMS service token.
+</p>
+<p>
+In that context, the IMS service token grants admin-level privileges, and the user indicates which Campaign user to impersonate. 
+</p>
+
+<pre class="code">
+const connectionParameters = sdk.ConnectionParameters.ofUserAndPassword(
+                                    "https://myInstance.campaign.adobe.com", 
+                                    "admin", "==ims_service_token_here");
+</pre>
+
+<p class="warning">This ability is reserved for Adobe services only.</p>
+
+
+
+
+
+<h1>Refreshing connection tokens</h1>
+
+<p>
+The <b>refreshClient</b> is an async callback function with the SDK client as parameter, it is called when the ACC session is expired.
+The callback must refresh the client session and return it. if a SOAP query fails with session expiration error then it will be retried when the callback is defined.
+</p>
+<pre class="code">
+const connectionParameters = sdk.ConnectionParameters.ofUserAndPassword(
+                                    url, "admin", "admin",
+                                    { refreshClient: async (client) => {
+                                        await client.logon();
+                                        return client;
+                                    }});
+</pre>
+
+
+<h1>IP Whitelisting</h1>
+<p>
+Campaign includes an IP whitelisting component which prevents connections from unauthorized IP addresses. This is a common source of authentication errors. 
+</p>
+<p>
+A node application using the SDK must be whitelisted to be able to access Campaign. The SDK <b>sdk.ip</b> function is a helper function that can help you find the IP or IPs which need to be whitelisted.
+</p>
+<p>
+This API is only meant for troubleshooting purposes and uses the <b>https://api.db-ip.com/v2/free/self</b> service.
+</p>
+
+<pre class="code">
+const ip = await sdk.ip();
+</pre>
+<p>
+Will return something like
+</p>
+<pre class="code">
+{ "ipAddress":"AAA.BBB.CCC.DDD","continentCode":"EU","continentName":"Europe","countryCode":"FR","countryName":"France","stateProv":"Centre-Val de Loire","city":"Bourges" }
+</pre>

package/docs/connectionParameters.html

@@ -0,0 +1,109 @@
+---
+layout: page
+title: Connection Parameters
+---
+
+<p>Connection parameters can also be passed an option object when creating a <b>client</b></p>
+
+<pre class="code">
+const connectionParameters = sdk.ConnectionParameters.ofUserAndPassword(
+    "https://myInstance.campaign.adobe.com", 
+    "admin", "admin",
+    { representation: "xml", rememberMe: true });
+</pre>
+
+
+<p>This table shows the various available properties and their values</p>
+
+<table>
+    <thead>
+        <tr>
+            <th>Property</th>
+            <th>Default</th>
+            <th>Description</th>
+        </tr>
+    </thead>
+    <tbody>
+        <tr>
+            <td>representation</td>
+            <td>"SimpleJson"</td>
+            <td> See below. Will determine if the SDK works with xml of json object. Default is JSON</td>
+        </tr>
+        <tr>
+            <td>rememberMe</td>
+            <td>false</td>
+            <td> The Campaign `rememberMe` attribute which can be used to extend the lifetime of session tokens</td>
+        </tr>
+        <tr>
+            <td>entityCacheTTL</td>
+            <td>300000</td>
+            <td> The TTL (in milliseconds) for the xtk entity cache</td>
+        </tr>
+        <tr>
+            <td>methodCacheTTL</td>
+            <td>300000</td>
+            <td> The TTL (in milliseconds) for the xtk method cache</td>
+        </tr>
+        <tr>
+            <td>optionCacheTTL</td>
+            <td>300000</td>
+            <td> The TTL (in milliseconds) for the xtk option cache</td>
+        </tr>
+        <tr>
+            <td>traceAPICalls</td>
+            <td>false</td>
+            <td> Activates tracing of API calls or not</td>
+        </tr>
+        <tr>
+            <td>transport</td>
+            <td>axios</td>
+            <td>Overrides the transport layer</td>
+        </tr>
+        <tr>
+            <td>noStorage</td>
+            <td>false</td>
+            <td>De-activate using of local storage</td>
+        </tr>
+        <tr>
+            <td>storage</td>
+            <td>localStorage</td>
+            <td>Overrides the local storage for caches</td>
+        </tr>
+        <tr>
+            <td>refreshClient</td>
+            <td>undefined</td>
+            <td>Async callback to run when the session token is expired</td>
+        </tr>
+        <tr>
+            <td>charset</td>
+            <td>UTF-8</td>
+            <td>The charset encoding used for http requests. In version 1.1.1 and above, the default will be UTF-8. It's possible to override (including setting an empty character set) with this option.</td>
+        </tr>
+        <tr>
+            <td>extraHttpHeaders</td>
+            <td>[string]:string</td>
+            <td>An optional dictionary (key/value pairs) of extra HTTP headers to pass to all API calls.</td>
+        </tr>
+        <tr>
+            <td>clientApp</td>
+            <td>string</td>
+            <td>An optional string describing the name and version of the SDK client application. It will be passed to the server in the ACC-SDK-Client-App HTTP header</td>
+        </tr>
+        <tr>
+            <td>noSDKHeaders</td>
+            <td>boolean</td>
+            <td>Can be set to disable passing ACC-SDK-* HTTP headers to the server</td>
+        </tr>
+        <tr>
+            <td>noMethodInURL</td>
+            <td>boolean</td>
+            <td>Can be set to true to remove the method name from the URL</td>
+        </tr>
+        <tr>
+            <td>timeout</td>
+            <td>number</td>
+            <td>Can be used to set the APIs call timeout (in ms)</td>
+        </tr>
+    </tbody>
+</table>
+

package/docs/contribute.html

@@ -0,0 +1,54 @@
+---
+layout: page
+title: Contributing
+---
+
+<p>Thanks for choosing to contribute!</p>
+
+<p>The following are a set of guidelines to follow when contributing to this project.</p>
+
+<h2>Code Of Conduct</h2>
+
+<p>
+This project adheres to the Adobe <a href="https://github.com/adobe/acc-js-sdk/blob/master/CODE_OF_CONDUCT.md">code of conduct</a>. By participating,
+you are expected to uphold this code. Please report unacceptable behavior to 
+<a href="mailto:Grp-opensourceoffice@adobe.com">Grp-opensourceoffice@adobe.com</a>.
+</p>
+
+<h2>Have A Question?</h2>
+
+<p>Start by filing an issue. The existing committers on this project work to reach
+  consensus around project direction and issue solutions within issue threads
+  (when appropriate).</p>
+
+<h2>Contributor License Agreement</h2>
+
+<p>All third-party contributions to this project must be accompanied by a signed contributor
+  license agreement. This gives Adobe permission to redistribute your contributions
+  as part of the project. <a href="https://opensource.adobe.com/cla.html">Sign our CLA</a>. You
+  only need to submit an Adobe CLA one time, so if you have submitted one previously,
+  you are good to go!</p>
+
+<h2>Code Reviews</h2>
+
+<p>All submissions should come in the form of pull requests and need to be reviewed
+  by project committers. Read <a href="https://help.github.com/articles/about-pull-requests/">GitHub's pull request documentation</a>
+  for more information on sending pull requests.</p>
+
+<p>Lastly, please follow the <a href="https://github.com/adobe/acc-js-sdk/blob/master/.github/PULL_REQUEST_TEMPLATE.md">pull request template</a> when
+  submitting a pull request!</p>
+
+<h2>From Contributor To Committer</h2>
+
+<p>We love contributions from our community! If you'd like to go a step beyond contributor
+  and become a committer with full write access and a say in the project, you must
+  be invited to the project. The existing committers employ an internal nomination
+  process that must reach lazy consensus (silence is approval) before invitations
+  are issued. If you feel you are qualified and want to get more deeply involved,
+  feel free to reach out to existing committers to have a conversation about that.</p>
+
+<h2>Security Issues</h2>
+
+<p>
+  Security issues shouldn't be reported on this issue tracker. Instead, <a href="https://helpx.adobe.com/security/alertus.html">file an issue to our security experts</a>.
+</p>

package/docs/dataTypes.html

@@ -0,0 +1,124 @@
+---
+layout: page
+title: Data Types
+---
+
+<p>Campaign uses a typed system with some specificities:</p>
+<ul>
+<li>for strings, "", null, or undefined are equivalent</li>
+<li>numerical values cannot be null or undefined (0 is used instead)</li>
+<li>boolean values cannot be null or undefined (false is used instead)</li>
+<li>conversion between types is automatic based on their ISO representation</li>
+</ul>
+
+<p></p>
+<table>
+  <thead>
+      <tr>
+          <th>XTK type</th>
+          <th></th>
+          <th>JS type</th>
+          <th>Comment / Description</th>
+      </tr>
+  </thead>
+  <tbody>
+      <tr>
+          <td>string</td>
+          <td>6</td>
+          <td>string</td>
+          <td>never null, defaults to ""</td>
+      </tr>
+      <tr>
+        <td>memo</td>
+        <td>12</td>
+        <td>string</td>
+        <td></td>
+      </tr>
+      <tr>
+        <td>CDATA</td>
+        <td>13</td>
+        <td>string</td>
+        <td></td>
+      </tr>
+      <tr>
+        <td>byte</td>
+        <td>1</td>
+        <td>number</td>
+        <td>signed integer in the [-128, 128[ range. Never null, defaults to 0</td>
+      </tr>
+      <tr>
+        <td>short</td>
+        <td>2</td>
+        <td>number</td>
+        <td>signed 16 bits integer in the [-32768, 32768[ range. Never null, defaults to 0</td>
+      </tr>
+      <tr>
+        <td>long</td>
+        <td>3</td>
+        <td>number</td>
+        <td>signed 32 bits integer. Never null, defaults to 0</td>
+      </tr>
+      <tr>
+        <td>int64</td>
+        <td></td>
+        <td>string</td>
+        <td>signed 64 bits integer. As JavaScript handles all numbers as doubles, it's not possible to properly represent an int64 as a number, and it's therefore represented as a string.</td>
+      </tr>
+      <tr>
+        <td>float</td>
+        <td>4</td>
+        <td>number</td>
+        <td>single-percision numeric value. Never null, defaults to 0</td>
+      </tr>
+      <tr>
+        <td>double</td>
+        <td>5</td>
+        <td>number</td>
+        <td>double-percision numeric value. Never null, defaults to 0</td>
+      </tr>
+      <tr>
+        <td>datetime</td>
+        <td>7</td>
+        <td>Date</td>
+        <td>UTC timestamp with second precision. Can be null</td>
+      </tr>
+      <tr>
+        <td>datetimetz</td>
+        <td></td>
+        <td></td>
+        <td></td>
+      </tr>
+      <tr>
+        <td>datetimenotz</td>
+        <td></td>
+        <td></td>
+        <td></td>
+      </tr>
+      <tr>
+        <td>date</td>
+        <td>10</td>
+        <td>Date</td>
+        <td>UTC timestamp with day precision. Can be null</td>
+      </tr>
+      <tr>
+        <td>boolean</td>
+        <td>15</td>
+        <td>boolean</td>
+        <td>boolean value, defaultint to false. Cannot be null</td>
+      </tr>
+      <tr>
+        <td>timespan</td>
+        <td></td>
+        <td></td>
+        <td></td>
+      </tr>
+      <tr>
+        <td>primarykey</td>
+        <td></td>
+        <td>string</td>
+        <td>A primary key is serialized with format <schemaId>|<keyField>[|<keyField>[...]]</td>
+      </tr>
+  </tbody>
+</table>
+
+

package/docs/differences.html

@@ -0,0 +1,4 @@
+---
+layout: page
+title: Differences between the SDK and Campaign
+---

package/docs/documentation.html

@@ -0,0 +1,21 @@
+---
+layout: page
+title: Documentation
+---
+
+<p>
+  This guide is divided in 3 sections
+</p>
+<ul>
+  <li>The <b>SDK documentation</b></li>
+  <li>The <b>Campaign documentation</b> which is independ from this SDK</li>
+  <li>And <b>Advanced topics</b> which provides more insights on the internals of the SDK</li>
+</ul>
+
+
+<p>
+  Campaign API is vast and before you start it's good to make sure you understand some of the
+  concepts of Campaign or the SDK.
+</p>
+
+<p class="ref">Start with the <a href="{{ site.baseurl }}/concepts.html">concepts</a> behind Campaign and the SDK.</p>

package/docs/domHelper.html

@@ -0,0 +1,88 @@
+---
+layout: page
+title: Working with XML, DOM Helper
+---
+
+<p>DOM manipulation is sometimes a bit painful. The &lt;b>DomUtil&lt;/b> helper provides a few convenience functions</p>
+
+<pre class="code">
+const DomUtil = sdk.DomUtil;
+</pre>
+
+<p>or</p>
+
+<pre class="code">
+const DomUtil = client.DomUtil;
+</pre>
+
+
+<p>Create DOM from XML string:</p>
+<pre class="code">
+const doc = DomUtil.parse(`&lt;root>
+                             &lt;one/>
+                           &lt;/root>`);
+</pre>
+
+<p>Writes a DOM document or element as a string:</p>
+<pre class="code">
+const s = DomUtil.toXMLString(docOrElement);
+</pre>
+
+<p>Creates a new document</p>
+<pre class="code">
+const queryDoc = DomUtil.newDocument("queryDef");
+</pre>
+
+<p>Escape text value</p>
+<pre class="code">
+const escaped = DomUtil.escapeXmlString(value);
+</pre>
+
+<p>Find element by name (finds the first element with given tag). This is a very common operation when manipulating Campaign XML documents</p>
+<pre class="code">
+const el = DomUtil.findElement(parentElement, elementName, shouldThrow);
+</pre>
+
+<p>Get the text value of an elemennt. This will accomodate text elements, cdata elements, as well has having multiple text child element (which is ususally not the case in Campaign)</p>
+<pre class="code">
+const text = DomUtil.elementValue(element);
+</pre>
+
+<p>Iterates over child elements</p>
+<pre class="code">
+var child = DomUtil.getFirstChildElement(parentElement);
+while (child) {
+    ...
+    child = DomUtil.getNextSiblingElement(child);
+}
+</pre>
+
+<p>Iterates over child elements of a given type</p>
+<pre class="code">
+var methodChild = DomUtil.getFirstChildElement(parentElement, "method");
+while (methodChild) {
+    ...
+    methodChild = DomUtil.getNextSiblingElement(methodChild, "method");
+}
+</pre>
+
+<p>Get typed attribute values, with automatic conversion to the corresponding xtk type, and handling default values</p>
+<pre class="code">
+const stringValue = DomUtil.getAttributeAsString(element, attributeName)
+const byteValue = DomUtil.getAttributeAsByte(element, attributeName)
+const booleanValue = DomUtil.getAttributeAsBoolean(element, attributeName)
+const shortValue = DomUtil.getAttributeAsShort(element, attributeName)
+const longValue = DomUtil.getAttributeAsLong(element, attributeName)
+</pre>
+
+<p>JSON to XML conversion (SimpleJson by default)</p>
+<pre class="code">
+const document = DomUtil.fromJSON(json);
+const json = DomUtil.toJSON(documentOrElement);
+</pre>
+
+<p>BadgerFish can be forced as well</p>
+<pre class="code">
+const document = DomUtil.fromJSON(json, "BadgerFish");
+const json = DomUtil.toJSON(documentOrElement, "BadgerFish");
+</pre>

package/docs/dynamicInvoke.html

@@ -0,0 +1,36 @@
+---
+layout: page
+title: Dynamic Invocation of SOAP calls
+---
+
+<p>Soap calls can be invoked dynamically as follows</p>
+
+<pre class="code">
+const namespace = client.NLWS["xtkSession"];
+const method = namespace["getOption"];
+const result = await method.call(namespace, parameters);
+</pre>
+
+<p>where parameters is the list of parameters to the SOAP call.</p>
+<p>Parameters can be a function which can compute and return the list of parameters as the function is being called:</p>
+
+<pre class="code">
+const result = await method.call(namespace, (method, callContext) => {
+  return parameters;
+});
+</pre>
+<p>The <b>method</b> parameter is the XML definition of the SOAP method call. The <b>callContext</b> is an object which contains the following attributes:</p>
+
+<ul>
+<li><b>schemaId</b> is the id of the schema containing the SOAP method
+<li><b>namespace</b> is the call namespace
+<li><b>object</b> is only used for non-static call and contains the "this" of the call.
+
+</ul>
+
+
+<p>
+  In <a href="{{ site.baseurl }}/sdk/update/2022/10/14/welcome.html">this blog post</a>, you'll find an advanced example of how to use a 
+  dynamic SOAP invocation to implement a REST proxy to the ACC API using the SDK. The example shows how to pass query parameters or body
+  to the SOAP call, and how to collect the names of the return value parameters to format the result as a proper JSON object.
+</p>

package/docs/entityAccessor.html

@@ -0,0 +1,22 @@
+---
+layout: page
+title: The Entity Accessor
+---
+
+
+<p>An <b>EntityAccessor</b> provides a simple interface to access entity objects regardless of their representation. For instance, a query result may be a DOM Element, or a object literal, or a BadgerFish objet. Accessing attribute values and sub elements requires to know which representation is used and which representation specific API to call. For instance, to get the "name" attribute of an entity, you'll write:</p>
+
+<ul>
+  <li>for Simple Json representation, access as JavaScript properties: entity.name or entity["name"]</li>
+  <li>for the XML representation, use the DOM API: entity.DomUtil.getAttribute("name)"</li>
+  <li>for Badget fish, access as JavaScript properties, but do not forget the "@" sign; entity["@name"]</li>
+</ul>
+
+<p>Once done, you'll probably want to cast the value to an XTK type using the XtkCaster.</p>
+
+<p>If you need to access entity attributes (or child elements) in a generic way, you can use the <b>EntityAccessor</b>. It has the following static methods:</p>
+<ul>
+  <li><b>getAttributeAsString</b>, <b>getAttributeAsLong</b>, <b>getAttributeAsBoolean</b> to get typed attribute values</li>
+  <li><b>getChildElements</b> to get the child elements. The result can be iterated on with a <b>for...of...</b> loop</li>
+  <li><b>getElement</b> to get a child element whose attributes and child elements can also be accessed by the EntityAccessor API</li>
+</ul>