Skip to content

Terra Dotta Software API Documentation


Back to Terra Dotta Software API Documentation Return to Public Site

getRandomFeaturedPrograms

Returns a single, randomly-selected featured program, based on the criteria specified below.

URL
http://{site root}/piapi/index.cfm?callname=getRandomFeaturedPrograms&ResponseEncoding=json
The value for {site root} would represent your installation URL. The values returned from this function are in the following table.



Top
Table 1: Input arguments for getRandomFeaturedPrograms
Standard Input Parameters (jump to call specific input arguments)
Argument Type Required Meaning
ResponseEncoding String Optional The data format to be returned by the API call. The value for ResponseEncoding can be one of the following values:
    Applicable values:
    (case insensitive)
  • XML - eXtensible Markup Language (default)
  • JSON - JavaScript Object Notation
  • SOAP - Simple Object Access Protocol
CallBack Boolean Optional Used with JSON only to specify if a callback function will be used or not.
CallBackName String Optional Used with JSON only to specify the callback function to use.
Call-specific Input Parameters (jump to standard input arguments)
ProgramType Integer Optional A filter for specifying the type(s) of programs to return. The default will return Outgoing with SideTrips and OneStep (1).
    Applicable values:
  • 1 - Outgoing with SideTrips and OneStep
  • 2 - Inbound Exchange
  • 3 - Scholarship
  • 4 - Risk Management
  • 14 - Advising

Default: Outgoing with SideTrips and OneStep


Top
Table 2: Return values for getFeaturedPrograms
Depending on the program type, some of the nodes may or may not be available. The following is a representation of all available nodes for all program types.
Return Value Type Meaning
program_id Integer The numeric program identifier.
program_name String The name of the program.
Locations Object Container object for all locations for the program, containing the following location object:
  • program_city
  • program_country
  • program_region
  • program_location_id
  • program_latitude
  • program_longitude
Terms Object Container object for all terms for the program, containing the following term objects:
  • progarm_term
Parameters Object Container object for all program parameter, containing the following parameter objects:
  • param_id
  • param_type
  • program_param_text
  • param_gloss
  • param_viewable
  • param_value


Using our original call:
http://{site root}/piapi/index.cfm?callName=getRandomFeaturedPrograms
We would receive a packet of data in XML format (the default), that might resemble the following:
(the following XML packet is formatted for readability)
<program>
 <program_id>10326</program_id>
 <program_name>Semester at Sea</program_name>
 <locations>
  <location>
   <program_city>Adelaide</program_city>
   <program_country>Australia</program_country>
   <program_region>Australia/Pacific Islands</program_region>
   <program_latitude>-34.93333</program_latitude>
   <program_longitude>138.6</program_longitude>
   <program_location_id>10141</program_location_id>
  </location>
  <location>
   <program_city>Aix-en-Provence</program_city>
   <program_country>France</program_country>
   <program_region>Europe</program_region>
   <program_latitude>43.5283</program_latitude>
   <program_longitude>5.44973</program_longitude>
   <program_location_id>10108</program_location_id>
  </location>
 </locations>
 <terms>
  <term>
   <program_term>Fall</program_term>
  </term>
  <term>
   <program_term>Spring</program_term>
  </term>
  <term>
   <program_term>Summer</program_term>
  </term>
 </terms>
 <parameters>
  <parameter>
   <param_id>10001</param_id>
   <param_type>MULTI</param_type>
   <program_param_text>Instruction language</program_param_text>
   <param_gloss>This is the language (or languages) in which courses are taught. It is sometimes independent of the native language of the country where the program takes place.</param_gloss>
   <param_viewable>1</param_viewable>
   <param_value>English</param_value>
  </parameter>
  <parameter>
   <param_id>10006</param_id>
   <param_type>MINIM</param_type>
   <program_param_text>Minimum GPA</program_param_text>
   <param_gloss/>
   <param_viewable>1</param_viewable>
   <param_value>2.75</param_value>
  </parameter>
 </parameters>
</program>


