Difference between revisions of "CCAPI Config"

Revision as of 18:37, 25 September 2014

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 that can be
used to secure your CCAPI config data: 
1. Instead of using the 'ccapi.xml' config file, use the specially formatted 'ccapi.cfm' file
   for the XML configuration data. An example 'ccapi.cfm' file can be found here: 
   "/ADF/lib/ccapi/ccapi.cfm"
2. Lock down your "/_cs_apps/config" directory via your web server, so this folder can not be
   accessed via the web. 

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.cfm".
3. Place the following CFML and XML content into the ccapi.cfm file

<cfprocessingdirective suppresswhitespace="Yes">
<cfxml variable="configXML">
<cfoutput>
<?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>
</cfoutput>
</cfxml>
</cfprocessingdirective>

XML Components

There are three major XML components in the CCAPI 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>

For CS 7.0.1+, 8.0.1+ and 9+ use the cs_remote.cfc the <webserviceURL> in the <wsVars> section

<wsVars>
    <webserviceURL>#request.site.url#commonspot/webservice/cs_remote.cfc?wsdl</webserviceURL>
</wsVars>

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.cfm file from above. The second parameter is the actual data for the custom element.