CCAPI Conduit Page Pool

New functionality for the ADF 1.8.0 release has been added to enhance the performance of creating and updating Global Custom Element records via the CCAPI. These enhancements will also help streamline the manual CCAPI setup and configuration when using ADF library methods to programmatically populate Global Custom Elements.

Traditionally, when using the CCAPI to populate the Global Custom Elements, each element would be placed on a single “CCAPI Conduit Page” or in some cases one “CCAPI Conduit Page” would be created for each installed ADF App. This single page (or set of pages) would all use a single CommonSpot user. Also, each element placed on these pages would need to be manually assigned a unique “Name” (a Named Element Instance) via the CommonSpot UI. When simultaneous CCAPI requests were made by multiple users these requests would need to “stand in line” and wait while each request was processed in order.

The new CCAPI Conduit Page Pool is made up of a group of multiple pages. These Conduit Pages no longer need to be configured with “Named” Elements. The are just blank Conduit Pages whose CommonSpot Page IDs are added to the “Pool”. When simultaneous ADF wrappered CCAPI calls are made these pages are requested, used and then released back into the pool in a round-robin fashion and are not specific to any specific App or Global Custom Element.

Setup the CCAPI Conduit Page Pool

Create multiple pages in a subsite in your site to be used as the CCAPI Conduit Page Pool. You can have just one page in your pool but we recommend starting with around 3 to 5 pages. More pages can be added to your Conduit Page Pool as needed.

1. Create a subsite for your Conduit Page Pool
   1. For this example we will create a subsite in the “webadmin” subsite called: “ccapi-page-pool”
   2. Only contributor users can access our “webadmin” subsite so our new subsite will inherit those permissions.
2. Create one new CommonSpot Page in the “ccapi-page-pool” Subsite using the “Blank Layout Template”.
   1. For this example we will create a page called “ccapiPoolPage1”.
   2. Also, disable the “Include in: Page Indexes and Full Text and Search Element Results” options in this new page’s “Standard Properties”.
3. Activate the new “ccapiPoolPage1” page.
4. Find and Record the page ID of the new CommonSpot Page, we will need this value later.
5. Copy this newly created page and repeat steps 2-4 for the number of Conduit Pages desired.
   1. Remember to give each new page a unique name.
   2. For this example we incremented each new page name with a number by one:
      1. ccapiPoolPage2
      2. ccapiPoolPage3
      3. etc.

Note: Start with 1 to 3 pages. Add addtional conduit pages, if after reviewing the logs it observed that many requests are being queued. 

Remember:

1. These pages must be “Activated”.
2. You must exit out of “Edit Mode” for each page in the pool.
3. Using the Out-of-the Box CommonSpot “Blank Layout Template” will help to enhance the performance of CCAPI populateCustomElement calls.
4. Pages that contain Local Custom Elements CAN NOT be configured to use the CCAPI Conduit Page Pool
5. Pages with TextBlock Elements (RTE) CAN NOT be configured to use the CCAPI Conduit Page Pool

Create CCAPI Conduit Page Users

Each CCAPI Conduit Page needs its own CommonSpot Contributor user. Since in CommonSpot a single contributor can only be logged in to author/edit a single page at a time the CCAPI Conduit Page Pool needs a contributor user account for each Pool Page.

1. Log in to the CommonSpot User Administrator.
2. Create a new CommonSpot user.
   1. For this example we created: ccapiUser1
3. Set the new user to be a “Dedicated Contributor”.
4. Assign this user to a Group that will have the permissions needed to access it’s Conduit Pool Page.
5. Repeat steps 2-4 for the number of the Conduit Pages configured above.

Setup a new CCAPI site configuration file

An example 'ccapi.cfm' configuration file can be found in your ADF folder: "/ADF/lib/ccapi/ccapi.cfm"

1. Under the root of your site root locate the '/_cs_apps/config/' directory. If this directory does not exist, create it.
2. If a “ccapi.cfm” file exists skip to Step 4.
3. If no “ccapi.cfm” file exists, copy the example “ccapi.cfm” from “/ADF/lib/ccapi/ccapi.cfm" into your '/_cs_apps/config/' directory.
4. Open the “ccapi.cfm” file in a text editor or a CFML IDE.

Configure the Settings for the Pages in the Conduit Page Pool

1. Update the <gceConduitPagePool> XML block
2. Set the Global Request Timeout value
   1. Default: 30 seconds
   2. The length of time a request will wait for a page to become available from the page pool before it gives up. (Each element can have its own timeout value.)
   3. Child node: <globalTimeout>30</globalTimeout>