We can modify the call to return the data in SOAP format by specifying ResponseEncoding=SOAP:
http://{site root}/piapi/index.cfm?callName=getRandomFeaturedPrograms&ResponseEncoding=SOAP
We would receive a packet of XML wrapped within a SOAP envelope that might resemble the following:
(the following XML packet is formatted for readability)
<soapenv:Envelope 
    xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
    xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
    mlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
 <soapenv:Body>
  <program>
   <program_id>10326</program_id>
   <program_name>Semester at Sea</program_name>
   <locations>
    <location>
     <program_city>Adelaide</program_city>
     <program_country>Australia</program_country>
     <program_region>Australia/Pacific Islands</program_region>
     <program_latitude>-34.93333</program_latitude>
     <program_longitude>138.6</program_longitude>
     <program_location_id>10141</program_location_id>
    </location>
    <location>
     <program_city>Aix-en-Provence</program_city>
     <program_country>France</program_country>
     <program_region>Europe</program_region>
     <program_latitude>43.5283</program_latitude>
     <program_longitude>5.44973</program_longitude>
     <program_location_id>10108</program_location_id>
    </location>
   </locations>
   <terms>
    <term>
     <program_term>Fall</program_term>
    </term>
    <term>
     <program_term>Spring</program_term>
    </term>
    <term>
     <program_term>Summer</program_term>
    </term>
   </terms>
   <parameters>
    <parameter>
     <param_id>10001</param_id>
     <param_type>MULTI</param_type>
     <program_param_text>Instruction language</program_param_text>
     <param_gloss>This is the language (or languages) in which courses are taught. It is sometimes independent of the native language of the country where the program takes place.</param_gloss>
     <param_viewable>1</param_viewable>
     <param_value>English</param_value>
    </parameter>
    <parameter>
     <param_id>10006</param_id>
     <param_type>MINIM</param_type>
     <program_param_text>Minimum GPA</program_param_text>
     <param_gloss/>
     <param_viewable>1</param_viewable>
     <param_value>2.75</param_value>
    </parameter>
   </parameters>
  </program>
 </soapenv:Body>
</soapenv:Envelope>


We can modify the call to return the data in JSON format by specifying ResponseEncoding=JSON:
http://{site root}/piapi/index.cfm?callName=getRandomFeaturedPrograms&ResponseEncoding=JSON
We would receive a JSON-encoded packet:
(the following JSON packet is formatted for readability)
_cb_getRandomFeaturedPrograms({
  "LOCATIONS": {
    "LOCATION": {
      "19": {
        "PROGRAM_REGION": "Australia/Pacific Islands",
        "PROGRAM_CITY": "Adelaide",
        "PROGRAM_COUNTRY": "Australia",
        "PROGRAM_LATITUDE": "-34.93333",
        "PROGRAM_LONGITUDE": "138.6",
        "PROGRAM_LOCATION_ID": 10141
      },
      "35": {
        "PROGRAM_REGION": "Europe",
        "PROGRAM_CITY": "Aix-en-Provence",
        "PROGRAM_COUNTRY": "France",
        "PROGRAM_LATITUDE": "43.5283",
        "PROGRAM_LONGITUDE": "5.44973",
        "PROGRAM_LOCATION_ID": 10108
      },
    }
  }
}, "PROGRAM_ID": 10326,
"TERMS": {
  "TERM": {
    "3": {
      "PROGRAM_TERM": "Summer"
    },
    "2": {
      "PROGRAM_TERM": "Spring"
    }
  }
},
"PARAMETERS": {
  "PARAMETER": {
    "13": {
      "PARAM_TYPE": "MULTI",
      "PARAM_GLOSS": "",
      "PARAM_VALUE": "Sociology",
      "PARAM_ID": 10090,
      "PROGRAM_PARAM_TEXT": "Area of Study",
      "PARAM_VIEWABLE": 1
    },
    "11": {
      "PARAM_TYPE": "MULTI",
      "PARAM_GLOSS": "",
      "PARAM_VALUE": "Psychology",
      "PARAM_ID": 10090,
      "PROGRAM_PARAM_TEXT": "Area of Study",
      "PARAM_VIEWABLE": 1
    },
  }
}
}, "PROGRAM_NAME": "Semester at Sea"
});
The data returned using JSON encoding is wrapped within the callback function, _cb_getRandomFeaturedPrograms(). By default, all JSON calls are returned within a callback wrapper function in form of:
_cb_callName()
Where callName represents the name of the function you originally called. To override this, you can specify the callBackName argument, as in:
http://{site root}/piapi/index.cfm?callName=getRandomFeaturedPrograms&ResponseEncoding=JSON&callBackName=MyCallBackFunction
This call would return the JSON packet wrapped within the callback function, MyCallBackFunction, as in:
_cb_MyCallBackFunction(...json-encoded data...)
In your custom pages, you would then create a corresponding function to handle this custom callback function:
<script language="JavaScript" type="text/javascript">
<!--
// <![CDATA[
function _cb_MyCallBackFunction(data)
{
    // put additional routines here
}
// ]]>
//-->
</script>
If you would like to receive the data without a callback function, you can use the argument callBack to override this. Specifying a value of false for the callBack argument returns the data without the callback function, as in:
http://{site root}/piapi/index.cfm?callName=getRandomFeaturedPrograms&ResponseEncoding=JSON&callBack=false
Note: specifying callBack=true is implied and is unnecessary for returning JSON data with a callback function.



