@adobe/acc-js-sdk 1.1.10 → 1.1.12

package/docs/soapAPIs.html

@@ -0,0 +1,234 @@
+---
+layout: page
+title: SOAP APIs
+---
+
+<p>The NLWS object allows to dynamically perform SOAP calls on the targetted Campaign instance.
+</p>
+<pre class="code">
+const NLWS = client.NLWS;
+</pre>
+
+<p>
+    Technically, NLWS is a JavaScript proxy whose properties are dynamically constructed. It has properties
+    for each schema, for instance <b>NLWS.xtkSession</b> corresponds to the APIs of the <b>xtk:session</b> schema.
+</p>
+
+<p>
+    Methods can then be called as <b>asynchronous</b> JavaScript functions. Note that in Campaign, method names
+    usually start with a capital letter (ex: xtk:session#GetServerTime where "G" is a capital letter). 
+    JavaScript convention is to use a lower case first character for function names, and the SDK will follow
+    JS conventions.
+</p>
+
+<pre class="code">
+const result = await NLWS.xtkSession.getServerTime();
+</pre>
+
+
+
+
+
+
+
+
+<h1>Passing parameters</h1>
+
+<p>
+    In order to know which parameters to pass to a method and which parameters are returned, look at the method definition in the schema. 
+    You can also capture SOAP requests and responses from a real session. The method definition in the schema will have a list of 
+    parameters. Parameters can be qualified as <b>in</b>, <b>out</b>, or <b>inout</b>. Unqualified parameters are considered to be <b>in</b>
+    (input) parameters. 
+</p>
+
+<p>
+    The parameters marked as <b>in</b>, <b>inout</b> or without an inout attribubte are input parameters of the API and must be passed 
+    in JavaScript to the method call. Refer to the <a href="{{ site.baseurl }}/dataTypes.hml">Data Types</a> page for a comprehensive view of all the data
+    types supported by the SDK. Parameters are passed positionally and not by name, i.e. you must pass each input parameter in the right
+    order, skipping output parameters.
+</p>
+
+<pre class="code">
+&lt;method name="GetFilesToDownload" static="true">
+    &lt;parameters>
+        &lt;param name="deliveryId" type="long" inout="in"/>
+        &lt;param name="filesToDownload" type="DOMDocument" inout="out"/>
+        &lt;param name="filesNotToDownload" type="DOMDocument" inout="out"/>
+    &lt;/parameters>
+&lt;/method>  
+</pre>
+<p class="caption">An example of a method definition with in and out parameters</p>
+
+<p>
+    Another important attribute is the <b>static</b> attribute of each method. Static methods can be called directly. Non-static methods
+    need an object instance. In the example above, the method takes one input parameter, a numeric delivery id, and returns 2 DOM
+    documents containing a list of files to downoad and a list of files not to download.
+</p>
+
+
+<pre class="code">
+const deliveryId = 1234;
+const [filesToDownload, filesNotToDownload] = client.NLWS.nmsDelivery.getFilesToDownload(deliveryId);
+</pre>
+
+
+<h1>XML &amp; JSON</h1>
+<p>
+In Campaign, many method attributes are XML elements or documents, as well as many return types. It's not very easy to use in JavaScript, so the SDK supports automatic XML<=> JSON conversion. Of yourse, you can still use XML if you want.
+</p>
+
+<p>We're supporting several flavors of JSON in addition to XML.</p>
+<ul>
+<li><b>SimpleJson</b> which is the recommeded and default representation</li>
+<li><b>BadgerFish</b> which was the only and default before 1.0.0, and is now a legacy flavor of JSON. It's a little bit complex and was deprecated in favor of `SimpleJson` (http://www.sklar.com/badgerfish/) </li>
+<li><b>xml</b> which can be use to perform no transformation: Campaign XML is returned directly without any transformations.</li>
+</ul>
+
+<p>The representation can set when creating a client. It's recommended to keep it to <b>SimpleJson</b>.</p>
+<pre class="code">
+const client = await sdk.init("https://myInstance.campaign.adobe.com", "admin", "admin", { representation: "SimpleJson" });
+</pre>
+
+<p>Here's an example of a queryDef in SimpleJson. This query will return an array containing one item for each external account in the Campaign database. Each item will contain the account id and name.</p>
+
+<pre class="code">
+const queryDef = {
+    schema: "nms:extAccount",
+    operation: "select",
+    select: {
+        node: [
+            { expr: "@id" },
+            { expr: "@name" }
+        ]
+    }
+};
+</pre>
+
+
+
+
+<h1>Calling static methods</h1>
+<p>
+Static SOAP methods are the easiest to call. Once you have a <b>NLWS</b> object and have logged on to the server, call a static mathod as followed. This example will use the <b>xtk:session#GetServerTime</b> method to displayt the current timestamp on the server.
+</p>
+
+<pre class="code">
+const NLWS = client.NLWS;
+result = await NLWS.xtkSession.getServerTime();
+console.log(result);
+</pre>
+
+<p></p>
+<ul>
+<li><b>xtkSession</b> is made of the namespace and entity to which the API applies. For instance <b>xtk:session</b> -> <b>xtkSession</b></li>
+<li><b>getServerTime</b> is the method name. In ACC, method names start with an upper case letter, but in JS SDK you can put it in lower case too (which is preferred for JavaScript code).</li>
+</ul>
+
+
+
+
+<h1>Returning multiple values</h1>
+<p>Campaign APIs can return one or multiple values. The SDK uses the following convention:</p>
+<ul>
+<li>no return value -> returns "null"</li>
+<li>one return value -> returns the value directly</li>
+<li>more that one return value -> returns an array of values</li>
+</ul>
+
+
+
+<h1>Calling non-static APIs</h1>
+
+<p>To call a non-static API, you need an object to call the API on. You create an object with the <b>create</b> method.
+    For instance, here's how one creates a QueryDef object.</p>
+
+<pre class="code">
+const queryDef = {
+    schema: "nms:extAccount",
+    operation: "select",
+    select: {
+        node: [
+            { expr: "@id" },
+            { expr: "@name" }
+        ]
+    }
+};
+const query = NLWS.xtkQueryDef.create(queryDef);
+</pre>
+
+<p>Note: the returned object is opaque and private, it should not be directly manipulated.</p>
+
+<p>The method can then be called directly on the object</p>
+<pre class="code">
+const extAccounts = await query.executeQuery();
+</pre>
+
+<p>In this example, the result is as follows</p>
+
+<pre class="code">
+{ extAccount:[
+    { id: "2523379", name: "cda_snowflake_extaccount" },
+    { id: "1782",    name: "defaultPopAccount" },
+    { id: "3643548", name: "v8" }
+]}
+</pre>
+
+<p>Some methods can mutate the object on which they apply. This is for instance the case of the xtk:queryDef#SelectAll method. You call it on a queryDef, and it internally returns a new query definition which contain select nodes for all the nodes of the schema. When such a method is called, the SDK will know how to "mutate" the corresponding object.</p>
+
+<pre class="code">
+const  queryDef = {
+    schema: "xtk:option",
+    operation: "get",
+    where: { condition: [ { expr:`@name='XtkDatabaseId'` } ] }
+  };
+const query = client.NLWS.xtkQueryDef.create(queryDef);
+await query.selectAll(false);
+var result = await query.executeQuery();
+</pre>
+
+<p>In the previous example, a queryDef is created without any select nodes. Then the selectAll method is called. After the call, the JavaScript queryDef object will contain a select elements with all the nodes corresponding to attributes of the xtk:option schema.</p>
+
+
+
+<h1>Passing XML parameters</h1>
+<p>Many Campaign APIs take arguments which are DOM documents or DOM elements. For example, the nms:delivery#DeployTriggerMessages first argument is a DOMElement which is supposed to be a <b>&lt;where></b> clause used as a condition to select Message Center deliveries to publish.</p>
+
+<pre class="code">
+&lt;method name="DeployTriggerMessages" static="true">
+    &lt;parameters>
+        &lt;param inout="in" name="deliveries" type="DOMElement"/>
+        &lt;param inout="in" name="localPublish" type="boolean"/>
+    &lt;/parameters>
+&lt;/method>
+</pre>
+
+<p>For example, one would want to use the following condition to republish a particular delivery</p>
+
+<pre class="code">
+await client.NLWS.nmsDelivery.DeployTriggerMessages({
+    condition: [ {
+    expr: "@internalName='DM23'"
+    }]
+}, false);
+</pre>
+
+<p>The JSON object corresponds to the following XML</p>
+<pre class="code">
+&lt;where>
+    &lt;condition expr="@internalName='DM23'"/>
+&lt;/where>
+</pre>
+
+<p>Note that in XML, unlike JSON, the root element <b>&lt;where></b> is explicitely named "where". When converting JSON to XML, there is no way for the SDK to know which tag name to used for the root XML element. The SDK contains some code to set it for the most common situation, but will rely on the user to specify, when necessary, the name of the root elment. This can be done using the <b>xtkschema</b> (all case insensitive) attribute as follows:</p>
+<pre class="code">
+await client.NLWS.nmsDelivery.DeployTriggerMessages({
+    xtkschema: 'xtk:where',
+    condition: [ {
+    expr: "@internalName='DM23'"
+    }]
+}, false);
+</pre>
+
+<p>When the <b>xtkschema</b> attribute is set, the part after the colon (i.e. "where" in this example) will be used as the root element, effectively generating the right XML.</p>
+
+<p>In our example, the `DeployTriggerMessages` will work properly regardless of the XML root of its `deliveries` parameter, so it's not needed to actually set the `xtkschema` attribute, but it's a best practice to do so, because some APIs will actually depend on receiving the right tag name.</p>

package/docs/timeouts.html

@@ -0,0 +1,23 @@
+---
+layout: page
+title: Handling timeouts
+---
+
+<p>By default, the SDK has a timeout of 5s when running in a node.js environment, and uses the browser defaults when run inside a browser (using the fetch API).</p>
+
+<p>It is possible to overwrite the transport layer (see <b>The Transport Protocol</b> and use your own code to make and configure HTTP requests) to tune the timeout value. It is a bit cumbersome though.</p>
+
+<p>Instead, you can use the <b>timeout</b> parameter, and set it either globally, as a connection parameter, or even at the API call level but using the <b>PushDown</b> mechanism described below.</p>
+
+<p>Sets a timeout of 10s gloally</p>
+<pre class="code">
+const connectionParameters = sdk.ConnectionParameters.ofUserAndPassword(
+                                    "https://myInstance.campaign.adobe.com", 
+                                    "admin", "admin",
+                                    { timeout: 10000 });
+</pre>
+
+<p>Override the timeout to 1 min for a particular API call</p>
+<pre class="code">
+NLWS.xml.pushDown({ timeout: 60000 }).xtkBuilder.installPackage(dom);
+</pre>

package/docs/transport.html

@@ -0,0 +1,45 @@
+---
+layout: page
+title: The Transport Protocol
+---
+
+<p>The SDK uses <b>axios</b> library internally to perform HTTP calls. This can be customized and one can use any other (async) protocol, which is implemented in the <b>transport.js</b> file.</p>
+<p>The transport protocol defines</p>
+<ul>
+    <li>What is an HTTP request</li>
+    <li>What is the corresponding response</li>
+    <li>How errors are handled</li>
+</ul>
+
+<p>The transport protocol exports a single asynchronous function <b>request</b> which takes two parameters.</p>
+
+<p>The first parameter is the request object with the following attributes. Note that it matches axios requests.</p>
+
+<ul>
+    <li><b>method</b> is the HTTP verb</li>
+    <li><b>url</b> is the URL to call</li>
+    <li><b>headers</b> is an object containing key value pairs with http headers and their values</li>
+    <li><b>data</b> is the request payload</li>
+
+</ul>
+
+<p>The second parameter is an set of additional parameters that have been pushed down to the transport layer (see the <b>Pushdown</b> paragraph for more details). In particular, the <b>timeout</b> parameter should be honored by the transport layer.</p>
+
+<p>If the request is successful, a promise is returned with the result payload, as a string.</p>
+
+<p>If the request fails, the promise is rejected with an error object with class <b>HttpError</b>, a litteral with the following attributes:</p>
+<ul>
+    <li><b>statusCode</b> is the HTTP status code, such as 404, 500, etc.</li>
+    <li><b>statusText</b> is the HTTP status text coming with the error</li>
+    <li><b>data</b> is the response data, if any</li>
+</ul>
+
+<p>For proper error handling by the ACC SDK, it's important that the actual class of returned objects is named <b>HttpError</b></p>
+
+<p>The transport can be overriden by using the <b>client.setTransport</b> call and passing it a transport function, i.e. an async function which</p>
+
+<ul>
+    <li>Takes a <b>Request</b> object litteral as a parameter</li>
+    <li>Returns a the request result in a promise</li>
+    <li>Returns a rejected promise containing an <b>HttpError</b> in case of failure</li>
+</ul>

package/docs/troubleshooting.html

@@ -0,0 +1,17 @@
+---
+layout: page
+title: Troubleshooting
+---
+<p>In the version 1.1.5 of the SDK, we are automatically adding the SOAP method name in the URL in order to simplify troubleshooting. Normally, all SOAP method calls are make to the soaprouter.jsp endpoint, which makes it difficult to understand which actual API call is being made.
+In fact the SOAP call name is available via the SOAPAction HTTP header, but it's usually not immediatelly visible.</p>
+
+<p>The SOAP calls URLs are now formed like this: <b>http://acc-sdk:8080/nl/jsp/soaprouter.jsp?xtk:queryDef:ExecuteQuery</b> where the SOAP method name is added as a query parameter. Campaign server ignores this parameter.</p>
+
+<p>This can be disabled using the <b>noMethodInURL</b> connection parameter</p>
+
+<pre class="code">
+const connectionParameters = sdk.ConnectionParameters.ofUserAndPassword(
+                                    "https://myInstance.campaign.adobe.com", 
+                                    "admin", "admin",
+                                    { noMethodInURL: true });
+</pre>

package/docs/writeDoc.html

@@ -0,0 +1,208 @@
+---
+layout: page
+title: Writing Documentation
+---
+
+<p>
+  The documentation of the SDK is written in HTML and uses <a href="https://jekyllrb.com/">Jekyll</a> 
+  and <a href="https://pages.github.com/">Github pages</a> to publish the web site.
+</p>
+
+<h1>Setting up the local environment (MacOS)</h1>
+
+<p>First, install <b>Ruby</b>. Do not use the default ruby install and setup a proper ruby env using <b>chruby</b> and <b>ruby-install</b></p>
+
+<pre class="code">
+brew install chruby ruby-install
+ruby-install ruby
+
+# You may have to start a new terminal for the following to work
+
+echo "source $(brew --prefix)/opt/chruby/share/chruby/chruby.sh" >> ~/.bash_profile
+echo "source $(brew --prefix)/opt/chruby/share/chruby/auto.sh" >> ~/.bash_profile
+echo "chruby ruby-3.1.2" >> ~/.bash_profile # run 'chruby' to see actual version
+
+ruby -v
+</pre>
+
+
+<p>Then install <b>bundler</b>, a dependency manager for Ruby.</p>
+
+<pre class="code">
+gem install bundler
+</pre>
+
+
+
+<p>Test the documentation site. Everything is available in the <b>docs</b> folder</p>
+
+<pre class="code">
+cd docs
+bundle install
+bundle exec jekyll serve 
+
+# visit it at http://127.0.0.1:4000
+</pre>
+
+
+
+
+<h1>Add a page</h1>
+
+<p>
+  To add a documentation page, you first need to add the page to the navigation menu. The menu is defined as a yaml
+  file in <b>docs/_data/navigation.yml</b>.
+</p>
+
+<p>
+  Edit this file and add your entry where you want. Make sure it is in the right section, the SDK documentation, 
+  or the Campaign documentation or advanced topics. Each entry has a name, which will be displayed in the navigation
+  menu, and the corresponding link to an html page containing the documentation.
+</p>
+
+
+<pre class="code">
+- name: Troubleshooting
+  link: troubleshooting.html
+- name: --
+- name: Documentation
+  link: documentation.html
+  children:
+    - name: Connecting to Campaign
+      link: connecting.html<span class="emphasis">
+    - name: My new page
+      link: myPage.html</span>
+    - name: Concepts
+      link: concepts.html
+</pre>
+<p class="caption">Adding page menu in the SDK documentation</p>
+
+
+<p>
+  Now you can create the HTML file for the page. Make sure you set the layout to <b>page</b> and give an appropriate
+  title in the file header (called the Jekyll front matter)
+</p>
+
+<pre class="code">
+  ---
+  <span class="emphasis">layout: page</span>
+  title: My new page
+  ---
+  &lt;p>Hello, I'm a new page&lt;/p>
+</pre>
+
+
+
+
+
+<h1>CSS reference</h1>
+
+<p>
+  A very simple CSS is used, defined in <b>assets/css/styles.css</b>
+</p>
+
+<h2>Headers</h2>
+<p>
+  Use the &lt;h1> and &lt;h2> elements for titles. Documentation pages should be short, and you should not use deeply nested headers
+</p>
+
+<pre class="code">
+&lt;h1>I'm a H1 header&lt;/h1>  
+&lt;h2>I'm a H2 header&lt;/h2>  
+</pre>
+
+<div class="doc-example">
+  <h1>I'm a H1 header</h1>  
+  <h2>I'm a H2 header</h2>  
+</div>
+
+
+<h2>Paragraphs</h2>
+<p></p>
+<ul>
+<li>Use the &lt;p> element for all text paragraph</li>
+<li>Use the <b>info</b> class to format a paragraph as an information notice</li>
+<li>Use the <b>warning</b> class to format a paragraph as an warning notice</li>
+<li>Use the <b>caption</b> class to format a paragraph as a caption to an image or a code block</li>
+<li>Use the <b>ref</b> class to format a paragraph as reference to another part of the documentation or an external site</li>
+</ul>
+<p></p>
+
+<pre class="code">
+&lt;p>I'm a simple paragraph with no additional CSS class&lt;/p>  
+&lt;p class="info">I'm an information notice&lt;/p>  
+&lt;p class="warning">I'm an warning notice&lt;/p>  
+&lt;p class="caption">I'm a caption notice&lt;/p>  
+&lt;p class="ref">I'm a reference to the &lt;a href="https://github.com/adobe/acc-js-sdk">ACC JS SDK&lt;/a>&lt;/p>
+</pre>
+  
+<div class="doc-example">
+  <p>I'm a simple paragraph with no additional CSS class</p>  
+  <p class="info">I'm an information notice</p>  
+  <p class="warning">I'm an warning notice</p>  
+  <p class="caption">I'm a caption notice</p>  
+  <p class="ref">I'm a reference to the <a href="https://github.com/adobe/acc-js-sdk">ACC JS SDK</a></p>
+</div>
+  
+
+
+<h2>Code snippets</h2>
+
+<p>
+  Use the &lt;pre class="code"> element to display code, scripts, etc.
+</p>
+
+<pre class="code">
+&lt;pre class="code">
+const greetings = "Hello, world";
+console.log(greetings);
+&lt;/pre>
+</pre>
+  
+<div class="doc-example">
+<pre class="code">
+const greetings = "Hello, world";
+console.log(greetings);
+</pre>
+</div>
+
+
+
+
+
+<h2>Emphasis</h2>
+<p></p>
+<ul>
+<li>Use the &lt;b> element to emphasis text in paragraphs</li>
+<li>Use the &lt;span class="emphasis"> element to highlight a particular section of code in a &lt;pre block</li>
+<li>Use the &lt;span class="comment"> element to darken a particular section of code in a &lt;pre block (like a comment)</li>
+</ul>
+<p></p>
+
+<pre class="code">
+&lt;p>I'm a simple paragraph with an &lt;b>important&lt;/b> word&lt;/p>  
+
+&lt;pre class="code">
+  const greetings = "I'm a code block with &lt;span class="emphasis">important&lt;/span> text";
+  console.log(greetings);
+&lt;/pre>
+&lt;pre class="code">
+  const greetings = "Hello, world"; &lt;span class="comment">// I'm a comment&lt;/span>
+  console.log(greetings);
+&lt;/pre>
+</pre>
+  
+<div class="doc-example">
+<p>I'm a simple paragraph with an <b>important</b> word</p>  
+
+<pre class="code">
+const greetings = "I'm a code block with <span class="emphasis">important</span> text";
+console.log(greetings);
+</pre>
+<p></p>
+<pre class="code">
+const greetings = "Hello, world"; <span class="comment">// I'm a comment</span>
+console.log(greetings);
+</pre>
+
+</div>

package/docs/xml2json.html

@@ -0,0 +1,96 @@
+---
+layout: page
+title: XML <=> JSON
+---
+
+<p>
+  In general, XML to JSON conversion is a tricky problem. In the case of Campaign, it's even trickier since the structure
+  of the XML documents is defined by Campaign, and is therefore imposed.
+</p>
+
+
+
+<h1>Converting collections (arrays)</h1>
+
+<p>
+  In Campaign, collections of objects are represented by multiple XML elements. There isn't generally a containing element.
+  For instance in the example below, we have books. Books have an author and chapters.
+</p>
+
+<pre class="code">
+&amp;book title="A confederacy of dunces">
+  &amp;author>John Kennedy Toole&amp;/author>
+  &amp;chapter name="Chapter I" pages="20">
+  &amp;/chapter>
+  &amp;chapter name="Chapter II" pages="34">
+  &amp;/chapter>
+&amp;/book>  
+</pre>
+
+<p>
+  As you can see, there is one "author" element and two "chapter" elements. But can there be multiple author elements?
+  Well it depends, and this depends on the schema, whether the schema author has decided that "author" is a single 
+  element or can be a collection (unbound="true"). 
+  But looking a the XML only, it's impossible to tell. We're going to assume that the author here is not a collection,
+  it is simply a string property that has been implemented as an XML element and not as an XML attribute. The corresponding
+  SimpleJson will be the following.
+</p>
+
+<pre class="code">
+  { "$author": "John Kennedy Toole",
+  "chapter": [
+   {
+      "name": "Chapter I",
+      "pages": 20
+    }, {
+      "name": "Chapter II",
+      "pages”: 3
+    },
+  ] }
+</pre>
+
+<p>
+  So far, so good, but what if the book only had one chapter?
+</p>
+
+<pre class="code">
+  &amp;book title="A confederacy of dunces">
+    &amp;author>John Kennedy Toole&amp;/author>
+    &amp;chapter name="Chapter I" pages="20">
+    &amp;/chapter>
+  &amp;/book>  
+</pre>
+
+<p>
+  This becomes trickier because now we have two alternatives: in JSON the "chapter" property can be
+  either an array of one element (which is what is expected) or the element itself
+</p>
+
+<pre class="code">
+  { "$author": "John Kennedy Toole",
+  "chapter": [
+   {
+      "name": "Chapter I",
+      "pages": 20
+  ] }
+
+  <span class="comment">// or</span>
+
+  { "$author": "John Kennedy Toole",
+  "chapter": {
+      "name": "Chapter I",
+      "pages": 20
+  } }
+</pre>
+
+
+<p>
+  And what if a particular book has no chapters? There will not even be any &lt;chapter> elements in the XML. How can
+  the SDK decide if it should create an empty chapters array or leave the chapter property undefined.
+</p>
+
+<p>
+  This is really painful from a user point of view at it can lead to complex and error prone code: every time a
+  JSON property is accessed, one has to wonder what type it is and whether it is the right type
+</p>
+