3. Set the Request Wait Time value
   1. Default: 200 milliseconds
   2. The length of time in milliseconds each request will wait before it tries again to request an available page from the page pool.
   3. Child node: <requestWaitTime>200</requestWaitTime>
4. Enable/Disable Conduit Page Pool Request Logging: (0/1)
   1. Default: 1
   2. A boolean value: 0 for disabled and 1 for enabled
   3. Child node: <logging>1</logging>
5. Configure the conduit page nodes
6. A set of nodes for the pages configured in the pool
7. Child node: <conduitPages>

Configure Pages for use in the Conduit Page Pool

1. Update the <conduitPages> XML block
2. Add <page##> nodes for each of the Conduit Pages you created above:

   <page1>
      <pageid>2001</pageid>
       <csuserid>ccapiUser1</csuserid>
       <cspassword>password</cspassword>
   </page1>

1. Update the <page##> node with a unique number value
2. Set the pageid for the page
   1. Use the pageID from the multiple ccapi conduit pages created above
   2. Child Node: <pageid>
3. Set the csuserid for the page
   1. Child Node: <csuserid>
4. Set the cspassword for the page
   1. Child Node: <cspassword>
5. Optional Setting: Instead of <pageid> use <pageURL> and use the relative URL for the page for the value. (eg. /webadmin/ccapi-page-pool/ccapiPoolPage1.cfm)
6. Repeat steps 2-6 for each of the Conduit Pages configured above.

Remember:

1. Each conduit page needs its own unique CommonSpot Contributor user.
2. Be careful not to set the RequestWaitTime to a value less than the default. It may have an undesirable effect on the page pool process or the server if the wait time is set to a value that is too low. (Also, a value less than 1 will be ignored.)

Your <gceConduitPagePool> XML node block may look something like this:

<gceConduitPagePool>
   <globalTimeout>30</globalTimeout><!-- // seconds →
   <requestWaitTime>200</requestWaitTime><!-- // milliseconds →
   <logging>1</logging>
   <conduitPages>
      <page1>
         <pageid>2001</pageid>
         <csuserid>ccapiUser1</csuserid>
         <cspassword>password</cspassword>
      </page1>
      <page2>
         <pageid>2002</pageid>
         <csuserid>ccapiUser2</csuserid>
         <cspassword>password</cspassword>
      </page2>
      <page3>
         <pageid>2003</pageid>
         <csuserid>ccapiUser3</csuserid>
         <cspassword>password</cspassword>
      </page3>
   </conduitPages>
</gceConduitPagePool>

Configure each Element to use the Conduit Page Pool

1. Update each of the element node blocks inside of the <elements> XML block
   1. Example Element Node: <News>
2. Inside the element node block add a <elementType> node with a value of “custom”
   1. <elementType>custom</elementType>
3. Inside the element node block add a <gceConduitConfig> node
   1. <News><gceConduitConfig>
4. Inside the <gceConduitConfig> add a <customElementName> node
5. Update the value of the <customElementName> node with the actual name of the Global Custom Element. (Found in your Elements manager in Site Admin)
   1. <customElementName>News Articles</customElementName>
6. Optional Setting: Add a element specific request timeout value
   1. <timeout>60</timeout>
7. Optional Setting: Instead of <customElementName> use <formID> and supply the formID value for Global Custom Element

Your <elements> XML node block may look something like this:

<elements>
   <News> 
      <elementType>custom</elementType>
      <gceConduitConfig>
         <timeout>60</timeout> <!-- // optional -->
         <customElementName>News Articles</customElementName>
      </gceConduitConfig>
   </News>
</elements>

Remember:

1. When updating an existing setting to use the CCAPI Conduit Page pool the <pageID>, <subsideID>, and <controlName> nodes are no longer needed.

Configure the <logging> and <wsVars> Sections

Refer to the CCAPI Configuration for information on updating the <logging> and <wsVars> nodes.

Note: Make sure you Reset the ADF whenever this file is added/modified

Notes for Developers

application.ADF.apipool

This variable structure handles the storage of the dynamic data that changes while the CCAPI Conduit Page Pool requests are being processed. Resetting the ADF clears and resets the Page Pool and any currently running requests.

application.ADF.apipoolconfig

This variable structure stores the static data for the configured Global Custom Elements and Pages Changes to the \_cs_apps\config\ccapi.cfm file are picked up when the ADF is reset