Example 1: Following is an example using JSON and client-side JavaScript to render the program names as link and indicating whether or not the programs are incoming:


Run Example 1 Top
(if your installation does not have any data, this example may not return anything)

<script language="javascript" type="text/javascript">
var prg_id ='';
/* Domain name, API url and site url */
/* Base url can be modified corresponding to the University/School */
var path=window.location.pathname.split('/');
var baseapiurl=window.location.protocol+'//'+window.location.host+'/'+path[1]+'/piapi/index.cfm';
var basesiteurl = window.location.protocol+'//'+window.location.host+'/'+path[1]+'/index.cfm';
var randomfeaturedprogramhtmlcontent = '<div id="randomfeaturedprogramcontainer"><table width="16%" border="1" rules="cols"><tr><th width="208" height="25" align="left" bgcolor="#CCCC99">Learn About Our Programs:</th></tr><tr><td align="center"    ><u >{PROGRAM_NAME} </u></td></tr><tr><td align="center"    ></td></tr><tr><td align="center">{PROGRAM_LOCATIONS} </td></tr><tr><td align="left"><p>Now accepting applications for: </p>{PROGRAM_TERMS}</td></tr><tr><td align="left">{PROGRAM_PARAMETERS}</td></tr><tr><td align="center"><input type="button" name="button" id="button" value="-Click to learn more-" onclick="getProgramBrochure()" /></td></tr></table></div>'

/* Function used to call random featured program API */
function callApi() {
  var url = baseapiurl + '?callname=getrandomfeaturedprograms&ResponseEncoding=json';
  var head = document.getElementsByTagName('head')[0];
  var script = document.createElement('script');
  script.type = 'text/javascript';
  script.src = url;
  head.appendChild(script);
}

