CCAPI Config

Overview

Sometimes your applications may need to add content programmatically (like creating pages, uploading documents and adding custom element content). The CCAPI Library Component makes it easy to add content into CommonSpot. The CCAPI Library Component utilizes an Application Configuration at the Site Level (XML) to load the settings into the CCAPI calls.

The CCAPI Config uses the Core Config object to handle its site specific configuration.

Note: CommonSpot must be configured to allow API calls before using the ADF CCAPI components.
Please read the section of the Developers Guide on the Content Creation API
(search for "loaderrequest.dat").

File format and location

Security-Note: 
When setting up the CCAPI configuration file there are a couple of approaches to secure your CCAPI login/password. 
# Instead of using the standard ccapi.xml file, use the specially formatted ccapi.cfm file. 
An example ccapi.cfm file can be found here: /ADF/lib/ccapi/ccapi.cfm
# Lock down you '/_cs_apps/config' directory via your web server so this folder is not web accessible. 
# Use both of the above approaches.

To allow each site to have its own configuration for the CCAPI:

1. Locate the '/_cs_apps/config/' directory in your site. If this directory does not exist, create it.
2. Place a file in this directory called "ccapi.xml".
3. Place the following XML content into the ccapi.xml file (an example file can be found here: /ADF/lib/ccapi/ccapi.cfm)

<?xml version="1.0" encoding="utf-8"?>
<settings>
  <logging>
   <enabled>1</enabled>
  </logging>
  <elements>
   <UniqueElementName>
    <pageID>30622</pageID>
    <subsiteID>1</subsiteID>
    <elementType>custom</elementType>
    <controlName>posts</controlName>
   </UniqueElementName>
 </elements>
 <wsVars>
  <webserviceURL>http://cfusion/commonspot/webservice/cs_service.cfc?wsdl</webserviceURL>
  <csuserid>csUserName</csuserid>
  <cspassword>csPassword</cspassword>
  <site>Demo</site>
  <siteURL>http://cfusion/demo</siteURL>
  <subsiteID>1</subsiteID>
  <cssites>commonspot-sites</cssites>
 </wsVars>
</settings>

XML Components

There are three major components in the CCAPI XML Config file:

1. <logging> This tag contains the flag to enable logging.
   
   
2. <elements> This tag contains the Custom Elements and Textblock elements that you would like to use. See the CCAPI Content page for additional information about how to add/edit data within Textblocks and Custom Elements.
   
   
3. <wsVars> This node contains the Web Services information for your site.
   
   

Example

For this example we will use a custom element called "News" with the following fields (Note: Field Labels in text, field names in brackets []):

• Title [title]
• Description [descr]
• Date Posted [datePosted]
• Content [content]
• Author [author]

Lets also assume that your Server has the following configuration:

• Site URL: http://cms.mysite.com
• CS Admin Username: admin
• CS Admin password: password

Sample Steps

If you want to easily populate this Custom Element using the CCAPI then you would do the following:

1. Create a page somewhere in your site (we usually create a page called ccapi.cfm)
2. Place thew "News" custom element in the page
3. Give the element the name "NewsElement" (using the Element Indicators in CS v.5+ you would click the "more" icon and then go to Name)
4. Save the page and move into read mode
5. View the source of the page and look for the page and subsite IDs (Note: this will be in a javascript block near the top of the page - look for "jsPageID" and "subsiteID") - for the sake of our example lets say the pageID = 1345 and the subsiteID = 4
6. Enter the code below into your CCAPI.xml file

 <?xml version="1.0" encoding="utf-8"?>
 <settings>
   <logging>
        <enabled>1</enabled>
    </logging>
    <elements>
        <News>
            <pageID>1345</pageID>
            <subsiteID>4</subsiteID>
            <elementType>custom</elementType>
            <controlName>NewsElement</controlName>
        </News>
    </elements>
    <wsVars>
        <webserviceURL>http://cms.mysite.com/commonspot/webservice/cs_service.cfc?wsdl</webserviceURL>
        <csuserid>admin</csuserid>
        <cspassword>password</cspassword>
        <site>Demo</site>
        <siteURL>http://cms.mysite.com</siteURL>
        <subsiteID>1</subsiteID>
        <cssites>commonspot-sites</cssites>
    </wsVars>
 </settings>

Analyzing the file

We have created a <News> node under the <elements> node. The word "News" is arbitrary and really only needs to be unique (e.g. each xml node within elements needs to be unique).

In the <News> element we have configured it to use the information from the ccapi.cfm page we created above. Notice how the <elementType> is "custom" - thats because we are working with a Custom Element. The <controlName> contains the value you entered in the "Name" field for the "News" element on the page.

In the <wsVars> node we completed the information based on the settings for the server.

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

Code sample

Now it is simple to use the CCAPI to make calls to populate this custom element. Sample code would look like this:

<cfscript>
 // setup a data structure for the news element content
 newsData = structNew();
 newsData.title = "My New News Article";
 newsData.descr = "We are adding content via the CCAPI with the ADF";
 newsData.datePosted = request.formattedTimestamp;
 newsData.content = "Here is the content of the article (can contain <html>)";
 newsData.author = "John Smith";
 // make the call to create content
 addContentResults = application.ADF.csContent.populateContent("News", newsData);
</cfscript>

The newsData structure contains all of the fields for the custom element. The call to "csContent" has 2 parameters the first being the "named element" - this matches the node in the <elements> section of the CCAPI.xml file from above. The second parameter is the actual data for the custom element.