Skip to content

Terra Dotta Software API Documentation


Back to Terra Dotta Software API Documentation Return to Public Site

getStaff

Retrieve all active or all inactive staff members. It may also be used to retrieve an individual staff member's details.

URL
http://{site root}/piapi/index.cfm?callName=getStaff
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 getStaff
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
user_id integer Optional The User_ID of the individual staff member of which to retrieve data for. When User_ID is passed in, the user_bio field is supplied, containing their full bio data.
itemSort string Optional Sorts search results based on the column value(s) you specify. The default value is "Dept_Ordinal, Dept_Name, User_Last_Name, User_First_Name"
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, or "asc".
showActive Boolean Optional A filter for specifying the type of user to return. The default will return active users.


Top
Table 2: Return values for getStaff
Return Value Type Meaning
dept_desc string The description of the department in which the staff member is a part of, if supplied.
dept_name string The department name in which the staff member is a part of, if supplied.
dept_ordinal integer The index value for the department in which the staff member is a part of
full_name string The staff members full name.
user_bio_file string UUID of the user clob record, used for storing the bio data (not implemented; send User_ID argument to receive the bio data).
user_email string The staff members email address.
user_first_name string The staff members first name.
user_id integer The user_id for the staff member.
user_is_active integer Whether or not the staff listing is active. 1 = Yes; 0 = No.
user_last_name string The staff members last name.
user_middle_name string The staff members middle name, if supplied.
user_phone string The staff members phone number.
user_title string The staff members title, if supplied.
user_bio string The full staff member bio. This column will only appear when the User_ID argument is provided.




Using our original call:
http://{site root}/piapi/index.cfm?callName=getStaff
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)
<staff>
<recordcount>29</recordcount>
<staffmember>
<dept_desc></dept_desc>
<dept_name></dept_name>
<dept_ordinal></dept_ordinal>
<full_name>David Booker</full_name>
<user_bio_file></user_bio_file>
<user_email>dbooker@terradottauniversity.com</user_email>
<user_first_name>David</user_first_name>
<user_id>1575</user_id>
<user_is_active>1</user_is_active>
<user_last_name>Booker</user_last_name>
<user_middle_name></user_middle_name>
<user_phone>555-555-5555</user_phone>
<user_title></user_title>
</staffmember>
<staffmember>
<dept_desc></dept_desc>
<dept_name></dept_name>
<dept_ordinal></dept_ordinal>
<full_name>Ai Cheng</full_name>
<user_bio_file></user_bio_file>
<user_email>acheng@terradottauniversity.com</user_email>
<user_first_name>Ai</user_first_name>
<user_id>1573</user_id>
<user_is_active>1</user_is_active>
<user_last_name>Cheng</user_last_name>
<user_middle_name></user_middle_name>
<user_phone>555-555-5555</user_phone>
<user_title></user_title>
</staffmember>
</staff>


We can modify the call to return the data in SOAP format by specifying ResponseEncoding=SOAP:
http://{site root}/piapi/index.cfm?callName=getStaff&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"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" >
  <soapenv:Body >
    <staff>
<recordcount>29</recordcount>
<staffmember>
<dept_desc></dept_desc>
<dept_name></dept_name>
<dept_ordinal></dept_ordinal>
<full_name>David Booker</full_name>
<user_bio_file></user_bio_file>
<user_email>dbooker@terradottauniversity.com</user_email>
<user_first_name>David</user_first_name>
<user_id>1575</user_id>
<user_is_active>1</user_is_active>
<user_last_name>Booker</user_last_name>
<user_middle_name></user_middle_name>
<user_phone>555-555-5555</user_phone>
<user_title></user_title>
</staffmember>
<staffmember>
<dept_desc></dept_desc>
<dept_name></dept_name>
<dept_ordinal></dept_ordinal>
<full_name>Ai Cheng</full_name>
<user_bio_file></user_bio_file>
<user_email>acheng@terradottauniversity.com</user_email>
<user_first_name>Ai</user_first_name>
<user_id>1573</user_id>
<user_is_active>1</user_is_active>
<user_last_name>Cheng</user_last_name>
<user_middle_name></user_middle_name>
<user_phone>555-555-5555</user_phone>
<user_title></user_title>
</staffmember>
      </staff>
     </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=getStaff&ResponseEncoding=JSON
We would receive a JSON-encoded packet:
(the following JSON packet is formatted for readability) 
_cb_getStaff(
{
"recordcount":29,
"columnlist":"dept_desc,dept_name,dept_ordinal,full_name,user_bio_file,
			user_email,user_first_name,user_id,user_is_active,user_last_name,
			user_middle_name,user_phone,user_title",
	"data":
		{
		"dept_desc":["",""],
		"dept_name":["",""],
		"dept_ordinal":["",""],
		"full_name":["David	Booker","Ai	Cheng"],
		"user_bio_file":["",""],
		"user_email":["dbooker@terradottauniversity.com","acheng@terradottauniversity.com"],
		"user_first_name":["David","Ai"],
		"user_id":[1575,1573],
		"user_is_active":[1,1],
		"user_last_name":["Booker","Cheng"],
		"user_middle_name":["",""],
		"user_phone":["555-555-5555","555-555-5555"],
		"user_title":["",""]
		 }
	}
 );
The data returned using JSON encoding is wrapped within the callback function, _cb_getStaff(). 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=getStaff&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=getStaff&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 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 ]" />

<!---// 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="getStaff" />
    <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#" />

Following are some additional call examples using the other available arguments.

To return all inactive staff members, you would specify a value of 0 for showActive, as in:
http://{site root}/piapi/index.cfm?callName=getStaff&showActive=O

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

Back to Terra Dotta Software API Documentation Top