/* Function to get random featured program to display on the page */
function _cb_getrandomfeaturedprograms(root) {
  /* Variable contains the featured program content block */
  var randomfeaturedpgm = randomfeaturedprogramhtmlcontent;
  if (root.PROGRAM_ID) {
    prg_id = root.PROGRAM_ID;
    if (root.PROGRAM_NAME)
    /* Variable to store program name */
    var prg_name = root.PROGRAM_NAME;
    /* Variable to store program location object */
    var prg_locations = root.LOCATIONS.LOCATION;
    /* Variable to append all locations */
    var appendlocation = "";
    /* Variable to append <br /> tag at the end of each country */
    var appendbreak = "<br />";
    if (prg_locations) {
      city = '';
      /* Variable to store boolean value */
      isSingleValue = false;
      country = '';
      for (var key in prg_locations) {
        if (!prg_locations[key].length) {
          var obj = prg_locations[key];
          multicity = '';
          multicountry = '';
          for (var prop in obj) {
            if (prop == 'PROGRAM_CITY') {
              multicity = obj[prop];
            }
            if (prop == 'PROGRAM_COUNTRY') {
              multicountry = obj[prop];
            }
          }
          if (multicity != '') appendlocation = appendlocation + multicity + ',';
          if (multicountry != '') appendlocation = appendlocation + multicountry + appendbreak;
        } else {
          isSingleValue = true;
          if (key == 'PROGRAM_CITY') {
            city = prg_locations[key];
          }
          if (key == 'PROGRAM_COUNTRY') {
            country = prg_locations[key];
          }
        }
      }
      if (isSingleValue) {
        if (city != '') appendlocation = appendlocation + city + ',';
        if (country != '') appendlocation = appendlocation + country + appendbreak;
      }
    }
    /* Variable to store term object */
    var prg_terms = root.TERMS.TERM;
    /* Variable to append all terms */
    var appendterm = "";
    /* Variable to append <UL> tag before each term/parameter value */
    var mainprefix = "<ul>";
    /* Variable to append </UL> tag after each term/parameter value */
    var mainsuffix = "</ul>";
    /* Variable to append <li> tag before each term/parameter value */
    var subprefix = "<li>";
    /* Variable to append </li> tag after each term/parameter value */
    var subsuffix = "</li>"
    if (prg_terms) {
      for (var key in prg_terms) {
        var obj = prg_terms[key];
        for (var prop in obj) {
          if (appendterm != '') appendterm = appendterm + subprefix + obj[prop] + subsuffix;
          else appendterm = subprefix + obj[prop] + subsuffix;
        }
      }
      appendterm = mainprefix + appendterm + mainsuffix;
    }
    /* Variable to append all parameters */
    var appendParameter = "";
    /* Variable to append all parameter text */
    var appendparametertext = "";
    /* Variable to append all parameter value */
    var appendparametervalue = "";
    /* Variable to store parameter text */
    var prev_param = "";
    /* Variable to append <p> before each parameter text */
    var appendPARA = "<P>";
    /* Variable to append </P> after each parameter text */
    var appendendPARA = "</P>";
    var prg_params = root.PARAMETERS.PARAMETER;
    if (prg_params) {
      for (var key in prg_params) {
        var obj = prg_params[key];
        for (var prop in obj) {
          if (prop == 'PROGRAM_PARAM_TEXT') {
            appendparametertext = appendparametertext + appendPARA + obj[prop] + appendendPARA + "||";
          }
          if (prop == 'PARAM_VALUE') {
            appendparametervalue = appendparametervalue + mainprefix + subprefix + obj[prop] + subsuffix + mainsuffix + "~";
          }
        }
      }
    }
    splitparametertext = appendparametertext.split('||');
    splitparametervalue = appendparametervalue.split('~');
    for (i = 0; i < splitparametertext.length; i++) {
      if (splitparametertext[i] != prev_param) {
        prev_param = splitparametertext[i];
        appendParameter = appendParameter + splitparametertext[i];
      }
      appendParameter = appendParameter + splitparametervalue[i];
    }
  }
  /* Replace the custom keywords used in the html content with corresponding values */
  randomfeaturedpgm = randomfeaturedpgm.replace('{PROGRAM_NAME}', prg_name);
  randomfeaturedpgm = randomfeaturedpgm.replace('{PROGRAM_LOCATIONS}', appendlocation);
  randomfeaturedpgm = randomfeaturedpgm.replace('{PROGRAM_TERMS}', appendterm);
  randomfeaturedpgm = randomfeaturedpgm.replace('{PROGRAM_PARAMETERS}', appendParameter);
  document.body.innerHTML = document.body.innerHTML + randomfeaturedpgm;
}
/* Function to get program brochure page */
function getProgramBrochure() {
  if (prg_id != '') location.href = basesiteurl + "?FuseAction=Programs.ViewProgram&program_id=" + prg_id;
}
</script>
<script language="JavaScript" type="text/javascript">
    callApi();
</script>
Example 2: Following is an example of using ColdFusion to call the API and returning the data in a SOAP envelope:

Run Example 2 Top
(if your installation does not have any data, this example will not return anything)

<!---// local variables //--->
<cfparam name="responsePacket" default="[ no response ]" />

<!---// connect to the API (GET or POST) //--->
<cfhttp result="httpCall" method="post" url="#REQUEST.CurrentAccount.AccountURL()#piapi/index.cfm">
    <cfhttpparam name="callName" type="url" value="getRandomFeaturedPrograms" />
    <cfhttpparam name="ResponseEncoding" type="url" value="SOAP" />
</cfhttp>

<!---// ensure the response is in XML format //--->
<cfif isXml(httpCall.fileContent)>
    <!---// parse response //--->
    <cfset responsePacket = xmlParse(httpCall.fileContent) />
    <!---// check to see if an error was thrown //--->
    <cfset err = xmlSearch(responsePacket, "//extrainfo") />
    <!---// an error was thrown //--->
    <cfif isArray(err) and not arrayIsEmpty(err)>
        <!---// throw error //--->
        <cfthrow message="#err[1].xmlText#" />
        <cfabort />    
    </cfif>
<cfelse>
    <!---// additional error checking //--->
</cfif>

<!---// additional code goes here //--->
<h2>Output for 'responsePacket':</h2>
<cfdump VAR="#responsePacket#" />


For additional techniques, be sure to visit the other program calls within these documentation pages.

Back to Terra Dotta Software API Documentation Top