Skip to content

Terra Dotta Software API Documentation


Back to Terra Dotta Software API Documentation Return to StudioAbroad

getProgramParameters

Returns a list of parameters for a specific to a program.

URL
http://{site root}/piapi/index.cfm?callName=getProgramParameters
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 getProgramParameters 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) Argument Type Required Meaning program_id Integer Required Program ID for which to gather parameters for. ViewableParams Integer Optional Whether or not the parameter is viewable. Enter 1 to return only viewable parameters, enter 0 to return only non-viewable parameters, or omit to return all program parameters. SearchableParams Integer Optional Whether or not the parameter is available as a selectable search option. Enter 1 to return only parameters that area available for searching, enter 0 for parameters that are unavailable for searching, or omit this field to return all parameters. param_id list Optional Unique program parameter identifier, or comma-delimited list of identifiers. Specifying this value will constrain the results to the value or list of values specified. itemSort string Optional Sorts search results based on the column value(s) you specify. The default value is "Param_Ordinal," which will sort by the pre-configured order.

Available sort options:

  • Param_Ordinal (default)
  • Program_Param_Text (display name of the parameter)
  • Param_ID
  • Param_Type
  • Param_Viewable
  • Param_Searchable
sortOrder string Optional Sorts search results in ascending or descending order, in conjunction with the value(s) you specify in itemSort. The default is ascending order.

Available ordering options:

  • asc (default)
  • desc (descending order)


Top
Table 2: Return values for getProgramParameters
Return Value Type Meaning
param_gloss String Program parameter glossary.
param_id Integer Unique identifier for the program parameter (ID).
param_ordinal Integer The internal sort order for the program parameter (typically used for placement within progam search pages).
param_searchable Integer Numeric value indicating the selection for "Available for search?" within the program parameter create and edit screens. 1 = "Yes"; 0 = "No". A value entered will return parameters based on this critera; however, if no value is chosen, the default is to return all parameters.
param_type String This value indicates the parameter type:
    Possible returned values:
  • MULTI - Multiple-selection parameter
  • SELCT - Single-selection parameter
  • YESNO - Yes or No parameter
  • MINIM - Minimum Value parameter
  • MAXIM - Maximum Value parameter
  • DATLK - Data Lookup parameter
  • DATAX - Data Lookup w/Search parameter
param_value String The value chosen for the program parameter.
param_viewable Integer Numeric value indicating the selection for "Available for display?" within the program parameter create and edit screens. 1 = "Yes"; 0 = "No". A value entered will return parameters based on this critera; however, if no value is chosen, the default is to return all parameters.
param_param_text String The descriptive name of the program paramter.

Using our original call:
http://{site root}/piapi/index.cfm?callName=getProgramParameters&ResponseEncoding=xml&Program_ID=10001
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)
<parameters>
    <recordcount>2</recordcount>
    <parameter>
        <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_id>10001</param_id>
        <param_ordinal>1</param_ordinal>
        <param_searchable>1</param_searchable>
        <param_type>MULTI</param_type>
        <param_value>Japanese</param_value>
        <param_viewable>1</param_viewable>
        <program_param_text>Instruction language</program_param_text>
    </parameter>
    <parameter>
        <param_gloss>
            Eligibility refers to the class status that must be attained in order to participate in a program. The greatest percentage of our programs require a student to be at least a sophomore. However, there are several programs which call for the student to be at least a junior. There can be other eligibility requirements for participation. See GPA and Language Requirement.
        </param_gloss>
        <param_id>10000</param_id>
        <param_ordinal>2</param_ordinal>
        <param_searchable>1</param_searchable>
        <param_type>MULTI</param_type>
        <param_value>2 Sophomore</param_value>
        <param_viewable>1</param_viewable>
        <program_param_text>Eligibility</program_param_text>
    </parameter> 
</parameters> 

We can modify the call to return the data in SOAP format by specifying ResponseEncoding=SOAP:
http://{site root}/piapi/index.cfm?callName=getProgramParameters&ResponseEncoding=SOAP&Program_ID=10001
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"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Body>
<parameters>
    <recordcount>2</recordcount>
    <parameter>
        <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_id>10001</param_id>
        <param_ordinal>1</param_ordinal>
        <param_searchable>1</param_searchable>
        <param_type>MULTI</param_type>
        <param_value>Japanese</param_value>
        <param_viewable>1</param_viewable>
        <program_param_text>Instruction language</program_param_text>
    </parameter>
    <parameter>
        <param_gloss>
            Eligibility refers to the class status that must be attained in order to participate in a program. The greatest percentage of our programs require a student to be at least a sophomore. However, there are several programs which call for the student to be at least a junior. There can be other eligibility requirements for participation. See GPA and Language Requirement.
        </param_gloss>
        <param_id>10000</param_id>
        <param_ordinal>2</param_ordinal>
        <param_searchable>1</param_searchable>
        <param_type>MULTI</param_type>
        <param_value>2 Sophomore</param_value>
        <param_viewable>1</param_viewable>
        <program_param_text>Eligibility</program_param_text>
    </parameter> 
</parameters> 
</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=getProgramParameters&ResponseEncoding=JSON&Program_ID=10001
We would receive a JSON-encoded packet:
(the following JSON packet is formatted for readability)
_cb_getProgramParameters(
{
   "recordcount":7,
   "columnlist":"param_gloss,param_id,param_ordinal,param_searchable,param_type,param_value,param_viewable,program_param_text",
   "data":{
      "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.",
         "Eligibility refers to the class status that must be attained in order to participate in a program. The greatest percentage of our programs require a student to be at least a sophomore. However, there are several programs which call for the student to be at least a junior. There can be other eligibility requirements for participation. See GPA and Language Requirement.",
         "",
         "",
         "",
         "",
         ""
      ],
      "param_id":[
         10001,
         10000,
         10002,
         10006,
         10008,
         10008,
         10009
      ],
      "param_ordinal":[
         1,
         2,
         3,
         4,
         5,
         5,
         6
      ],
      "param_searchable":[
         1,
         1,
         1,
         1,
         1,
         1,
         1
      ],
      "param_type":[
         "MULTI",
         "MULTI",
         "SELCT",
         "MINIM",
         "MULTI",
         "MULTI",
         "YESNO"
      ],
      "param_value":[
         "Japanese",
         "2 Sophomore",
         "Japanese",
         3.0,
         "Apartment",
         "Dormitory",
         "Yes"
      ],
      "param_viewable":[
         1,
         1,
         1,
         1,
         1,
         1,
         1
      ],
      "program_param_text":[
         "Instruction language",
         "Eligibility",
         "Target Language",
         "Minimum GPA",
         "Housing Options",
         "Housing Options",
         "Satisfies diversity req"
      ]
   }
}
);
For additional techniques, be sure to visit the other program calls within these documentation pages. The data returned using JSON encoding is wrapped within the callback function, _cb_getProgramParameters(). 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=getProgramParameters&Program_ID=10001&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=getProgramParameters&ResponseEncoding=JSON&Program_ID=10001&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 of using ColdFusion to call the API and returning the data in a SOAP envelope:
Run Example 1 Top
(if your installation does not have any data, this example will not return anything)

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

<!---// 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="getProgramParameters" />
    <cfhttpparam name="ResponseEncoding" type="url" value="SOAP" />
    <cfhttpparam name="Program_id" type="url" value="#url.program_id#" />
</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